TinyVue Icon组件完全使用指南

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

如果你用过 Element Plus、Ant Design 或其他 UI 库，大概率已经习惯这样的写法：先 import 一个图标组件，再像普通 Vue 组件一样放在模板里。理所当然，简单直接。

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

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

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

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

这就是 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 支持四种使用图标的方式：

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

适合 Options API，在 components 中注册后，模板里直接写 。

方式二： 动态绑定（推荐，Composition API）

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

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

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

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

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

---

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

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

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 属性：

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

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

或者配合 TinyVue 的 Tooltip 组件：

---

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

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

5.1 形状切换：线性 vs 面性

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

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

5.2 双色切换：主色 + 副色

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

5.3 托底效果

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

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. 实战：一个完整的图标配置面板

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

---

总结：Icon 该怎么用？

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

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

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