PatternsSemantic
Chip
@mox-hub/patterns 模式 · Semantic · canonical
chip@mox-hub/patternsSemanticcanonicalsrc/components/chip.tsx变体轴
tonedefaultdangerprimary
shapepillsoft
变体演示chip
标签可关闭soft
Props API
| Prop | 类型 | 默认值 | 说明 |
|---|---|---|---|
| tone* | ChipTone | "default" | — |
| shape* | ChipShape | "pill" | — |
| variant* | ChipVariant | "outline" | — |
| onClick* | () => void | — | — |
| onRemove* | () => void | — | — |
| disabled* | boolean | — | — |
| icon* | ReactNode | — | — |
| children* | ReactNode | — | — |
| labels* | Partial<{ remove: string; }> | — | — |
源码
import { X } from "lucide-react"
import type * as React from "react"
import { RawButton } from "@mox-hub/ui/components/raw/raw-button"
import { TONE_CLASS as TONE_VISUALS } from "@mox-hub/ui/components/tone"
import { cn } from "@mox-hub/ui"
import { usePatternLabels } from "../lib/i18n"
const CHIP_DEFAULT_LABELS = { remove: "移除" }
type ChipTone = "default" | "danger" | "primary" | "info" | "warning" | "success"
type ChipShape = "pill" | "soft"
type ChipVariant = "outline" | "status"
const OUTLINE_TONE_CLASS: Record<ChipTone, { base: string; remove: string }> = {
default: {
base: "border-border text-content-text-secondary hover:bg-muted hover:text-foreground",
remove: "hover:text-destructive",
},
danger: {
base: "border-border text-content-text-secondary hover:border-accent-red/40 hover:bg-accent-red-light hover:text-accent-red",
remove: "hover:text-destructive",
},
primary: {
base: "border-dashed border-border text-muted-foreground hover:border-primary hover:text-primary",
remove: "hover:text-destructive",
},
info: {
base: "border-border text-content-text-secondary hover:border-accent-blue/40 hover:bg-accent-blue-light hover:text-accent-blue",
remove: "hover:text-destructive",
},
warning: {
base: "border-border text-content-text-secondary hover:border-accent-yellow/40 hover:bg-accent-yellow-light hover:text-accent-yellow",
remove: "hover:text-destructive",
},
success: {
base: "border-border text-content-text-secondary hover:border-accent-green/40 hover:bg-accent-green-light hover:text-accent-green",
remove: "hover:text-destructive",
},
}
/** status 变体:静态状态胶囊,复用 tone 唯一词表的浅底槽。 */
const STATUS_TONE_CLASS: Record<ChipTone, string> = {
default: TONE_VISUALS.default.light,
danger: TONE_VISUALS.danger.light,
info: TONE_VISUALS.info.light,
warning: TONE_VISUALS.warning.light,
success: TONE_VISUALS.success.light,
// primary 不在 Tone 五档词表内,沿用 accent-purple 浅底(与 AI 标识一致)
primary: "bg-accent-purple-light text-accent-purple",
}
const SHAPE_CLASS: Record<ChipShape, string> = {
pill: "rounded-full px-2.5 py-1",
soft: "rounded-md px-2 py-0.5",
}
const CHIP_BASE =
"inline-flex min-w-0 max-w-full shrink-0 items-center gap-1 truncate border bg-background text-xs whitespace-nowrap transition-colors"
/**
* Chip —— 语义组件层首件(G 类批 G1;G5 裁决示范组件,自 stash 留档复活)
*
* 标签 / 胶囊 / 可关闭标签的唯一实现:可关闭标签、驳回原因 chips、过滤器 tag、
* 计数胶囊等形态的唯一真相源,业务面不再为标签形态裸写 button。
*
* **raw vs ui 边界判例一(G8 落点,后续语义组件照此裁断)**:
* - 「容器可点击」的展示件不是动作钮——可点击语义用 `RawButton` 承载(button 元素
* 可达性 + `type="button"` 防表单误提交),**刻意不用 `<Button>`**:chip 不参与
* §4.5 动作钮形态收敛,换 Button 会把它卷进 variant/size 轴。
* - 尾部 × 关闭钮同理走 `RawButton`(删除的是 chip 自身,非页面动作钮)。
* - 纯展示态(无 onClick 且无 onRemove)用 `span`。
*
* **props 面封闭(G8 裁决口径,本组件即首例)**:显式声明 props,不接 `className`
* (形态内聚,不留样式透传口子)、不透传 variant、不 extends HTMLAttributes。
* 复核记录:stash 原实现曾接 className,批 G1 复核时按 G8 摘除。
*
* 形态:
* - `shape="pill"`(默认)胶囊——动作 chips / 计数胶囊;`shape="soft"` 小圆角——标签 tag。
* - `variant="outline"`(默认)悬停语义色:`danger` 悬停转红(驳回原因 chips)、
* `primary` 悬停转主色(Add tag,dashed 虚线框)。
* - `variant="status"` 静态状态胶囊:复用 tone 五档浅底(default/info/warning/success/danger)
* + primary 的 AI 紫;用于替代已弃用的 `status-pill`。
*/
function Chip({
tone = "default",
shape = "pill",
variant = "outline",
onClick,
onRemove,
disabled,
icon,
children,
labels,
}: {
/** 语义色:outline 控制悬停色 / status 控制静态浅底色 */
tone?: ChipTone
/** pill 胶囊(动作 chips / 计数胶囊)| soft 小圆角(标签 tag) */
shape?: ChipShape
/** outline 可交互样式(默认)| status 静态状态胶囊 */
variant?: ChipVariant
/** 可点击语义(内部 RawButton 承载;不传且无 onRemove 时为 span 展示) */
onClick?: () => void
/** 传入则渲染尾部 × 关闭钮 */
onRemove?: () => void
disabled?: boolean
icon?: React.ReactNode
children?: React.ReactNode
labels?: Partial<typeof CHIP_DEFAULT_LABELS>
}) {
const D = usePatternLabels("chip", CHIP_DEFAULT_LABELS)
const outline = OUTLINE_TONE_CLASS[tone]
const toneClass =
variant === "status" ? STATUS_TONE_CLASS[tone] : outline.base
const interactive = Boolean(onClick)
const removeButton = onRemove ? (
<RawButton
aria-label={labels?.remove ?? D.remove}
disabled={disabled}
onClick={
interactive
? (e) => {
e.stopPropagation()
onRemove()
}
: onRemove
}
className={cn("ms-0.5 rounded-full transition-colors", outline.remove)}
>
<X className="size-2.5" />
</RawButton>
) : null
if (!interactive) {
return (
<span
className={cn(
CHIP_BASE,
SHAPE_CLASS[shape],
toneClass,
variant === "status"
? "border-transparent font-semibold"
: "font-normal",
disabled && "pointer-events-none opacity-40",
)}
>
{icon}
{children}
{removeButton}
</span>
)
}
return (
<RawButton
disabled={disabled}
onClick={onClick}
className={cn(
CHIP_BASE,
SHAPE_CLASS[shape],
toneClass,
variant === "status"
? "border-transparent font-semibold"
: "font-normal",
disabled && "pointer-events-none opacity-40",
)}
>
{icon}
{children}
{removeButton}
</RawButton>
)
}
export { Chip }
export type { ChipTone, ChipShape, ChipVariant }
可访问性与 RTL
- 键盘:交互件保留
:focus-visible焦点环;浮层支持 Escape 关闭与焦点归还,菜单 / 页签按 Base UI 约定支持方向键。 筛选菜单、拖拽排序、执行树与模型 listbox 等关键键盘流由 Playwright 断言覆盖,见规范示例 · 交互与可访问性。 - RTL:间距、对齐与方向性图标使用逻辑属性 (
ms-*/text-start/rtl:-scale-x-100);通过ThemeProvider或I18nProvider的direction="rtl"驱动,`lint:rtl` 会拦截新增物理类。 - 文案:优先用组件
labels/translate/translatorprops,其次用I18nProvider目录;内置 zh-CN 默认值,en-US 为参考翻译。见Theming · i18n 与 RTL。 - 对比度:高对比度 token、2px 控件边框与 3px 焦点环由主题层统一提供,见Foundations · Contrast。
用法说明
标签/胶囊/可关闭标签唯一实现:tone + shape 封闭轴;容器可点击语义用 RawButton,不用 Button。