Chip 标签Chip · ChipGroup
两种用途:可选中的标签用来筛选(多选或单选,立即生效);可移除的标签用来展示已添加的条目。只是展示状态、不可交互的小标记请用 Badge。
可选中
传了 selected / defaultSelected / onChange 之一,Chip 就渲染成可按下的按钮,选中时“长出”对勾。
标签组
ChipGroup 负责换行排布,并用一个数组管理选中项。默认多选;multiple={false} 时选中一个会取消其它。
多选(受控)
筛选条件:open
单选与整组禁用
可移除
传 onRemove 就显示移除按钮。点击后标签先缩小淡出,再调用 onRemove;放在 ChipGroup 里时其余标签会滑过去补位。
设计前端无障碍动效设计系统
静态与禁用
什么交互属性都不传时只是一个静态标签。
只读标签带图标不可移除
规格
- 筛选
- 对勾宽度 0 → 14 · 弹簧
- 移除
- 140ms 缩小淡出 → 其余 FLIP 补位
- 叉号
- 悬停只变底色,不旋转
API
Chip
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
value | string | — | 在 ChipGroup 里标识这一项。 |
selected | boolean | — | 是否选中(受控)。 |
defaultSelected | boolean | — | 初始是否选中(非受控)。传了它(哪怕是 false)就变成可选中。 |
onChange | (selected: boolean) => void | — | 选中状态变化时触发。 |
onRemove | () => void | — | 传了就显示移除按钮;退场动画播完后调用。 |
removeLabel | string | '移除' | 移除按钮的可读名称;children 是字符串时会拼成“移除 xxx”。 |
icon | ReactNode | — | 文字前的图标。 |
disabled | boolean | — | 禁用。 |
ChipGroup
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
value | string[] | — | 选中项的 value 列表(受控)。传了 value / defaultValue / onChange 之一,组内带 value 的 Chip 就变成可选中。 |
defaultValue | string[] | — | 初始选中项(非受控)。 |
onChange | (value: string[]) => void | — | 选中项变化时触发。单选时数组里最多一个。 |
multiple | boolean | true | 是否可多选。 |
disabled | boolean | — | 整组禁用。 |
无障碍
- 可选中的 Chip 是
<button aria-pressed>,Enter / Space 切换,读屏读“已按下 / 未按下”。选中除了底色还有对勾。 - 可移除的 Chip 本身是静态文字,里面的移除按钮才可聚焦,名称是“移除 + 标签文字”。
- ChipGroup 是
role="group",每个 Chip 各自是 Tab 停靠点;请给组aria-label或放进带 label 的 Field。 - 移除一项后焦点会随被删的按钮一起消失,必要时请自己把焦点移到相邻的标签或输入框上。