TinyVue Icon组件完全手册

TinyVue Icon 组件完全指南：你的图标不是组件，是"函数"

开篇：不是所有图标都叫图标

如果你用过 Element Plus、Ant Design 或者其他 UI 库，你一定习惯了这样的写法：

<el-icon><Search /></el-icon>

先 import 一个图标组件，然后把它当普通 Vue 组件一样放在模板里。理所当然，简单直接。

然后你打开 TinyVue 的文档，找到 Icon，依葫芦画瓢写了一段：

<template>
  <tiny-icon-shared></tiny-icon-shared>
</template><script setup>
import { IconShared } from '@opentiny/vue-icon'
</script>

报错了。页面上什么都没有。

你检查了 import 路径，检查了组件注册，检查了版本号——全对。那为什么图标不显示？

因为你少了一步：图标不是组件，是函数。你需要先执行它。

<script setup>
import { IconShared } from '@opentiny/vue-icon'// ️ 关键一步：执行函数，返回真正的 Vue 组件
const TinyShared = IconShared()
</script><template>
  <component :is="TinyShared"></component>
</template>

这就是 TinyVue Icon 和其他组件库最大的区别：图标是函数，不是组件。 你 import 回来的 IconShared 是一个工厂函数，调用它之后才会返回一个真正的 Vue 组件实例。

这不是 Bug，这是 Feature。接下来我们深入拆解。

---

1. 为什么图标是"函数"？

TinyVue 包含 600+ 个图标。如果每个图标都是一个独立的 Vue 组件文件，意味着你需要维护 600+ 个 .vue 文件，打包体积也会非常膨胀。

TinyVue 的做法是：所有图标共享一个底层工厂函数。你调用 IconShared() 时，工厂函数会根据预定义的 SVG 数据创建一个 Vue 组件，然后返回给你。

// 伪代码示意
function createIconComponent(svgPathData) {
  return {
    name: 'IconShared',
    render() {
      return h('svg', { class: 'tiny-svg' }, [
        h('path', { d: svgPathData })
      ])
    }
  }
}

这样做的好处：

• 按需打包：你只 import 你用到的图标，Tree-shaking 生效
• 体积极小：每个图标只是一个含 SVG path 的函数，而不是一个完整的 .vue 文件
• 统一管理：所有图标共享同一套渲染逻辑，修改一处即可影响全局

---

2. 四种引入姿势，只有三种是对的

以 IconShared 为例，TinyVue 支持四种使用图标的方式：

方式一：标签式引入（推荐）

<template>
  <tiny-shared></tiny-shared>
</template><script>
import { IconShared } from '@opentiny/vue-icon'export default {
  components: {
    TinyShared: IconShared()  // 注册为组件
  }
}
</script>

适合 Options API，在 components 中注册后，模板里直接写 <tiny-shared />。

方式二：<component :is> 动态绑定（推荐，Composition API）

<template>
  <component :is="tinyShared"></component>
</template><script setup>
import { IconShared } from '@opentiny/vue-icon'const tinyShared = IconShared()
</script>

适合 Composition API，不需要单独注册组件，直接绑定渲染。

方式三：作为其他组件的属性传入

<template>
  <tiny-button :icon="tinyShared">分享</tiny-button>
</template><script setup>
import { IconShared } from '@opentiny/vue-icon'
import { TinyButton } from '@opentiny/vue'const tinyShared = IconShared()
</script>

当你需要给 Button、Input 等组件设置 icon 属性时，传入执行后的图标变量即可。

方式四： 模板上直接执行函数（错误示范）

<template>
  <!--  不要在模板上绑定函数执行！ -->
  <component :is="IconShared()"></component>
</template>

为什么不行？ 每次模板重新渲染，IconShared() 都会被重新调用、创建一个全新的组件实例。这会导致性能问题，并在 Vue 的 diff 算法中产生不可预测的行为。

---

3. 尺寸和颜色：用 CSS 控制，简单到不行

TinyVue 图标渲染出来是 <svg> 元素，带有 tiny-svg 类名。所以你可以用纯 CSS 控制它的外观：

<template>
  <component :is="tinyShared" class="my-icon"></component>
</template><style scoped>
.my-icon {
  font-size: 48px;   /* 控制大小（SVG 撑满 font-size） */
  fill: #e74c3c;     /* 控制颜色 */
}
</style>

CSS 属性	作用	示例值
font-size	控制图标尺寸	14px / 24px / 48px
fill	控制 SVG 填充色	#0067d1 / red
color	控制默认颜色	var(--tv-color-icon-control)
vertical-align	垂直对齐	middle
cursor	鼠标样式（做可点击图标时）	pointer

TinyVue 图标也支持 CSS 变量，你可以直接在全局或局部样式中覆盖：

.tiny-svg {
  fill: var(--tv-color-icon-control, #5e7ce0);
  color: var(--tv-color-icon-control, #5e7ce0);
}

---

4. 给图标加 Tooltip：注意层级

你可能想当然地给图标加上 title 属性：

<component :is="tinyShared" title="分享"></component>

但这不会生效。 TinyVue 图标组件自身不支持 title 属性透传。

正确做法是在父元素上设置 title：

<span title="分享到社交媒体">
  <component :is="tinyShared"></component>
</span>

或者配合 TinyVue 的 Tooltip 组件：

<tiny-tooltip content="分享到社交媒体">
  <component :is="tinyShared"></component>
</tiny-tooltip>

---

5. 标准图标（Advance Icons）：线面切换、双色、托底

TinyVue 为 SaaS 业务梳理了 600+ 个标准图标，统一从 @opentiny/vue-icon 引入。这些图标支持三大增强功能：

5.1 形状切换：线性 vs 面性

通过 shape 属性在线性和面性之间切换：

<template>
  <!-- 线性图标（默认） -->
  <component :is="tinyShare" shape="line"></component>  <!-- 面性图标 -->
  <component :is="tinyShare" shape="filled"></component>
</template><script setup>
import Svgs from '@opentiny/vue-icon'const tinyShare = Svgs['IconShare']()
</script>

shape 值	效果
'line'（默认）	线性图标，描边风格
'filled'	面性图标，填充风格

5.2 双色切换：主色 + 副色

部分图标支持双色填充，通过 first-color 和 second-color 控制：

<template>
  <component
    :is="tinyShare"
    first-color="#0067D1"
    second-color="#36C18D"
  ></component>
</template><script setup>
import Svgs from '@opentiny/vue-icon'
const tinyShare = Svgs['IconShare']()
</script>

5.3 托底效果

通过 underlay 属性给图标加上背景底框：

<template>
  <component
    :is="tinyShare"
    :underlay="{
      background: '#eef3fe',
      borderRadius: '4px',
      scale: 0.8
    }"
  ></component>
</template>

underlay 属性	类型	说明	默认值
background	string	托底背景色	#eef3fe
borderRadius	string	托底圆角	4px
scale	number	中心缩放比例	0.8

---

6. 图标全家福：分类、搜索、复制

TinyVue 提供了一个图标集合页面，所有图标按类别分组：

分类	典型图标
Left	IconAngleLeft, IconArrowLeft, IconChevronLeft...
Right	IconArrowRight, IconAngleRight, IconChevronRight...
TextAlign	IconAlignCenter, IconAlignLeft, IconAlignRight...
Upward	IconArrowUp, IconChevronUp, IconDeltaUp...
Downward	IconArrowDown, IconChevronDown, IconDeltaDown...
Cycle	IconRefresh, IconDownload, IconUpload, IconRepeat...
Sort	IconAscending, IconDescending, IconSort...
Filter	IconFilter, IconClearFilter, IconDefinedFiltration...
Reduce	IconMinus, IconMinusCircle, IconMinusSquare...

你可以搜索图标名称，点击图标即可一键复制名称到剪贴板，粘贴到代码中就能用。

---

7. 实战：一个完整的图标配置面板

综合运用以上所有特性，做一个图标配置面板：

<template>
  <div class="icon-panel">
    <!-- 配置区 -->
    <div class="config">
      <label>形状：
        <tiny-radio-group v-model="shape">
          <tiny-radio label="line">线性</tiny-radio>
          <tiny-radio label="filled">面性</tiny-radio>
        </tiny-radio-group>
      </label>
      <label>主色：<input type="color" v-model="firstColor" /></label>
      <label>副色：<input type="color" v-model="secondColor" /></label>
      <label>托底：
        <tiny-switch v-model="isUnderlay"></tiny-switch>
      </label>
    </div>    <!-- 图标展示区 -->
    <div class="demo-area">
      <component
        :is="currentIcon"
        :shape="shape"
        :first-color="firstColor"
        :second-color="secondColor"
        :underlay="isUnderlay ? underlay : null"
        class="demo-icon"
      ></component>
    </div>
  </div>
</template><script setup>
import { ref, computed } from 'vue'
import Svgs from '@opentiny/vue-icon'
import { TinyRadioGroup, TinyRadio, TinySwitch } from '@opentiny/vue'const shape = ref('line')
const firstColor = ref('#0067D1')
const secondColor = ref('#36C18D')
const isUnderlay = ref(false)
const underlay = { background: '#eef3fe', borderRadius: '8px', scale: 0.85 }const currentIcon = Svgs['IconShare']()
</script><style scoped>
.demo-icon {
  font-size: 80px;
  cursor: pointer;
  transition: all 0.3s;
}
.demo-icon:hover {
  transform: scale(1.1);
}
.config {
  display: flex;
  gap: 16px;
  align-items: center;
  margin-bottom: 32px;
}
</style>

---

总结：Icon 该怎么用？

操作	正确做法	错误做法
引入图标	import { IconXxx } from '@opentiny/vue-icon'	当成普通组件直接 import
使用图标	先执行 IconXxx() 再绑定	模板里直接 IconXxx()
控制尺寸	CSS font-size	设置 width/height 属性
控制颜色	CSS fill	—
设置提示	父元素 title 或 <tiny-tooltip>	图标上直接 title
线面切换	shape="line" / shape="filled"	—
双色图标	first-color + second-color	—
托底效果	:underlay="{ background, borderRadius, scale }"	—

TinyVue Icon 的设计哲学一句话概括：图标是轻量工厂函数，不是重量组件。 这种设计让它能承载 600+ 个图标而不膨胀，同时提供了线面切换、双色、托底等企业级功能。

记住三步走：import → 执行 → 绑定。 顺序不能错，步骤不能少。