跳到正文

FaSelectPage 分页选择器 ​

在下拉面板内集成关键字搜索、分页和选中项回显,requestApi 使用 Fast PagedInput / PagedResult 契约。

自 2.0.28 起,#tag 获得 { data, deleteTag, selectDisabled },#label 同时获得原生 index。选项仍由 requestApi 分页提供。

服务端搜索、分页与标签回显

可操作示例
查看代码
Vue
<template>
	<div class="demo-stack">
		<FaSelectPage
			ref="selectRef"
			v-model="value"
			v-model:label="label"
			:request-api="requestApi"
			clearable
			:placeholder="english ? 'Search and paginate' : '搜索并翻页'"
			:loading-text="english ? 'Loading…' : '加载中...'"
			:no-match-text="english ? 'No matching users' : '暂无匹配的数据'"
			:no-data-text="english ? 'No users' : '暂无数据'"
			style="max-width: 420px"
			@change="changedData = $event"
		/>
		<div>
			<ElButton @click="selectRef?.focus?.()">{{ english ? "Focus" : "聚焦" }}</ElButton>
			<ElButton @click="selectRef?.blur?.()">{{ english ? "Blur" : "失焦" }}</ElButton>
			<ElButton @click="selectRef?.refresh(1)">{{ english ? "Refresh page 1" : "刷新到第一页" }}</ElButton>
		</div>
		<span class="demo-value" role="status">{{ english ? "Completed requests" : "已完成请求" }}: {{ completedRequests }}</span>
		<span class="demo-value">
			{{ english ? "Current user" : "当前用户" }}: {{ label ?? (english ? "None" : "未选择") }} ({{ value ?? "—" }}) ·
			{{ english ? "Change data" : "change 数据" }}: {{ JSON.stringify(changedData) }}
		</span>
	</div>
</template>

<script setup lang="ts">
import { computed, ref, useTemplateRef } from "vue";
import { ElButton } from "element-plus";
import { FaSelectPage } from "fast-element-plus";
import type { PagedInput, PagedResult } from "fast-element-plus";

const selectRef = useTemplateRef<InstanceType<typeof FaSelectPage>>("selectRef");
const props = defineProps<{ language?: "zh-CN" | "en-US" }>();
const english = computed(() => props.language === "en-US");
const completedRequests = ref(0);
const value = ref<number | null>(null);
const label = ref<string | null>(null);
const changedData = ref<unknown>();
const allRows = computed(() =>
	Array.from({ length: 36 }, (_, index) => ({
		value: index + 1,
		label: `${english.value ? "User" : "业务用户"} ${String(index + 1).padStart(2, "0")}`,
	}))
);

const requestApi = async (input?: PagedInput): Promise<PagedResult<Record<string, unknown>>> => {
	await new Promise<void>((resolve) => {
		window.setTimeout(resolve, 250);
	});
	const keyword = input?.searchValue?.toLowerCase() ?? "";
	const filtered = allRows.value.filter((item) => item.label.toLowerCase().includes(keyword));
	const pageIndex = input?.pageIndex ?? 1;
	const pageSize = input?.pageSize ?? 10;
	completedRequests.value++;
	return {
		pageIndex,
		pageSize,
		totalRows: filtered.length,
		rows: filtered.slice((pageIndex - 1) * pageSize, pageIndex * pageSize),
	};
};
</script>

在上方示例中可以点击「聚焦」或「刷新到第一页」,通过输入焦点和已完成请求次数确认方法执行。

FaSelectPage 完整 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""
remoteFast 修改是否启用远程搜索模式。BooleanFastfalseELfalse
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
requestApi必填Fast 新增异步数据请求函数。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{}
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 新增清除当前选择集合。—
selectedListFast 新增当前选中的完整数据对象集合。—
scrollToEL 原生 · 未透传滚动表格或虚拟列表到指定位置。—
handleCloseEL 原生 · 未透传调用 Element Plus 内部关闭处理。—

FaSelectPage 实例方法 ​

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

focus 聚焦 ​

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

签名 ​

ts
focus(): void;

示例 ​

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

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

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

输入: 无参数。

返回: void。

blur 失焦 ​

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

签名 ​

ts
blur(): void;

示例 ​

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

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

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

输入: 无参数。

返回: void。

refresh 刷新 ​

刷新

签名 ​

ts
refresh(pageIndex?: number): Promise<void>;

示例 ​

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

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

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

输入 ​

输入值输入值类型必填/默认值输入值说明
pageIndexnumber | undefined否刷新时要切换到的页码。

返回 ​

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

setSelection 勾选 ​

设置选择

签名 ​

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

示例 ​

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

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

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

输入 ​

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

返回 ​

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

clearSelection 勾选 ​

清除选择

签名 ​

ts
clearSelection(): void;

示例 ​

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

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

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

输入: 无参数。

返回: void。

状态与生命周期 ​

最新有效响应按 value 优先更新标签,旧选中项仅用于保留不在当前页的数据。清空选择或替换 initParam 时清理旧回显;卸载或请求被新版本替代后,旧响应不再更新状态。