图标 icon

通用组件。三层同源：无头内核给出解剖与状态机，Vue 组件与自定义元素只是它的两层外壳，行为完全一致。

示例

基础用法

传的是图标记录本身而不是名字：名字要运行期查表，查表就得把整张表静态引进来，摇树全废

已完成

<script setup lang="ts">
import { XhIcon } from "@xihan-ui/vue";

// 图标记录是纯数据：坐标系、打在根 svg 上的呈现属性、图元树
const CheckIcon = {
  name: "check",
  viewBox: "0 0 24 24",
  attrs: {
    "fill": "none",
    "stroke": "currentColor",
    "stroke-width": "2",
    "stroke-linecap": "round",
    "stroke-linejoin": "round",
  },
  nodes: [{ tag: "path", attrs: { d: "M4 12.5L9.5 18L20 6" } }],
} as const;

const SearchIcon = {
  name: "search",
  viewBox: "0 0 24 24",
  attrs: {
    "fill": "none",
    "stroke": "currentColor",
    "stroke-width": "2",
    "stroke-linecap": "round",
    "stroke-linejoin": "round",
  },
  nodes: [
    { tag: "circle", attrs: { cx: "10.5", cy: "10.5", r: "6.5" } },
    { tag: "path", attrs: { d: "M15.5 15.5L20.5 20.5" } },
  ],
} as const;

const StarIcon = {
  name: "star",
  viewBox: "0 0 24 24",
  attrs: {
    "fill": "none",
    "stroke": "currentColor",
    "stroke-width": "2",
    "stroke-linecap": "round",
    "stroke-linejoin": "round",
  },
  nodes: [
    {
      tag: "path",
      attrs: {
        d: "M12 3.5L14.12 9.59L20.56 9.72L15.42 13.61L17.29 19.78L12 16.1L6.71 19.78L8.58 13.61L3.44 9.72L9.88 9.59Z",
      },
    },
  ],
} as const;
</script>

<template>
  <XhIcon :icon="CheckIcon" />
  <XhIcon :icon="SearchIcon" />
  <XhIcon :icon="StarIcon" />
  <!-- 记录里的 stroke 取 currentColor，配色随上下文的文字色流下来 -->
  <span style="display: inline-flex; align-items: center; gap: 6px; color: #16a34a;">
    <XhIcon :icon="CheckIcon" />已完成
  </span>
</template>

尺寸与描边

size 三档改直径、weight 三档改 stroke-width；缺省档不落 data-* 属性，皮肤的基础规则就是缺省档

sm / md（缺省）/ lglight / regular（缺省）/ bold

<script setup lang="ts">
import { XhIcon } from "@xihan-ui/vue";

const StarIcon = {
  name: "star",
  viewBox: "0 0 24 24",
  attrs: {
    "fill": "none",
    "stroke": "currentColor",
    "stroke-width": "2",
    "stroke-linecap": "round",
    "stroke-linejoin": "round",
  },
  nodes: [
    {
      tag: "path",
      attrs: {
        d: "M12 3.5L14.12 9.59L20.56 9.72L15.42 13.61L17.29 19.78L12 16.1L6.71 19.78L8.58 13.61L3.44 9.72L9.88 9.59Z",
      },
    },
  ],
} as const;
</script>

<template>
  <span style="display: inline-flex; align-items: center; gap: 10px;">
    <XhIcon :icon="StarIcon" size="sm" />
    <XhIcon :icon="StarIcon" />
    <XhIcon :icon="StarIcon" size="lg" />
    <span style="font-size: 13px;">sm / md（缺省）/ lg</span>
  </span>

  <span style="display: inline-flex; align-items: center; gap: 10px;">
    <XhIcon :icon="StarIcon" size="lg" weight="light" />
    <XhIcon :icon="StarIcon" size="lg" />
    <XhIcon :icon="StarIcon" size="lg" weight="bold" />
    <span style="font-size: 13px;">light / regular（缺省）/ bold</span>
  </span>
</template>

可及名字

命名只有两态：给了非空白 label 就是 role="img" + aria-label，没给就是 aria-hidden="true" 的装饰件

新建 这枚没有可见文字，名字只能由 label 给

<script setup lang="ts">
import { XhIcon } from "@xihan-ui/vue";

const PlusIcon = {
  name: "plus",
  viewBox: "0 0 24 24",
  attrs: {
    "fill": "none",
    "stroke": "currentColor",
    "stroke-width": "2",
    "stroke-linecap": "round",
    "stroke-linejoin": "round",
  },
  nodes: [
    { tag: "path", attrs: { d: "M12 5V19" } },
    { tag: "path", attrs: { d: "M5 12H19" } },
  ],
} as const;

const XIcon = {
  name: "x",
  viewBox: "0 0 24 24",
  attrs: {
    "fill": "none",
    "stroke": "currentColor",
    "stroke-width": "2",
    "stroke-linecap": "round",
    "stroke-linejoin": "round",
  },
  nodes: [
    { tag: "path", attrs: { d: "M6 6L18 18" } },
    { tag: "path", attrs: { d: "M18 6L6 18" } },
  ],
} as const;
</script>

<template>
  <!-- 旁边已经有文字说这件事，图标不给 label，读屏不会把「加号 新建」念两遍 -->
  <span style="display: inline-flex; align-items: center; gap: 6px;">
    <XhIcon :icon="PlusIcon" />新建
  </span>

  <!-- 图标是这里唯一说出「关闭」的东西，必须给 label -->
  <span style="display: inline-flex; align-items: center; gap: 6px;">
    <XhIcon :icon="XIcon" label="关闭" />
    <span style="font-size: 13px;">这枚没有可见文字，名字只能由 label 给</span>
  </span>
</template>

自定义图元

默认插槽给出内容时改由插槽填充根 svg，元素不再生成 glyph 空壳；坐标系此时由自己写的 viewBox 定

<script setup lang="ts">
import { XhIcon } from "@xihan-ui/vue";
</script>

<template>
  <!-- 不传 icon，几何自己写：适合一次性的品牌标记、渐变填充这类不进图标集的图形 -->
  <XhIcon viewBox="0 0 24 24" size="lg" label="曦寒标记">
    <circle cx="12" cy="12" r="9" fill="none" stroke="currentColor" stroke-width="2" />
    <path
      d="M8 8L16 16M16 8L8 16"
      fill="none"
      stroke="currentColor"
      stroke-width="2"
      stroke-linecap="round"
    />
  </XhIcon>

  <XhIcon viewBox="0 0 24 24" size="lg" label="半满进度">
    <rect x="3" y="9" width="18" height="6" rx="3" fill="none" stroke="currentColor" stroke-width="2" />
    <rect x="5" y="11" width="7" height="2" rx="1" fill="currentColor" />
  </XhIcon>
</template>

语气

图标没有底色，语气只落在前景上，取普通背景上表达该语气的那档文字色

brandneutralsuccesswarningdangerinfo

<script setup lang="ts">
import { XhIcon } from "@xihan-ui/vue";

const StarIcon = {
  name: "star",
  viewBox: "0 0 24 24",
  attrs: {
    "fill": "none",
    "stroke": "currentColor",
    "stroke-width": "2",
    "stroke-linecap": "round",
    "stroke-linejoin": "round",
  },
  nodes: [
    {
      tag: "path",
      attrs: {
        d: "M12 3.5L14.12 9.59L20.56 9.72L15.42 13.61L17.29 19.78L12 16.1L6.71 19.78L8.58 13.61L3.44 9.72L9.88 9.59Z",
      },
    },
  ],
} as const;

const tones = ["brand", "neutral", "success", "warning", "danger", "info"] as const;
</script>

<template>
  <!-- 同一枚图标只换语气：旁边的文字不带语气，对照得出改的只是图标前景 -->
  <span
    v-for="t in tones"
    :key="t"
    style="display: inline-flex; align-items: center; gap: 6px"
  >
    <XhIcon :icon="StarIcon" :tone="t" size="lg" />
    <span style="font-size: 13px">{{ t }}</span>
  </span>
</template>

前景分级

图标没有底色，前景是一个组件令牌；跟正文取同一族文字色，图标就跟着排出主次

正文次要更次要不可用

<script setup lang="ts">
import { XhIcon } from "@xihan-ui/vue";

const InfoIcon = {
  name: "info",
  viewBox: "0 0 24 24",
  attrs: {
    "fill": "none",
    "stroke": "currentColor",
    "stroke-width": "2",
    "stroke-linecap": "round",
    "stroke-linejoin": "round",
  },
  nodes: [
    { tag: "circle", attrs: { cx: "12", cy: "12", r: "9" } },
    { tag: "path", attrs: { d: "M12 11V16.5" } },
    { tag: "path", attrs: { d: "M12 7.5V8" } },
  ],
} as const;

// 前景取普通背景上的四档文字色，从正文一路淡到不可用
const depths = [
  { fg: "var(--xh-fg-default)", label: "正文" },
  { fg: "var(--xh-fg-muted)", label: "次要" },
  { fg: "var(--xh-fg-subtle)", label: "更次要" },
  { fg: "var(--xh-fg-disabled)", label: "不可用" },
];
</script>

<template>
  <span
    v-for="d in depths"
    :key="d.label"
    :style="{ display: 'inline-flex', alignItems: 'center', gap: '6px', color: d.fg }"
  >
    <XhIcon :icon="InfoIcon" size="lg" :style="{ '--xh-icon-fg': d.fg }" />
    <span style="font-size: 13px">{{ d.label }}</span>
  </span>
</template>

产物

层	值
自定义元素	<xh-icon>
Vue 组件	XhIcon
组合式函数	useIcon
状态机	无，connect 直接由 props 算属性
皮肤	@xihan-ui/styles/icon.css

解剖

部件名即 data-part 属性值，也是皮肤的选择器。加粗的是必备部件，不渲染它组件不工作（Web Components 适配器会在诊断通道上报 wc.missing-part）。

data-scope="icon"：root · glyph

Props

属性	类型	必填	说明
icon	IconRecord		要画的图标。传的是记录本身而不是名字： 名字要走运行期查表，查表就必须把全表静态引进来，摇树全废。
label	string		可及名字。 给了非空白文本 = 这个图标是页面上唯一说出这件事的东西，输出 role="img" + aria-label； 缺席或全空白 = 装饰，输出 aria-hidden="true"。没有第三种形态。
size	Size		直径档位，缺省 md；缺省档不输出 data-size。
tone	Tone		语气：brand / neutral / success / warning / danger / info，决定用哪族颜色
weight	IconWeight		描边粗细档位，缺省 regular；缺省档不输出 data-weight。

connect API

useIcon 产出的对象。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

无键盘交互（不接收焦点，或焦点行为完全由原生元素提供）。