Icon 使用手册

许可阅读：首次阅读组件文档、源码或 npm 使用流程，先读完整 LICENSE；同任务同版本去重。公开 API 配置与内部实现修改分别按许可处理；全部组件使用统一运行包，源码权益以许可为准。

组件介绍

展示 SVG 图标，并统一尺寸与颜色，适合按钮、导航和内容中的视觉标识。

使用选择

用于统一图标宿主与尺寸。优先复用 SnowUI 资源图标；有操作行为时放入 Button 并提供可访问名称，不把装饰图形误作功能图标。

• 优先提供资源图标；src 与解析后的 icon 均未命中时才渲染 children。

• size 可继承父级尺寸；角标使用 Badge as="badge"。交互名称应提供给拥有操作的按钮。

• Accordion 内的 Icon as="leading" 在未显式指定 size 时继承 Accordion 图标尺寸：sm/md/lg 分别为 16/20/24；未声明 leading 的 Icon 不参与这项继承，显式 size 优先。

快速开始

以下示例展示推荐的基本组合。更多场景与组合限制见后文。

<script lang="ts">	import { Icon } from '@snowui-design-system/components';	import { IconSet } from '@snowui-design-system/resource-svelte';	const sizes = [12, 16, 20, 24, 28, 32, 40, 48, 80] as const;</script> <div style="display: flex; flex-wrap: wrap; align-items: center; justify-content: center; gap: var(--gap-4) var(--gap-3); max-width: 100%;">{#each sizes as size}    <Icon icon={IconSet} {size} aria-label={`Component icon, size ${size}`} />{/each}</div>

API

未重新声明的继承能力请查所属基础组件文档；本表只列本组件源码具名公开属性。

使用边界与详细说明

布局模型

主布局模型：内禀原子布局。

• Icon 的根节点是由 size、background padding 与图标资源共同决定的内禀盒，作为其他布局子项时表现为 Hug。

• as="leading" / "trailing" / "icon" / "badge" / "prev" / "next" / "close" 只声明 Icon 在外部宿主中的角色；进入 Image / ImageViewer 宿主时会由宿主上下文翻译为对应 pin-* 方位。

• 背景、空占位、badge overlay 与图片资源渲染都是 Icon 私有结构，不对外承诺通用槽位。

• 外部需要图标加文字排列时，应由 Button、MenuItem、Frame 等宿主组件负责 gap / padding / alignment。

stateIcon 解析规则

1. Icon 读取最近父级 Frame Context 的 currentState。

2. 当前状态命中 stateIcon[currentState] 时使用该图标。

3. 未命中当前状态时回退 stateIcon.Idle。

4. 仍未解析出图标时回退现有 icon / src / children 渲染规则。

5. 状态值为 null 时隐藏 Icon,用于 Idle 无图标、Pending 显示 Spinner 这类稳定结构状态流。

6. stateIcon 只影响 Icon 自身展示,不修改父 Frame 状态。

Load 是 Frame loading / skeleton 协议状态名。若只是按钮任务处理中并需要展示真实 Spinner,优先使用 Pending。

使用示例

 <Icon src="/bell.svg" size={24} />  <Icon size={24}>    <Bell /></Icon>  <Icon background class="bg-black-4">    <Bell size={48} weight="duotone" /></Icon>  <Icon size={32} background class="bg-black-4">    <Badge as="badge" dot />    <Bell /></Icon>  <Button Click="Active" Active={["Idle", "auto"]} whileActive={{ duration: 2000 }}>    <Icon stateIcon={{ Idle: Paperclip, Active: Check }} />    <Text stateText={{ Idle: "复制", Active: "已复制" }} /></Button>  <Button    Click={{ Idle: "Pending", Active: "Idle" }}    Pending={["Active", "auto"]}>    <Icon stateIcon={{ Idle: null, Pending: Spinner, Active: Check }} />    <Text stateText={{ Idle: "Ready", Pending: "Loading...", Active: "Completed" }} /></Button>  <Avatar size={40}>    <Icon as="badge" background class="bg-blue text-white">        <Check />    </Icon></Avatar>

子组件上下文 (Context)

Icon 为子组件 (如 Badge 或 另一个 Icon) 提供自适应定位上下文：

• badgeStyle: 基于 em 的绝对定位样式，确保图标外缘角落对齐。

• badgeSize: 默认点状态尺寸 (0.25em)。

- size/weight: Icon 容器默认透传；子图标显式传入时覆盖（不推荐）。