代码演示

如何引入

import { Select } from '@douyinfe/semi-ui';
const Option = Select.Option;

基本使用

以数组形式传入 Option

多选

分组

不同尺寸

不同校验状态样式

配置前缀、后缀、清除按钮

• 可以通过prefix传入选择框前缀，通过suffix传入选择框后缀，可以为文本或者 ReactNode
  当 prefix、suffix 传入的内容为文本或者 Icon 时，会自动带上左右间隔，若为自定义 ReactNode，则左右间隔为 0
• 通过showClear控制清除按钮是否展示
• 通过showArrow控制右侧下拉箭头是否展示

内嵌标签

在顶部/底部渲染附加项

• innerTopSlot 和 innerBottomSlot将会被渲染在 optionList 内部，当滚动到 optionList 顶部/底部时展现
• outerTopSlot 和 outerBottomSlot将会被渲染为与 optionList 平级，无论 optionList 是否滚动，都会始终展现

受控组件

动态修改 Options

联动

开启搜索

搜索框位置

远程搜索

自定义搜索逻辑

自定义已选项标签渲染

• 单选时 renderSelectedItem(optionNode:object) => content:ReactNode
• 多选时 renderSelectedItem(optionNode:object, { index:number, onClose:function }) => { isRenderInTag:bool, content:ReactNode }
  • isRenderInTag 为 true 时，会自动将 content 包裹在 Tag 中渲染（带有背景色以及关闭按钮）
  • isRenderInTag 为 false 时，将直接渲染返回的 content

自定义弹出层样式

获取选项的其他属性

创建条目

虚拟化

• height: Option 列表高度值，默认 270 (v2.20.8 前为 300)
• width: Option 列表宽度值，默认 100%
• itemSize: 每行 Option 的高度，必传

.semi-select-option-list > div {
    will-change: unset !important; // 由于 react-window自带样式是内联的，所以这里用 important 覆盖
}

自定义触发器

interface TriggerRenderProps {
  value: array<object> // 当前所有已选中的options
  inputValue: string; // 当前input框的输入值
  onSearch: (inputValue: string) => void; // 用于更新 input框值的函数，当你在triggerRender自定义的Input组件值更新时你应该调用该函数，用于向Select内部同步状态。注意 filter 需同时设为true, v2.32 提供
  onRemove: (option: object) => void; // 用于移除单个已选项，option至少需带有 label、value 两项，v2.32提供
  onClear: () => void; // 用于清空值的函数
  disabled: boolean; // 是否禁用Select
  placeholder: string; // Select的placeholder
  componentProps: object // 所有用户传给Select的props
}

自定义候选项渲染

• 简单的自定义：通过 Option 的 label 属性或者 children 传入 ReactNode，你可以控制候选项的渲染，此时内容会自动带上内边距、背景色等样式
• 完全自定义：通过传入renderOptionItem，你可以完全接管列表中候选项的渲染，并且从回调入参中，获取到相关的状态值。实现更高自由度的结构渲染
  注意事项：
  1. props 传入的 style 需在 wrapper dom 上进行消费，否则在虚拟化场景下会无法正常使用
  2. props 传入的 className、onMouseEnter 需在 wrapper dom 上进行消费，否则上下键盘操作时显示会有问题
  3. 选中(selected)、聚焦(focused)、禁用(disabled)等状态的样式需自行加上，你可以从 props 中获取到相对的 boolean 值
  4. 如果你的自定义 item 为 Select.Option，需要将 renderProps.onClick 透传给 Option 的 onSelect prop

.components-select-demo-renderOptionItem {
    .custom-option-render {
        display: flex;
        font-size: 14px;
        line-height: 20px;
        word-break: break-all;
        padding-left: 12px;
        padding-right: 12px;
        padding-top: 8px;
        padding-bottom: 8px;
        color: var(--semi-color-text-0);
        position: relative;
        display: flex;
        align-items: center;
        cursor: pointer;
        box-sizing: border-box;
        .option-right {
            margin-left: 8px;
            display: inline-flex;
            align-items: center;
        }
        &:active {
            background-color: var(--semi-color-fill-1);
        }
        &-focused {
            background-color: var(--semi-color-fill-0);
        }
        &-selected {
            //font-weight: 700;
        }
        &-disabled {
            color: var(--semi-color-disabled-text);
            cursor: not-allowed;
        }
        &:first-of-type {
            margin-top: 4px;
        }
        &:last-of-type {
            margin-bottom: 4px;
        }
    }
}

API 参考

Select Props

Option Props

不同 Option 的 label 必须唯一，不允许重复

OptGroup Props

Methods

Accessibility

ARIA

• Select trigger 的 role 为 combobox，弹出层的 role 为 listbox，可选项的 role 为 option
• Select trigger 具有 aria-haspopup、aria-expanded、aria-controls 属性，表示 trigger 与弹出层的关系
• 多选时，listbox aria-multiselectable 为 true，表示当前可以多选
• Option 选中时，aria-selected 为 true；当 Option 禁用时，aria-disabled 为 true
• 属性 aria-activedescendant 能够保证在朗读旁白时识别到当前的选择的 option(更多用法请参考Managing Focus in Composites Using aria-activedescendant)

键盘和焦点

• Select 聚焦后，键盘用户可以通过 上箭头 或 下箭头 或 Enter 键打开下拉菜单，并将焦点自动聚焦到下拉菜单中的第一个选项上（defaultActiveFirstOption 默认为 true）
• 当下拉菜单打开时：
  • 使用 Esc 键或 Tab 键可以关闭菜单
  • 使用 上箭头 或 下箭头 可以切换选项
  • 被聚焦的选项可以通过 Enter 键选中，并收起面板
• 当焦点在下拉菜单中，且用户使用的 innerBottomSlot 或 outerBottomSlot 属性的自定义 slot 中含有可交互元素时：
  • 可以使用 Tab 键切换到这些可交互元素上
  • 当焦点在自定义 slot 的首个可交互元素上时，使用 Shift + Tab ，焦点回到 Select 框上

• Select 聚焦后，键盘用户可以通过 上箭头 或 下箭头 或 Enter 键打开下拉菜单。此时焦点仍然处于 Select 框，用户可以输入内容，同时也能使用 上箭头 或 下箭头 切换选项
• 当下拉菜单打开时：键盘交互与不带 Filter 功能的 Select 一致
• 当焦点在 Select 框上，且用户使用的 innerBottomSlot 或 outerBottomSlot 属性的自定义 slot 中含有可交互元素时：
  • 可以使用 Tab 键切换到这些可交互元素上
  • 当焦点在自定义 slot 的首个可交互元素上时，使用 Shift + Tab ，焦点回到 Select 框上

文案规范

• 选择器标签
  • 用 1-3 个词描述需要用户所做的输入
  • 使用语句书写规范（首字母大写，其余小写）
  • 避免使用标点符号和介词（“the”, “an”, “a”）
  • 标签需是独立语句。不要让标签是前半句语句，选项是后半句语句。
  • 使用描述性语句，而不是指示性语句。如果选项需要更多解释，可以在选择框下使用帮助文本。
• 选择器选项
  • 如果没有默认选项，就使用“Select”做占位文案
  • 选项要按首字母顺序或者其他有逻辑的排列顺序，使用户更好地找到选项
  • 使用语句书写规范（首字母大写，其余小写），避免在句尾使用逗号和分号
  • 清晰表达出选项所表示的选择目的

设计变量

FAQ

• 为什么 Semi 的 Select 要求 label 必须唯一，而不是 value 必须唯一?
  • 首先，我们一定需要一个唯一标识符用来做选中的判断。几乎所有 UI 库，对 Select.Option 使用时，最低要求都只会要求传入 label、value 两个值，而不会再单独要求传入一个 key（过于繁琐）。Semi 延续了这个设定
  • 那么为什么在 Semi 中 用 label 而不是 value 呢？
    • 以 value 还是 label 作为唯一判断符，本质上是 用户直觉 vs 研发直觉 的取舍。以 value 为唯一判断比较符合工程师直觉，但站在用户视角来看，他们能看到的只有 label，对 value 基本上是无感知的。
    • label 是用户唯一能感知的内容。从交互的角度而言，如果出现两个或多个展示上一模一样的选项，对用户而言，他们看上去是一样的，无法进行区分。用户第一反应往往是重复了，这个系统是不是出 bug 了。其次如果两个 option 展示上一模一样，但选中的作用又不一样（例如一个 value 为 0，另一个为 1，他们的处理逻辑完全不同）的话，也会让用户非常困惑。在现实生活的线下实体表单里，基本不可能出现两个一模一样的选项。
    • 假如我们以 value 作为判断符，以下例子，用户点击了 A 进行选中，实际上却看到 A、B、C 都被同时选中了。同样也会非常困惑，第一反应也往往是系统出 bug 了。

        <Select placeholder='choose your color'>
            <Option label='A' value='color' />
            <Option label='B' value='color' />
            <Option label='C' value='color' />
        </Select>
      

    • label 唯一、value 重复，在日常使用中会更为常见。例如，一个根据 app 名称选择公司 id 的选择器，value 是 app 对应的公司 id，label 是 app 的名称。

        <Select placeholder='choose company by app'>
          <Option label='vigo' value='bytedance' />
          <Option label='douyin' value='bytedance' />
        </Select>
      

  • 分组情况下，重复 label 并不会造成用户困惑为什么仍要求 label 必须唯一？
    • 选择面板打开情况下，确实不会造成用户使用上的困惑，但是选择面板收起后，重复 label 属于哪个分组对用户而言仍具有迷惑性。
  • 我的数据里确实就有多个 label 一样的选项，无法避免。这个交互能绕过吗？
    • 可以。我们不推荐向用户展示重复的 label option，但如果你确定你需要这么做，当你往 label 传入 ReactNode 类型时，可以绕过这个限制。
• 可搜索的 Select，使用远程数据动态更新optionList，为什么在异步请求完成之前有时候会出现暂无数据？
  请检查是否设置了remote={true}，不设置 remote 的情况下，默认会将 input 框输入值与当前的 optionList 进行一次对比筛选，如果无匹配时，就会显示暂无数据。
  可以通过设置 remote 为 true 关闭对本地当前数据的匹配筛选。
• 使用 jsx 方式声明 Option，label 为 i18n 后的内容，切换 locale 后未能重新渲染
  • children jsx 方式声明 Options 时，由于是 ReactNode，不可能用 deepEqual 来做对比判断内容是否有更新（性能消耗过大），所以会收集 children ReactNode 的 key，当 key 不变时，就认为 Options 都没有发生变化，不会走重新收集数据的流程。你可以将 locale 也作为 Option key 的一部分。
  • 使用 optionList 方式传入，也可以解决问题。因为对于 object 形式传入，key 相对有限，Select 内部会使用 isEqual 来判断是否发生变化
• 使用 jsx 方式声明 Option，动态切换 disabled 属性后未能重新渲染
  • 原因同上，你可以重新给 Option 设定不同的 key 值，或者使用 optionList 方式声明候选项
• Select 会自动限制下拉菜单的宽度吗？
  • 会给 minWidth，但不会写死 width。如果有需要的话，可以自己通过 dropdownStyle 来添加。
• 设置 allowCreate 后，动态更新 optionList 或者 children 不生效
  • allowCreate 主要用于本地创建的场景，开启该项后，相当于强接管了 optionList / children，不会再响应外部对这两类值的更新。
• 为什么单选选择选项后没有触发 blur 事件？
  • 在 V2.17.0 前，Select 单选选择后，会触发 Select 的 blur 事件。
  • 在 V2.17.0 后，Select 增加了 A11y 支持，不会触发 Select 的 blur 事件。
    • 单选选择中，Select 浮层关闭，依然保持焦点在 trigger（此时可以通过 Enter 回车键再次打开 Select 浮层）
    • 无论单选或多选，按下 Esc，仅 Select 浮层关闭，trigger 保持焦点（此时可以通过 Enter 回车键再次打开 Select 浮层）