Virtualized Select 虚拟化选择器

TIP

这个组件目前在测试当中,如果在使用中发现任何漏洞和问题,请在 GitHub 中提交 issue 以便我们进行处理。

背景

在某些使用情况下,单个选择器可能最终加载数万行数据。将这么多的数据渲染至 DOM 中可能会给浏览器带来负担,从而造成性能问题。为了更好的用户和开发者体验,我们决定添加此组件。

基础用法

适用广泛的基础选择器

Please select

多选

最基础的多选选择器

Please select

尺寸

使用 size 属性改变选择器大小。除了默认大小外,还有另外两个选项: large, small。

Please select
Please select
Please select

隐藏多余标签的多选

默认情况下选中值会以 Tag 的形式展现,你也可以设置collapse-tags属性将它们合并为一段文字。您可以使用 collapse-tags-tooltip 属性来启用鼠标悬停折叠文字以显示具体所选值的行为。

use collapse-tags

Please select

use collapse-tags-tooltip

Please select

use max-collapse-tags

Please select

可过滤的多选

当选项太多时,你可以使用 filterable 选项来启用过滤功能来找到所需的选项。

Please select

禁用选择器本身或选项

您可以选择禁用 Select 或者 Select 中的某个选项。

Please select
Please select

给选项进行分组

只要数据格式满足特定要求,我们就可以按照自己的意愿为选项进行分组。

Please select

一键清除

我们可以同时清除所有选定的选项。此设定也适用于单选。

Please select
Please select

自定义选项的渲染模板

我们也可以通过自定义模板来渲染自己想要的选项内容。

Please select

自定义下拉菜单的头部 2.5.2

您可以自定义下拉菜单的头部。

使用slot 自定义内容

Select

自定义下拉菜单的底部 2.5.2

您可以自定义下拉菜单的底部。

使用slot 自定义内容

Select

创建临时选项

创建并选中未包含在初始选项中的条目。

通过使用 allow-create 属性,用户可以通过输入框创建新项目。为了使 allow-create 正常工作, filterable 的值必须为 true。本例还使用了 default-first-option 属性,在该属性为 true 的情况下,按下回车就可以选中当前选项列表中的第一个选项,无需使用鼠标或键盘方向键进行定位。

TIP

最好在使用 allow-create 属性的同时设置 :reserve-keyword="false"。

Please select
Please select

set reserve-keyword false

Please select

远程搜索

输入关键字以从远程服务器中查找数据。

从服务器搜索数据,输入关键字进行查找。为了启用远程搜索,需要将filterable和remote设置为true,同时传入一个remote-method。 remote-method为一个Function,它会在输入值发生变化时调用,参数为当前输入值。

default

Please enter a keyword

use remote-show-suffix

Please enter a keyword

使用 value-key 键属性

当 options.value 是一个对象时,您应该为它设置一个唯一的标识名称

TIP

在 2.4.0 之前,value-key既用作所选对象的唯一值,也用作options中表示值的对应 key。现在 value-key 仅作为所选对象的唯一值使用,选项中值的 key 是 props.value.

a0

自定义选项 2.4.2

当您的 options 格式不同于默认格式 您可以通过 props 属性自定义 options

Please select

自定义标签 2.5.0

您可以自定义标签。

将自定义的标签插入 el-select 的 slot 中即可。 collapse-tags, collapse-tags-tooltip, max-collapse-tags 在此模式下不生效.

自定义加载 2.5.2

修改加载区域内容

loading icon1

Please enter a keyword

loading icon2

Please enter a keyword

空值配置2.7.0

若想配置如空字符串为有效值而不是空值,可以配置 empty-values 为 [null, undefined].

如果您想要将清空值更改为 null, 请设置 value-on-clear 为 null

All

自定义标签 2.7.4

您可以自定义标签

a0: Option 1
a0: Option 1

自定义宽度 2.9.2

下拉框的宽度默认根据label的值计算。如果通过default slot自定义下拉框选项,选项中显示的文本可能与label的值不相等,从而导致计算错误。在这种情况下,可以通过设置fit-input-width属性为一个数字来固定其宽度。

Please select
Please select
Please select

API

Attributes

属性名说明类型默认值
value绑定值,对应官方 model-value / v-modelstring / number / boolean / object / array—
options选项数据,value / label 字段可通过 props 自定义array—
props选项字段别名配置,见下表object—
multiple是否多选booleanfalse
disabled是否禁用booleanfalse
valueKey对象值作为唯一标识的字段名stringvalue
size组件尺寸enum''
clearable是否可清空booleanfalse
clearIcon自定义清空图标ReactNodeCircleClose
collapseTags多选时是否将标签折叠为文本booleanfalse
multipleLimit多选可选数量上限,0 表示不限number0
id原生 input 的 idstring—
name原生 input 的 namestring—
effect浮层主题enum / stringlight
autocomplete原生 input 的 autocompletestringoff
placeholder占位文本stringPlease select
filterable是否可过滤booleanfalse
allowCreate是否允许创建新选项,需 filterable 为 truebooleanfalse
filterMethod自定义过滤方法,参数为当前输入值Function—
loading是否正在从服务端加载数据booleanfalse
loadingText加载中文案string—
reserveKeyword选中过滤项后是否保留关键词booleantrue
defaultFirstOption回车时选中第一个匹配项,配合 filterable / remotebooleanfalse
noMatchText无匹配项文案,也可用 empty 插槽string—
noDataText无选项文案,也可用 empty 插槽stringNo Data
popperClass下拉与标签浮层的自定义类名string / object''
popperStyle下拉与标签浮层的自定义样式string / object—
teleported下拉是否 teleportbooleantrue
appendTo下拉挂载目标CSSSelector / HTMLElement—
persistent不活跃时是否保留下拉 DOMbooleantrue
automaticDropdown非过滤模式下聚焦是否自动展开booleanfalse
fitInputWidth下拉宽度是否与输入框一致;传数字时固定为该宽度boolean / numbertrue
suffixIcon自定义后缀图标ReactNodeArrowDown
height下拉面板高度number274
itemHeight每项高度number34
estimatedOptionHeight动态行高估算值;传入后启用动态尺寸列表number—
scrollbarAlwaysOn是否总是显示滚动条booleanfalse
remote是否从服务端搜索数据booleanfalse
debounce远程搜索防抖时长(毫秒)number300
remoteMethod输入值变化时调用,参数为当前输入值Function—
remoteShowSuffix远程搜索时是否显示后缀图标booleanfalse
validateEvent是否触发表单校验booleantrue
offset下拉与输入框的间距number12
showArrow下拉是否显示箭头booleantrue
placement下拉位置enumbottom-start
fallbackPlacements下拉翻转兜底位置array['bottom-start', 'top-start', 'right', 'left']
collapseTagsTooltip悬停折叠文本时是否展示全部标签booleanfalse
tagTooltip折叠标签浮层配置object{}
maxCollapseTags折叠时最多展示的标签数number1
tagType标签类型enuminfo
tagEffect标签主题enumlight
ariaLabel原生 input 的 aria-labelstring—
emptyValues空值集合array—
valueOnClear清空时返回的值string / number / boolean / Function—
tabindex输入框的 tabindexstring / number—

props

属性名说明类型默认值
value选项对象中作为值的字段名stringvalue
label选项对象中作为文案的字段名stringlabel
options选项对象中作为子选项的字段名stringoptions
disabled选项对象中作为禁用态的字段名stringdisabled

tag-tooltip

tagTooltip 中显式设置的字段优先,未设置的字段继承 Select 的 effect、popperClass、popperStyle、teleported、appendTo 等配置,最后回退到 Tooltip 的默认值。

属性名说明类型默认值
appendTo浮层内容挂载目标CSSSelector / HTMLElement—
placement浮层位置enumbottom
fallbackPlacements浮层翻转兜底位置array['bottom', 'top', 'right', 'left']
effect浮层主题enum / string—
popperClass浮层自定义类名string—
popperStyle浮层自定义样式string / object—
teleported浮层是否 teleportboolean—
showAfter显示延时(毫秒)number—
hideAfter隐藏延时(毫秒)number—
autoClose自动关闭延时(毫秒)number—
offset浮层与触发元素的间距number—

Events

事件名说明类型
onChange选中值变化时触发Function
onVisibleChange下拉显示/隐藏时触发Function
onRemoveTag多选移除标签时触发,参数为被移除的值Function
onClear点击清空图标时触发Function
onBlur输入框失焦时触发Function
onFocus输入框聚焦时触发Function
onEndReached下拉滚动到边界时触发Function

Slots(React props)

名称说明类型
children选项渲染器,参数为 { item, index, disabled }Function
header下拉顶部内容ReactNode
footer下拉底部内容ReactNode
empty选项为空时的内容ReactNode
loadingSlot加载中内容(对应官方 loading 插槽)ReactNode
prefix输入框前缀内容ReactNode
tag自定义标签,参数为 { data, selectDisabled, deleteTag }Function
label自定义选中值文案,参数为 { index, label, value }Function

Exposes

名称说明类型
focus聚焦输入框Function
blur输入框失焦并收起下拉Function
scrollTo滚动到指定索引的选项Function
selectedLabel当前选中项文案,多选返回数组string / array

Type Declarations

type SelectV2Value =
  | string
  | number
  | boolean
  | Record<string, unknown>
  | unknown[]
  | null
  | undefined

interface SelectV2OptionProps {
  label?: string
  value?: string
  disabled?: string
  options?: string
}

interface SelectV2TagTooltipProps {
  appendTo?: string | HTMLElement
  placement?: Placement
  fallbackPlacements?: Placement[]
  effect?: 'dark' | 'light' | string
  popperClass?: string
  popperStyle?: CSSProperties
  teleported?: boolean
  showAfter?: number
  hideAfter?: number
  autoClose?: number
  offset?: number
}

interface SelectV2OptionRenderParams {
  item: SelectV2OptionType
  index: number
  disabled: boolean
}

interface SelectV2LabelRenderParams {
  index: number
  label: unknown
  value: unknown
}

interface SelectV2TagRenderParams {
  data: SelectV2Option[]
  selectDisabled: boolean
  deleteTag: (event: MouseEvent, option: SelectV2Option) => void
}