For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/zh/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/zh/llms-full.txt, and this page is available as Markdown at https://rickyshin93.github.io/tao-ui/zh/components/select.md.
v0.0.57
  • 简体中文
  • Select 选择器

    数据录入@rockshin/tao-ui

    从候选列表中选择一个或多个值,也可以搜索、创建标签和定制选项内容。下面按使用场景展示当前支持的能力,每个示例都可以独立复制运行。

    示例通常随视口切换到手机抽屉;标注“桌面”的示例显式使用 mobile={false},用于展示输入、菜单或弹层专属能力。

    基础与外观

    基础用法

    用 options 定义选项,defaultValue 设置初始选择。FormField 为控件提供可访问的标签。

    TSX

    三种尺寸

    small、medium、large 分别适用于紧凑工具栏、常规表单和重点操作。桌面下拉选项的字号与行高同步变化;手机抽屉保留便于触摸的列表尺寸。

    TSX

    外观变体

    使用 outlined、filled 或 borderless 匹配表单所在的背景。变体也可以通过 TaoProvider 统一设置。

    TSX

    禁用控件与选项

    选项上的 disabled 只禁用这一项;控件上的 disabled 禁用整个选择器,保留当前值供用户查看。

    TSX

    校验状态

    status 支持 error 和 warning。配合字段说明展示原因;错误状态同时设置 aria-invalid。

    Production changes need a review.

    TSX

    受控选择

    使用 value 和 onChange 同步外部状态。单选清除时回调值为空字符串;下方按钮也可以修改选择。

    Value: react
    TSX

    多选与标签

    多选

    mode="multiple" 使用字符串数组表示选中项。移除标签或再次点击选项取消选择,allowClear 一次清空全部。

    Selected: design, engineering
    TSX

    最大选择数量

    maxCount 限制可选数量;达到上限后,未选中的选项不可选。移除一项后恢复。本例固定桌面弹层。

    1 / 2 selected
    TSX

    标签输入

    mode="tags" 配合 showSearch 允许输入新值。输入新标签后按 Enter 创建;notFoundContent={null} 隐藏没有匹配建议的空弹层。本例固定桌面输入模式。

    Labels: design
    TSX

    自动分词

    粘贴 design,frontend;docs 后按 Enter,使用 tokenSeparators 批量创建标签并去重。multiple 模式只接受已有选项的值或文本,tags 还能创建新值。

    Paste design,frontend;docs, then press Enter.

    Labels: (none)
    TSX

    标签数量与长度

    maxTagCount 控制显示数量,maxTagTextLength 截断长文本,maxTagPlaceholder 定制折叠提示。它们只改变展示,不减少实际选中值。

    TSX

    隐藏已选项

    hideSelected 从候选列表中移除已选择的项目。删除标签后,该项重新出现在列表。本例固定桌面弹层。

    TSX

    选择与清除事件

    onChange 提供完整值与已有选项对象;onSelect、onDeselect、onClear 描述具体操作。新创建标签没有对应的已有选项对象。

    No action yet
    TSX

    搜索与数据

    自定义搜索

    filterOption 可组合文本、值和描述等字段。这里输入城市名、机场代码或国家都能找到选项,例如 hnd 或 Japan。

    TSX

    分组选项

    在选项的 options 中嵌套子项构成分组。搜索保留匹配项所属的组,分组标题不作为可选择值。

    TSX

    联动选择

    上游选择变化时同步更新下游选项和当前值,避免残留不属于新列表的值。这里由区域决定可选城市。

    Asia / Tokyo
    TSX

    异步搜索与加载

    用本地数据和 500ms 延迟模拟搜索请求。输入变化时取消旧任务,配合 loading、受控搜索和空状态展示完整过程;真实项目可替换为接口请求。本例固定桌面输入模式。

    Local demo with a simulated 500ms request.

    TSX

    自定义空状态

    notFoundContent 可以是文本或 React 节点。空列表与筛选无结果时都会展示该内容;外部操作可补充选项。

    TSX

    内容与样式

    选项图标与描述

    通过选项的 icon 和 description 提供辨识信息。保持 label 为简短文本,便于搜索和选中值展示。

    TSX

    自定义选项内容

    optionRender 接收选项和展平后的索引。可以组合标题与辅助说明,选项的键盘和选择行为仍由 Select 负责。

    TSX

    自定义选中内容

    labelRender 控制单选后的展示内容,可以与下拉列表中的文本不同。这里在城市名旁展示机场代码。

    TSX

    自定义选择标签

    tagRender 定制多选标签。使用回调提供的 closable、disabled 和 onClose 保留删除行为;本例复用 tao-ui 的 Tag。

    TSX

    前后缀与操作图标

    prefix 添加前缀,suffixIcon、allowClear.clearIcon、removeIcon 与 loadingIcon 分别替换对应图标。自定义图标不改变清除和移除行为。

    TSX

    语义化样式

    通过 styles 和 classNames 定制公开语义部件,无需依赖内部类名。弹层通过 Portal 渲染时,也会使用指定的样式和类。

    TSX

    弹层与交互

    扩展下拉菜单

    popupRender 保留原菜单并添加操作区。这里可以输入名称并创建新项目;新增按钮保留输入焦点。本例固定桌面弹层。

    TSX

    弹出位置

    placement 指定上下方向与左右对齐;靠近视口边缘时仍会自动避让。本例固定桌面弹层。

    TSX

    弹层宽度与列表滚动

    popupMatchSelectWidth 默认为与触发器同宽,也支持 false 或指定像素宽度。当前数字宽度仍受触发器最小宽度约束;这里用 200px 控件展示 240px 弹层。listHeight 限制选项区域高度,较长列表在内部滚动。本例为普通列表,不做虚拟滚动。

    TSX

    完整显示长文件名

    开启 optionLabelWrap 后,内置选项标签完整换行,连续无空格的文件名也能断行,不限制行数。勾选图标独占一列,与首行对齐。桌面弹层宽度不超过视口可用空间,可配合 popupMatchSelectWidth 加宽菜单;手机抽屉同样换行。输入框中的已选标签保持紧凑;自定义 optionRender 内容自行控制换行。

    TSX

    受控展开与焦点

    open、onOpenChange 控制弹层。通过 ref 调用 focus() 和 blur(),并在外部操作后保持明确的焦点去向。

    Popup: closed
    TSX

    弹层挂载容器

    getPopupContainer 指定弹层所在的 DOM 容器。自定义容器需要留出弹层空间,并避免父级的裁剪样式遮挡。本例把弹层挂载在当前面板中。

    TSX

    表单与移动

    继承全局配置

    通过 TaoProvider 统一 size、variant 和 disabled;局部属性优先。下面第二个选择器覆盖了全局禁用与尺寸。

    TSX

    表单提交

    桌面单选可用 name 将值交给原生 FormData,字段标签使用 id 关联。多选和手机抽屉应通过受控值自行序列化。本例提交只显示结果,不发送请求。

    Not submitted
    TSX

    移动端抽屉标题按 mobileTitle → 最近的 Form.Item / FormField 的 label → 本地化默认文案取值。必填星号和帮助信息不会带入标题,placeholder 只用于输入提示。独立使用或搭配原生 HTML label 时,可显式设置 mobileTitle="出发日期"。

    移动端单选与多选

    默认随视口切换,mobile 可强制打开底部抽屉。单选立即确认;多选在点击 Done 后提交,直接关闭会放弃本次草稿。切换预览设备可对比桌面弹层与手机抽屉。

    390 × 640
    TSX

    使用说明

    • 少量需要直接比较的互斥选项,优先使用 Radio。
    • 单选使用字符串,多选和标签使用字符串数组;onChange 的第二个参数提供匹配到的已有选项。自由输入的新标签不保证有对应选项对象。
    • 标签数量示例使用数字 maxTagCount,便于观察固定数量的折叠效果。
    • 手机抽屉支持搜索、分组、自定义选项和单选/多选确认。标为桌面模式的示例使用 mobile={false},便于演示输入与弹层操作;弹出位置、弹层宽度与挂载容器属于桌面弹层配置。
    • 桌面单选的 name 可用于原生表单提交。手机和多选使用受控值,在应用的提交逻辑中序列化。

    API

    Select

    属性说明类型默认值
    optionsAvailable options; nested options form groups.SelectOption[] (必填)-
    valueControlled selection. Use an array for multiple or tags mode.string | string[] | undefined-
    defaultValueInitial selection for an uncontrolled Select.string | string[] | undefined-
    onChangeCalled with the new selection and its matching option or options.((value: string | string[], option?: SelectOption | SelectOption[] | undefined) => void) | undefined-
    onSelectCalled when an option is selected.((value: string, option: SelectOption) => void) | undefined-
    onDeselectCalled when a selected option is removed.((value: string, option: SelectOption) => void) | undefined-
    onClearCalled when the selection is cleared.(() => void) | undefined-
    modeMultiple selection or free-form tags. Omit for single selection."multiple" | "tags" | undefined-
    placeholderHint displayed when no value is selected.string | undefined-
    sizeControl and desktop popup size; inherits from TaoProvider when omitted.TaoSize | undefined-
    variantControl appearance; inherits from TaoProvider when omitted.TaoVariant | undefined-
    disabledDisable interaction; inherits from TaoProvider when omitted.boolean | undefined-
    statusValidation appearance: error or warning.TaoStatus | undefined-
    showSearchEnable searching the option list.boolean | undefined-
    filterOptionCustom search predicate receiving the query and option.((input: string, option: SelectOption) => boolean) | undefined-
    searchValueControlled search input text.string | undefined-
    onSearchCalled when the search text changes.((value: string) => void) | undefined-
    allowClearShow a clear action, optionally with a custom icon.boolean | { clearIcon?: ReactNode; } | undefined-
    loadingShow the loading indicator.boolean | undefined-
    loadingIconReplace the default loading indicator.ReactNode-
    notFoundContentContent shown when there are no matching options. Defaults to No results.ReactNode-
    prefixContent before the selected value.ReactNode-
    suffixIconReplace the dropdown indicator.ReactNode-
    removeIconReplace the remove icon on selected tags.ReactNode-
    autoFocusFocus the control when it mounts.boolean | undefined-
    idIdentifier for the control and its associated label.string | undefined-
    nameName used for form submission.string | undefined-
    openControlled popup visibility.boolean | undefined-
    defaultOpenInitial popup visibility.boolean | undefined-
    onOpenChangeCalled when popup visibility changes.((open: boolean) => void) | undefined-
    placementDesktop popup position. Defaults to bottomLeft.SelectPlacement | undefined-
    popupMatchSelectWidthDesktop popup width: match the trigger, use intrinsic width, or specify pixels. Defaults to true.number | boolean | undefined-
    listHeightDesktop option-list height in pixels. Defaults to 256.number | undefined-
    getPopupContainerChoose the desktop popup portal container; mobile drawers portal to document.body.((trigger: HTMLElement) => HTMLElement) | undefined-
    optionRenderCustomize each option's content.((option: SelectOption, info: { index: number; }) => ReactNode) | undefined-
    optionLabelWrapWrap built-in option labels without truncation on desktop and mobile. Defaults to false; custom optionRender controls its own content.boolean | undefined-
    labelRenderCustomize the selected option's label.((option: SelectOption) => ReactNode) | undefined-
    popupRenderWrap or extend the desktop menu or mobile drawer content.((menu: ReactNode) => ReactNode) | undefined-
    tagRenderCustomize a selected tag, including its remove action.((props: TagRenderProps) => ReactNode) | undefined-
    maxTagCountMaximum visible tags, or fit tags to the available width with 'responsive'.number | "responsive" | undefined-
    maxTagPlaceholderContent representing selected tags hidden by maxTagCount.ReactNode | ((omittedValues: SelectOption[]) => ReactNode)-
    maxTagTextLengthMaximum displayed character count for each tag label.number | undefined-
    maxCountMaximum number of selected values in multiple or tags mode.number | undefined-
    autoClearSearchValueClear the search after selecting an option. Defaults to true.boolean | undefined-
    tokenSeparatorsCharacters that split entered text into selections in multiple or tags mode.string[] | undefined-
    hideSelectedHide already selected options from the list.boolean | undefined-
    mobileForce mobile or desktop. Otherwise use viewport <576px; an open popup keeps its presentation until closed.boolean | undefined-
    mobileTitleMobile drawer title. Defaults to the Form.Item/FormField label, then locale text.ReactNode-
    classNameCSS class on the root element.string | undefined-
    styleInline styles on the root element.CSSProperties | undefined-
    classNamesCSS classes keyed by typed semantic parts.Partial<Record<SelectSemanticPart, string>> | undefined-
    stylesInline styles keyed by typed semantic parts.Partial<Record<SelectSemanticPart, CSSProperties>> | undefined-

    SelectOption

    属性类型说明
    labelReactNode选项文本;建议使用字符串,以便默认搜索和触发器展示。
    valuestring唯一值;分组也需要稳定的值。
    disabledboolean禁止选择或移除该项。
    iconReactNode选项图标。
    descriptionReactNode选项辅助说明。
    optionsSelectOption[]子选项;存在时该项作为分组。

    TagRenderProps

    tagRender 接收 { label, value, closable, disabled, onClose }。用 closable 决定是否提供删除操作,并把删除动作交给 onClose。

    SelectRef

    通过 ref 使用 focus()、blur() 与 nativeElement。避免依赖内部 DOM 层级。