MultiSelect 多选选择器
从一列选项里选多个,平时只占一行。选项不多且值得全部摆出来时用 CheckboxGroup 或可选中的 Chip。
基本用法
和 Select 用同一种 options。点选后列表不收起,可以连续勾选;点外面、按 Esc 或 Tab 收起。触发框里默认把已选项显示成小标签,超过 2 个折成 +N。
触发框里怎么显示
display="count" 只显示“已选 N 项”;maxChips 调整最多显示几个小标签;renderValue 完全自定义。
分组、尺寸与状态
受控用法
value 是选中值的数组,顺序就是点选的顺序。
value:[design, a11y]
配合 Field 与表单
传 name 时每个选中值渲染一个同名的隐藏 input。接入 Field 的方式和 Select 相同。
可以选多个
API
属性
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
options* | Array<SelectOption | { label: string; options: SelectOption[] }> | — | 选项;可以混入分组。SelectOption 的字段见 Select。 |
value | string[] | — | 选中的值(受控)。 |
defaultValue | string[] | [] | 初始选中的值(非受控)。 |
onChange | (value: string[]) => void | — | 选中项变化时触发。 |
display | 'chips' | 'count' | 'chips' | 触发框里显示小标签,或“已选 N 项”。 |
maxChips | number | 2 | chips 模式最多显示几个,其余折成 +N。 |
renderValue | (selected: SelectOption[]) => ReactNode | — | 自定义触发框里的内容。 |
placeholder | ReactNode | '请选择' | 没选时显示的文字。 |
size | 'sm' | 'md' | 'lg' | 'md' | 尺寸。 |
disabled / invalid | boolean | — | 禁用 / 校验未通过。 |
name / form | string | — | 配合表单:每个选中值一个同名隐藏 input。 |
open / defaultOpen / onOpenChange | boolean / boolean / (open) => void | — | 列表的展开状态。 |
placement | Placement | 'bottom-start' | 列表相对触发框的位置。 |
无障碍
- 触发框是
role="combobox"的按钮,列表是多选的role="listbox",选项用aria-selected表达勾选。 - 键盘和 Select 相同,区别是 Enter / Space 只切换高亮项的勾选,不收起列表;Esc 或 Tab 收起。
- 触发框里的小标签只是展示,不能单独聚焦或移除;要取消某一项,展开列表再点一次。
- 折叠成 +N 后看不到全部已选项,重要场景请在别处完整列出。
- 必须有可读名称:
aria-label,或把 Field 给的 id 接到触发框上。