跳到主要内容

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。
valuestring[]—选中的值(受控)。
defaultValuestring[][]初始选中的值(非受控)。
onChange(value: string[]) => void—选中项变化时触发。
display'chips' | 'count''chips'触发框里显示小标签,或“已选 N 项”。
maxChipsnumber2chips 模式最多显示几个,其余折成 +N。
renderValue(selected: SelectOption[]) => ReactNode—自定义触发框里的内容。
placeholderReactNode'请选择'没选时显示的文字。
size'sm' | 'md' | 'lg''md'尺寸。
disabled / invalidboolean—禁用 / 校验未通过。
name / formstring—配合表单:每个选中值一个同名隐藏 input。
open / defaultOpen / onOpenChangeboolean / boolean / (open) => void—列表的展开状态。
placementPlacement'bottom-start'列表相对触发框的位置。

无障碍

  • 触发框是 role="combobox" 的按钮,列表是多选的 role="listbox",选项用 aria-selected 表达勾选。
  • 键盘和 Select 相同,区别是 Enter / Space 只切换高亮项的勾选,不收起列表;Esc 或 Tab 收起。
  • 触发框里的小标签只是展示,不能单独聚焦或移除;要取消某一项,展开列表再点一次。
  • 折叠成 +N 后看不到全部已选项,重要场景请在别处完整列出。
  • 必须有可读名称:aria-label,或把 Field 给的 id 接到触发框上。