选择器

下拉选择器。

何时使用

• 弹出一个下拉菜单给用户选择操作，用于代替原生的选择器，或者需要一个更优雅的多选器时。
• 当选项少时（少于 5 项），建议直接将选项平铺，使用 Radio 是更好的选择。
• 如果你在寻找一个可输可选的输入框，那你可能需要 AutoComplete。

代码演示

• 基本使用 · basic

• 带搜索框 · search

• 自定义搜索 · search-filter-option

• 多字段搜索 · search-multi-field

• 多选 · multiple

• 三种大小 · size

• 自定义下拉选项 · option-render

• 带排序的搜索 · search-sort

• 标签 · tags

• 分组 · optgroup

• 联动 · coordinate

• 获得选项的文本 · label-in-value

• 自动分词 · automatic-tokenization

• 自定义分词 · custom-tokenization

• 搜索用户 · select-users

• 前后缀 · suffix

• 扩展菜单 · custom-dropdown-menu

• 隐藏已选择选项 · hide-selected

• 形态变体 · variant

• 自定义选择标签 · custom-tag-render

• 自定义选中 label · custom-label-render

• 响应式 maxTagCount · responsive

• 大数据 · big-data

• 自定义状态 · status

• 弹出位置 · placement

• 最大选中数量 · maxCount

• 自定义语义结构的样式和类 · style-class

API

通用属性参考：通用属性

Select props

注意，如果发现下拉菜单跟随页面滚动，或者需要在其他弹层中触发 Select，请尝试使用 getPopupContainer={triggerNode => triggerNode.parentElement} 将下拉弹层渲染节点固定在触发器的父元素中。

showSearch

Select Methods

Option props

OptGroup props

Semantic DOM

语义说明来源: vendor/.dumi/theme/common/SelectSemanticTemplate.tsx

主题变量（Design Token）

类型、继承关系和原生令牌声明保持固定源码原文；默认值由原生主题计算，并可能受 ConfigProvider 覆盖。本表不伪造静态默认值。

声明来源: vendor/components/select/style/token.ts

import type { CSSProperties } from 'react';

import type { FullToken, GetDefaultToken } from '../../theme/internal';

export interface MultipleSelectorToken {
  /**
   * @desc 多选标签背景色
   * @descEN Background color of multiple tag
   */
  multipleItemBg: string;
  /**
   * @desc 多选标签边框色
   * @descEN Border color of multiple tag
   */
  multipleItemBorderColor: string;
  /**
   * @desc 多选标签高度
   * @descEN Height of multiple tag
   */
  multipleItemHeight: number;
  /**
   * @desc 小号多选标签高度
   * @descEN Height of multiple tag with small size
   */
  multipleItemHeightSM: number;
  /**
   * @desc 大号多选标签高度
   * @descEN Height of multiple tag with large size
   */
  multipleItemHeightLG: number;
  /**
   * @desc 多选框禁用背景
   * @descEN Background color of multiple selector when disabled
   */
  multipleSelectorBgDisabled: string;
  /**
   * @desc 多选标签禁用文本颜色
   * @descEN Text color of multiple tag when disabled
   */
  multipleItemColorDisabled: string;
  /**
   * @desc 多选标签禁用边框色
   * @descEN Border color of multiple tag when disabled
   */
  multipleItemBorderColorDisabled: string;
  /**
   * @internal
   */
}

export interface ComponentToken extends MultipleSelectorToken {
  /**
   * @desc 下拉菜单 z-index
   * @descEN z-index of dropdown
   */
  zIndexPopup: number;
  /**
   * @desc 选项选中时文本颜色
   * @descEN Text color when option is selected
   */
  optionSelectedColor: string;
  /**
   * @desc 选项选中时文本字重
   * @descEN Font weight when option is selected
   */
  optionSelectedFontWeight: CSSProperties['fontWeight'];
  /**
   * @desc 选项选中时背景色
   * @descEN Background color when option is selected
   */
  optionSelectedBg: string;
  /**
   * @desc 选项激活态时背景色
   * @descEN Background color when option is active
   */
  optionActiveBg: string;
  /**
   * @desc 选项内间距
   * @descEN Padding of option
   */
  optionPadding: CSSProperties['padding'];
  /**
   * @desc 选项字体大小
   * @descEN Font size of option
   */
  optionFontSize: number;
  /**
   * @desc 选项行高
   * @descEN Line height of option
   */
  optionLineHeight: CSSProperties['lineHeight'];
  /**
   * @desc 选项高度
   * @descEN Height of option
   */
  optionHeight: number;
  /**
   * @desc 选框背景色
   * @descEN Background color of selector
   */
  selectorBg: string;
  /**
   * @desc 清空按钮背景色
   * @descEN Background color of clear button
   */
  clearBg: string;
  /**
   * @desc 单选大号回填项高度
   * @descEN Height of single selected item with large size
   */
  singleItemHeightLG: number;
  /**
   * @desc 箭头的行末内边距
   * @descEN Inline end padding of arrow
   */
  showArrowPaddingInlineEnd: number;
  /**
   * @desc 悬浮态边框色
   * @descEN Hover border color
   */
  hoverBorderColor: string;
  /**
   * @desc 激活态边框色
   * @descEN Active border color
   */
  activeBorderColor: string;
  /**
   * @desc 激活态 outline 颜色
   * @descEN Active outline color
   */
  activeOutlineColor: string;
}

export interface SelectorToken {
  selectAffixPadding: number | string;
  inputPaddingHorizontalBase: number | string;
  multipleSelectItemHeight: number;
  selectHeight: number;
}

export interface SelectToken extends FullToken<'Select'>, SelectorToken {
  rootPrefixCls: string;

  /** @private Used for internal calculation */
  INTERNAL_FIXED_ITEM_MARGIN: number;
}

FAQ

mode="tags" 模式下为何搜索有时会出现两个相同选项？

这一般是 options 中的 label 和 value 不同导致的，你可以通过 optionFilterProp="label" 将过滤设置为展示值以避免这种情况。

点击 popupRender 里的元素，下拉菜单不会自动消失？

你可以使用受控模式，手动设置 open 属性：codesandbox。

反过来希望点击 popupRender 里元素不消失该怎么办？

Select 当失去焦点时会关闭下拉框，你可以通过阻止默认行为来避免丢失焦点导致的关闭：

<Select
  popupRender={() => (
    <div
      onMouseDown={(e) => {
        e.preventDefault();
        e.stopPropagation();
      }}
    >
      Some Content
    </div>
  )}
/>

自定义 Option 样式导致滚动异常怎么办？

这是由于虚拟滚动默认选项高度为 24px，如果你的选项高度小于该值则需要通过 listItemHeight 属性调整，而 listHeight 用于设置滚动容器高度：

<Select listItemHeight={10} listHeight={250} />

注意：listItemHeight 和 listHeight 为内部属性，如无必要，请勿修改该值。

为何无障碍测试会报缺失 aria- 属性？

Select 无障碍辅助元素仅在弹窗展开时创建，因而当你在进行无障碍检测时请先打开下拉后再进行测试。对于 aria-label 与 aria-labelledby 属性缺失警告，请自行为 Select 组件添加相应无障碍属性。

Select 虚拟滚动会模拟无障碍绑定元素。如果需要读屏器完整获取全部列表，你可以设置 virtual={false} 关闭虚拟滚动，无障碍选项将会绑定到真实元素上。

使用 tagRender 生成的自定义标签，点击关闭时会呼出下拉框

如果你不希望点击某个元素后下拉框自动出现（例如关闭按钮），可以在其上阻止 MouseDown 事件的传播。

<Select
  tagRender={(props) => {
    const { closable, label, onClose } = props;
    return (
      <span className="border">
        {label}
        {closable ? (
          <span
            onMouseDown={(e) => e.stopPropagation()}
            onClick={onClose}
            className="cursor-pointer"
          >
            ❎
          </span>
        ) : null}
      </span>
    );
  }}
/>

原生通用属性

Tips: 以下通用属性适用于 antd 大部分组件，不支持的组件会单独说明。

安装并复现示例

npm install antd@6.6.5 @ant-design/icons@6.3.4 dayjs@1.11.23

使用 ConfigProvider 和原生 App，并单独配置 dayjs 语言。每个示例在查看代码中列出完整源码文件和额外固定依赖。示例名称用于选择演示，不是组件通用属性。主题、语言与 SSR 初始化见资源安装指南。

原生类型参考

源码查看器包含未修改的原生实现和以下声明文件，继承类型仍位于原生包中。代码中的英文注释保留为源码参考。

• vendor/components/select/index.tsx
• vendor/components/select/style/select-input.ts
• vendor/components/select/style/token.ts
• vendor/components/select/useIcons.tsx
• vendor/components/select/usePopupRender.tsx

来源与许可

https://github.com/ant-design/ant-design/tree/4a39f54842eade4e565ab336ef6097cd7e723cdd

保留原生中英文正文与可执行示例；官网专用的嵌入章节和令牌表格在本地展开。Ant Design 使用 MIT 许可，另列依赖的许可证也需保留。上传预览禁止向外发起请求，不提供后端服务。