选择器 Select

基本用法

选择器的基本用法。通过 trigger-props 属性自定义下拉框的属性，比如可以让下拉框自动适应最小宽度。

自定义触发元素

使用 #trigger 插槽替换默认选择框，例如改为点击按钮打开下拉菜单。插槽直接提供 value、displayValue、inputValue、selectedOptions、popupVisible、disabled、 loading 和 multiple，无需在外部重新查找选项或拼接展示文本。

无边框模式

设置 bordered="false" 开启无边框模式，常用于沉浸式使用。

允许清除

通过设置 allow-clear ，显示清除按钮。

允许创建

通过设置 allow-create ，让选择器可以创建选项中不存在的条目。

回退选项

使用 fallback-option 自定义选项中不存在的值，默认会在输入框中展示不存在的选项值。可能用于选项还没有获取完，或者远程搜索时选项改变了。

自定义字段名

可以通过 field-names 属性自定义 options 中数据的格式，支持同时映射 value、label 和分组使用的 children 字段。

下拉菜单的页脚

自定义下拉菜单的页脚

分组

通过 options 中使用 isGroup: true 的对象添加分组选项。

下拉菜单的页头

自定义下拉菜单的页头

自定义选择框展示内容

通过 #label 插槽可以自定义选择框展示内容。

联动选择框

展示联动选择框的实现方法。

加载中

选择框和下拉菜单显示加载中状态。

多选选择器

通过设置 multiple ，可以让选择器支持多选。此外通过 max-tag-count 可以设置最多显示的标签个数。

远程搜索

使用 search 事件进行远程搜索，并改变选项。

下拉菜单滚动

可以通过 dropdown-scroll 监听下拉菜单的滚动事件。或者通过 dropdown-reach-bottom 监听下拉菜单滚动到底部的事件。

允许搜索

通过设置 allow-search ，可以让选择器支持对选项的搜索，配合 filter-option 可以自定义搜索。

选项文本省略

默认情况下，每个选项都会使用 Ellipsis 处理溢出文本。选项数量较多、开启虚拟列表或需要减少文本测量开销时，可以设置 ellipsis="performant-ellipsis"；设置 :ellipsis="false" 可关闭内置省略。使用 #option 插槽后，选项内容完全由插槽控制。

选择框大小

选择框分为 mini、small、medium、large 四种尺寸。

虚拟列表

当前示例同时展示了两种推荐写法：直接传空对象，观察 Select 默认补齐的固定 36px 行高；或者显式传 itemSize，让配置更直观。对于大多数下拉场景，只要提供弹层高度，默认固定高度模式就足够了。

通过 virtual-list-props 开启虚拟列表。Select 的下拉项当前默认按固定高度处理：如果你没有显式传 itemSize 或 minItemSize，组件会按 36px 选项高度补齐固定模式；如果要手动指定固定高度，请传 itemSize；只有显式传 minItemSize 时，才会切到动态高度模式。完整参数可参考 LLMs.txt。

API

<select> Props

参数名	描述	类型	默认值	版本
multiple	是否开启多选模式（多选模式默认开启搜索）	boolean	false
model-value (v-model)	绑定值	string| number| boolean| Record<string, unknown>| (string | number | boolean | Record<string, unknown>)[] | null	-
default-value	默认值（非受控模式）	string| number| boolean| Record<string, unknown>| (string | number | boolean | Record<string, unknown>)[]	'' | []
input-value (v-model)	输入框的值	string	-
default-input-value	输入框的默认值（非受控模式）	string	''
size	选择框的大小	'mini' | 'small' | 'medium' | 'large'	'medium'
placeholder	占位符	string	-
fit-width	宽度是否适应文字内容	boolean	false
max-w-full	最大宽度是否限制为父容器宽度	boolean	true
loading	是否为加载中状态	boolean	false
spin-props	传递给下拉加载中 Spin 的属性	SpinProps	-
disabled	是否禁用	boolean	false
error	是否为错误状态	boolean	false
ellipsis	是否使用 Ellipsis 渲染默认选项；performant-ellipsis 使用高性能实现，false 关闭	boolean | 'performant-ellipsis'	true
allow-clear	是否允许清空	boolean	true
allow-search	是否允许搜索	boolean | { retainInputValue?: boolean }	true
allow-create	是否允许创建	boolean	false
max-tag-count	多选模式下，最多显示的标签数量。responsive 会自动收敛为组件当前支持的展示模式	number | 'responsive'	'responsive'
popup-container	弹出框的挂载容器	string | HTMLElement	-
bordered	是否显示输入框的边框	boolean	true
default-active-first-option	是否在无值时默认选择第一个选项	boolean	true	2.43.0
popup-visible (v-model)	是否显示下拉菜单	boolean	-
default-popup-visible	弹出框默认是否可见（非受控模式）	boolean	false
unmount-on-close	是否在下拉菜单关闭时销毁元素	boolean	false
filter-option	是否过滤选项	boolean | ((inputValue: string, option: SelectOptionData) => boolean)	true
options	选项数据	(string | number | boolean | SelectOptionData | SelectOptionGroup)[]	[]
virtual-list-props	传递虚拟列表属性，传入此参数以开启虚拟滚动	VirtualListProps	-
trigger-props	下拉菜单的触发器属性	TriggerProps	-
fallback-option	自定义值中不存在的选项	boolean| (( value: string | number | boolean | Record<string, unknown> ) => SelectOptionData)	true	2.10.0
show-extra-options	是否在下拉菜单中显示额外选项	boolean	true	2.10.0
value-key	用于确定选项键值的属性名	string	'value'	2.18.0
search-delay	触发搜索事件的延迟时间	number	500	2.18.0
limit	多选时最多的选择个数	number	0	2.18.0
field-names	自定义 SelectOptionData 中的字段	SelectFieldNames	-	2.22.0
scrollbar	是否开启虚拟滚动条	boolean | ScrollbarProps	true	2.38.0
show-header-on-empty	空状态时是否显示header	boolean	false
show-footer-on-empty	空状态时是否显示footer	boolean	false
tag-nowrap	标签内容不换行	boolean	false	2.56.1

<select> Events

事件名	描述	参数	版本
change	值发生改变时触发	value: string | number | boolean | Record<string, unknown> | (string | number | boolean | Record<string, unknown>)[] | null
input-value-change	输入框的值发生改变时触发	inputValue: string
popup-visible-change	下拉框的显示状态改变时触发	visible: boolean
clear	点击清除按钮时触发	-
remove	点击标签的删除按钮时触发	removed: string | number | boolean | Record<string, unknown> | undefined
search	用户搜索时触发	inputValue: string
dropdown-scroll	下拉菜单发生滚动时触发	-
dropdown-reach-bottom	下拉菜单滚动到底部时触发	-
exceed-limit	多选超出限制时触发	value: string | number | boolean | Record<string, unknown> | undefined ev: Event	2.18.0

<select> Slots

插槽名	描述	参数	版本
trigger	自定义触发元素	SelectTriggerSlotProps	2.22.0
prefix	前缀元素	-	2.22.0
search-icon	选择框的搜索图标	-	2.16.0
loading-icon	选择框的加载中图标	-	2.16.0
arrow-icon	选择框的箭头图标	-	2.16.0
footer	下拉框的页脚	-
header	下拉框的页头	-	2.43.0
label	选择框的显示内容	data: SelectOptionData
tag	多选标签的显示内容	data: SelectOptionData
option	选项内容	data: SelectOptionData
empty	选项为空时的显示内容	-

Type

/**
 * @zh 选项
 * @en Option
 */
type Option = string | number | SelectOptionData | SelectOptionGroup;

/**
 * @zh 筛选
 * @en Filter
 */
type FilterOption = boolean | ((inputValue: string, option: SelectOptionData) => boolean);

SelectOptionData

参数名	描述	类型	默认值
value	选项值	string | number | boolean | Record<string, unknown>	-
label	选项内容	string	-
disabled	是否禁用	boolean	false
tagProps	选项对应的多选标签的属性	Record<string, unknown>	-

SelectOptionGroup

参数名	描述	类型	默认值
isGroup	是否为选项组	true	-
label	选项组标题	string	-
options	选项组中的选项	SelectOption[]	-

VirtualListProps

参数名	描述	类型	默认值	版本
items	列表数据	unknown[]	[]
keyField	用于提取每项唯一键，支持字段名或函数	string | ((item, index) => string | number)	'key'
itemSize	固定高度模式的 item 高度，传入后作为初始尺寸提示	number | string | ((item, index) => number)	-
minItemSize	动态高度模式的最小 item 高度；未传 itemSize 时用于初始估算	number | string	32
buffer	额外渲染缓冲区（像素）	number	200

其余参数与暴露方法可参考 LLMs.txt。

FAQ

使用 Object 格式作为选项的值

当使用 Object 格式作为选项的值时，需要通过 value-key 属性为选择器指定获取唯一标识的字段名，默认值为 value。此外 value 的对象值需要在 setup 中定义好，不能够在模版中创建对象，这样会导致重复渲染。

例如当我需要指定 key 为唯一标识时：

<template>
  <sd-select
    v-model="value"
    :style="{ width: '320px' }"
    placeholder="Please select ..."
    value-key="key"
    :options="options"
  />
</template>

<script setup>
  import { ref } from 'vue';

  const value = ref();
  const options = [
    {
      value: 'beijing',
      label: 'Beijing',
      key: 'extra1',
    },
    {
      value: 'shanghai',
      label: 'Shanghai',
      key: 'extra2',
    },
    {
      value: 'guangzhou',
      label: 'Guangzhou',
      key: 'extra3',
    },
    {
      value: 'chengdu',
      label: 'Chengdu',
      key: 'extra4',
    },
  ];
</script>

滚动容器中的下拉菜单分离问题

Select 组件默认没有开启容器滚动的事件监听功能，如果遇到在滚动容器中下拉菜单分离的问题，可以手动开启内部 Trigger 组件的 updateAtScroll 功能。如果是在全局环境中存在此种情况，可以使用 ConfigProvider 组件默认开启此属性。

<sd-select :trigger-props="{ updateAtScroll: true }"></sd-select>