Select

代码演示

如何引入

import { Select } from '@chenzy-design/svelte';

基本使用

每个 <Select.Option> 都必须声明 value 属性，label 将会被渲染至下拉列表中。

以数组形式传入 Option

可以直接通过 optionList 传入一个对象数组，每个对象必须包含 value / label 属性（当然其他属性也可以通过此方式传入）。

多选

配置 multiple 属性，可以支持多选。

配置 maxTagCount 可以限制已选项展示的数量，超出部分将以 +N 的方式展示。

配置 ellipsisTrigger 对溢出部分的 tag 做自适应处理，当宽度不足时，最后一个 tag 内容作截断处理。开启该功能后会有一定性能损耗，不推荐在大表单场景下使用。

配置 expandRestTagsOnClick 可以在设置 maxTagCount 情况下通过点击展示全剩余的 tag。

使用 showRestTagsPopover 可以设置在超出 maxTagCount 后，hover +N 是否显示 Popover，默认为 false。并且，还可以在 restTagsPopoverProps 属性中配置 Popover。

配置 max 属性可限制最大可选的数量，超出最大限制数量后无法选中，同时会触发 onExceed 回调。

分组

用 <Select.OptGroup> 进行分组（分组功能仅支持通过组合式 children 方式声明，不支持 optionList 方式传入）。

不同尺寸

通过 size 控制选择器的大小尺寸：small / default / large。

不同校验状态样式

validateStatus：default / warning / error，仅影响背景颜色等样式表现。

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

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

在顶部/底部渲染附加项

我们在弹出层顶部、底部分别预留了插槽，当你需要在弹出层中添加自定义 node 时，可以通过 innerBottomSlot 或者 outerBottomSlot 传入，自定义 node 将会被渲染在弹出层底部；可以通过 innerTopSlot 或者 outerTopSlot 传入，自定义 node 将会被渲染在弹出层顶部。

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

通过 outerTopSlot 将内容插入顶部插槽。

受控组件

传入 value 时 Select 为受控组件，所选中的值完全由 value 决定。

动态修改 Options

如果需要动态更新 Options，应该使用受控的 value。

联动

使用受控 value，实现不同 Select 之间的联动。如果是带有层级关系的复杂联动建议直接使用 Cascader 组件。

开启搜索

将 filter 置为 true，开启搜索能力。默认搜索策略将为 input 输入值与 option 的 label 值进行 include 对比。

默认情况下，多选选中后会自动清空搜索关键字。若你希望保留，可以通过 autoClearSearchValue 设为 false 关闭默认行为。

搜索框位置

默认搜索框展示于 Select 的 Trigger 触发器上。通过 searchPosition 可以指定不同的位置，可选 dropdown、trigger。若希望定制位于 dropdown 中的 Input 搜索框的 placeholder，可以通过 searchPlaceholder 控制。

远程搜索

带有远程搜索，防抖请求，加载状态的多选示例。通过 filter 开启搜索能力，将 remote 设置为 true 关闭对当前数据的筛选过滤，通过动态更新 optionList 更新下拉菜单中的备选项，并使用受控的 value 属性。

自定义搜索逻辑

可以将 filter 置为自定义函数，定制你想要的搜索策略。如下例子，选项 label 值都是大写，默认的检索策略是字符串 include 对比，会区分大小写。通过传入自定义 filter 函数，检索时输入小写字母也能搜到相应内容。

自定义已选项标签渲染

默认情况下，选中选项后会将 option.label 的内容回填到选择框中。你可以通过 renderSelectedTag 自定义已选项内容渲染，多选态下内容仍会套进选择器自身的 Tag 容器；也可以通过 renderSelectedItem 完全自定义单个已选 chip（多选态生效，不再套 Tag 容器，需自行处理关闭等交互）。

shenyue@example.com

申悦

曲晨一

申悦

曲晨一

查看源码 ▼

自定义弹出层样式

你可以通过 dropdownClassName、dropdownStyle 控制弹出层的样式。例如当自定义弹出层的宽度时，可以通过 dropdownStyle 传入 width。

获取选项的其他属性

默认情况下 onChange 只能拿到 value，如果需要拿选中节点的其他属性，可以使用 onChangeWithObject 回调。此时回调函数的入参将会是 object，包含 option 的各种属性，例如 { value, label, ...rest }。

创建条目

设置 allowCreate，可以创建并选中选项中不存在的条目。允许通过 renderCreateItem 自定义创建标签时的内容显示。可以配合 defaultActiveFirstOption 属性使用，自动选中第一项，当输入完内容直接回车时，可立即创建。

虚拟化

传入 virtualize 时开启列表虚拟化，用于大量 Option 节点的情况优化性能。virtualize 是一个包含下列值的对象：

• height：Option 列表高度值，默认 270。
• width：Option 列表宽度值，默认 100%。
• itemSize：每行 Option 的高度，必传。

自定义触发器

如果 Select 默认的触发器样式满足不了你的需求，可以用 triggerRender 自定义选择框的展示。如果想保留搜索筛选能力，又不希望自己渲染 Input 相关的结构，可以同时通过 searchPosition='dropdown'，将默认的搜索框置于下拉列表中。

triggerRender 入参除 value/selectedOptions/placeholder/open 等状态外，还提供 onSearch/onRemove/onClear 三个回调，用于向 Select 内部同步搜索词、移除单个已选项、清空全部已选项。下面第三个例子复用了 TagInput 的拖拽排序能力，通过 triggerRender 为 Select 增加已选项排序功能。

自定义候选项渲染

通过传入 renderOptionItem，你可以完全接管列表中候选项的渲染，并且从回调入参中，获取到相关的状态值。

注意事项：

1. 选中（selected）、聚焦（focused）、禁用（disabled）等状态的样式需自行加上，你可以从入参中获取到相对的 boolean 值。
2. 入参的 onMouseEnter、onClick 需在 wrapper dom 上消费，否则上下键盘操作时显示会有问题。

命令式方法

通过 bind:this 拿到组件实例后，可以命令式调用 open / close / focus / selectAll / deselectAll 等方法。

API 参考

Select Props

Option 属性

<Select.Option> 组合式声明候选项支持的属性（optionList 数组中每个对象也需具备 label / value）：

OptGroup 属性

<Select.OptGroup> 组合式分组声明支持的属性（仅组合式支持，optionList 数组不支持分组）：

Methods

绑定在组件实例上的方法，可以通过 bind:this 拿到实例后调用：

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。

键盘和焦点

不带 Filter 功能的 Select：

• Select 聚焦后，键盘用户可以通过 上箭头 或 下箭头 或 Enter 键打开下拉菜单，并将焦点自动聚焦到下拉菜单中的第一个选项上（defaultActiveFirstOption 默认为 true）。
• 当下拉菜单打开时：使用 Esc 键或 Tab 键可以关闭菜单；使用 上箭头 或 下箭头 可以切换选项；被聚焦的选项可以通过 Enter 键选中，并收起面板。

带 Filter 功能的 Select：

• Select 聚焦后，键盘用户可以通过 上箭头 或 下箭头 或 Enter 键打开下拉菜单。此时焦点仍然处于 Select 框，用户可以输入内容，同时也能使用 上箭头 或 下箭头 切换选项。