Element Plus 图标体系完全指南从安装注册到 el-icon 源码级剖析【免费下载链接】element-plus A Vue.js 3 UI Library made by Element team项目地址: https://gitcode.com/GitHub_Trending/el/element-plusElement Plus 内置了一套基于 Vue 3 的 SVG 图标组件库element-plus/icons-vue本文以 icon.md 为主线系统讲解图标的四种引入方式按需、全量、浏览器 CDN、自动导入、el-icon容器组件的属性与插槽并结合 icon.vue、icon.ts 与 icon.test.tsx 等源码揭示其内部实现原理。读完本文你将掌握在项目中注册、使用与定制 Element Plus 图标的全部姿势并能读懂其底层工作方式。图标体系概览Element Plus 提供了一套常见的内置 SVG 图标。与传统的字体图标iconfont不同这套图标以单个 Vue 组件的形式存在每个图标就是一个独立的 SVG 组件可以像普通组件一样被导入、注册与组合使用。需要特别说明的是图标组件库element-plus/icons-vue是独立于 Element Plus 主库发布的包因此无论你使用全量引入、按需引入还是 CDN 方式SVG 图标本身都可以在任意版本下使用只要安装即可。全部可用的 SVG 图标清单来自 element-plus/icons-vue 包其图标源工程为 element-plus-icons本文末节的 Icon Collection 也提供了可视化集合页面。安装使用包管理器选择任一你喜欢的包管理器安装element-plus/icons-vue$ npm install element-plus/icons-vue$ yarn add element-plus/icons-vue$ pnpm install element-plus/icons-vue该包在仓库内被大量组件内部依赖例如 icon.ts 中直接以具名导入方式引入了CircleCheck、CircleClose、SuccessFilled、WarningFilled、Loading等图标用于 Message、Notification、Form 校验等场景的状态反馈图标这说明图标库与 Element Plus 主库存在真实的运行时依赖关系。引入与注册方式Element Plus 官方提供了四种典型的图标接入方式可按项目场景灵活选择。全量注册所有图标如果希望在全局模板中直接以标签形式使用任意图标需要在入口文件如main.ts中导入全部图标并全局注册// main.ts // if youre using CDN, please remove this line. import * as ElementPlusIconsVue from element-plus/icons-vue const app createApp(App) for (const [key, component] of Object.entries(ElementPlusIconsVue)) { app.component(key, component) }代码中Object.entries遍历导出的所有图标组件将每个图标的导出名称如Edit、Share作为组件名注册到应用实例上。全局注册后模板中可直接书写Edit /这样的图标标签。⚠️ 一个重要的坑HTML 标准中已经预定义了名为menu的标签MDN 参考因此如果你直接注册Menu图标渲染时会被浏览器解释为原生menu元素而无法生效。必须使用别名注册才能正确渲染该图标。这种全量注册方式的优点是无需逐个导入缺点是会将全部图标打进首屏包体如果追求极致体积可结合下面的按需引入方式。按需引入推荐与全量注册不同按需引入只需在使用的组件中显式导入需要的图标script setup import { Edit, Share, Delete, Search, Loading } from element-plus/icons-vue /scriptVue 3 的script setup语法会自动将导入的组件暴露给模板使用因此无需任何手动注册即可直接书写Edit /。这也是 Element Plus 官方文档示例中采用的方式配合构建工具的 Tree-Shaking只有被实际引用的图标才会被打进产物。浏览器直接引入CDN不使用打包工具时可以通过 HTML 标签直接引入 Element Plus Icons加载后全局变量为ElementPlusIconsVuescript src//unpkg.com/element-plus/icons-vue/scriptscript src//cdn.jsdelivr.net/npm/element-plus/icons-vue/script不同的 CDN 提供方引入方式略有差异这里以 unpkg 和 jsDelivr 为例你也可以使用其他 CDN 提供商。版本锁定建议官方建议 CDN 用户在链接地址上锁定版本号以免未来 Element Plus 升级时受到不兼容更新的影响。锁定版本的方法请查阅 unpkg 官网说明。同时注意上文的import * as ElementPlusIconsVue行在使用 CDN 时需删除。自动导入unplugin 方案对于追求零手动导入的工程化场景可使用 unplugin-icons 与 unplugin-auto-import 自动导入任意 Iconify 图标集合。unplugin-icons 负责将图标按需编译为组件unplugin-auto-import 负责自动解析并注入导入语句二者配合可在模板中直接使用图标而无需手动import官方还提供了对应的工程化最佳实践模板见文档中的 vite.config.ts 配置示例。Simple Usage基本用法图标组件本身是纯 SVG 组件默认不携带任何尺寸、颜色等属性若希望图标从父级继承样式属性最常用的方式是把 SVG 图标放进el-icon容器中!-- Use el-icon to provide attributes to SVG icon -- template div el-icon :sizesize :colorcolor Edit / /el-icon !-- Or use it independently without derive attributes from parent -- Edit / /div /template将图标包裹在el-icon内时el-icon的size与color会作用于内部 SVG直接在模板中使用Edit /时图标不继承父级任何属性需要自行提供。Combined with el-icon结合 el-icon 使用el-icon为原始 SVG 图标提供了额外的属性能力并附带一套开箱即用的样式template p with extra class bis-loading/b, your icon is able to rotate 360 deg in 2 seconds, you can also override this /p el-icon :size20 Edit / /el-icon el-icon color#409efc classno-inherit Share / /el-icon el-icon Delete / /el-icon el-icon classis-loading Loading / /el-icon el-button typeprimary el-icon stylevertical-align: middle Search / /el-icon span stylevertical-align: middle Search /span /el-button /template示例中的关键用法:size20以数字形式指定图标尺寸内部会换算为font-size并作用于 SVGcolor#409efc直接指定 SVG 的填充色classis-loading附加该 class 后图标可在2 秒内旋转 360 度即旋转动画你可以在项目中覆写此样式图标与按钮组合将el-icon放进el-button配合vertical-align: middle实现图文垂直居中的常见场景。实现原理从源码看 el-icon 的渲染el-icon组件的核心实现非常精简见 icon.vuetemplate i :classns.b() :stylestyle v-bind$attrs slot / /i /template script langts setup import { computed } from vue import { addUnit } from element-plus/utils import { useNamespace } from element-plus/hooks defineOptions({ name: ElIcon, inheritAttrs: false, }) const props definePropsIconProps() const ns useNamespace(icon) const style computedCSSProperties(() { const { size, color } props const fontSize addUnit(size) if (!fontSize !color) return {} return { fontSize, --color: color, } }) /script从中可以提炼出几个关键实现细节渲染容器最终渲染为一个i元素class 为命名空间生成的el-icon由useNamespace(icon)提供SVG 图标通过默认插槽注入size 的换算size属性经addUnit工具函数统一附加单位。查看 style.ts 中addUnit(value, defaultUnit px)的实现可知传入数字时默认追加px单位因此:size20最终表现为font-size: 20pxcolor 的传递color被写入 CSS 自定义属性--color。由于el-icon内部 SVG 的填充色默认继承currentColor即继承字体颜色通过 CSS 变量与继承链共同作用即可让内部图标跟随el-icon的color值零配置时不产生多余样式当既没有size也没有color时style计算返回空对象不会污染 DOM。该实现被单元测试 icon.test.tsx 直接验证test(render, () { const wrapper mount(() Icon color#000000 size{18} /) expect(wrapper.element.getAttribute(style)).toContain(--color: #000000) expect(wrapper.element.getAttribute(style)).toContain(font-size: 18px) })测试断言表明传入size{18}与color#000000后元素 style 中确实分别出现了font-size: 18px与--color: #000000与 icon.ts 中声明的IconPropssize?: number | string、color?: string完全对应。此外组件通过 index.ts 中的withInstall(Icon)被包装为可安装的插件组件ElIcon因此既支持el-icon标签形式也支持app.use/app.component全局注册。Using SVG icon directly直接使用 SVG 图标如果不想引入el-icon容器也可以直接使用 SVG 图标组件但此时图标默认不携带任何属性需要自行提供宽高与间距template div stylefont-size: 20px !-- Since svg icons do not carry any attributes by default -- !-- You need to provide attributes directly -- Edit stylewidth: 1em; height: 1em; margin-right: 8px / Share stylewidth: 1em; height: 1em; margin-right: 8px / Delete stylewidth: 1em; height: 1em; margin-right: 8px / Search stylewidth: 1em; height: 1em; margin-right: 8px / /div /template这里直接通过style设置width: 1em; height: 1em使图标尺寸跟随外层容器的font-size: 20px1em 20px并用margin-right控制图标间距。这种写法适合对图标有精细控制、不想引入额外容器的场景。Icon Collection图标集合{#icon-collection}Element Plus 提供了一份可视化的图标集合页面IconList组件渲染于文档站点你可以在其中浏览全部内置图标。任意版本可用只要安装了element-plus/icons-vueSVG 图标即可在任何版本下使用点击即复制在图标集合页中点击任意图标即可复制方便快速插入到项目中。APIAttributesel-icon 属性NameDescriptionTypeDefaultcolorSVG tags fill attribute^[string]inherit from colorsizeSVG icon size, size x size^[number] / ^[string]inherit from font sizecolorSVG 标签的 fill 填充色类型为string默认继承当前颜色inherit from colorsize图标尺寸宽高相等size x size类型为number或string默认继承字体大小inherit from font size。由于实现上是通过font-size驱动 SVG 尺寸所以传入字符串时也支持20px、1.5em等任意 CSS 长度写法。Slotsel-icon 插槽NameDescriptiondefaultCustomize default contentdefault插槽用于放置自定义内容。默认情况下这里放入的是某个 SVG 图标组件你也可以放入任意自定义内容配合el-icon的尺寸/颜色继承机制实现统一的图标化渲染。总结Element Plus 的图标体系由独立包element-plus/icons-vue提供配合轻量容器组件el-icon使用。接入方式覆盖全量注册、按需引入、CDN 直引与 unplugin 自动导入四种场景el-icon仅有两个属性size、color与一个默认插槽内部通过addUnit换算font-size、通过 CSS 变量--color传递填充色整体实现轻巧且可测试。实战中建议正式项目优先使用按需引入或 unplugin 自动导入以控制包体CDN 场景务必锁定版本号若遇到Menu等与 HTML 原生标签冲突的图标记得使用别名注册。【免费下载链接】element-plus A Vue.js 3 UI Library made by Element team项目地址: https://gitcode.com/GitHub_Trending/el/element-plus创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考