Tag
tag给内容打上语义状态标签,可带图标和关闭按钮
用法
语气色
tone 覆盖语义状态光谱:neutral / brand / info / success / warning / danger。
默认处理中外接浏览器模式成功警告错误
tsx
<>
<Tag>默认</Tag>
<Tag tone="brand">处理中</Tag>
<Tag tone="info">外接浏览器模式</Tag>
<Tag tone="success">成功</Tag>
<Tag tone="warning">警告</Tag>
<Tag tone="danger">错误</Tag>
</>分类色
tone 管状态,color 管分类 —— 渠道、业务线、文件类型这类「属于哪一类」的着色常有十几二十种,语义六档接不住。color 走语义 token,自动吃明暗主题;也接受任意 CSS 颜色。
抖音小红书视频号哔哩哔哩快手知乎自定义色
tsx
<>
<Tag color="chart-1">抖音</Tag>
<Tag color="chart-2">小红书</Tag>
<Tag color="chart-3">视频号</Tag>
<Tag color="chart-4">哔哩哔哩</Tag>
<Tag color="chart-5">快手</Tag>
<Tag color="chart-6">知乎</Tag>
<Tag color="#ec4899">自定义色</Tag>
</>变体
variant 提供 soft(默认浅底)/ solid 实底 / outline 描边。
softsolidoutline
tsx
<>
<Tag variant="soft" tone="brand">soft</Tag>
<Tag variant="solid" tone="brand">solid</Tag>
<Tag variant="outline" tone="brand">outline</Tag>
</>状态圆点
dot 前导状态点;pulse 让点呼吸闪烁,表达进行态。
运行中部署中重试中
tsx
<>
<Tag dot tone="success">运行中</Tag>
<Tag dot pulse tone="brand">部署中</Tag>
<Tag dot pulse tone="warning">重试中</Tag>
</>带图标
icon 槽放前导图标(存在时不渲染 dot)。
已通过已驳回
tsx
<>
<Tag tone="success" icon={<CircleCheck />}>已通过</Tag>
<Tag tone="danger" icon={<CircleX />}>已驳回</Tag>
</>可关闭
传 onClose 渲染关闭按钮,点击触发回调由调用方移除标签。
可移除
tsx
<Tag tone="brand" onClose={() => remove(tag)}>
可移除
</Tag>药丸形 · 可点标签
shape="pill" 全圆;render 渲染成链接,补焦点环与悬停反馈 —— 版本号链到更新日志这类可点标签。
v0.44.012
tsx
<Tag variant="outline" size="sm" shape="pill" render={<a href="/changelog" />}>
v0.44.0
</Tag>何时用
表达对象状态/类别的小标记(运行中、待审核、已驳回等),支持状态圆点与呼吸动画表达进行态。展示数值/计数徽记用 [[Badge]];可输入/可移除的过滤令牌用 Chip,本组件偏只读状态标记。
导入
ts
import { Tag, tagVariants } from "@hulianui/ui"Props
| 名称 | 类型 | 默认 | 说明 |
|---|---|---|---|
| variant | "soft" | "solid" | "outline" | "soft" | 视觉变体:soft 浅底(最常用于状态标签)/ solid 实底 / outline 描边。三档各自的底与文字色见「三档配色」 |
| tone | "neutral" | "brand" | "info" | "success" | "warning" | "danger" | "neutral" | 语气色。取值集与 Alert 一致。 |
| color | string | - | 分类色:渠道 / 业务线 / 文件类型这类「属于哪一类」的着色(见下节「语义色 vs 分类色」)。语义色名(chart-2 / primary …)、任意 CSS 颜色或 var(--color-*) 都收,与 [[Dot]] 的 color / [[Brand]] 的 color 同一条路径。与 tone 同时传时 color 优先。 |
| size | "sm" | "md" | "md" | 尺寸。 |
| dot | boolean | false | 前导状态圆点(颜色随 tone)。与 icon 互斥:icon 优先于 dot。 |
| pulse | boolean | false | 圆点呼吸动画(进行态语义)。仅在 dot 为真时生效。 |
| isDisabled | boolean | false | 禁用:降透明度、屏蔽指针事件、关闭按钮不可点。 |
| shape | "rounded" | "pill" | "rounded" | rounded 小圆角;pill 全圆药丸(版本号、计数这类短标签)。 |
| render | ReactElement | - | 渲染成自定义元素(<a href> / 框架路由件):版本号指向更新日志、标签指向筛选页这类可点标签。皮肤合并进该元素并补焦点环与悬停反馈;与 Button / Link 的 render 约定一致。不要与 onClose 同用(链接里套按钮是无效嵌套)。 |
| className | string | - | - |
| …HTMLAttributes | HTMLAttributes<HTMLSpanElement> | - | 透传 span 原生属性。状态标签常用 title 挂完整值做 hover 全文(表格里显示「Word」、title 是完整 MIME),以及 data-testid / aria-* |
Events
| 事件 | 类型 | 说明 |
|---|---|---|
| onClose | () => void | 提供则渲染关闭(×)按钮,点击触发该回调。 |
Slots
| 插槽 | 类型 | 说明 |
|---|---|---|
| icon | ReactNode | 前导图标槽;存在时不渲染 dot。 |
| children | ReactNode | 标签文本。 |
三档配色
自己拼一块带语义色的高亮区(不是 Tag、不是 Alert)时照这张表配 —— 它就是本组件内部那份配方:
| 档 | 底 | 文字 |
|---|---|---|
| solid | bg-warning | text-warning-foreground |
| soft | bg-warning-subtle(或 bg-warning/12) | text-warning |
| outline | border-warning | text-warning |
-foreground 只配实心底:亮色下它就是白。浅底上按命名直觉写 text-warning-foreground 得到的是白字白底、文字整个看不见,而暗色下反而是对的(那边 -foreground 是近黑),谁在暗色主题里开发谁查不出来。浅底的文字色一律用语义色本身。
语义色 vs 分类色
tone是语义轴:六档状态色,全库共用同一套枚举,回答「它现在是什么状态」——成功 / 警告 / 错误 / 进行中 / 中性说明 / 与主操作有关。color是分类轴:回答「它属于哪一类」,与状态无关。渠道、业务线、文件类型、标签体系常有十几二十种,语义色接不住;硬映射只会让「成功」和「渠道 A」共用一个绿,读的人再从颜色反推含义就会错。- 两者同时传时
color优先(tone是语义快捷方式)。分类色同样吃明暗主题:soft 是 12% 混合底、outline 是描边、solid 是实底,不必为每个色再准备亮暗两套值。 - 极浅的分类色(例如
chart-3的琥珀)配solid时前景走primary-foreground,白字对比偏弱 —— 分类色优先用 soft / outline。
禁忌 / 坑
brand与info不是同一件事(#232)。brand是主色,意思是「这条和产品/主操作有关」;info走独立的 info 色,意思是「这是中性事实说明,读一下就好」。表达「当前处于什么模式」这类既不成功也不警告的事实,用info——用brand会让一个不可点的标签在页面里与主 CTA 抢注意力,用neutral则会和一堆灰标签糊在一起读不出来。两者在 tokens 0.8.0 补齐--color-info前确实是一个颜色(见 Alert 的同一段历史),现在不是了。color不是第六档语义色。要表达状态仍然用tone;把「成功」写成color="chart-2",暗色表里的绿就只是一段数据序列色,换主题时语义会漂。pulse只在dot为真时生效,单独传pulse无动画。icon与dot互斥,同传时只渲染icon——想要圆点就别传 icon。onClose列表场景需自行维护移除后的状态(受控数组 filter),组件本身不删元素。- 关闭按钮的无障碍标签跟随
ConfigProvider:zhCN为“移除”,enUS为 “Remove”。旧自定义 locale 缺少components.tag时回退中文。
相关
Sparkline · ImageViewer · LiveProductCard · DiffStat · ScoreRing · Badge
Playground
状态标签
<Tag dot>状态标签</Tag>