Tag 标签
用于分类、筛选、语义状态和可移除元数据的紧凑标签。
Tag 标签
Demo
标签
示例加载中...
可关闭
可关闭标签适用于可移除筛选项或用户自定义标签。
示例加载中...
图标与自定义色
示例加载中...
交互与禁用
示例加载中...
标签 + 按钮
示例加载中...
交互契约
- 根元素是静态元数据，不带 live region 角色；标签文案必须不依赖颜色也能表达含义。
label默认是空字符串；null会归一化为空字符串。- 默认插槽会替换
label内容，但保留图标和关闭按钮区域。 color默认是var(--tx-color-primary)；未传background与border时会基于color用color-mix派生。- 关闭控件是原生
button type="button"，带aria-label="Remove tag"。 - 点击关闭按钮会阻止冒泡，因此
close不会同时触发标签根部的click。 disabled会降低透明度、禁用关闭按钮，并阻断click与close事件。
API
Props
| 属性名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
label | string | null | '' | 未提供默认插槽时显示的文本。 |
icon | string | '' | 前置图标 class。 |
color | string | 'var(--tx-color-primary)' | 主文字/图标色，也作为派生背景和边框的基准色。 |
background | string | '' | 自定义背景色；默认使用 color 的半透明混合。 |
border | string | '' | 自定义边框色；默认使用 color 的半透明混合。 |
size | 'sm' | 'md' | 'sm' | 标签密度。 |
closable | boolean | false | 渲染关闭按钮。 |
disabled | boolean | false | 禁用标签点击与关闭交互。 |
pill | boolean | false | 使用全圆角胶囊外形（根节点加 .pill class）；用于筛选芯片等需要与方角标签在形状上区分的场景。 |
variant | 'outline' | 'soft' | 'plain' | 'outline' | 填充配方，见下表。 |
dot | string | - | 前置圆点颜色；不传则不渲染圆点。让标签在保持文字可读的同时携带分类色。 |
dotSize | number | 6 | 圆点直径（像素）。 |
count | number | - | 尾部计数徽标；传 0 会渲染，不传则不渲染。 |
三种 variant 的配方：
| 值 | 填充 | 发丝边 | 文字 | 适用 |
|---|---|---|---|---|
outline | 12% | 32% | 原色 | 默认，与既有标签完全一致 |
soft | 20% | 34% | 92% 原色混入墨色 | 彩色底上的 11px 小字更稳 |
plain | 中性填充 | 中性发丝边 | 次级墨色 | 忽略 color，用于 +3 这类溢出计数与不该抢眼的元信息 |
background / border 显式传值时仍然优先于任何 variant。
Events
| 事件名 | 参数 | 说明 |
|---|---|---|
click | MouseEvent | disabled=false 时点击标签根元素触发。 |
close | - | disabled=false 时点击关闭按钮触发。 |
Slots
| 插槽名 | Props | 说明 |
|---|---|---|
default | - | 替换标签内容区域中的 label 文本。 |
最佳实践
- 标签用于元数据和状态提示，不要替代主按钮。
label保持简短；长文本会破坏表格和筛选行的紧凑节奏。- 可移除筛选项、用户标签、临时范围使用
closable。 - 使用原始自定义颜色且对比度不足时，显式提供
background/border。 - 删除行为需要宿主确认；
TxTag只发出操作意图。
审阅说明
- 可访问性说明: 关闭控件是原生
button，但标签级click绑定在不可聚焦的span上。click只适合可选的指针交互；必须键盘可达的标签操作应改用按钮或复选模式。 - 实测覆盖:
tag.test.ts覆盖 label/icon/style 渲染、默认插槽覆盖、click 与 close 事件分离、禁用阻断，以及禁用关闭按钮状态。
Source
- Component source:
packages/tuffex/packages/components/src/tag/src/TxTag.vue。 - Types:
packages/tuffex/packages/components/src/tag/src/types.ts导出TagProps与TagEmits。 - Export alias:
packages/tuffex/packages/components/src/tag/index.ts导出Tag、TxTag、TagProps、TagEmits与TxTagInstance。 - Coverage:
packages/tuffex/packages/components/src/tag/__tests__/tag.test.ts覆盖渲染、插槽、事件与禁用行为。
查看源码
packages/tuffex/packages/components/src/tag/index.ts