🧩 Aria/样式分离 — Aria 层 Tag 负责 open/close 状态；STag 注入 tagVariants 类并提供默认关闭控件
🎨 8 种颜色 — ThemeColor 值（primary/destructive/success/warning/info/carbon/secondary/accent）
🖌️ 5 种变体 — solid/pure/outline/soft/ghost/raw，覆盖实心、描边与淡色等外观
📐 6 种尺寸 — 来自 ThemeSize 的 xs–2xl
🟦 2 种形状 — auto（圆角）与 rounded（胶囊）
❌ 可关闭 — closable 渲染由 v-model:open 驱动的关闭按钮；关闭控件为带本地化 aria-label 的真实 <button>（可键盘操作）
🌐 RTL 就绪 — 布局使用 inline-flex 与逻辑间距
♿ 无障碍友好 — 关闭按钮可聚焦、拥有可访问名称，默认态与可关闭态 axe-core 均零违规

组件家族

STag（样式层）— 入口包装组件；tagVariants 配方 + leading/trailing/close 插槽
Tag（Aria）— 状态基础组件；通过 useControllableState 维护 open，并通过插槽 props 暴露 close 动作

演示

基础

100%

Tag

插槽

100%

this is content

API

Aria 层

Tag

8 属性1 事件

属性

属性名	类型	默认值	描述
class	ClassValue	—	应用于根元素的额外类名。
color	ThemeColor	—	组件的主题颜色。
size	ThemeSize	—	组件的视觉尺寸。
variant	TagVariant	—	该组件的视觉变体。
shape	TagShape	—	组件的结构。
content	string	—	内容。
closable	boolean	—	该组件是否可以闭合。
open	boolean	—	该组件是否为开源。若提供该信息，则受控。

事件

事件名	参数	描述
update:open	boolean	在打开状态发生变化时触发。

注意事项

架构与对标差异

Aria 层 Tag 是最小的显隐/关闭状态基础组件，STag 将全部样式收敛到 tagVariants 配方，并提供默认关闭控件。这与 shadcn/ui 的 headless/样式分离一致；而 Ant Design、Element Plus、Mantine、Naive UI 则提供带 closable/onClose prop 的单一样式化标签。VeanUI 的关闭按钮是可聚焦的真实 <button>，其 aria-label 由 tag.remove（如 Remove {label}）本地化而来；多个对标库则依赖对屏幕阅读器不够健壮的纯 × 字形。

能力	VeanUI	shadcn/ui	Ant Design Tag	Element Plus Tag	Mantine Badge	Naive UI Tag
Aria/样式分离	✅	✅	—	—	—	—
颜色变体（8）	✅	✅	✅	✅	✅	✅
变体（solid/outline/soft）	✅	✅	✅	✅	✅	✅
尺寸变体（6）	✅	—	✅	✅	✅	✅
形状（auto / 胶囊）	✅	✅	✅	✅	✅	✅
可关闭标签	✅	—	✅	✅	—	✅
本地化关闭 `aria-label`	✅	—	—	✅	—	—
受控显隐（`open`）	✅	—	—	—	—	—
RTL 就绪	✅	✅	✅	—	—	✅

— = 不支持或采用不同交互模型。

运行时注意

关闭按钮的 aria-label 由本地化 tag.remove 模板基于 content prop 生成。若你通过 default 插槽而非 content 传入标签文本，默认关闭 aria-label 将回退为纯动词——请通过 close 插槽或 content prop 覆盖。
open 默认 true。使用 :open="false" 或 v-model:open 控制显隐。
variant="pure"/outline 会刻意用 foreground/border token 覆盖颜色前景色；soft/ghost 使用半透明色给背景着色。
关闭按钮继承标签文本颜色并使用透明背景/边框；在 soft 背景上依然可见，但请为你选择的颜色/背景组合验证对比度。
标签根节点为 <div>——若需要整块标签可点击，请自行在外层包裹链接或按钮。

Roadmap

核心标签 API 无阻塞缺口。独立的 tag-group 与 checkable 标签行为为已评估增强项，记录在 docs/roadmap/README.md。

FAQ

如何制作可关闭的标签？

设置 closable 并用 v-model 绑定 open：

<STag v-model:open="open" closable content="Linux" />

如何响应标签关闭？

监听 @update:open——点击关闭按钮时会发出 false：

<STag :open="open" closable content="Linux" @update:open="onClose" />

如何改变变体、形状与颜色？

使用 variant（solid/pure/outline/soft/ghost/raw）、shape（auto/rounded）与 color：

<STag variant="soft" shape="rounded" color="success" content="Active" />

如何在文本前后添加图标？

使用 leading / trailing 插槽：

<STag content="Status">
  <template #leading><SIcon icon="lucide:circle" /></template>
</STag>

如何自定义关闭按钮？

使用 close 插槽并从其 props 中读取 close 动作：

<STag v-model:open="open" closable content="Linux">
  <template #close="{ close }">
    <button type="button" aria-label="Dismiss" @click="close">×</button>
  </template>
</STag>

快速跳转

同分类组件

标签

概述

用法

特性