FaSelectPage 分页选择器
在下拉面板内集成关键字搜索、分页和选中项回显,requestApi 使用 Fast PagedInput / PagedResult 契约。
自 2.0.28 起,#tag 获得 { data, deleteTag, selectDisabled },#label 同时获得原生 index。选项仍由 requestApi 分页提供。
服务端搜索、分页与标签回显
可操作示例查看代码
<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
| 属性 | 来源 | 说明 | 类型 | 默认值 |
|---|---|---|---|---|
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 |
loadingText | Fast 全局增强 | 远程数据加载期间显示的文字。 | String | Fast加载中...EL— |
noMatchText | Fast 全局增强 | 筛选没有匹配结果时显示的文字。 | String | Fast暂无匹配的数据EL— |
noDataText | Fast 全局增强 | 没有可用选项或树节点时显示的文字。 | String | Fast暂无数据EL— |
collapseTags | Fast 全局增强 | 多选时是否折叠标签。 | Boolean | FasttrueELfalse |
collapseTagsTooltip | Fast 全局增强 | 是否以 Tooltip 展示折叠标签。 | Boolean | FasttrueELfalse |
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 |
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 |
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 事件
| 名称 | 来源 | 说明 | 参数 / 类型 |
|---|---|---|---|
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 插槽
| 名称 | 来源 | 说明 | 参数 / 类型 |
|---|---|---|---|
default | EL 原生 | 组件默认内容插槽。 | — |
header | EL 原生 | 自定义头部内容或表格头部业务区域。 | — |
footer | EL 原生 | 自定义底部操作区域;弹层中可获得 loading 和 close。 | — |
prefix | EL 原生 | 自定义选择器输入框前缀内容。 | — |
empty | EL 原生 | 组件无数据时的自定义内容。 | — |
tag | EL 原生 | 自定义多选标签内容。 | — |
loading | EL 原生 | 自定义加载状态内容。 | — |
label | EL 原生 | 自定义表单标签、树节点标签或选择项标签。 | — |
实例成员
| 名称 | 来源 | 说明 | 参数 / 类型 |
|---|---|---|---|
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 聚焦
使选择器的输入框获取焦点
签名
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>输入
| 输入值 | 输入值类型 | 必填/默认值 | 输入值说明 |
|---|---|---|---|
pageIndex | number | undefined | 否 | 刷新时要切换到的页码。 |
返回
| 返回值 | 返回值类型 | 返回值说明 |
|---|---|---|
result | Promise<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>输入
| 输入值 | 输入值类型 | 必填/默认值 | 输入值说明 |
|---|---|---|---|
value | ElSelectorValue | ElSelectorValue[] | 是 | 要设置的表单值、选择值或过滤关键字。 |
返回
| 返回值 | 返回值类型 | 返回值说明 |
|---|---|---|
result | void | 没有返回值。 |
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 时清理旧回显;卸载或请求被新版本替代后,旧响应不再更新状态。
