Icon 图标
用于显示矢量图标。
用法
显示一个图标
组件结构
加粗的是必需部件。
data-scope="icon"：root · glyph
示例
尺寸与描边
设置图标大小和描边粗细
可访问名称
为独立图标提供名称
自定义图形
直接提供 SVG 图形
颜色
使用语义颜色
旋转与翻转
改变图标方向
设计指引
何时使用
- 为操作、状态或条目提供图形标识。
- 作为独立信息使用时提供可访问名称。
何时不用
特性
- 直接接收可摇树优化的图标记录。
label区分信息图标与装饰图标。- 支持八档尺寸和三档描边粗细。
- 支持旋转与水平、垂直翻转。
- 颜色只作用于图标前景。
组合
最佳实践
- 图标旁已有同义文字时保持装饰状态。
- 同一操作区域使用一致的描边粗细。
反模式
- 不要为装饰图标重复提供名称。
- 不要只用图标表达不明确的状态。
API 参考
产物
| 层 | 值 |
|---|---|
| 自定义元素 | <xh-icon> |
| Vue 组件 | XhIcon |
| 组合式函数 | useIcon |
| 状态机 | 无，connect 直接由 props 算属性 |
| 皮肤 | @xihan-ui/styles/icon.css |
Props
| 属性 | 类型 | 必填 | 说明 |
|---|---|---|---|
flip | IconFlip | 翻转轴：horizontal / vertical / both，不翻转时不写。旋转与翻转同时提供时两者叠加。 | |
icon | IconRecord | 要绘制的图标。传入的是记录本身而不是名字： 名字需要运行期查表，查表就必须把全表静态引入，摇树完全失效。 | |
label | string | 可及名。 提供非空白文本 = 该图标是页面上唯一表达该信息的元素，输出 role="img" + aria-label； 缺席或全空白 = 装饰，输出 aria-hidden="true"。没有第三种形态。 | |
rotate | IconRotate | string | 旋转档位：90 / 180 / 270，不旋转时不写。 接受字符串是因为 WC 侧的档位来自 DOM 属性；不是这三档的值一律不写出。 | |
size | IconSize | 直径档位，默认 md；默认档不输出 data-size。 | |
tone | Tone | 颜色：brand / neutral / success / warning / danger / info。 | |
weight | IconWeight | 描边粗细档位，默认 regular；默认档不输出 data-weight。 |
connect API
getXxxProps() 返回对应部件的宿主属性。
| 成员 | 类型 | 说明 |
|---|---|---|
label | string | undefined | 解析后的可及名；装饰态为 undefined。 |
decorative | boolean | 是否装饰态（label 未提供或全空白）。 |
nodes | readonly IconNode[] | 要铺进 glyph 的图元树；未传 icon 时为空数组。 |
content | IconRecord | undefined | 当前铺设内容的身份。即 icon 本身：记录是模块级常量，引用相等即内容相等。 不用字符串签名：签名要遍历整棵树再拼串，每次 wire 都要付出一次。 |
getRootProps | () => T['element'] | |
getGlyphProps | () => T['element'] |
无障碍
键盘
规格出处：W3C APG
无键盘交互（不接收焦点，或焦点行为完全由原生元素提供）。
ARIA
以下属性由 connect 生成。
| 部件 | 属性 | 值 |
|---|---|---|
root | aria-hidden | 'true' | undefined |
root | aria-label | props.label | undefined |
root | role | undefined | 'img' |
样式参考
皮肤
@xihan-ui/styles/icon.css 使用 [data-scope="icon"][data-part="root"] 部件选择器，位于 xihan.components 层。覆盖样式使用 xihan.overrides。
数据属性
由 connect 生成；条件不成立时不输出无值属性。
| 部件 | 属性 | 值 |
|---|---|---|
root | data-flip | props.flip |
root | data-icon | icon?.name |
root | data-rotate | rotateAttr(props.rotate) |
root | data-size | props.size |
root | data-tone | props.tone |
root | data-weight | props.weight |
CSS 变量
本组件公开覆盖槽由独立皮肤的实际消费位生成；默认来源、作用部件和状态均与 CSS 同源。
| 变量 | 部件 | CSS 属性 | 状态 | 默认来源 | 说明 |
|---|---|---|---|---|---|
--xh-icon-fg | root | color | defaulttone | --xh-_tone-fgcurrentColor | icon 的 root 部件 color 覆盖槽。 |
--xh-icon-shift | root | vertical-align | default | --xh-glyph-baseline-shift | icon 的 root 部件 vertical-align 覆盖槽。 |
--xh-icon-size | autoplay-triggerbranch-indicatorbranch-triggercancel-triggercaps-lock-indicatorclear-triggerclose-triggercolumn-visibility-triggercontroldecrement-triggeredit-triggerellipsis-triggerexpand-triggerflip-horizontal-triggerflip-vertical-triggerincrement-triggerindicatoritemitem-checkboxitem-close-triggeritem-delete-triggeritem-indicatormove-down-triggermove-up-triggernext-triggernext-year-triggerprev-triggerprev-year-triggerrootrotate-left-triggerrotate-right-triggerrow-select-triggerscroll-to-end-triggerselect-all-triggerseparatorsort-triggersubmit-triggerto-source-triggerto-target-triggertrendtriggertrigger-indicatortruncationvisibility-triggerwindow-state-triggerzoom-in-triggerzoom-out-trigger | block-sizeinline-sizemargin-inline-start | @media (min-width: 640px)defaultdirectionemptyis([data-part='edit-trigger'], [data-part='submit-trigger'], [data-part='cancel-trigger'])mode=sendmode=stopnot([aria-busy='true'])size=2xlsize=3xlsize=4xlsize=lgsize=mdsize=smsize=textsize=xlsort=ascsort=descstate=checkedstate=completedstate=indeterminatestate=pausedstate=runningstate=visible | --xh-_color-swatch-picker-mark--xh-glyph-size-2xl--xh-glyph-size-3xl--xh-glyph-size-4xl--xh-glyph-size-lg--xh-glyph-size-md--xh-glyph-size-sm--xh-glyph-size-text--xh-glyph-size-xl | icon 的 autoplay-trigger、branch-indicator、branch-trigger、cancel-trigger、caps-lock-indicator、clear-trigger、close-trigger、column-visibility-trigger、control、decrement-trigger、edit-trigger、ellipsis-trigger、expand-trigger、flip-horizontal-trigger、flip-vertical-trigger、increment-trigger、indicator、item、item-checkbox、item-close-trigger、item-delete-trigger、item-indicator、move-down-trigger、move-up-trigger、next-trigger、next-year-trigger、prev-trigger、prev-year-trigger、root、rotate-left-trigger、rotate-right-trigger、row-select-trigger、scroll-to-end-trigger、select-all-trigger、separator、sort-trigger、submit-trigger、to-source-trigger、to-target-trigger、trend、trigger、trigger-indicator、truncation、visibility-trigger、window-state-trigger、zoom-in-trigger、zoom-out-trigger 部件 block-size、inline-size、margin-inline-start 覆盖槽。 |
--xh-icon-stroke | root | stroke-width | defaultweight=boldweight=light | --xh-glyph-stroke-bold--xh-glyph-stroke-light--xh-glyph-stroke-regular | icon 的 root 部件 stroke-width 覆盖槽。 |
动效
本组件皮肤不含过渡与关键帧，也没有脚本驱动的动效：状态一变，外观立即到位。