FaSelectPage 分页选择器

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

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

查看代码

Vue

<template>
	<div class="demo-stack">
		<FaSelectPage
			v-model="value"
			v-model:label="label"
			:request-api="requestApi"
			clearable
			placeholder="搜索并翻页"
			style="max-width: 420px"
			@change="changedData = $event"
		/>
		<span class="demo-value">当前用户：{{ label ?? "未选择" }}（{{ value ?? "—" }}）；change 数据：{{ JSON.stringify(changedData) }}</span>
	</div>
</template>

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

const value = ref<number | null>(null);
const label = ref<string | null>(null);
const changedData = ref<unknown>();
const allRows = Array.from({ length: 36 }, (_, index) => ({ value: index + 1, label: `业务用户 ${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.filter((item) => item.label.toLowerCase().includes(keyword));
	const pageIndex = input?.pageIndex ?? 1;
	const pageSize = input?.pageSize ?? 10;
	return {
		pageIndex,
		pageSize,
		totalRows: filtered.length,
		rows: filtered.slice((pageIndex - 1) * pageSize, pageIndex * pageSize),
	};
};
</script>

FaSelectPage 完整 API

Props 属性 (57)

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""
remote	Fast 修改	是否启用远程搜索模式。	Boolean	FastfalseELfalse
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
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	{}
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 暴露（10）

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

FaSelectPage 实例方法

focus 聚焦

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

签名

focus(): void;

示例

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

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

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

输入

该方法没有输入参数。

返回

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

blur 失焦

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

签名

blur(): void;

示例

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

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

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

输入

该方法没有输入参数。

返回

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

refresh 刷新

刷新

签名

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

示例

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

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

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

输入

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

返回

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

setSelection 勾选

设置选择

签名

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

示例

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

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

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

输入

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

返回

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

clearSelection 勾选

清除选择

签名

clearSelection(): void;

示例

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

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

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

输入

该方法没有输入参数。

返回

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

状态与生命周期

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