icon图标(默认支持222个图标集的超过38万个图标, 也就是iconify) ​

Hidden Title ​

属性事件插槽简介 ​

Element Plus Icon Documentation

基础用法 ​

icon 也支持直接传入 Emoji 文本，例如 <s-icon icon="❌" />；source="auto" 下会按文本字形渲染，不会当作 Element Plus 图标名解析。

不同图标来源对比 ​

单个字符串会优先匹配 Element Plus 图标名，匹配不到时自动按 CSS class 处理。若名称存在歧义，可使用 source="css" 或 source="element-plus" 显式指定来源。

主题（theme 默认值：default） ​

切换主题查看不同类型和变体图标的颜色。基础用法：通过顶部选项切换主题。theme 可选值 default / chenghua / shijingshan / sybz / gulou，默认值 default。

Iconify 图标（ https://icon-sets.iconify.design/ ） ​

Iconify 汇集了大量开源图标集。使用 s-icon 时不需要单独安装 @iconify/vue，也不需要导入每一个图标组件，只要提供图标名称即可。

在编辑器中悬浮 s-icon 标签时，类型签名顶部的 Iconify图标查询 会显示 https://icon-sets.iconify.design/。这是类型提示中的查询入口，无需作为组件属性传入。

组件库默认推荐：Tabler Icons ​

sybz-components 默认推荐业务项目使用 Tabler Icons，图标名称统一以 tabler: 开头，例如：

<s-icon icon="tabler:layout-dashboard" />
<s-icon icon="tabler:user" />
<s-icon icon="tabler:settings" />
<s-icon icon="tabler:search" />
<s-icon icon="tabler:trash" />

<s-icon icon="tabler:layout-dashboard" />
<s-icon icon="tabler:user" />
<s-icon icon="tabler:settings" />
<s-icon icon="tabler:search" />
<s-icon icon="tabler:trash" />

Tabler 很适合后台管理系统：它以线性图标为主，线宽、圆角和视觉尺寸比较统一，覆盖菜单、表格操作、表单、文件、用户、权限、数据看板等常见后台场景。

项目使用时遵循以下约定：

• 新增业务功能图标时，优先从 tabler:* 中选择。
• 同一个页面不要混用 tabler:*、mdi:*、lucide:* 等多套线性图标。
• 企业或产品 Logo 可以使用 logos:*，这是品牌图标的例外情况。
• 项目已有 Element Plus 图标不要求立即替换；新增或统一改造时优先使用 Tabler。

这里的“默认推荐”是组件库的视觉规范，不会偷偷修改图标名称。仍然需要写完整的 tabler:图标名，这样代码中可以直接看出图标来源。

第一步：查找图标 ​

优先打开 Tabler Icons 图标集，搜索需要的图标并复制名称。例如首页图标的名称是 tabler:home。如果 Tabler 确实没有合适的图标，再到 Iconify Icon Sets 的全部图标集中搜索。

Iconify 名称由两部分组成，中间使用英文冒号连接：

tabler:home
│      └─ 图标名称：home
└──────── 图标集前缀：tabler（Tabler Icons）

tabler:home
│      └─ 图标名称：home
└──────── 图标集前缀：tabler（Tabler Icons）

后台项目常用名称包括 tabler:layout-dashboard、tabler:user、tabler:settings、tabler:search、tabler:edit 和 tabler:trash。

第二步：直接使用 ​

将复制的名称传给 icon。当名称包含 : 时，source="auto" 会自动识别为 Iconify 图标，因此通常不用手动设置 source：

<s-icon icon="tabler:home" />

<s-icon icon="tabler:home" />

第一次显示某个在线图标时，浏览器会从 Iconify API 获取图标数据并缓存。组件库只加载页面实际使用的图标，不会把整个图标库打包进项目。

修改大小、颜色和提示文字 ​

Iconify 图标与普通 s-icon 使用相同的 size、color、type、variant 和 tooltip 属性：

<s-icon icon="tabler:home" size="24" />
<s-icon icon="tabler:circle-check" type="success" size="28" />
<s-icon icon="tabler:alert-triangle" type="warning" variant="light" size="24" />
<s-icon icon="tabler:search" color="#165dff" content="搜索" placement="top" />

<s-icon icon="tabler:home" size="24" />
<s-icon icon="tabler:circle-check" type="success" size="28" />
<s-icon icon="tabler:alert-triangle" type="warning" variant="light" size="24" />
<s-icon icon="tabler:search" color="#165dff" content="搜索" placement="top" />

大部分线性、单色图标使用 currentColor，可以通过 color 或 type 改色。logos:vue 这类品牌图标自身包含多种颜色，通常不会跟随 color 改变。

什么时候需要 source="iconify" ​

默认的 source="auto" 已经能识别 tabler:home 这类带冒号的名称。只有希望明确限定图标来源，或者自定义名称无法被自动识别时，才需要显式设置：

<s-icon icon="tabler:search" source="iconify" />

<s-icon icon="tabler:search" source="iconify" />

source 的全部可选值为 auto / element-plus / iconify / svg / url，默认值为 auto。

透传 Iconify 专属属性 ​

通过 iconifyAttrs 可以把属性直接传给底层 Iconify Icon，例如翻转图标或监听加载完成：

<script setup lang="ts">
const handleLoad = () => {
  console.log('图标加载完成')
}
</script>

<template>
  <s-icon
    icon="tabler:login"
    :iconify-attrs="{
      flip: 'horizontal',
      onLoad: handleLoad,
    }"
  />
</template>

<script setup lang="ts">
const handleLoad = () => {
  console.log('图标加载完成')
}
</script>

<template>
  <s-icon
    icon="tabler:login"
    :iconify-attrs="{
      flip: 'horizontal',
      onLoad: handleLoad,
    }"
  />
</template>

内网或离线项目 ​

在线模式需要浏览器能够访问 Iconify API。如果项目运行在内网、离线环境，或者不希望运行时发送图标请求，可以提前注册图标数据。

注册单个图标时，从 sybz-components 导入 addIconifyIcon：

import { addIconifyIcon } from 'sybz-components'

addIconifyIcon('project:rocket', {
  width: 24,
  height: 24,
  body: '<path fill="currentColor" d="这里填写图标的 SVG path" />',
})

import { addIconifyIcon } from 'sybz-components'

addIconifyIcon('project:rocket', {
  width: 24,
  height: 24,
  body: '<path fill="currentColor" d="这里填写图标的 SVG path" />',
})

注册后使用方式与在线图标完全相同：

<s-icon icon="project:rocket" />

<s-icon icon="project:rocket" />

需要一次注册多个图标时，可以使用 addIconifyCollection：

import { addIconifyCollection } from 'sybz-components'

addIconifyCollection({
  prefix: 'project',
  width: 24,
  height: 24,
  icons: {
    home: {
      body: '<path fill="currentColor" d="这里填写 home 图标路径" />',
    },
    user: {
      body: '<path fill="currentColor" d="这里填写 user 图标路径" />',
    },
  },
})

import { addIconifyCollection } from 'sybz-components'

addIconifyCollection({
  prefix: 'project',
  width: 24,
  height: 24,
  icons: {
    home: {
      body: '<path fill="currentColor" d="这里填写 home 图标路径" />',
    },
    user: {
      body: '<path fill="currentColor" d="这里填写 user 图标路径" />',
    },
  },
})

之后分别通过 project:home 和 project:user 使用。建议在应用入口文件中统一注册，确保页面渲染前图标数据已经可用。

常见问题 ​

• 图标不显示：先检查名称是否包含英文冒号，并确认图标名称在 Iconify 网站中存在。
• 本地开发能显示、内网不能显示：通常是内网无法访问 Iconify API，应改用离线注册。
• 设置 color 没有效果：图标可能是 logos:* 这类自带颜色的品牌图标。
• 想使用普通 Element Plus 图标：直接写 <s-icon icon="delete" />，名称不含冒号时，source="auto" 会按 Element Plus 图标处理。

插槽 ​

旋转角度（rotate 默认值：''） ​

语义类型与背景样式（type 默认值：未设置，variant 默认值：plain） ​

常用图标查找 ​

所有图标 ​

鼠标指针（cursor 默认值：pointer） ​

背景圆角（borderRadius 默认值：8px） ​

阴影和 Hover 动画（shadow 默认值：never，hoverAnimation 默认值：false） ​

在线图片（source 默认值：auto） ​

容器宽高（width / height 默认值：未设置，size 默认值：16px） ​

基础写法：<s-icon icon="search" height="100%" />。width、height 支持数字、数字字符串和 CSS 长度（如 px / rem / em / % / calc()），数字自动补 px。只设置一边时另一边保持相等；同时设置两边时分别生效。未设置宽高时保留原有尺寸行为，size 控制内部图案大小，图案在容器中居中。

height="100%" 相对直接父容器计算，需要父容器有可解析的高度。示例让表单字段容器具有 40px 高度，输入框和图标都设置 height="100%"，图标自动成为 40 × 40 的正方形。父容器仅由内容撑高时，不能仅凭 100% 自动跟随整个表单高度。显式宽高包含背景内边距和边框。

鼠标移入高亮（highlight 默认值：false） ​

highlight 有两种高亮方式，保证警告色、错误色不会被换成主题色：

--s-icon-hover-color 默认取主题主色：Element Plus 下是 --el-color-primary，成华、石景山、sybz 会替换为各自的品牌主色，鼓楼主题取 --s-gl-primary。--s-icon-hover-filter 默认是 brightness(0.85)，觉得加深不够明显可以改成 brightness(0.75) 或 saturate(1.3) brightness(0.9)：

<s-icon icon="tabler:trash" highlight style="--s-icon-hover-color: var(--el-color-danger)" />
<s-icon icon="tabler:bell" type="warning" highlight style="--s-icon-hover-filter: saturate(1.3) brightness(0.9)" />

<s-icon icon="tabler:trash" highlight style="--s-icon-hover-color: var(--el-color-danger)" />
<s-icon icon="tabler:bell" type="warning" highlight style="--s-icon-hover-filter: saturate(1.3) brightness(0.9)" />

两种方式都只改线条，所以 highlight 可以和 hoverAnimation、shadow="hover" 随意组合，三个 Hover 效果互不覆盖；禁用状态（disabled）下不会触发。

属性 ​

事件 ​

说明 ​

• 组件底层使用 el-icon，tooltip 相关属性如 content、placement、effect 可直接透传。
• 在支持 Vue 模板类型提示的编辑器中，输入 icon 会提示 Element Plus 图标名；同时仍可传入 Vue 图标组件、小写、短横线、自定义 SVG 或 Iconify 名称。
• source="auto" 会先识别在线图片 URL，再按 图标集前缀:图标名称 格式识别 Iconify；完整用法见上方“Iconify 图标”和“在线图片”章节。