Tag 使用手册

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

组件介绍

以可交互标签表达标记、筛选条件或路径片段，适合组织内容与收敛选择范围。

使用选择

用于带边界的标签内容及公开的关闭操作。关闭和选中是不同语义；需要独立按钮或选择控件时使用对应组件。

• closable 显示关闭操作，onClose 通知页面移除数据；关闭不会替页面修改列表。

• variant、shape 和 toggle 分别控制外观、形状与切换能力；parts 仅配置默认关闭按钮。

• 内置关闭按钮名称随LocaleProvider更新，可用Provider messages覆盖；标签内容与关闭后移除责任仍由调用方负责。

快速开始

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

<script lang="ts">	import { Tag, Button, Frame, ScrollArea } from '@snowui-design-system/components';</script> <ScrollArea axis="horizontal" horizontalTrackPosition="viewport" style="max-width: 100%;"><Frame singleLine gap={3} width="max-content" minWidth="100%" class="justify-center">	<Tag toggle>Design</Tag>	<Tag toggle>Engineering</Tag>	<Tag toggle>Product</Tag></Frame></ScrollArea>

API

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

使用边界与详细说明

设计形态

设计稿中的 Tag 形态统一收敛为以下能力组合：

设计稿中的左侧 Dot 仅作组合展示，Tag 不内置 leading Icon；X 由 closable 内置提供。设计稿内 X 与文字紧贴，组件默认 gap=0，外部覆盖 --snowui-tag-gap 或传 gap 时会同步影响 Icon、文字与 X 的间距。

与 Chip / Badge 的区分

组件特有属性 (Component-Specific Props)

不提供 size 属性：设计稿只有单一尺寸。

关键字 (Keyword)

布局模型

主布局模型：内联外壳布局（与 Button 一致）。定义见 ../../../specs/maintainers/LayoutProtocol.md §12.4（源码参考：specs/maintainers/LayoutProtocol.md）。

• 子元素通过 gap 自然排列；外部覆盖 --snowui-tag-gap 或传 gap 即可同步影响所有子元素间距（包括内置 X 与文字、外部 Icon 与文字）。

• 不内置 leading Icon；需要 Dot 由消费方显式传入 <Icon as="leading">。

• 删除 X 由 closable={true} 自动渲染在末尾；视觉与 hover 复用 Button bare emphasis="muted"（默认图标为 Components 自有语义 close，其包内形状快照来源为 close-regular.svg）；默认 width: 0、min-width: 0 不占位，hover Tag 时显形，hover X 自身时透明度提升到 1。激活态下 X 颜色源切到 Brand：未 hover X 时 40%，hover X 时 100%。

• 边距按元素类型决定（与 Figma 对齐）：文字与边的间距 8px、Icon / X 与边的间距 4px。组件通过 MutationObserver 检测真实首/末位节点（包含文本节点），按节点类型写到 data-edge-left / data-edge-right（"icon" / "text"），CSS [data-edge-*="icon"] 把对应侧 padding 从 8px 收紧到 4px。纯 CSS :first-child / :last-child 只看元素节点，无法识别"末位文字"的情况，因此走 JS。closable 的 X 不计入边距检测（X 由 [data-closable]:hover 单独管理右 padding）。

• 箭头形状（left-arrow / right-arrow）由内部 SVG 背景路径实现，不进入子元素布局；组件用 ResizeObserver 获取当前宽高并生成完整外轮廓，所有拐点都通过二次贝塞尔圆角化，尽量复原 Workshop node-id=11951-40471。

无障碍 (Accessibility)

与 Button 一致，自动输出 aria-pressed：

• 当 variant="active"（映射到 currentState="Active"）或通过 toggle / Click={{ Idle: "Active", Active: "Idle" }} 切到 Active 时，根节点输出 aria-pressed="true"；处于 Idle 时输出 aria-pressed="false"。

• 消费方显式传入 aria-pressed 或 aria-selected 时外部值优先，用于列表选择语境改用 aria-selected。

• 删除 X 渲染为真实 button type="button"，内置名称随LocaleProvider更新（默认简中“关闭标签”、英文“Close tag”），键盘可达。

• 删除 X 点击时组件内部会 stopPropagation()，避免误触 Tag 根节点的 onclick；移除逻辑仍由消费方在 onClose 中决定。

布局变量链

用法示例

 <Tag>Label</Tag>  <Tag closable onClose={() => remove('foo')}>Label</Tag>  <Tag>    <Icon as="leading"><DotCircle Weight="fill" /></Icon>    Label</Tag>  <Tag variant="active" closable>    <Icon as="leading"><DotCircle Weight="fill" /></Icon>    Filtered</Tag>  <Tag toggle>Filter</Tag>  <Tag closable style="--snowui-tag-gap: 4px;">    <Icon as="leading"><DotCircle Weight="fill" /></Icon>    Label</Tag>  <Tag shape="right-arrow">Home</Tag><Tag shape="left-arrow">Settings</Tag>  <Tag shape="right-arrow" closable>Filters</Tag>  <Tag whileClick={false} Click={{ Idle: "Active", Active: "Idle" }}>    Label</Tag>  <Tag aria-selected={isSelected} variant={isSelected ? "active" : "default"}>    Label</Tag>