选择器 Select

当用户需要从一组同类数据中选择一个或多个时，可以使用下拉选择器，点击后选择对应项。

安装

npm install @arco-design/web-react@2.66.18

在入口引入 @arco-design/web-react/dist/css/arco.css，用 ConfigProvider 设置语言。React 19 项目还需在入口最先引入 @arco-design/web-react/es/_util/react-19-adapter，否则 Message、Modal 等命令式 API 无法渲染。

示例

• 基础用法：基础选择器。
• 允许清除：支持清除按钮。
• 多选模式：指定 mode=multiple，即可使用多选。通过 maxTagCount 设置最多显示的标签个数，通过 renderTag 属性自定义标签的渲染方式，实现更复杂的定制。
• 带有前置标签：通过 addBefore 设置前置标签 (2.41.0)
• 允许创建：指定 allowCreate 为 true，即可创建选项中不存在的条目。通过 allowCreate.formatter 格式化用户创建的选项。
• 搜索：指定showSearch=true，可以对展开的选项进行搜索，配合 filterOption 可以自定义搜索。 搜索框聚焦时默认会清空已输入的内容，通过指定 showSearch={ retainInputValue: true } 来保留内容。
• 远程搜索：指定 showSearch，并且结合 filterOption 和 onSearch，可以使用远程搜索功能。
• 自定义弹出框宽度：这个例子展示了弹出框可以根据内容自动调节宽度，最小宽度为输入框的宽度。 triggerProps.autoAlignPopupWidth 参数为弹出框宽度跟输入框保持一致。 triggerProps.autoAlignPopupMinWidth 参数为弹出框最小宽度跟输入框保持一致。 可以自由组合。
• 不同尺寸：通过 size 选择 Select 的尺寸（mini, small, default, large），高度分别对应24px、28px、32px、36px。
• 定制回显内容：使用 renderFormat 可以定制回显内容。 注意：在如远程加载选项数据的场景下，value 中对应的选项可能在某些时刻并不存在，需要判断若 option 不存在则返回 value 作为显示的内容。
• 分组：使用 Select.Group 对下拉菜单选项进行编组。
• 指定可选项：通过传入options指定可选项。
• 滚动加载选项：当动态加载时，可通过onPopupScroll来监听滚动事件
• 自动分词：设置 tokenSeparators 可以使用自动分词功能。试试复制 Beijing,Shanghai,Shenzhen|Nanjing/Xi'an|Hangzhou 到输入框里。只在 multiple 模式下可用。
• 自定义触发节点：设置 triggerElement 可以自定义触发下拉框的节点。当自定义了触发节点时，由于内部绑定的键盘处理事件失效，所以快捷键操作将不可用，需要通过组件引用的 hotkeyHandler 进行额外处理。
• 扩展菜单：使用 dropdownRender 对下拉菜单进行自由扩展。
• 无边框：使用 bordered = false，可以使用无边框的选择器。
• 自定义标签样式：指定 renderTag 来自定义标签节点。
• 联动：省市联动示例。
• 隐藏已选择项：在下拉列表中隐藏已选择的项。
• 大数据：Select 使用了虚拟滚动技术，在大量数据的情况也能保证性能。 当指定了 triggerProps.autoAlignPopupWidth = false 且 Option.label 为非文本类型时，由于无法在选项列表首次渲染时获取选项的最大宽度，虚拟滚动会被自动关闭。
• 拖拽排序：多选时，指定 dragToSort 属性以允许对已输入的值进行拖拽排序。
• 宽度自适应：通过 autoWidth 属性可以设置 Select 的宽度自适应
• 最大标签数：通过 maxTagCount 属性可以设置 Select 的最大标签数。 maxTagCount=responsive 时会根据容器尺寸动态显示标签数。因为会监听所有 Tag 及容器的尺寸变化，所以在选项较多时不建议使用，可能存在性能问题。

示例来自 Arco Design 官方仓库（MIT），固定在 npm 2.66.18 对应的提交；部分示例使用在线图片或上传地址，预览中网络请求被禁用。

API

Select

Select.Option

Select.OptGroup

Select Reference Type

LabeledValue

export type LabeledValue = {
  value: string | number;
  label: ReactNode;
};

OptionInfo

export interface OptionInfo extends PropsWithChildren<OptionProps> {
  child?: ReactElement;
  _valid: boolean;
  _index: number;
  _origin: "children" | "options" | "userCreatedOptions" | "userCreatingOption";
}

AvailableVirtualListProps

export type AvailableVirtualListProps = Pick<
  VirtualListProps<any>,
  | "height"
  | "itemHeight"
  | "threshold"
  | "isStaticItemHeight"
  | "scrollOptions"
  | "onScroll"
  | "wrapperChild"
>;

InputValueChangeReason

// 造成输入框值改变的原因：用户输入、选中选项、选项下拉框收起、触发自动分词
export type InputValueChangeReason =
  | "manual"
  | "optionChecked"
  | "optionListHide"
  | "tokenSeparator";

ObjectValueType

export type ObjectValueType = {
  value?: any;
  label?: ReactNode;
  closable?: boolean;
};

VirtualListProps