Select

何时使用 {#when-to-use}

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

代码演示 {#examples}

<code src="./demo/basic.tsx">基本使用</code> <code src="./demo/search.tsx">带搜索框</code> <code src="./demo/search-filter-option.tsx">自定义搜索</code> <code src="./demo/search-multi-field.tsx">多字段搜索</code> <code src="./demo/multiple.tsx">多选</code> <code src="./demo/size.tsx">三种大小</code> <code src="./demo/option-render.tsx">自定义下拉选项</code> <code src="./demo/search-sort.tsx">带排序的搜索</code> <code src="./demo/tags.tsx">标签</code> <code src="./demo/optgroup.tsx">分组</code> <code src="./demo/coordinate.tsx">联动</code> <code src="./demo/search-box.tsx">搜索框</code> <code src="./demo/label-in-value.tsx">获得选项的文本</code> <code src="./demo/automatic-tokenization.tsx">自动分词</code> <code src="./demo/select-users.tsx">搜索用户</code> <code src="./demo/suffix.tsx" version="5.22.0">前后缀</code> <code src="./demo/custom-dropdown-menu.tsx">扩展菜单</code> <code src="./demo/hide-selected.tsx">隐藏已选择选项</code> <code src="./demo/variant.tsx" version="5.13.0">形态变体</code> <code src="./demo/filled-debug.tsx" debug>Filled debug</code> <code src="./demo/custom-tag-render.tsx">自定义选择标签</code> <code src="./demo/custom-label-render.tsx">自定义选中 label</code> <code src="./demo/responsive.tsx">响应式 maxTagCount</code> <code src="./demo/big-data.tsx">大数据</code> <code src="./demo/status.tsx">自定义状态</code> <code src="./demo/placement.tsx">弹出位置</code> <code src="./demo/placement-debug.tsx" debug>动态高度</code> <code src="./demo/debug.tsx" debug>Debug 专用</code> <code src="./demo/render-panel.tsx" debug>_InternalPanelDoNotUseOrYouWillBeFired</code> <code src="./demo/option-label-center.tsx" debug>选项文本居中</code> <code src="./demo/debug-flip-shift.tsx" iframe="200" debug>翻转+偏移</code> <code src="./demo/component-token.tsx" debug>组件 Token</code> <code src="./demo/maxCount.tsx" version="5.13.0">最大选中数量</code> <code src="./demo/style-class.tsx" version="6.0.0">自定义语义结构的样式和类</code>

API

通用属性参考：通用属性

Select props

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

showSearch

Select Methods

Option props

OptGroup props

Semantic DOM

<code src="./demo/_semantic.tsx" simplify="true"></code>

主题变量（Design Token）{#design-token}

<ComponentTokenTable component="Select"></ComponentTokenTable>

FAQ

mode="tags" 模式下为何搜索有时会出现两个相同选项？ {#faq-tags-mode-duplicate}

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

点击 popupRender 里的元素，下拉菜单不会自动消失？ {#faq-popup-not-close}

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

反过来希望点击 popupRender 里元素不消失该怎么办？ {#faq-popup-keep-open}

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

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

自定义 Option 样式导致滚动异常怎么办？ {#faq-custom-option-scroll}

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

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

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

为何无障碍测试会报缺失 aria- 属性？ {#faq-aria-attribute}

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

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

使用 tagRender 生成的自定义标签，点击关闭时会呼出下拉框 {#faq-tagrender-dropdown}

如果你不希望点击某个元素后下拉框自动出现（例如关闭按钮），可以在其上阻止 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>
    );
  }}
/>