FaSelect 选择器

保留 ElSelect 原生筛选、多选、创建、远程搜索和插槽能力，并增加对象数据转换、标签双向绑定、懒加载和主动刷新。

本地数据、单选、多选与标签同步

查看代码

Vue

<template>
	<div class="demo-row">
		<FaSelect
			v-model="departmentId"
			v-model:label="departmentName"
			:data="departments"
			clearable
			filterable
			placeholder="选择部门"
			style="width: 240px"
		/>
		<FaSelect
			v-model="roles"
			v-model:label="roleNames"
			:data="departments"
			multiple
			clearable
			placeholder="选择多个部门"
			style="width: 300px"
			@change="changedRoleData = $event"
		/>
	</div>
	<p style="margin: 14px 0 0; color: var(--el-text-color-secondary)">
		当前值：{{ departmentId ?? "未选择" }}；当前标签：{{ departmentName ?? "未选择" }}
	</p>
	<p style="margin: 6px 0 0; color: var(--el-text-color-secondary)">
		多选值：{{ JSON.stringify(roles) }}；多选标签：{{ JSON.stringify(roleNames) }}；change 数据：{{ JSON.stringify(changedRoleData) }}
	</p>
</template>

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

const departmentId = ref<number>();
const departmentName = ref<string | null>(null);
const roles = ref<number[]>([]);
const roleNames = ref<string[] | null>([]);
const changedRoleData = ref<unknown>();

const departments = [
	{ value: 1, label: "研发中心" },
	{ value: 2, label: "产品中心" },
	{ value: 3, label: "运营中心", disabled: true },
];
</script>

字段映射、隐藏、禁用与详情插槽

查看代码

Vue

<template>
	<FaSelect
		v-model="value"
		:data="data"
		:props="{ label: 'name', disabled: 'locked', hide: 'hidden' }"
		value-key="id"
		more-detail
		clearable
		placeholder="选择部门"
		style="max-width: 420px"
	>
		<template #default="option">
			<div class="demo-option-detail">
				<strong>{{ option.label }}</strong
				><small>{{ option["description"] }}</small>
			</div>
		</template>
	</FaSelect>
</template>

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

const value = ref<number | null>(null);
const data = [
	{ id: 1, name: "平台研发部", locked: false, description: "负责 SDK 与基础设施" },
	{ id: 2, name: "业务研发部", locked: false, description: "负责业务应用交付" },
	{ id: 3, name: "归档部门", locked: true, description: "不可继续选择" },
	{ id: 4, name: "隐藏部门", hidden: true, description: "不会出现在下拉列表" },
];
</script>

首次展开懒加载与主动刷新

查看代码

Vue

<template>
	<div class="demo-row">
		<FaSelect ref="selectRef" v-model="value" :request-api="requestApi" clearable placeholder="首次展开时加载" style="width: 300px" />
		<ElButton :loading="selectRef?.loading" @click="selectRef?.refresh()">主动刷新</ElButton>
	</div>
</template>

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

interface SelectExpose {
	loading: boolean;
	refresh: () => Promise<void>;
}

const selectRef = useTemplateRef<SelectExpose>("selectRef");
const value = ref<number | null>(null);
let loadCount = 0;

const requestApi = async (): Promise<Record<string, unknown>[]> => {
	await new Promise<void>((resolve) => {
		window.setTimeout(resolve, 450);
	});
	loadCount++;
	return [
		{ value: 1, label: `研发中心（第 ${loadCount} 次加载）` },
		{ value: 2, label: "产品中心" },
		{ value: 3, label: "运营中心" },
	];
};
</script>

FaSelect 完整 API

Props 属性 (60)

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

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

Events 事件（11）

名称	来源	说明	参数 / 类型
update:modelValue	EL 原生	更新 v-model。	—
change	EL 原生	值或选择发生变化。	—
popup-scroll	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 原生	自定义多选标签内容。	—
loading	EL 原生	自定义加载状态内容。	—
label	EL 原生	自定义表单标签、树节点标签或选择项标签。	—

Expose 暴露（9）

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

关联组件：FaSelectOption

根据 data、字段映射和显式 value、label、disabled、children 生成 ElOption 或 ElOptionGroup；显式属性优先于数据字段。

FaSelectOption 完整 API

Props 属性 (6)

属性	来源	说明	类型	默认值
value	Fast 新增	选项绑定值；显式传入时优先于 data 字段映射。	String / Number / Boolean / Object	false
label	Fast 新增	显示文本或同步标签值。	String	—
disabled	Fast 新增	是否禁用组件或当前选项。	Boolean	false
children	Fast 新增	选项分组的子选项数据。	Array	—
data	Fast 新增	组件数据。	Object	{}
moreDetail	Fast 新增	是否启用更宽的选项详情布局。	Boolean	false

Events 事件（0）

名称	来源	说明	参数 / 类型
无运行时 Emits 声明。

Slots 插槽（1）

名称	来源	说明	参数 / 类型
default(option)	Fast 新增	组件默认内容插槽。	(option)

Expose 暴露（0）

名称	来源	说明	参数 / 类型
无。

FaSelect 实例方法

focus 聚焦

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

签名

focus(): void;

示例

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

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

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

输入

该方法没有输入参数。

返回

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

blur 失焦

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

签名

blur(): void;

示例

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

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

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

输入

该方法没有输入参数。

返回

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

refresh 刷新

刷新

签名

refresh(): Promise<void>;

示例

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

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

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

输入

该方法没有输入参数。

返回

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

setSelection 勾选

设置选择

签名

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

示例

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

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

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

输入

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

返回

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

clearSelection 勾选

清除选择

签名

clearSelection(): void;

示例

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

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

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

输入

该方法没有输入参数。

返回

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