跳到正文

FaSelect 选择器 ​

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

自 2.0.28 起,选项继续使用 data 或 requestApi,字段映射沿用 valueKey 和 props。#tag 获得 { data, deleteTag, selectDisabled },#label 获得 { label, value, index }。

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

可操作示例
查看代码
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 属性

EL 默认值取自导入 Fast 前的 Element Plus。 2.14.7

属性来源说明类型默认值
modelValueFast 修改v-model 绑定值。String / Number / Boolean / Object / ArrayFastfalseELfalse
loadingFast 修改加载状态。BooleanFastfalseELfalse
popperClassFast 修改下拉浮层的自定义类名。String / Array / Object / BooleanFast""EL""
loadingTextFast 全局增强远程数据加载期间显示的文字。StringFast加载中...EL—
noMatchTextFast 全局增强筛选没有匹配结果时显示的文字。StringFast暂无匹配的数据EL—
noDataTextFast 全局增强没有可用选项或树节点时显示的文字。StringFast暂无数据EL—
collapseTagsFast 全局增强多选时是否折叠标签。BooleanFasttrueELfalse
collapseTagsTooltipFast 全局增强是否以 Tooltip 展示折叠标签。BooleanFasttrueELfalse
propsFast 修改字段映射配置。ObjectFast{"label":"label","hide":"hide","disabled":"disabled","children":"children"}EL{"label":"label","value":"value","disabled":"disabled","options":"options"}
labelFast 新增显示文本或同步标签值。String / Array—
widthFast 新增组件宽度。String / Number100%
moreDetailFast 新增是否启用更宽的选项详情布局。Booleanfalse
lazyFast 新增是否启用懒加载。Booleantrue
defaultSelectedFast 新增是否根据当前值初始化选中项。Booleanfalse
dataFast 新增组件数据。Array[]
requestApiFast 新增异步数据请求函数。Function—
initParamFast 新增请求初始化参数。String / Number / Object—
nameEL 原生图标名称、CSS 类名或外部 SVG 地址。String—
idEL 原生组件根输入元素的原生 id。String—
autocompleteEL 原生输入框原生 autocomplete 属性。Stringoff
automaticDropdownEL 原生获得焦点后是否自动打开下拉菜单。Booleanfalse
sizeEL 原生组件尺寸。String—
effectEL 原生下拉浮层使用的 Tooltip 主题。Stringlight
disabledEL 原生是否禁用组件或当前选项。Booleanfalse
clearableEL 原生是否允许清空。Booleanfalse
filterableEL 原生是否允许筛选。Booleanfalse
allowCreateEL 原生是否允许创建新选项。Booleanfalse
popperStyleEL 原生下拉浮层根元素的自定义样式。String / Array / Object / Booleanfalse
popperOptionsEL 原生传递给 Popper 的定位配置。Object{}
remoteEL 原生是否启用远程搜索模式。Booleanfalse
debounceEL 原生远程搜索输入的防抖时间,单位毫秒。Number300
remoteMethodEL 原生远程搜索关键字变化时调用的数据加载函数。Function—
filterMethodEL 原生本地筛选选项时调用的过滤函数。Function—
multipleEL 原生是否允许多选。Booleanfalse
multipleLimitEL 原生多选模式允许选择的最大项目数,0 表示不限制。Number0
placeholderEL 原生占位提示。String—
defaultFirstOptionEL 原生按 Enter 时是否默认选择首个匹配选项。Booleanfalse
reserveKeywordEL 原生多选远程搜索选中项目后是否保留关键字。Booleantrue
valueKeyEL 原生选项值为对象时用于唯一标识选项的字段名。Stringvalue
tagTooltipEL 原生折叠标签 Tooltip 的自定义配置。Object{}
maxCollapseTagsEL 原生折叠多选标签前最多保留的标签数量。Number1
teleportedEL 原生是否将下拉浮层传送到 appendTo 指定的容器。Booleantrue
persistentEL 原生下拉浮层隐藏后是否保留在 DOM 中。Booleantrue
clearIconEL 原生清空按钮使用的图标组件。String / Object / Function{"name":"CircleClose","__name":"circle-close"}
fitInputWidthEL 原生下拉浮层宽度是否至少与输入框一致。Booleanfalse
suffixIconEL 原生选择器右侧显示的后缀图标组件。String / Object / Function{"name":"ArrowDown","__name":"arrow-down"}
tagTypeEL 原生多选标签使用的 Element Plus 类型。Stringinfo
tagEffectEL 原生多选标签使用的 Element Plus 主题效果。Stringlight
validateEventEL 原生模型值变化时是否触发表单校验。Booleantrue
remoteShowSuffixEL 原生远程搜索模式下是否显示选择器后缀图标。Booleanfalse
showArrowEL 原生下拉浮层是否显示指向触发元素的箭头。Booleantrue
offsetEL 原生偏移量或浮层偏移。Number12
placementEL 原生下拉浮层相对触发元素的首选位置。Stringbottom-start
fallbackPlacementsEL 原生首选位置空间不足时依次尝试的浮层位置。Array["bottom-start","top-start","right","left"]
tabindexEL 原生组件输入元素的原生 tabindex。String / Number0
appendToEL 原生浮层挂载目标。String / Object—
optionsEL 原生虚拟选择器的选项数据。Array—
emptyValuesEL 原生视为空值的模型值集合。Array—
valueOnClearEL 原生清空时写入模型的值或值生成函数。String / Number / Boolean / Functionfalse
ariaLabelEL 原生组件面向辅助技术的可访问名称。String—

Events 事件

名称来源说明参数 / 类型
update:modelValueEL 原生更新 v-model。—
changeEL 原生值或选择发生变化。—
popup-scrollEL 原生选择器下拉列表滚动时触发。—
end-reachedEL 原生选择器滚动到下拉列表边界时触发。—
remove-tagEL 原生多选模式移除标签时触发,参数为被移除的值。—
visible-changeEL 原生选择器下拉浮层显示状态变化时触发。—
focusEL 原生组件获得焦点时触发。—
blurEL 原生组件失去焦点时触发。—
clearEL 原生点击清空按钮并完成清空时触发。—
update:labelFast 新增更新标签绑定值。—
dataChangeFast 新增异步数据加载完成时触发。—

Slots 插槽

名称来源说明参数 / 类型
defaultEL 原生组件默认内容插槽。—
headerEL 原生自定义头部内容或表格头部业务区域。—
footerEL 原生自定义底部操作区域;弹层中可获得 loading 和 close。—
prefixEL 原生自定义选择器输入框前缀内容。—
emptyEL 原生组件无数据时的自定义内容。—
tagEL 原生自定义多选标签内容。—
loadingEL 原生自定义加载状态内容。—
labelEL 原生自定义表单标签、树节点标签或选择项标签。—

实例成员

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

关联组件:FaSelectOption ​

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

从 2.0.28 起,普通选项可通过 created 向底层 ElOption 传递创建状态。

FaSelectOption 完整 API

Props 属性

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

Slots 插槽

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

FaSelect 实例方法 ​

以下代码为调用片段。行、选项和字段应对应实际数据。

focus 聚焦 ​

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

签名 ​

ts
focus(): void;

示例 ​

vue
<template>
	<FaSelect ref="componentRef" />
	<button type="button" @click="handleExample">调用方法</button>
</template>

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

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

输入: 无参数。

返回: void。

blur 失焦 ​

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

签名 ​

ts
blur(): void;

示例 ​

vue
<template>
	<FaSelect ref="componentRef" />
	<button type="button" @click="handleExample">调用方法</button>
</template>

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

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

输入: 无参数。

返回: void。

refresh 刷新 ​

刷新

签名 ​

ts
refresh(): Promise<void>;

示例 ​

vue
<template>
	<FaSelect ref="componentRef" />
	<button type="button" @click="handleExample">调用方法</button>
</template>

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

const componentRef = ref<InstanceType<typeof FaSelect>>();
async function handleExample() {
	const result = await componentRef.value?.refresh();
	console.log(result);
}
</script>

输入 ​

该方法没有输入参数。

返回 ​

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

setSelection 勾选 ​

设置选择

签名 ​

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

示例 ​

vue
<template>
	<FaSelect ref="componentRef" />
	<button type="button" @click="handleExample">调用方法</button>
</template>

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

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

输入 ​

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

返回 ​

返回值返回值类型返回值说明
resultvoid没有返回值。

clearSelection 勾选 ​

清除选择

签名 ​

ts
clearSelection(): void;

示例 ​

vue
<template>
	<FaSelect ref="componentRef" />
	<button type="button" @click="handleExample">调用方法</button>
</template>

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

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

输入: 无参数。

返回: void。