做前端组件库的人通常对“图标”又爱又恨。爱是因为它小随手一个svg就能画出来恨也是因为它小小到项目里没人愿意专门维护它最后图标变成了一场灾难。最近在基于 TinyVue 组件库做中后台项目的重构我特意把它的图标系统从头到尾翻了一遍发现这个看起来不起眼的部分其实藏着不少工程化细节。这篇是这个系列的第一篇先把opentiny/vue-icon这个图标组件库本身讲透。如果你正准备在项目里接入 TinyVue或者只是好奇组件库的图标系统应该怎么设计这篇都值得看一下。我不只会告诉你“怎么装、怎么用”还会讲清每个设计决策背后的原因以及我在实际集成过程中踩过的坑。1. 为什么每个成熟组件库都绕不开一套自研图标系统1.1 图标问题在真实项目里到底有多痛先聊个场景。你接手一个中后台项目侧边栏菜单图标来自 iconfont 字体文件按钮图标是设计师切的 PNG 雪碧图表格里的状态小图标又是一批 base64。三套来源、三种尺寸规范、三种换色方式用起来是什么感受改一个颜色要翻半天 CSS换一个图标要重新走一遍切图流程更别提不同显示器下字体图标渲染发虚的问题。图标这东西单个看起来都是小事但在一个长期维护的项目里它是“高频使用、低频维护”的典型。高频使用意味着只要它乱了整个界面的精致度立刻下降低频维护意味着一旦混乱大家都会选择继续往上叠新的临时方案而不是停下来治理。组件库存在的意义之一就是消灭这种局部混乱而图标作为组件库最底层的“原子”资源必须有一套统一的、可编程的、按需加载的承载方案。这个矛盾在 TinyVue 里被解决得比较彻底。它没有把图标做成一张大图片也没有丢给你一个字体文件而是把每个图标都封装成了一个独立组件和普通 Vue 组件一样可以被引入、传参、复用。这套思路就是“图标组件库”的核心图标不再是静态资源而是代码的一部分。1.2 从 iconfont 到组件化图标一条必然的演进路线前端的图标方案其实经历过好几代。最早是切图一张张小 PNG 被放进img或背景下简单粗暴但没法缩放和换色后来有了 CSS Sprite 雪碧图把多个小图标拼成一张图靠background-position定位减少请求数但维护时很痛苦再后来 iconfont 字体图标火起来一套字体文件承载几十上百个图标用 HTML 实体或 class 引用解决了矢量和换色问题。字体图标也有硬伤。它是“用字体渲染图形”所以本质上只能呈现单色多色图标要做很多 hack不同操作系统和浏览器对字体抗锯齿的处理不一致低分辨率下边缘发虚还经常出现因为字体加载时机导致的首屏空白。真正适合组件库的是用内联 SVG 来实现图形再用 Vue 组件来管理这些 SVG。TinyVue 的图标系统就是这么做的这也是为什么它敢说自己的图标既能在 Vue 2 项目里跑也能在 Vue 3 项目里跑因为底层依赖的只是 SVG 标准和组件化机制。2. TinyVue 图标库的底牌SVG 方案的取舍与设计2.1 三种主流图标方案放在一起看先上一张对比表把 SVG 组件、字体图标、位图雪碧图放在一起差异就很清楚了对比维度SVG 组件化方案字体图标 iconfont位图/雪碧图缩放效果矢量任意尺寸清晰矢量但低分辨率下抗锯齿不佳放大后模糊多色支持支持SVG 内部任意 fill/stroke基本只支持单色天然支持但不能动态换色动态换色通过 currentColor 或 fill 实现通过 CSS color 实现但多色受限基本做不到按需加载每个图标独立组件Tree Shaking 友好通常整套字体文件一起加载整张雪碧图一起加载可访问性支持 title/role 等语义标签依赖字体渲染语义较弱基本是背景图语义缺失维护成本有 svg 源文件即可可走 CI 自动化需要管理字体文件生成流程需要重新切图、定位坐标核心差异在于 SVG 方案把图标的“表现层”和“逻辑层”打通了。一个path的fill属性可以直接绑定 CSS 变量或组件属性这意味着你可以在运行时根据主题、状态甚至用户权限去动态改变图标颜色和样式。这种灵活性是位图和字体都无法替代的。2.2 TinyVue 图标组件化的内部逻辑TinyVue 的图标库之所以好用不是因为 SVG 本身有多神奇而是因为它在 SVG 外面包了一层组件化规范。每个图标大致长这样template svg viewBox0 0 24 24 width1em height1em fillcurrentColor path d.../path /svg /template这里有几个关键细节值得展开。第一viewBox统一为0 0 24 24这是一个约定俗成的设计网格绝大多数设计稿里的图标都遵循这个坐标系保证了所有图标放在一起视觉大小是一致的。第二宽高用的是1em而不是固定像素这样图标默认继承父级字号你改font-size它就跟着缩放。第三fill用的是currentColor这样图标的颜色默认跟随 CSS 的color属性父元素一个color就能控制整组图标。我刚才说这是“大致长这样”因为 TinyVue 内部还做了尺寸和颜色的属性透传。最终从使用者的角度看一个图标组件就暴露几个属性名字、尺寸、颜色、自定义类名。这种封装让图标的使用门槛降得非常低业务方不需要懂 SVG 知识只要知道图标叫什么名字就够了。2.3 命名规范和查询方式图标系统的体验很大程度取决于命名。TinyVue 的图标命名整体是语义化的比如添加叫Add关闭叫Close刷新叫Refresh帮助叫Help。组件导出名会在语义词后面加上Icon后缀例如AddIcon、CloseIcon、RefreshIcon。在使用tiny-icon组件的时候去掉后缀用语义名即可比如nameAdd。命名看起来是个小事但实际影响很大。团队在沟通时直接说“用 Add 图标”而不是“排行榜第一个图标”远远高效。而且语义化命名方便你记忆和推断不需要每次都打开图标列表查。我第一次用的时候没看文档凭感觉写了nameEdit还真就存在。当然我建议你还是去官方文档的图标展示页确认一下具体有哪些名字不同版本之间图标数量会有增加但既有命名基本保持稳定。3. 实操安装、引入并在业务页面中用起来3.1 安装这件事比你想的更简单TinyVue 的图标组件库不是独立发行的一套庞大体系它跟随主包一起走。安装主包即可npm install opentiny/vue如果你只想单独使用图标也可以显式安装图标包npm install opentiny/vue-icon我建议直接安装主包因为一套中后台系统里不可能只用图标后面你要用表格、弹窗、表单组件都是迟早的事。安装完之后主题样式也别漏掉TinyVue 的组件依赖主题包提供的基础样式图标在不同主题下才能保证颜色和尺寸的协调npm install opentiny/vue-theme样式入口在主包里通过 import 引一次import opentiny/vue-theme/index.css这一步很多人会忘记结果组件样式全是乱的还以为是图标库本身的问题。3.2 两种用法TinyIcon 壳组件 vs 直接使用图标组件TinyVue 提供了两种使用方式我在项目里会根据场景切换。第一种是使用tiny-icon壳组件适合在模板里动态切换图标名的场景template div classdemo-icon-box tiny-icon nameAdd size24px color#5e7ce0/tiny-icon tiny-icon nameHelp size1.5em colorvar(--ti-base-color-info)/tiny-icon /div /template script setup import { TinyIcon } from opentiny/vue /script第二种是直接引入具体的图标组件适合某个图标在页面里被故意强调、或者你需要给它绑定复杂事件的场景template CloseIcon classclose-btn clickhandleClose/CloseIcon /template script setup import { CloseIcon } from opentiny/vue-icon /script两种方式不冲突甚至可以混用。我的经验是列表页、菜单栏这种“图标跟着配置走”的场景用tiny-icon配合 name 字符串最舒服因为你可以把图标名直接放在路由配置或接口返回的数据里而页面里固定的操作按钮直接引入图标组件配合编辑器自动补全和类型提示更舒服。3.3 高频属性与注意事项TinyVue 图标组件最常用的属性就这么几个建议把它们作为团队内的“图标使用规范”固定下来属性说明推荐值示例name图标语义名仅在tiny-icon上使用Add、Closesize宽高尺寸支持 em 和 px16px、1.25emcolor图标颜色支持色值和 CSS 变量#333、var(--ti-base-color-info)class自定义类名用于覆盖样式或挂载动画close-btn尺寸方面我建议优先使用 em这样图标能跟随按钮或文字的字号变化整体比例不会失调。颜色方面优先使用 CSS 变量或继承 currentColor保证换肤时图标能跟着主题一起变而不是把颜色写死。还要注意一点tiny-icon的name属性必须严格匹配内置图标的语义名。如果传了不存在的名字页面不会崩溃但图标区域会留空看起来像“缺失”。排查的时候先看控制台有没有警告再看名字是否拼写正确。4. 按需加载与体积控制小图标也不能拖垮首屏4.1 全量引入的代价组件库里图标数量动辄上百个如果一次性全部引入哪怕每个 SVG 只有几百字节也会在首屏 bundle 里堆出几十 KB 体积。更麻烦的是SVG 图标在被渲染成组件时会注册到 Vue 组件系统里组件实例的创建开销比一个普通img高。一两个无所谓几十个同时出现低端设备上的渲染时间立刻就能感知到。TinyVue 的图标系统本身是支持按需加载的但如果你在主入口里写import { TinyIcon } from opentiny/vue这是把TinyIcon壳组件和它依赖的映射关系引进来并不意味着你要把所有图标组件全注册。真正吃掉体积的是“全量注册图标组件”的写法所以要避免类似这样的代码import * as Icons from opentiny/vue-icon Object.entries(Icons).forEach(([name, component]) { app.component(name, component) })这种写法虽然省事但会把整个图标包卷进首屏属于典型的“省小力气、吃大亏”。4.2 真正可靠的按需落地方式在实项目中我推荐两条路并行。一条是手动按需用到哪个图标就 import 哪个这依赖现代构建工具的 Tree Shaking只要图标包本身是 ESM 模块且标记了无副作用没被引用的图标组件最终会被摇掉。这也是为什么我前面强调要直接import { CloseIcon } from opentiny/vue-icon而不是走全量注册。另一条是自动按需如果你已经在用unplugin-vue-components做组件自动导入可以配置 TinyVue 的 resolver让它在模板里发现tiny-icon或AddIcon时自动注册对应组件这样连 import 都不用写了。这套配置在 TinyVue 官方文档里有现成示例我在这里就不展开复制了但核心思路是“按使用声明”而不是“先全部备好”。4.3 首屏之外symbol 雪碧图是个折中方案如果你的项目里有大量图标集中在某一个页面而且这些图标是动态变化的逐个 import 会变得很难维护。我的处理方式是导入一个symbol雪碧图把需要用到的图标以symbol形式统一定义页面里通过use引用。这个方案的好处是运行时“一次引入、多出使用”减少重复 SVG DOM坏处是主题换色不如内联 SVG 灵活。所以我只把它用在高频静态图标上比如侧边栏菜单、状态标识动态交互图标还是走组件方式。选用哪个方案本质是在“维护成本”和“运行时性能”之间做权衡没有绝对最优。5. 扩展与自定义把业务图标也纳入组件体系5.1 内置图标不够用时的处理顺序中后台项目早晚会遇到内置图标覆盖不了业务语义的情况比如你自己产品特有的“导出报表”“智能审核”这类图标。我处理这类需求的顺序是先看内置库里有没有语义相近的有就直接用没有就找设计师要 SVG 源文件然后封装成 Vue 组件最后才考虑引入第三方图标库。为什么不推荐一上来就引入 antd 图标或 Element 图标因为一套组件库的图标风格是统一的线宽、圆角和视觉重心混入另一套图标会在整体视觉上“露出破绽”细看会发现粗的粗、细的细很不专业。TinyVue 的图标体系里塞一个风格完全不同的业务图标会破坏整套界面的一致性。拿到 SVG 源文件后封装一个极简组件template svg>script setup import { computed } from vue import { DownloadIcon, LoadingIcon, CheckIcon } from opentiny/vue-icon const props defineProps({ status: String }) const currentIcon computed(() { if (props.status downloading) return LoadingIcon if (props.status done) return CheckIcon return DownloadIcon }) /script template component :iscurrentIcon classstatus-icon/component /template用component :is的好处是不用在模板里堆条件分支而且新增状态时只需要在映射表里加一项。如果后续状态很多还可以把这个映射表抽成独立的配置对象配合withDefaults做类型提示。5.3 可访问性图标不只是给看得见的人用的业务图标纳入组件体系之后千万别忘了可访问性。装饰性图标比如按钮旁边的放大镜应该加上aria-hiddentrue让屏幕阅读器忽略它有语义的图标比如“下载成功”的绿色对勾应该提供可读的说明文字比如用roleimg配合title标签。template CheckIcon roleimg aria-label下载成功 classsuccess-icon/CheckIcon /template这一步很不起眼但在团队里定下“图标组件必须考虑读屏”的规矩后整体产品无障碍水平会明显提升。很多前端团队不做这个不是不想做是压根没人提过导致问题一再出现。6. 集成过程中我踩过的几个坑6.1 图标全部不显示但页面不报错我第一次把 TinyVue 接入一个老项目时遇到最诡异的现象是页面渲染正常组件一个都不少但所有图标位置都是空白。排查链路是先确认图标组件有没有被正确注册再确认模板里的name和官方文档一致最后才发现问题是主题样式没有引入。TinyVue 的图标默认依赖主题包里的基础布局样式在未引入主题 CSS 的情况下svg虽然没有被销毁但尺寸被继承成了 0视觉上看就是消失。这个坑提醒我图标不显示不要一上来就怀疑组件坏了先看样式链路是不是完整。优先级是主题样式引入 组件注册 name 正确性。6.2 颜色不生效currentColor 的继承被截断另一个高频问题是明明在组件上写了color#f00图标颜色却不变化。原因是图标内部的 path 已经写死了fill#333外层的color根本传不进去。TinyVue 内置图标默认是currentColor的但如果你在全局 CSS 里写过类似svg path { fill: #333 !important; }这样的全局样式就把所有图标的默认色全部覆盖了再传color也没用。我的建议是尽量不要用这种全量svg path选择器写样式它的杀伤范围是所有 SVG包括你自己封装的自定义图标。如果真的要让某个图标单独变色用组件上的fill直接绑定或者给这个图标单独加 class 控制都比全局覆盖稳妥。6.3 按需加载没有生效bundle 里还是塞了整个图标包还有一次我发现打包产物体积异常排查之后发现是入口文件用了全量注册那套代码导致 Tree Shaking 没机会工作。你以为写了import { TinyIcon }就万事大吉实际上真正拖垮体积的是那句Object.entries(Icons).forEach(...)。这种写法把opentiny/vue-icon的导出全部遍历了一遍构建工具无法静态分析哪些被用到只能全部保留。遇到体积异常优先在项目里搜vue-icon相关的 import看看有没有* as和app.component强注册的代码。把它们改成逐个 import打包体积会肉眼可见地降下来。6.4 版本升级后图标名字对不上TinyVue 迭代速度不慢图标库偶尔会新增或调整命名。升级依赖之后一定要回归一遍所有用到图标的地方尤其是把图标名存在数据库或配置文件里的项目。这类问题运行时不会报错只会默默留白如果模块上又没有自动化截图对比很容易漏。我的做法是升级前先翻一下官方文档的图标变更日志同时在本地把内置图标列表导出成 JSON和我项目里的配置数组做一次差集校验发现不匹配的名字直接改掉。这个脚本不复杂但能避免把 bug 带上线。最后聊点个人体会把图标做成组件库看起来是“小工程”做起来才知道水有多深。设计规范、命名规范、加载策略、主题适配、可访问性任何一环漏掉都会在后续维护里加倍还回来。我个人的经验是接入 TinyVue 图标系统时宁可先花半天时间把图标清单、使用规范和按需加载方案定下来也不要等项目上线后再回头补课。这个系列才刚开始后续我打算接着拆 TinyVue 图标系统的命名规范细节、主题定制方案以及怎么从零搭建一套适配自家业务的图标组件库。如果你在接入过程中也遇到了我没提到的坑欢迎把你的现象和报错贴到评论区我来帮你一起定位原因。
