FaSelectV2 虚拟选择器

适用于大数据量虚拟列表，支持本地数据、远程数据、分页结果、自定义选项、标签同步和主动刷新。选项的实际高度与虚拟列表偏移均服从 itemHeight。

千条数据虚拟滚动、多选与自定义选项

查看代码

Vue

<template>
	<div class="demo-stack">
		<FaSelectV2
			v-model="value"
			v-model:label="label"
			:data="data"
			multiple
			filterable
			more-detail
			clearable
			placeholder="从 1000 项中筛选"
			style="max-width: 480px"
			@change="changedData = $event"
		>
			<template #default="{ item }">
				<div class="demo-option-detail">
					<strong>{{ item.label }}</strong
					><small>{{ item["group"] }}</small>
				</div>
			</template>
		</FaSelectV2>
		<span class="demo-value"
			>值：{{ JSON.stringify(value) }}；标签：{{ JSON.stringify(label) }}；change 数据：{{ JSON.stringify(changedData) }}</span
		>
	</div>
</template>

<script setup lang="ts">
import { ref } from "vue";

const value = ref<number[]>([]);
const label = ref<string[] | null>([]);
const changedData = ref<unknown>();
const data = Array.from({ length: 1000 }, (_, index) => ({
	value: index + 1,
	label: `虚拟选项 ${String(index + 1).padStart(4, "0")}`,
	group: `分组 ${Math.floor(index / 100) + 1}`,
}));
</script>

FaSelectV2 完整 API

Props 属性 (65)

Fast 与 Element Plus 2.14.6 的属性已合并展示；Fast 修改项优先排列，未透传的原生属性保留用于兼容性核对。

属性	来源	说明	类型	默认值
collapseTags	Fast 修改	多选时是否折叠标签。	Boolean	FasttrueELfalse
collapseTagsTooltip	Fast 修改	是否以 Tooltip 展示折叠标签。	Boolean	FasttrueELfalse
itemHeight	Fast 修改	虚拟列表选项高度。	Number	Fast34EL34
loading	Fast 修改	加载状态。	Boolean	FastfalseELfalse
loadingText	Fast 修改	远程数据加载期间显示的文字。	String	Fast加载中...EL—
modelValue	Fast 修改	v-model 绑定值。	String / Number / Boolean / Object / Array	FastfalseELfalse
noDataText	Fast 修改	没有可用选项或树节点时显示的文字。	String	Fast暂无数据EL—
noMatchText	Fast 修改	筛选没有匹配结果时显示的文字。	String	Fast暂无匹配的数据EL—
options	Fast 修改	虚拟选择器的选项数据。	Array	Fast—EL—
popperClass	Fast 修改	下拉浮层的自定义类名。	String	Fast""ELfalse
props	Fast 修改	字段映射配置。	Object	Fast{"label":"label","value":"value","disabled":"disabled","options":"options"}EL{"label":"label","value":"value","disabled":"disabled","options":"options"}
label	Fast 新增	显示文本或同步标签值。	String / Array	—
width	Fast 新增	组件宽度。	String / Number	100%
moreDetail	Fast 新增	是否启用更宽的选项详情布局。	Boolean	false
lazy	Fast 新增	是否启用懒加载。	Boolean	true
defaultSelected	Fast 新增	是否根据当前值初始化选中项。	Boolean	false
data	Fast 新增	组件数据。	Array	[]
pageResult	Fast 新增	分页数据。	Boolean	false
requestApi	Fast 新增	异步数据请求函数。	Function	—
initParam	Fast 新增	请求初始化参数。	String / Number / Object	—
allowCreate	EL 原生	是否允许创建新选项。	Boolean	false
autocomplete	EL 原生	输入框原生 autocomplete 属性。	String	none
automaticDropdown	EL 原生	获得焦点后是否自动打开下拉菜单。	Boolean	false
clearable	EL 原生	是否允许清空。	Boolean	false
clearIcon	EL 原生	清空按钮使用的图标组件。	String / Object / Function	{"name":"CircleClose","__name":"circle-close"}
effect	EL 原生	下拉浮层使用的 Tooltip 主题。	String	light
tagTooltip	EL 原生	折叠标签 Tooltip 的自定义配置。	Object	{}
maxCollapseTags	EL 原生	折叠多选标签前最多保留的标签数量。	Number	1
defaultFirstOption	EL 原生	按 Enter 时是否默认选择首个匹配选项。	Boolean	false
disabled	EL 原生	是否禁用组件或当前选项。	Boolean	false
estimatedOptionHeight	EL 原生	Controls virtual-list sizing mode: if undefined, the list uses fixed item height from item-height; if provided, the list uses dynamic item sizing and this value as the estimated item height.	Number	—
filterable	EL 原生	是否允许筛选。	Boolean	false
filterMethod	EL 原生	本地筛选选项时调用的过滤函数。	Function	—
height	EL 原生	组件高度。	Number	274
id	EL 原生	组件根输入元素的原生 id。	String	—
multiple	EL 原生	是否允许多选。	Boolean	false
multipleLimit	EL 原生	多选模式允许选择的最大项目数，0 表示不限制。	Number	0
name	EL 原生	图标名称、CSS 类名或外部 SVG 地址。	String	—
remoteMethod	EL 原生	远程搜索关键字变化时调用的数据加载函数。	Function	—
reserveKeyword	EL 原生	多选远程搜索选中项目后是否保留关键字。	Boolean	true
placeholder	EL 原生	占位提示。	String	—
teleported	EL 原生	是否将下拉浮层传送到 appendTo 指定的容器。	Boolean	true
persistent	EL 原生	下拉浮层隐藏后是否保留在 DOM 中。	Boolean	true
popperStyle	EL 原生	下拉浮层根元素的自定义样式。	String / Array / Object / Boolean	false
popperOptions	EL 原生	传递给 Popper 的定位配置。	Object	{}
remote	EL 原生	是否启用远程搜索模式。	Boolean	false
debounce	EL 原生	远程搜索输入的防抖时间，单位毫秒。	Number	300
size	EL 原生	组件尺寸。	String	—
valueKey	EL 原生	选项值为对象时用于唯一标识选项的字段名。	String	value
scrollbarAlwaysOn	EL 原生	Controls whether the scrollbar is always displayed	Boolean	false
validateEvent	EL 原生	模型值变化时是否触发表单校验。	Boolean	true
offset	EL 原生	偏移量或浮层偏移。	Number	12
remoteShowSuffix	EL 原生	远程搜索模式下是否显示选择器后缀图标。	Boolean	false
showArrow	EL 原生	下拉浮层是否显示指向触发元素的箭头。	Boolean	true
placement	EL 原生	下拉浮层相对触发元素的首选位置。	String	bottom-start
fallbackPlacements	EL 原生	首选位置空间不足时依次尝试的浮层位置。	Array	["bottom-start","top-start","right","left"]
tagType	EL 原生	多选标签使用的 Element Plus 类型。	String	info
tagEffect	EL 原生	多选标签使用的 Element Plus 主题效果。	String	light
tabindex	EL 原生	组件输入元素的原生 tabindex。	String / Number	0
appendTo	EL 原生	浮层挂载目标。	String	—
fitInputWidth	EL 原生	下拉浮层宽度是否至少与输入框一致。	Boolean / Number	true
suffixIcon	EL 原生	选择器右侧显示的后缀图标组件。	String / Object / Function	{"name":"ArrowDown","__name":"arrow-down"}
emptyValues	EL 原生	视为空值的模型值集合。	Array	—
valueOnClear	EL 原生	清空时写入模型的值或值生成函数。	String / Number / Boolean / Function	false
ariaLabel	EL 原生	组件面向辅助技术的可访问名称。	String	—

Events 事件（10）

名称	来源	说明	参数 / 类型
update:modelValue	EL 原生	更新 v-model。	—
change	EL 原生	值或选择发生变化。	—
end-reached	EL 原生	选择器滚动到下拉列表边界时触发。	—
remove-tag	EL 原生	多选模式移除标签时触发，参数为被移除的值。	—
visible-change	EL 原生	选择器下拉浮层显示状态变化时触发。	—
focus	EL 原生	组件获得焦点时触发。	—
blur	EL 原生	组件失去焦点时触发。	—
clear	EL 原生	点击清空按钮并完成清空时触发。	—
update:label	Fast 新增	更新标签绑定值。	—
dataChange	Fast 新增	异步数据加载完成时触发。	—

Slots 插槽（8）

名称	来源	说明	参数 / 类型
default	EL 原生	组件默认内容插槽。	—
header	EL 原生	自定义头部内容或表格头部业务区域。	—
footer	EL 原生	自定义底部操作区域；弹层中可获得 loading 和 close。	—
prefix	EL 原生	自定义选择器输入框前缀内容。	—
empty	EL 原生	组件无数据时的自定义内容。	—
tag	EL 原生	自定义多选标签内容。	{ data: Option[], selectDisabled: boolean, deleteTag: (event: MouseEvent, option: Option) => void }
loading	EL 原生	自定义加载状态内容。	—
label	EL 原生	自定义表单标签、树节点标签或选择项标签。	{ index: number, label: string | any, value: string | any }

Expose 暴露（9）

名称	来源	说明	参数 / 类型
focus	EL 原生	让输入或选择组件获得焦点。	—
blur	EL 原生	让输入或选择组件失去焦点。	—
selectedLabel	EL 原生	选择器当前显示的标签文本。	—
loading	Fast 新增	Fast 业务加载状态。	—
refresh	Fast 新增	重新执行组件数据请求或刷新业务内容。	—
setSelection	Fast 新增	设置选择器的选中值及标签。	—
clearSelection	Fast 新增	清除当前选择集合。	—
scrollTo	EL 原生	滚动表格或虚拟列表到指定位置。	—
resetScrollTop	EL 原生 · 未透传	将虚拟选择器滚动位置重置到顶部。	—

FaSelectV2 实例方法

focus 聚焦

使选择器的输入框获取焦点

签名

focus(): void;

示例

<template>
	<FaSelectV2 ref="componentRef" />
</template>

<script setup lang="ts">
import { ref } from "vue";
import { FaSelectV2 } from "fast-element-plus";

const componentRef = ref<InstanceType<typeof FaSelectV2>>();
componentRef.value?.focus();
</script>

输入

该方法没有输入参数。

返回

返回值	返回值类型	返回值说明
result	void	没有返回值。

blur 失焦

使选择器的输入框失去焦点，并隐藏下拉框

签名

blur(): void;

示例

<template>
	<FaSelectV2 ref="componentRef" />
</template>

<script setup lang="ts">
import { ref } from "vue";
import { FaSelectV2 } from "fast-element-plus";

const componentRef = ref<InstanceType<typeof FaSelectV2>>();
componentRef.value?.blur();
</script>

输入

该方法没有输入参数。

返回

返回值	返回值类型	返回值说明
result	void	没有返回值。

scrollTo 滚动

滚动到指定选项索引。

签名

scrollTo(index: number): void;

示例

<template>
	<FaSelectV2 ref="componentRef" />
</template>

<script setup lang="ts">
import { ref } from "vue";
import { FaSelectV2 } from "fast-element-plus";

const componentRef = ref<InstanceType<typeof FaSelectV2>>();
componentRef.value?.scrollTo(120);
</script>

输入

输入值	输入值类型	必填/默认值	输入值说明
index	number	是	从零开始的选项索引。

返回

返回值	返回值类型	返回值说明
result	void	没有返回值。

refresh 刷新

刷新

签名

refresh(): Promise<void>;

示例

<template>
	<FaSelectV2 ref="componentRef" />
</template>

<script setup lang="ts">
import { ref } from "vue";
import { FaSelectV2 } from "fast-element-plus";

const componentRef = ref<InstanceType<typeof FaSelectV2>>();
const result = await componentRef.value?.refresh();
</script>

输入

该方法没有输入参数。

返回

返回值	返回值类型	返回值说明
result	Promise<void>	异步完成后的结果；Promise 拒绝时由调用方处理。

setSelection 勾选

设置选择

签名

setSelection(value: Exclude<ElSelectorModelValue, null | undefined>): void;

示例

<template>
	<FaSelectV2 ref="componentRef" />
</template>

<script setup lang="ts">
import { ref } from "vue";
import { FaSelectV2 } from "fast-element-plus";

const componentRef = ref<InstanceType<typeof FaSelectV2>>();
componentRef.value?.setSelection(1);
</script>

输入

输入值	输入值类型	必填/默认值	输入值说明
value	ElSelectorValue | ElSelectorValue[]	是	要设置的表单值、选择值或过滤关键字。

返回

返回值	返回值类型	返回值说明
result	void	没有返回值。

clearSelection 勾选

清除选择

签名

clearSelection(): void;

示例

<template>
	<FaSelectV2 ref="componentRef" />
</template>

<script setup lang="ts">
import { ref } from "vue";
import { FaSelectV2 } from "fast-element-plus";

const componentRef = ref<InstanceType<typeof FaSelectV2>>();
componentRef.value?.clearSelection();
</script>

输入

该方法没有输入参数。

返回

返回值	返回值类型	返回值说明
result	void	没有返回值。