Select 选择器
Select 是一个点开后显示选项菜单的输入框:选一个,或用 multiple 选多个(显示成标签),用 filterable 可以输入文字过滤。选项列表和 Popselect 共用。焦点始终留在输入框上:它是驱动列表的 combobox,和 WAI-ARIA 的组合框模式一致。
演示
基础用法
点击输入框,或聚焦后按 ↓ / Enter / 空格打开菜单。菜单和输入框一样宽,在下方弹出,下方放不下时翻到上方。禁用项会被跳过。
多选
multiple 把选中项显示成标签(点 × 移除),菜单选完不关,值是数组。maxTagCount 只显示前几个标签,其余折叠成 +N。clearable 在有值时悬停显示清空按钮。
可过滤
filterable 可以在输入框里打字过滤选项(按标签、不区分大小写;传 filter 自定义)。第一个匹配项自动成为当前项,直接按 Enter 就选中。
可过滤 + 多选
两个都开时:打字过滤列表,按 Enter 把当前项加成标签;菜单保持打开,每选一个输入的文字自动清空(clearFilterAfterSelect),可以接着输下一个。在空的输入框里按退格删除最后一个标签,点标签上的 × 删除那一个。
远程搜索
设置 remote 后 Select 不自己过滤:onSearch 拿到输入的文字,由你传入对应的选项。loading 用加载图标代替右侧的箭头。
尺寸和状态
size 设置输入框高度(和同尺寸的按钮对齐);status 改变边框颜色。
键盘
焦点在输入框上时:↓ / ↑ / Enter(不可过滤时还有空格)打开菜单;↑ / ↓ 移动当前项(跳过禁用项,到头循环);Enter 选中;Home / End 和输入首字母跳转(可过滤时它们用来编辑文字);Esc 关闭;Tab 关闭并移到下一个元素。
Props
| 名称 | 类型 | 默认值 | 说明 | 版本 |
|---|---|---|---|---|
options | SelectMixedOption[] | 必填 | 选项 { label, value, disabled? },可以分组 { type: "group", label, key, children }。 | 未发布 |
value | SelectValue | SelectValue[] | null | undefined | 受控的值;multiple 时是数组。 | 未发布 |
defaultValue | SelectValue | SelectValue[] | null | null | 非受控时的初始值。 | 未发布 |
onUpdateValue | (value, option) => void | undefined | 值变化时调用,带上选中的选项。 | 未发布 |
multiple | boolean | false | 多选,显示成标签。 | 未发布 |
filterable | boolean | false | 可以输入文字过滤。 | 未发布 |
filter | (pattern, option) => boolean | 标签包含 | 判断选项是否匹配输入的文字。 | 未发布 |
onSearch | (pattern: string) => void | undefined | 输入时调用。 | 未发布 |
remote | boolean | false | 不在本地过滤,选项由 onSearch 提供。 | 未发布 |
clearFilterAfterSelect | boolean | true | 多选时选中后清空输入的文字。 | 未发布 |
clearable | boolean | false | 有值时悬停显示清空按钮。 | 未发布 |
onClear | () => void | undefined | 清空后调用。 | 未发布 |
placeholder | ReactNode | 语言包「请选择」 | 没有值时显示。 | 未发布 |
size | small | medium | large | medium | 输入框高度和字号。 | 未发布 |
status | success | warning | error | undefined | 边框颜色。 | 未发布 |
disabled | boolean | false | 不能打开或修改。 | 未发布 |
loading | boolean | false | 用加载图标代替箭头。 | 未发布 |
maxTagCount | number | undefined | 多选时最多显示几个标签,其余显示成 +N。 | 未发布 |
renderLabel | (option, selected) => ReactNode | undefined | 自定义选项标签(菜单和输入框里都用)。 | 未发布 |
renderTag | (option, remove) => ReactNode | undefined | 自定义选中项的标签。 | 未发布 |
consistentMenuWidth | boolean | true | 菜单和输入框一样宽;关掉后至少一样宽。 | 未发布 |
placement | PopoverPlacement | bottom-start | 菜单弹出的位置。 | 未发布 |
show / defaultShow | boolean | undefined / false | 受控 / 初始的菜单状态。 | 未发布 |
onUpdateShow | (show: boolean) => void | undefined | 菜单打开或关闭时调用。 | 未发布 |
header / footer | ReactNode | undefined | 选项上方 / 下方的行。 | 未发布 |
empty | ReactNode | 语言包「暂无数据」 | 没有选项时显示。 | 未发布 |
to / zIndex | 同 Popover。 | 未发布 | ||
onFocus / onBlur | (event) => void | undefined | 焦点进入 / 离开输入框。 | 未发布 |
aria-label、aria-labelledby 和 id 传给 combobox 元素;className、style 和 ref 传给输入框外层。