FaTable 表格
FaTable 在 Element Plus 表格上集成搜索表单、分页、远程请求、列设置和行选择。
自 2.0.28 起,style 应用于 FaTable 外层容器,#append 在传入时才渲染。empty-text 可替换内置空态文案。FaTableColumn 的 #filterIcon 可接收 filterOpened,#expand 可读取 expanded 和 expandable。列的 show-overflow-tooltip 支持透传配置对象。
常用示例
基础用法
本地数据、关键字搜索、复制、标签与日期列
可操作示例查看代码
<template>
<FaTable :data="rows" :pagination="false" :tool-btn="false" hide-search-time>
<FaTableColumn prop="name" label="项目" min-width="180" copy />
<FaTableColumn prop="owner" label="负责人" width="120" />
<FaTableColumn prop="status" label="状态" width="100" tag :enum="statusOptions" />
<FaTableColumn prop="createdTime" label="创建时间" type="dateTime" width="180" />
</FaTable>
</template>
<script setup lang="ts">
import type { FaTableEnumColumnCtx } from "fast-element-plus";
const rows = [
{ id: 1, name: "Fast Admin", status: 1, owner: "小方", createdTime: "2026-08-20 09:30:00" },
{ id: 2, name: "Fast Element Plus", status: 1, owner: "Fast 团队", createdTime: "2026-08-22 14:10:00" },
{ id: 3, name: "Fast.NET", status: 0, owner: "SDK 团队", createdTime: "2026-08-25 18:20:00" },
];
const statusOptions: FaTableEnumColumnCtx[] = [
{ label: "停用", value: 0, type: "danger" },
{ label: "启用", value: 1, type: "success" },
];
</script>远程分页
示例用本地数据模拟接口。requestApi 接收分页和搜索参数,返回的 rows 是当前页,totalRows 是符合条件的总条数。实际接入可运行跨包分页示例,遇到问题可查阅排错步骤。
远程搜索、分页、列设置与响应式搜索表单
可操作示例查看代码
<template>
<FaTable :request-api="requestApi" :columns="columns" column-setting-btn>
<template v-if="english" #empty>No rows found</template>
</FaTable>
</template>
<script setup lang="ts">
import { computed } from "vue";
import type { FaTableColumnCtx, FaTableEnumColumnCtx, PagedInput, PagedResult } from "fast-element-plus";
const props = defineProps<{ language?: "zh-CN" | "en-US" }>();
const english = computed(() => props.language === "en-US");
const statuses = computed<FaTableEnumColumnCtx[]>(() => [
{ label: english.value ? "Inactive" : "停用", value: 0, type: "danger" },
{ label: english.value ? "Active" : "启用", value: 1, type: "success" },
]);
const allRows = computed(() => {
const owners = english.value ? ["Platform", "Business", "SDK"] : ["平台组", "业务组", "SDK 组"];
return Array.from({ length: 57 }, (_, index) => ({
id: index + 1,
name: `${english.value ? "Module" : "业务模块"} ${String(index + 1).padStart(2, "0")}`,
owner: owners[index % owners.length],
status: index % 4 === 0 ? 0 : 1,
createdTime: `2026-08-${String((index % 26) + 1).padStart(2, "0")} 10:30:00`,
}));
});
const columns = computed<FaTableColumnCtx[]>(() => [
{ prop: "name", label: english.value ? "Module name" : "模块名称", minWidth: 180, copy: true, search: { el: "el-input", order: 3 } },
{ prop: "owner", label: english.value ? "Owner" : "负责人", width: 120, search: { el: "el-input", order: 2 } },
{ prop: "status", label: english.value ? "Status" : "状态", width: 100, tag: true, enum: statuses.value, search: { el: "el-select", order: 1 } },
{ prop: "createdTime", label: english.value ? "Created at" : "创建时间", type: "dateTime", width: 180 },
]);
const requestApi = async (input?: PagedInput): Promise<PagedResult<Record<string, unknown>>> => {
await new Promise<void>((resolve) => {
window.setTimeout(resolve, 300);
});
let result = allRows.value;
for (const key of ["name", "owner", "status"] satisfies Array<keyof (typeof allRows.value)[number]>) {
const value: unknown = input?.[key];
if (value === undefined || value === null || value === "") continue;
if (typeof value !== "string" && typeof value !== "number" && typeof value !== "boolean") continue;
result = result.filter((row) => String(row[key]).includes(String(value)));
}
const pageIndex = input?.pageIndex ?? 1;
const pageSize = input?.pageSize ?? 20;
return {
pageIndex,
pageSize,
totalRows: result.length,
rows: result.slice((pageIndex - 1) * pageSize, pageIndex * pageSize),
};
};
</script>行选择
单选、整行选择与禁用行
可操作示例查看代码
<template>
<div class="demo-stack">
<FaTable
:data="rows"
:pagination="false"
:tool-btn="false"
hide-search-time
selection-column
single
row-click-selection
:row-selectable="handleRowSelectable"
@selection-change="handleSelectionChange"
>
<FaTableColumn prop="name" label="名称" min-width="180" />
<FaTableColumn prop="locked" label="是否锁定" width="120">
<template #default="{ row }"
><ElTag :type="row['locked'] ? 'danger' : 'success'">{{ row["locked"] ? "锁定" : "可选" }}</ElTag></template
>
</FaTableColumn>
</FaTable>
<span class="demo-value">当前单选:{{ selectedNames.join("、") || "未选择" }}</span>
</div>
</template>
<script setup lang="ts">
import { ref } from "vue";
import type { DefaultRow } from "fast-element-plus";
const selectedNames = ref<string[]>([]);
const rows = [
{ id: 1, name: "可选择记录", locked: false },
{ id: 2, name: "锁定记录", locked: true },
{ id: 3, name: "点击整行选择", locked: false },
];
const handleRowSelectable = (row: DefaultRow): boolean => !row["locked"];
const handleSelectionChange = (selection: DefaultRow[]): void => {
selectedNames.value = selection.map((item) => String(item["name"]));
};
</script>高级表格场景
树形表格与默认展开
可操作示例查看代码
<template>
<FaTable :data="rows" default-expand-all :pagination="false" :tool-btn="false" hide-search-time>
<FaTableColumn prop="name" label="模块" min-width="220" />
<FaTableColumn prop="owner" label="负责团队" min-width="160" />
</FaTable>
</template>
<script setup lang="ts">
const rows = [
{
id: 1,
name: "组件",
owner: "前端团队",
children: [
{ id: 11, name: "表单组件", owner: "表单小组" },
{ id: 12, name: "表格组件", owner: "数据小组" },
],
},
{
id: 2,
name: "SDK",
owner: "平台团队",
children: [{ id: 21, name: "Fast.NET", owner: "SDK 小组" }],
},
];
</script>Element Plus 原生树表只需要提供 row-key 和 children 数据,不要设置 tree-data;Fast 的 treeData 用于把分组数据的子项展开为普通表格行。
展开行、自定义内容与展开事件
可操作示例查看代码
<template>
<div class="demo-stack">
<FaTable :data="rows" :pagination="false" :tool-btn="false" hide-search-time @expand-change="handleExpand">
<template #expand="{ row }">
<div v-if="row">
<strong>{{ row["name"] }}</strong>
<p style="margin: 6px 0 0">{{ row["description"] }}</p>
</div>
</template>
<FaTableColumn prop="name" label="项目" min-width="200" />
<FaTableColumn prop="owner" label="负责团队" min-width="140" />
</FaTable>
<span class="demo-value">已展开:{{ expandedNames.join("、") || "无" }}</span>
</div>
</template>
<script setup lang="ts">
import { ref } from "vue";
const expandedNames = ref<string[]>([]);
const rows = [
{ id: 1, name: "Fast.Element.Plus", owner: "Fast 团队", description: "面向团队编码习惯封装的 Element Plus 业务组件库。" },
{ id: 2, name: "Fast.NET", owner: "SDK 团队", description: "Fast 系列 .NET SDK 基础能力。" },
{ id: 3, name: "Fast.Admin", owner: "平台团队", description: "后台管理与权限业务应用。" },
];
const handleExpand = (row: Record<string, unknown>, expanded: boolean | Record<string, unknown>[]): void => {
const name = String(row["name"]);
if (Array.isArray(expanded)) {
expandedNames.value = expanded.map((item) => String(item["name"]));
} else if (expanded) {
expandedNames.value = [...new Set([...expandedNames.value, name])];
} else {
expandedNames.value = expandedNames.value.filter((item) => item !== name);
}
};
</script>固定列、状态筛选、远程排序与内容提示
可操作示例查看代码
<template>
<FaTable :data="rows" :pagination="false" :tool-btn="false" height="320" hide-search-time border @sort-change="handleSort">
<FaTableColumn prop="name" label="名称" min-width="230" fixed show-overflow-tooltip />
<FaTableColumn prop="owner" label="负责人" width="110" />
<FaTableColumn
prop="status"
label="状态筛选"
width="130"
:filters="[
{ text: '进行中', value: '进行中' },
{ text: '已完成', value: '已完成' },
{ text: '已暂停', value: '已暂停' },
]"
:filter-method="filterStatus"
/>
<FaTableColumn prop="visits" label="访问量排序" width="140" sortable align="right" />
<FaTableColumn label="固定操作" width="110" fixed="right">
<template #default="{ row }"
><ElButton link type="primary">查看 {{ row["id"] }}</ElButton></template
>
</FaTableColumn>
</FaTable>
</template>
<script setup lang="ts">
import { ref } from "vue";
interface RowData {
id: number;
name: string;
owner: string;
status: string;
visits: number;
}
const sourceRows: RowData[] = [
{ id: 1, name: "Fast.Element.Plus 文档与案例建设", owner: "小方", status: "进行中", visits: 1860 },
{ id: 2, name: "Fast.NET SDK", owner: "研发组", status: "已完成", visits: 5320 },
{ id: 3, name: "Fast.Admin 权限中心", owner: "平台组", status: "进行中", visits: 2980 },
{ id: 4, name: "移动端业务门户", owner: "前端组", status: "已暂停", visits: 920 },
];
const rows = ref([...sourceRows]);
const filterStatus = (value: unknown, row: Record<string, unknown>): boolean => row["status"] === value;
const handleSort = ({ prop, order }: { order: "" | "ascending" | "descending"; prop: string }): void => {
if (!order) {
rows.value = [...sourceRows];
return;
}
const key = prop as keyof RowData;
const direction = order === "ascending" ? 1 : -1;
rows.value = [...sourceRows].sort((left, right) => {
const leftValue = Number(left[key]);
const rightValue = Number(right[key]);
return leftValue === rightValue ? 0 : leftValue > rightValue ? direction : -direction;
});
};
</script>头部、工具、操作、页脚插槽与 Expose
可操作示例查看代码
<template>
<FaTable ref="tableRef" :data="rows" :pagination="false" hide-search-time>
<template #header><ElTag type="primary">自定义头部插槽</ElTag></template>
<template #toolButton>
<ElButton type="primary" @click="tableRef?.refresh()">刷新</ElButton>
<ElButton @click="tableRef?.reset()">重置</ElButton>
</template>
<FaTableColumn prop="name" label="项目" min-width="180" />
<FaTableColumn prop="version" label="版本" width="120" />
<template #operation="{ row }"><ElButton link type="primary" @click="ElMessage.info(`查看 ${String(row['name'])}`)">查看</ElButton></template>
<template #footer
><div class="demo-value">表格 Loading:{{ tableRef?.loading ? "是" : "否" }}</div></template
>
</FaTable>
</template>
<script setup lang="ts">
import { useTemplateRef } from "vue";
import { ElMessage } from "element-plus";
import { version } from "fast-element-plus";
interface TableExpose {
loading: boolean;
refresh: () => Promise<void>;
reset: () => Promise<void>;
}
const tableRef = useTemplateRef<TableExpose>("tableRef");
const rows = [
{ id: 1, name: "Fast.Element.Plus", version },
{ id: 2, name: "Fast.NET.Core", version: "3.5.42" },
];
</script>更新懒加载节点
懒加载并替换子行
可操作示例查看代码
<template>
<div class="demo-stack">
<ElButton :disabled="!isLoaded" @click="handleReplace">替换子行</ElButton>
<FaTable ref="tableRef" :data="rows" row-key="id" lazy :load="handleLoad" :pagination="false" :tool-btn="false" hide-search-time>
<FaTableColumn prop="name" label="节点" />
</FaTable>
</div>
</template>
<script setup lang="ts">
import { ref, useTemplateRef } from "vue";
import { ElButton } from "element-plus";
import { FaTable, FaTableColumn } from "fast-element-plus";
import type { DefaultRow } from "fast-element-plus";
const tableRef = useTemplateRef<{ updateKeyChildren: (key: string, data: DefaultRow[]) => void }>("tableRef");
const isLoaded = ref(false);
const rows = [{ id: "parent", name: "父行", hasChildren: true }];
function handleLoad(_row: DefaultRow, _node: unknown, resolve: (rows: DefaultRow[]) => void) {
resolve([{ id: "original", name: "初始子行" }]);
isLoaded.value = true;
}
function handleReplace() {
tableRef.value?.updateKeyChildren("parent", [{ id: "replacement", name: "替换后的子行" }]);
}
</script>FaTable 完整 API
Props 属性
EL 默认值取自导入 Fast 前的 Element Plus。 2.14.7
| 属性 | 来源 | 说明 | 类型 | 默认值 |
|---|---|---|---|---|
data | Fast 修改 | 组件数据。 | Array | Fast[]EL[] |
size | Fast 修改 | 组件尺寸。 | String | Fast—EL— |
height | Fast 修改 | 组件高度。 | String / Number | Fast—EL— |
border | Fast 全局增强 | 是否显示表格边框。 | Boolean | FasttrueELfalse |
rowKey | Fast 全局增强 | 行或节点唯一键。 | String / Function | FastidEL— |
highlightCurrentRow | Fast 全局增强 | 是否高亮当前行。 | Boolean | FasttrueELfalse |
tableKey | Fast 新增 | 表格实例及持久化配置使用的唯一标识。 | String | 运行时生成 |
requestApi | Fast 新增 | 异步数据请求函数。 | (params?: PagedInput) => Promise<PagedResult<DefaultRow> | DefaultRow[]> | — |
dataCallback | Fast 新增 | 表格请求数据完成后的转换或回调函数。 | (data: PagedResult<DefaultRow> | DefaultRow[]) => void | — |
initParam | Fast 新增 | 请求初始化参数。 | String / Number / Object | — |
columns | Fast 新增 | 表格列配置。 | Array / Boolean | false |
columnsChange | Fast 新增 | 列设置变化回调。 | Function | — |
searchFormCols | Fast 新增 | 搜索表单响应式列数。 | String / Number / Object | {"xs":2,"sm":3,"md":4,"lg":5,"xl":6} |
collapsedSearch | Fast 新增 | 是否默认折叠表格搜索条件。 | Boolean | true |
advancedSearchDrawer | Fast 新增 | 是否在 Drawer 中展示高级搜索条件。 | Boolean | false |
searchForm | Fast 新增 | 搜索表单初始值。 | Boolean | true |
headerCard | Fast 新增 | 表格头部是否使用卡片容器样式。 | Boolean | true |
refreshBtn | Fast 新增 | 是否显示刷新按钮。 | Boolean | true |
searchBtn | Fast 新增 | 是否显示搜索按钮。 | Boolean | true |
columnSettingBtn | Fast 新增 | 是否显示列设置按钮。 | Boolean | false |
toolBtn | Fast 新增 | 是否显示表格工具按钮区域。 | Boolean | true |
hideSearchTime | Fast 新增 | 是否隐藏默认时间搜索项。 | Boolean | false |
futureSearchTime | Fast 新增 | 时间搜索是否允许选择未来日期。 | Boolean | false |
dataSearchRange | Fast 新增 | 表格默认时间搜索范围。 | String | Past3D |
selectionColumn | Fast 新增 | 是否显示内置选择列,默认 false(2.0.23 起)。 | Boolean | false |
indexColumn | Fast 新增 | 是否显示内置序号列,默认 true(2.0.23 起)。 | Boolean | true |
pagination | Fast 新增 | 是否显示分页或分页配置。 | Boolean | true |
pageSizes | Fast 新增 | 分页可选每页数量。 | Array | [20,30,50,100] |
hideImage | Fast 新增 | 是否隐藏图片列预览。 | Boolean | false |
single | Fast 新增 | 是否使用单选表格模式。 | Boolean | false |
rowClickSelection | Fast 新增 | 点击行时是否切换选择。 | Boolean | false |
treeData | Fast 新增 | 将每个父项的 children 展开为表格行,并把父项字段合并到子项;Element Plus 树表展开无需启用。 | Boolean | false |
props | Fast 新增 | 字段映射配置。 | Object | {"children":"children"} |
autoRefresh | Fast 新增 | 是否按配置自动刷新。 | Boolean | true |
rowSelectable | Fast 新增 | 判断表格行是否允许选择的函数。 | Function | — |
width | EL 原生 | 组件宽度。 | String / Number | — |
maxHeight | EL 原生 | 表格的最大高度,可传像素数值或带 px 单位的字符串。 | String / Number | — |
fit | EL 原生 | 内容如何适应容器。 | Boolean | true |
stripe | EL 原生 | 是否显示斑马纹。 | Boolean | false |
showHeader | EL 原生 | 是否显示表头。 | Boolean | true |
showSummary | EL 原生 | 是否在表尾显示合计行。 | Boolean | false |
sumText | EL 原生 | 合计行第一列显示的文字。 | String | — |
summaryMethod | EL 原生 | 自定义合计行各列的计算方法。 | Function | — |
rowClassName | EL 原生 | 为所有行指定类名,或通过回调逐行返回类名。 | String / Function | — |
rowStyle | EL 原生 | 为所有行指定样式,或通过回调逐行返回样式。 | Object / Function | — |
cellClassName | EL 原生 | 为所有单元格指定类名,或通过回调逐格返回类名。 | String / Function | — |
cellStyle | EL 原生 | 为所有单元格指定样式,或通过回调逐格返回样式。 | Object / Function | — |
headerRowClassName | EL 原生 | 表头行的类名,可统一指定或通过回调逐行返回。 | String / Function | — |
headerRowStyle | EL 原生 | 表头行的样式,可统一指定或通过回调逐行返回。 | Object / Function | — |
headerCellClassName | EL 原生 | 表头单元格的类名,可统一指定或通过回调逐格返回。 | String / Function | — |
headerCellStyle | EL 原生 | 表头单元格的样式,可统一指定或通过回调逐格返回。 | Object / Function | — |
currentRowKey | EL 原生 | 设置当前行的键,仅用于写入。 | String / Number | — |
emptyText | EL 原生 | 空数据提示文字。 | String | — |
expandRowKeys | EL 原生 | 指定需要展开的行键。使用前需设置 row-key。 | Array | — |
rowExpandable | EL 原生 | 判断某行能否展开的回调,在启用展开列时生效。 | Function | — |
defaultExpandAll | EL 原生 | 是否默认展开全部节点。 | Boolean | false |
defaultSort | EL 原生 | 初始排序规则,prop 指定排序字段,order 指定排序方向。 | Object | — |
tooltipEffect | EL 原生 | 内容溢出提示的主题。 | String | — |
tooltipOptions | EL 原生 | 内容溢出时的 Tooltip 配置。 | Object | — |
spanMethod | EL 原生 | 按单元格返回跨行和跨列数量的回调。FaTable 的合并行为以列配置为准。 | Function | — |
selectOnIndeterminate | EL 原生 | 部分行已选中时,点击表头复选框是否全选。为 false 时取消全选。 | Boolean | true |
indent | EL 原生 | 相邻树层级之间的水平缩进像素。 | Number | 16 |
treeProps | EL 原生 | 树形行数据的字段映射配置。 | Object | {"hasChildren":"hasChildren","children":"children","checkStrictly":false} |
lazy | EL 原生 | 是否启用懒加载。 | Boolean | false |
load | EL 原生 | 树节点懒加载函数。 | Function | — |
style | EL 原生 | 表格单元格或表头单元格的自定义样式。 | Object | {} |
className | EL 原生 | 表格单元格或表头单元格的自定义类名。 | String | "" |
tableLayout | EL 原生 | 表格行、列和单元格使用的布局算法。 | String | fixed |
scrollbarAlwaysOn | EL 原生 | 是否始终显示表格滚动条。 | Boolean | false |
flexible | EL 原生 | 避免表格在弹性布局的主轴上被内容最小尺寸撑开。 | Boolean | false |
showOverflowTooltip | EL 原生 | 内容溢出时在悬停提示中显示。表级配置应用到各列。 | Boolean / Object | false |
tooltipFormatter | EL 原生 | 格式化溢出提示显示的内容。 | Function | — |
appendFilterPanelTo | EL 原生 | 列筛选面板的挂载元素。 | String | — |
scrollbarTabindex | EL 原生 | 表格正文滚动容器的 tabindex。 | Number / String | — |
allowDragLastColumn | EL 原生 | 是否允许拖动调整最后一列的宽度。 | Boolean | true |
preserveExpandedContent | EL 原生 | 折叠展开行后是否仍将其内容保留在 DOM 中。 | Boolean | false |
nativeScrollbar | EL 原生 | 是否使用浏览器原生滚动条。 | Boolean | false |
Events 事件
| 名称 | 来源 | 说明 | 参数 / 类型 |
|---|---|---|---|
select | EL 原生 | 选择行或选项时触发。 | — |
selectAll | EL 原生 | 表格全选状态变化时触发,参数为当前选择行。 | — |
selectionChange | EL 原生 | 表格选择集合变化时触发。 | (newSelection: DefaultRow[]) |
cellMouseEnter | EL 原生 | 鼠标进入单元格时触发。 | — |
cellMouseLeave | EL 原生 | 鼠标离开单元格时触发。 | — |
cellClick | EL 原生 | 点击单元格时触发,参数为行、列、单元格和原生事件。 | — |
cellDblclick | EL 原生 | 双击单元格时触发。 | — |
cellContextmenu | EL 原生 | 右键点击单元格时触发。 | — |
rowClick | EL 原生 | 点击表格行时触发,参数与 ElTable row-click 一致。 | — |
rowContextmenu | EL 原生 | 右键点击表格行时触发。 | — |
rowDblclick | EL 原生 | 双击表格行时触发。 | — |
headerClick | EL 原生 | 点击表头单元格时触发。 | — |
headerContextmenu | EL 原生 | 右键点击表头单元格时触发。 | — |
sortChange | EL 原生 | 表格排序条件变化时触发。 | (data: { column: TableColumnCtx<DefaultRow>; prop: string; order: "" | "ascending" | "descending" }) |
filterChange | EL 原生 | 表格筛选条件变化时触发。 | — |
currentChange | EL 原生 | 表格当前行、树当前节点或选择值变化时触发。 | — |
headerDragend | EL 原生 | 拖动表头改变列宽结束时触发。 | — |
expandChange | EL 原生 | 表格行展开状态变化时触发。 | — |
scroll | EL 原生 | 表格或选择器滚动时触发。 | — |
refresh | Fast 新增 | 刷新数据时触发。 | — |
reset | Fast 新增 | 重置搜索条件时触发。 | — |
sizeChange | Fast 新增 | 表格每页条数变化时触发。 | — |
paginationChange | Fast 新增 | 表格页码或每页条数变化时触发。 | — |
customCellClick | Fast 新增 | 点击 Fast 链接列时触发,参数为自定义事件名和当前单元格上下文。 | — |
Slots 插槽
| 名称 | 来源 | 说明 | 参数 / 类型 |
|---|---|---|---|
default | EL 原生 | 组件默认内容插槽。 | — |
append | EL 原生 | 在表格最后一行之后追加自定义内容。 | — |
empty | EL 原生 | 组件无数据时的自定义内容。 | — |
topHeader | Fast 新增 | 自定义表格最顶部内容。 | — |
header | Fast 新增 | 自定义头部内容或表格头部业务区域。 | — |
toolButton | Fast 新增 | 自定义表格常用工具按钮区域。 | — |
toolButtonAdv | Fast 新增 | 自定义表格高级工具按钮区域。 | — |
expand({ row, column, $index, ...tableContext }) | Fast 新增 | 自定义展开行内容;提供插槽即启用展开列(2.0.23 起),参数包含 row、column、$index 和表格上下文。 | ({ row, column, $index, ...tableContext }) |
operation | Fast 新增 | 自定义表格操作列内容。 | — |
pagination | Fast 新增 | 自定义表格分页区域。 | — |
footer | Fast 新增 | 自定义底部操作区域;弹层中可获得 loading 和 close。 | — |
columnSetting | Fast 新增 | 自定义表格列设置区域。 | — |
动态命名列/搜索插槽 | Fast 新增 | 按列 slot、headerSlot 或搜索字段名动态生成的业务插槽。 | — |
实例成员
| 名称 | 来源 | 说明 | 参数 / 类型 |
|---|---|---|---|
clearSelection | EL 原生 | 清除当前选择集合。 | — |
getSelectionRows | EL 原生 | 获取表格当前选中的行。 | — |
getHalfSelectionRows | Fast 新增 | 获取树形表格中处于半选状态的行。 | — |
toggleRowSelection | EL 原生 | 切换指定表格行的选中状态。 | — |
toggleAllSelection | EL 原生 | 切换表格全选状态。 | — |
toggleRowExpansion | EL 原生 | 切换指定表格行的展开状态。 | — |
setCurrentRow | EL 原生 | 设置表格当前高亮行。 | — |
clearSort | EL 原生 | 清除表格排序状态。 | — |
clearFilter | EL 原生 | 清除表格列筛选条件。 | — |
doLayout | EL 原生 | 重新计算表格布局。 | — |
sort | EL 原生 | 按指定列和顺序执行表格排序。 | — |
scrollTo | EL 原生 | 滚动表格或虚拟列表到指定位置。 | — |
setScrollTop | EL 原生 | 设置表格纵向滚动位置。 | — |
setScrollLeft | EL 原生 | 设置表格横向滚动位置。 | — |
columns | EL 原生 | ElTable 当前渲染的列上下文集合。 | — |
updateKeyChildren | EL 原生 | 按节点 key 更新树或树形表格的子节点。 | — |
loading | Fast 新增 | Fast 业务加载状态。 | — |
tableData | Fast 新增 | 表格当前渲染的数据集合。 | — |
tablePagination | Fast 新增 | 表格当前分页状态。 | — |
searchParam | Fast 新增 | 表格当前提交给请求函数的搜索参数。 | — |
selected | Fast 新增 | 表格是否存在选中行。 | — |
selectedList | Fast 新增 | 当前选中的完整数据对象集合。 | — |
selectedListIds | Fast 新增 | 当前选中行的主键集合。 | — |
indeterminateSelectedListIds | Fast 新增 | 树形表格中半选行的主键集合。 | — |
tableWidth | Fast 新增 | 表格计算后的可用宽度。 | — |
tableHeight | Fast 新增 | 表格计算后的可用高度。 | — |
toggleRowIndeterminateSelection | Fast 新增 | 切换树形表格行的半选状态。 | — |
refresh | Fast 新增 | 重新执行组件数据请求或刷新业务内容。 | — |
reset | Fast 新增 | 重置表格搜索条件、分页和数据。 | — |
doRender | Fast 新增 | 强制重新计算并渲染表格内容。 | — |
doLoading | Fast 新增 | 在统一 Loading 和遮罩状态下执行同步或异步函数。 | — |
FaTableColumn API
除 ElTableColumn 原生列能力外,提供图片、日期、时间、精度数值、千分位、复制、链接、标签、合并行和时间信息等业务列类型。
prop 支持使用点分隔的嵌套字段路径,例如 profile.name、profile.createdTime。默认、日期/时间、数值、链接、标签、枚举和图片列都会按完整路径读取行数据,本地排序也使用相同路径解析规则。
图片、链接、复制、数值、枚举与日期列
可操作示例查看代码
<template>
<FaTable :data="rows" :pagination="false" :tool-btn="false" hide-search-time>
<FaTableColumn prop="details.image" label="图片" type="image" original-image width="90" />
<FaTableColumn prop="details.name" label="名称" min-width="180" copy link :click="handleLinkClick" />
<FaTableColumn prop="amount" label="千分位" type="gd2" width="130" align="right" />
<FaTableColumn prop="ratio" label="六位小数" type="d6" width="120" align="right" />
<FaTableColumn prop="status" label="枚举标签" tag :enum="statuses" width="100" />
<FaTableColumn prop="details.createdTime" label="日期时间" type="dateTime" width="180" />
</FaTable>
</template>
<script setup lang="ts">
import { ElMessage } from "element-plus";
import type { FaTableEnumColumnCtx } from "fast-element-plus";
const image = `data:image/svg+xml;charset=UTF-8,${encodeURIComponent(
'<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 120 80"><rect width="120" height="80" rx="8" fill="#409eff"/><text x="60" y="48" text-anchor="middle" font-size="20" fill="white">Fast</text></svg>'
)}`;
const rows = [
{
id: 1,
details: { name: "Fast.Element.Plus", image, createdTime: "2026-08-26 09:30:00" },
amount: 12345.6,
ratio: 0.876543,
status: 1,
},
{
id: 2,
details: { name: "Fast.NET", image, createdTime: "2026-08-25 16:20:00" },
amount: 9876543.21,
ratio: 0.123456,
status: 0,
},
];
const statuses: FaTableEnumColumnCtx[] = [
{ label: "停用", value: 0, type: "danger" },
{ label: "启用", value: 1, type: "success" },
];
const handleLinkClick = ({ row }: { row: Record<string, unknown> }): void => {
ElMessage.info(`Row ${String(row["id"])}`);
};
</script>图片缩略图、原图预览、隐藏图片与空值占位
可操作示例查看代码
<template>
<FaTable :data="rows" :pagination="false" :tool-btn="false" hide-search-time>
<FaTableColumn prop="cover" label="缩略图与预览" type="image" original-image width="130" />
<FaTableColumn prop="cover" label="隐藏缩略图" type="image" hide-image width="130" />
<FaTableColumn prop="name" label="资源名称" min-width="180" />
</FaTable>
</template>
<script setup lang="ts">
const createImage = (text: string, color: string): string =>
`data:image/svg+xml;charset=UTF-8,${encodeURIComponent(
`<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 320 200"><rect width="320" height="200" rx="20" fill="${color}"/><circle cx="70" cy="70" r="32" fill="rgba(255,255,255,.32)"/><path d="M30 170 105 105l48 42 42-32 95 55" fill="none" stroke="white" stroke-width="16" stroke-linecap="round" stroke-linejoin="round"/><text x="250" y="58" text-anchor="middle" font-size="30" fill="white">${text}</text></svg>`
)}`;
const rows = [
{ id: 1, name: "项目封面", cover: createImage("封面", "#409eff") },
{ id: 2, name: "产品截图", cover: createImage("截图", "#67c23a") },
{ id: 3, name: "无图片占位", cover: "" },
];
</script>通过 columns 给部门列设置 spanProp: "department",相邻且部门相同的两行会共用一个部门单元格,工作事项和操作信息仍逐行显示。
在 2.0.27 中,只配置业务列的 spanProp 时,内置序号可能重复。本例用 :index-column="false" 关闭内置序号列。
相同数据合并与操作时间信息列
可操作示例查看代码
<template>
<FaTable :data="rows" :columns="columns" :pagination="false" :tool-btn="false" :index-column="false" hide-search-time border />
</template>
<script setup lang="ts">
import { computed } from "vue";
import { FaTable } from "fast-element-plus";
import type { FaTableColumnCtx } from "fast-element-plus";
const props = defineProps<{ language?: string }>();
const english = computed(() => props.language === "en-US");
const columns = computed<FaTableColumnCtx[]>(() => [
{ prop: "department", label: english.value ? "Department (merged)" : "部门(自动合并)", spanProp: "department", minWidth: 150 },
{ prop: "name", label: english.value ? "Task" : "工作事项", minWidth: 180 },
{ prop: "createdTime", label: english.value ? "Activity" : "操作信息", type: "timeInfo", minWidth: 240 },
]);
const rows = computed(() => [
{
id: 1,
department: english.value ? "Engineering" : "研发中心",
name: english.value ? "Maintain components" : "组件库维护",
createdUserName: "Fang",
createdTime: "2026-08-27 09:20:00",
},
{
id: 2,
department: english.value ? "Engineering" : "研发中心",
name: english.value ? "Build the docs site" : "文档站建设",
createdUserName: english.value ? "Frontend team" : "前端组",
createdTime: "2026-08-27 10:35:00",
},
{
id: 3,
department: english.value ? "Product" : "产品中心",
name: english.value ? "Review requirements" : "需求评审",
createdUserName: english.value ? "Product team" : "产品组",
createdTime: "2026-08-26 16:10:00",
},
]);
</script>Fast 列类型
| 类型 | 用途 |
|---|---|
default | 默认业务列 |
image | 图片与预览列 |
date、time、dateTime | 日期、时间和日期时间格式化 |
d2、d4、d6 | 固定 2、4、6 位小数 |
gd2、gd4、gd6 | 带千分位的固定精度数值 |
timeInfo | 用户和时间信息组合展示 |
Props 属性
EL 默认值取自导入 Fast 前的 Element Plus。 2.14.7
| 属性 | 来源 | 说明 | 类型 | 默认值 |
|---|---|---|---|---|
type | Fast 修改 | Fast 业务列类型。 | String | FastdefaultELdefault |
width | Fast 修改 | 组件宽度。 | String / Number | FastautoEL"" |
align | Fast 修改 | 当前列单元格的对齐方式。 | String | FastleftEL— |
headerAlign | Fast 修改 | 当前列表头的对齐方式,省略时使用 align。 | String | FastleftEL— |
show | Fast 新增 | 是否显示当前表格列或布局项。 | Boolean | false |
smallWidth | Fast 新增 | 小尺寸模式下的表格列宽度。 | String / Number | — |
autoWidth | Fast 新增 | 是否根据单元格内容自动计算表格列宽。 | Boolean | false |
slot | Fast 新增 | 自定义表格单元格使用的命名插槽。 | String | — |
headerSlot | Fast 新增 | 自定义表格列头使用的命名插槽。 | String | — |
headerRender | Fast 新增 | 使用 TSX 自定义表格列头的渲染函数。 | Function | — |
render | Fast 新增 | 使用 TSX 自定义表格单元格的渲染函数。 | Function | — |
_children | Fast 新增 | 多级表头的子列配置。 | Array | — |
hideImage | Fast 新增 | 是否隐藏图片列预览。 | Boolean | false |
copy | Fast 新增 | 是否显示单元格复制操作。 | Boolean | false |
link | Fast 新增 | 将单元格显示为链接按钮。 | Boolean | false |
spanProp | Fast 新增 | 计算表格纵向合并行时使用的字段名。 | String | — |
click | Fast 新增 | 链接列点击回调,参数包含当前行和行索引。 | Function | — |
clickEmit | Fast 新增 | 链接列点击时触发的自定义事件名称。 | String | — |
originalImage | Fast 新增 | 图片列是否使用原图地址进行展示和预览。 | Boolean | false |
dateFix | Fast 新增 | 日期列是否同时显示相对时间标签。 | Boolean | false |
dateFormat | Fast 新增 | 日期列的自定义格式化模板。 | String | — |
tag | Fast 新增 | 将单元格显示为枚举标签。 | Boolean | false |
enum | Fast 新增 | 枚举字典、字典名称或按行返回字典的函数。 | String / Array / Function | — |
dataDeleteField | Fast 新增 | 标记逻辑删除状态的字段名,命中后单元格显示删除遮罩。 | String | — |
timeInfoField | Fast 新增 | 时间信息列中用户名和时间字段的映射。 | Object | {"userName":"createdUserName","time":"createdTime"} |
label | EL 原生 | 显示文本或同步标签值。 | String | — |
className | EL 原生 | 表格单元格或表头单元格的自定义类名。 | String | — |
labelClassName | EL 原生 | 当前列表头的自定义类名。 | String | — |
property | EL 原生 | 表格列对应的数据字段,语义与 prop 相同。 | String | — |
prop | EL 原生 | 此列读取的行字段,也可使用 property 指定。 | String | — |
minWidth | EL 原生 | 列的最小宽度。表格有剩余空间时可按比例分配给此类列。 | String / Number | "" |
renderHeader | EL 原生 | 自定义当前列的表头渲染函数。 | Function | — |
sortable | EL 原生 | 是否允许排序。使用 custom 并监听 sort-change 可接入远程排序。 | Boolean / String | false |
sortMethod | EL 原生 | 自定义比较函数,返回值规则与 Array.sort 一致。 | Function | — |
sortBy | EL 原生 | 指定本地排序字段。使用数组时按字段顺序逐项比较。配置 sortMethod 后以比较函数为准。 | String / Function / Array | — |
resizable | EL 原生 | 是否允许调整 Drawer 尺寸。 | Boolean | true |
columnKey | EL 原生 | 用于标识列的键,筛选事件可用它定位被筛选的列。 | String | — |
showOverflowTooltip | EL 原生 | 当前列的单元格溢出时是否显示悬停提示。 | Boolean / Object | false |
tooltipFormatter | EL 原生 | 格式化当前列溢出提示显示的内容。 | Function | — |
fixed | EL 原生 | 将列固定在左侧或右侧。设为 true 时固定在左侧。 | Boolean / String | false |
formatter | EL 原生 | 显示值格式化函数。 | Function | — |
selectable | EL 原生 | 判断某行能否勾选的回调,仅适用于选择列。 | Function | — |
reserveSelection | EL 原生 | 刷新数据后是否保留选择,需设置 row-key,仅适用于选择列。 | Boolean | false |
filterMethod | EL 原生 | 本地筛选选项时调用的过滤函数。 | Function | — |
filteredValue | EL 原生 | 当前选中的筛选值。 | Array | — |
filters | EL 原生 | 列筛选选项,每项需包含 text 和 value。 | Array | — |
filterPlacement | EL 原生 | 列筛选面板的弹出位置。 | String | — |
filterMultiple | EL 原生 | 列筛选是否允许多选。 | Boolean | true |
filterClassName | EL 原生 | 列筛选面板的自定义类名。 | String | — |
index | EL 原生 | 自定义序号列的编号,仅适用于 type 为 index 的列。 | Number / Function | — |
sortOrders | EL 原生 | 点击列头时依次切换的排序状态。 | Array | ["ascending","descending",null] |
Events 事件
| 名称 | 来源 | 说明 | 参数 / 类型 |
|---|---|---|---|
imagePreview | Fast 新增 | 打开图片预览时触发,参数为图片地址。 | — |
customCellClick | Fast 新增 | 点击 Fast 链接列时触发,参数为自定义事件名和当前单元格上下文。 | — |
Slots 插槽
| 名称 | 来源 | 说明 | 参数 / 类型 |
|---|---|---|---|
default(scope) | EL 原生 | 自定义表格单元格内容,参数包含行、列和行索引。 | (scope) |
header(scope) | EL 原生 | 自定义表格列头,参数包含列和列索引。 | (scope) |
filter-icon | EL 原生 · 未透传 | 自定义列筛选图标。 | { filterOpened: boolean } |
expand | EL 原生 · 未透传 | 自定义展开列内容,Element Plus 2.13.2 起支持 expandable 插槽参数。 | { expanded: boolean, expandable: boolean } |
其他关联组件
FaTableColumnsSettingDialog
FaTable 内部的列设置弹窗,由 columnSettingBtn 控制显示。通过每行左侧的拖动手柄调整列顺序;触屏操作需要短按后拖动,避免滚动列表时误排序。它依赖 FaTable 提供的状态,只应通过 FaTable.TableColumnsSettingDialog 或 FaTable 内部流程使用。
Props 属性
| 属性 | 来源 | 说明 | 类型 | 默认值 |
|---|---|---|---|---|
change | Fast 新增 | 列配置发生变化后调用的保存回调。 | Function | — |
实例成员
| 名称 | 来源 | 说明 | 参数 / 类型 |
|---|---|---|---|
open | Fast 新增 | 执行 Fast 异步打开流程。 | — |
change | Fast 新增 | 组件公开实例成员。 | — |
FaTablePagination
FaTable 内部分页栏,读取表格分页状态并触发页码、每页条数变化。它依赖 FaTable 上下文,不作为独立分页组件使用。
Props 属性
| 属性 | 来源 | 说明 | 类型 | 默认值 |
|---|---|---|---|---|
pageSizes | Fast 新增 | 分页可选每页数量。 | Array | [20,30,50,100] |
Events 事件
| 名称 | 来源 | 说明 | 参数 / 类型 |
|---|---|---|---|
sizeChange | Fast 新增 | 表格每页条数变化时触发。 | — |
currentChange | Fast 新增 | 表格当前行、树当前节点或选择值变化时触发。 | — |
FaTableSearchForm
FaTable 的响应式搜索容器,负责基础搜索、高级搜索、折叠和重置操作。通常由 FaTable 根据列配置自动创建。
Props 属性
| 属性 | 来源 | 说明 | 类型 | 默认值 |
|---|---|---|---|---|
show必填 | Fast 新增 | 是否显示当前表格列或布局项。 | Boolean | false |
collapsedSearch | Fast 新增 | 是否默认折叠表格搜索条件。 | Boolean | true |
advancedSearchDrawer | Fast 新增 | 是否在 Drawer 中展示高级搜索条件。 | Boolean | false |
cols | Fast 新增 | 各响应式断点的列数。 | String / Number / Object | {"xs":2,"sm":3,"md":4,"lg":5,"xl":6} |
search必填 | Fast 新增 | 执行表格搜索的异步函数。 | Function | — |
reset必填 | Fast 新增 | 重置表格搜索条件的异步函数。 | Function | — |
Slots 插槽
| 名称 | 来源 | 说明 | 参数 / 类型 |
|---|---|---|---|
动态命名列/搜索插槽 | Fast 新增 | 按列 slot、headerSlot 或搜索字段名动态生成的业务插槽。 | — |
FaTableSearchFormItem
根据 FaTableColumn 的 search 配置渲染具体输入组件,并在值变化时触发表格搜索。它依赖 FaTable 搜索状态,不应脱离 FaTable 单独使用。
Props 属性
| 属性 | 来源 | 说明 | 类型 | 默认值 |
|---|---|---|---|---|
column必填 | Fast 新增 | 当前搜索项对应的 FaTable 列配置。 | Object | — |
search必填 | Fast 新增 | 当前搜索值变化后执行的异步搜索函数。 | Function | — |
Slots 插槽
| 名称 | 来源 | 说明 | 参数 / 类型 |
|---|---|---|---|
动态命名列/搜索插槽 | Fast 新增 | 按列 slot、headerSlot 或搜索字段名动态生成的业务插槽。 | — |
FaTable 实例方法
以下代码为调用片段。行、选项和字段应对应实际数据。
clearSelection 勾选
用于多选表格,清空用户的选择
签名
clearSelection(): void;示例
<template>
<FaTable ref="componentRef" />
<button type="button" @click="handleExample">调用方法</button>
</template>
<script setup lang="ts">
import { ref } from "vue";
import { FaTable } from "fast-element-plus";
const componentRef = ref<InstanceType<typeof FaTable>>();
function handleExample() {
componentRef.value?.clearSelection();
}
</script>输入: 无参数。
返回: void。
getSelectionRows 勾选
返回当前选中的行
签名
getSelectionRows(): import("element-plus/es/components/table/src/table/defaults.mjs").DefaultRow[];示例
<template>
<FaTable ref="componentRef" />
<button type="button" @click="handleExample">调用方法</button>
</template>
<script setup lang="ts">
import { ref } from "vue";
import { FaTable } from "fast-element-plus";
const componentRef = ref<InstanceType<typeof FaTable>>();
function handleExample() {
const result = componentRef.value?.getSelectionRows();
console.log(result);
}
</script>输入
该方法没有输入参数。
返回
| 返回值 | 返回值类型 | 返回值说明 |
|---|---|---|
result | DefaultRow[] | 方法调用结果,具体数据与当前组件状态一致。 |
getHalfSelectionRows 勾选
返回当前半选中的行。
签名
getHalfSelectionRows(): import("element-plus/es/components/table/src/table/defaults.mjs").DefaultRow[];示例
<template>
<FaTable ref="componentRef" />
<button type="button" @click="handleExample">调用方法</button>
</template>
<script setup lang="ts">
import { ref } from "vue";
import { FaTable } from "fast-element-plus";
const componentRef = ref<InstanceType<typeof FaTable>>();
function handleExample() {
const result = componentRef.value?.getHalfSelectionRows();
console.log(result);
}
</script>输入
该方法没有输入参数。
返回
| 返回值 | 返回值类型 | 返回值说明 |
|---|---|---|
result | DefaultRow[] | 方法调用结果,具体数据与当前组件状态一致。 |
toggleRowSelection 勾选
用于多选表格,切换某一行的选中状态, 如果使用了第二个参数,则可直接设置这一行选中与否
签名
toggleRowSelection(row: import("element-plus/es/components/table/src/table/defaults.mjs").DefaultRow, selected?: boolean, ignoreSelectable?: boolean): void;示例
<template>
<FaTable ref="componentRef" />
<button type="button" @click="handleExample">调用方法</button>
</template>
<script setup lang="ts">
import { ref } from "vue";
import { FaTable } from "fast-element-plus";
const componentRef = ref<InstanceType<typeof FaTable>>();
const row = { id: 1, name: "Fast" };
function handleExample() {
componentRef.value?.toggleRowSelection(row, true, true);
}
</script>输入
| 输入值 | 输入值类型 | 必填/默认值 | 输入值说明 |
|---|---|---|---|
row | DefaultRow | 是 | 目标表格行数据。 |
selected | boolean | undefined | 否 | 是否选中目标行。 |
ignoreSelectable | boolean | undefined | 否 | 是否忽略 selectable 限制。 |
返回
| 返回值 | 返回值类型 | 返回值说明 |
|---|---|---|
result | void | 没有返回值。 |
toggleAllSelection 勾选
用于多选表格,切换全选和全不选
签名
toggleAllSelection(): void;示例
<template>
<FaTable ref="componentRef" />
<button type="button" @click="handleExample">调用方法</button>
</template>
<script setup lang="ts">
import { ref } from "vue";
import { FaTable } from "fast-element-plus";
const componentRef = ref<InstanceType<typeof FaTable>>();
function handleExample() {
componentRef.value?.toggleAllSelection();
}
</script>输入: 无参数。
返回: void。
toggleRowExpansion 展开
用于可扩展的表格或树表格,如果某行被扩展,则切换。 使用第二个参数,您可以直接设置该行应该被扩展或折叠。
签名
toggleRowExpansion(row: import("element-plus/es/components/table/src/table/defaults.mjs").DefaultRow, expanded?: boolean): void;示例
<template>
<FaTable ref="componentRef" />
<button type="button" @click="handleExample">调用方法</button>
</template>
<script setup lang="ts">
import { ref } from "vue";
import { FaTable } from "fast-element-plus";
const componentRef = ref<InstanceType<typeof FaTable>>();
const row = { id: 1, name: "Fast" };
function handleExample() {
componentRef.value?.toggleRowExpansion(row, true);
}
</script>输入
| 输入值 | 输入值类型 | 必填/默认值 | 输入值说明 |
|---|---|---|---|
row | DefaultRow | 是 | 目标表格行数据。 |
expanded | boolean | undefined | 否 | 是否展开目标行。 |
返回
| 返回值 | 返回值类型 | 返回值说明 |
|---|---|---|
result | void | 没有返回值。 |
setCurrentRow 当前项
用于单选表格,设定某一行为选中行, 如果调用时不加参数,则会取消目前高亮行的选中状态。
签名
setCurrentRow(row?: import("element-plus/es/components/table/src/table/defaults.mjs").DefaultRow | undefined): void;示例
<template>
<FaTable ref="componentRef" />
<button type="button" @click="handleExample">调用方法</button>
</template>
<script setup lang="ts">
import { ref } from "vue";
import { FaTable } from "fast-element-plus";
const componentRef = ref<InstanceType<typeof FaTable>>();
const row = { id: 1, name: "Fast" };
function handleExample() {
componentRef.value?.setCurrentRow(row);
}
</script>输入
| 输入值 | 输入值类型 | 必填/默认值 | 输入值说明 |
|---|---|---|---|
row | DefaultRow | undefined | 否 | 目标表格行数据。 |
返回
| 返回值 | 返回值类型 | 返回值说明 |
|---|---|---|
result | void | 没有返回值。 |
clearSort 排序
用于清空排序条件,数据会恢复成未排序的状态
签名
clearSort(): void;示例
<template>
<FaTable ref="componentRef" />
<button type="button" @click="handleExample">调用方法</button>
</template>
<script setup lang="ts">
import { ref } from "vue";
import { FaTable } from "fast-element-plus";
const componentRef = ref<InstanceType<typeof FaTable>>();
function handleExample() {
componentRef.value?.clearSort();
}
</script>输入: 无参数。
返回: void。
clearFilter 筛选
传入由columnKey 组成的数组以清除指定列的过滤条件。 如果没有参数,清除所有过滤器
签名
clearFilter(columnKeys?: string[] | string): void;示例
<template>
<FaTable ref="componentRef" />
<button type="button" @click="handleExample">调用方法</button>
</template>
<script setup lang="ts">
import { ref } from "vue";
import { FaTable } from "fast-element-plus";
const componentRef = ref<InstanceType<typeof FaTable>>();
function handleExample() {
componentRef.value?.clearFilter(["name"]);
}
</script>输入
| 输入值 | 输入值类型 | 必填/默认值 | 输入值说明 |
|---|---|---|---|
columnKeys | string | string[] | undefined | 否 | 需要清除筛选条件的列 key;省略时清除全部。 |
返回
| 返回值 | 返回值类型 | 返回值说明 |
|---|---|---|
result | void | 没有返回值。 |
doLayout 布局
对 Table 进行重新布局。 当表格可见性变化时,您可能需要调用此方法以获得正确的布局
签名
doLayout(): void;示例
<template>
<FaTable ref="componentRef" />
<button type="button" @click="handleExample">调用方法</button>
</template>
<script setup lang="ts">
import { ref } from "vue";
import { FaTable } from "fast-element-plus";
const componentRef = ref<InstanceType<typeof FaTable>>();
function handleExample() {
componentRef.value?.doLayout();
}
</script>输入: 无参数。
返回: void。
sort 排序
手动排序表格。 参数 prop 属性指定排序列,order 指定排序顺序。
签名
sort(prop: string, order: string): void;示例
<template>
<FaTable ref="componentRef" />
<button type="button" @click="handleExample">调用方法</button>
</template>
<script setup lang="ts">
import { ref } from "vue";
import { FaTable } from "fast-element-plus";
const componentRef = ref<InstanceType<typeof FaTable>>();
function handleExample() {
componentRef.value?.sort("name", "ascending");
}
</script>输入
| 输入值 | 输入值类型 | 必填/默认值 | 输入值说明 |
|---|---|---|---|
prop | string | 是 | 表单字段路径或表格排序字段名。 |
order | string | 是 | 排序方向,例如 ascending 或 descending。 |
返回
| 返回值 | 返回值类型 | 返回值说明 |
|---|---|---|
result | void | 没有返回值。 |
scrollTo 滚动
滚动到一组特定坐标
签名
scrollTo(options: ScrollToOptions | number, yCoord?: number): void;示例
<template>
<FaTable ref="componentRef" />
<button type="button" @click="handleExample">调用方法</button>
</template>
<script setup lang="ts">
import { ref } from "vue";
import { FaTable } from "fast-element-plus";
const componentRef = ref<InstanceType<typeof FaTable>>();
function handleExample() {
componentRef.value?.scrollTo({ top: 120, behavior: "smooth" }, 1);
}
</script>输入
| 输入值 | 输入值类型 | 必填/默认值 | 输入值说明 |
|---|---|---|---|
options | number | ScrollToOptions | 是 | 滚动距离或标准 ScrollToOptions。 |
yCoord | number | undefined | 否 | 纵向滚动坐标。 |
返回
| 返回值 | 返回值类型 | 返回值说明 |
|---|---|---|
result | void | 没有返回值。 |
setScrollTop 滚动
设置垂直滚动位置
签名
setScrollTop(top?: number): void;示例
<template>
<FaTable ref="componentRef" />
<button type="button" @click="handleExample">调用方法</button>
</template>
<script setup lang="ts">
import { ref } from "vue";
import { FaTable } from "fast-element-plus";
const componentRef = ref<InstanceType<typeof FaTable>>();
function handleExample() {
componentRef.value?.setScrollTop(120);
}
</script>输入
| 输入值 | 输入值类型 | 必填/默认值 | 输入值说明 |
|---|---|---|---|
top | number | undefined | 否 | 纵向滚动距离。 |
返回
| 返回值 | 返回值类型 | 返回值说明 |
|---|---|---|
result | void | 没有返回值。 |
setScrollLeft 滚动
设置水平滚动位置
签名
setScrollLeft(left?: number): void;示例
<template>
<FaTable ref="componentRef" />
<button type="button" @click="handleExample">调用方法</button>
</template>
<script setup lang="ts">
import { ref } from "vue";
import { FaTable } from "fast-element-plus";
const componentRef = ref<InstanceType<typeof FaTable>>();
function handleExample() {
componentRef.value?.setScrollLeft(120);
}
</script>输入
| 输入值 | 输入值类型 | 必填/默认值 | 输入值说明 |
|---|---|---|---|
left | number | undefined | 否 | 横向滚动距离。 |
返回
| 返回值 | 返回值类型 | 返回值说明 |
|---|---|---|
result | void | 没有返回值。 |
updateKeyChildren 节点
适用于 lazy Table, 需要设置 rowKey, 更新 key children
签名
updateKeyChildren(key: string, data: import("element-plus/es/components/table/src/table/defaults.mjs").DefaultRow[]): void;示例
展开懒加载子行示例中的父行,再点击「替换子行」。传入字符串行键和新的子行数组。
输入
| 输入值 | 输入值类型 | 必填/默认值 | 输入值说明 |
|---|---|---|---|
key | string | 是 | 节点、行或列的唯一标识。 |
data | DefaultRow[] | 是 | 要查询、插入、删除或替换的业务数据。 |
返回
| 返回值 | 返回值类型 | 返回值说明 |
|---|---|---|
result | void | 没有返回值。 |
toggleRowIndeterminateSelection 勾选
部分选中(样式不一样而已),用于多选表格,切换某一行的选中状态, 如果使用了第二个参数,则可直接设置这一行选中与否
签名
toggleRowIndeterminateSelection(row: DefaultRow, selected?: boolean): void;示例
<template>
<FaTable ref="componentRef" />
<button type="button" @click="handleExample">调用方法</button>
</template>
<script setup lang="ts">
import { ref } from "vue";
import { FaTable } from "fast-element-plus";
const componentRef = ref<InstanceType<typeof FaTable>>();
const row = { id: 1, name: "Fast" };
function handleExample() {
componentRef.value?.toggleRowIndeterminateSelection(row, true);
}
</script>输入
| 输入值 | 输入值类型 | 必填/默认值 | 输入值说明 |
|---|---|---|---|
row | DefaultRow | 是 | 目标表格行数据。 |
selected | boolean | undefined | 否 | 是否选中目标行。 |
返回
| 返回值 | 返回值类型 | 返回值说明 |
|---|---|---|
result | void | 没有返回值。 |
refresh 刷新
异步方法,刷新表格
签名
refresh(): Promise<void>;示例
<template>
<FaTable ref="componentRef" />
<button type="button" @click="handleExample">调用方法</button>
</template>
<script setup lang="ts">
import { ref } from "vue";
import { FaTable } from "fast-element-plus";
const componentRef = ref<InstanceType<typeof FaTable>>();
async function handleExample() {
const result = await componentRef.value?.refresh();
console.log(result);
}
</script>输入
该方法没有输入参数。
返回
| 返回值 | 返回值类型 | 返回值说明 |
|---|---|---|
result | Promise<void> | 异步完成后的结果;Promise 拒绝时由调用方处理。 |
reset 重置
异步方法,重置表格
签名
reset(): Promise<void>;示例
<template>
<FaTable ref="componentRef" />
<button type="button" @click="handleExample">调用方法</button>
</template>
<script setup lang="ts">
import { ref } from "vue";
import { FaTable } from "fast-element-plus";
const componentRef = ref<InstanceType<typeof FaTable>>();
async function handleExample() {
const result = await componentRef.value?.reset();
console.log(result);
}
</script>输入
该方法没有输入参数。
返回
| 返回值 | 返回值类型 | 返回值说明 |
|---|---|---|
result | Promise<void> | 异步完成后的结果;Promise 拒绝时由调用方处理。 |
doRender 渲染
对 Table 进行重新渲染。当 TableKey 发生变化的时候可以通过此方法重新渲染表格
签名
doRender(): Promise<void>;示例
<template>
<FaTable ref="componentRef" />
<button type="button" @click="handleExample">调用方法</button>
</template>
<script setup lang="ts">
import { ref } from "vue";
import { FaTable } from "fast-element-plus";
const componentRef = ref<InstanceType<typeof FaTable>>();
async function handleExample() {
const result = await componentRef.value?.doRender();
console.log(result);
}
</script>输入
该方法没有输入参数。
返回
| 返回值 | 返回值类型 | 返回值说明 |
|---|---|---|
result | Promise<void> | 异步完成后的结果;Promise 拒绝时由调用方处理。 |
doLoading 加载
Table 加载
签名
doLoading(loadingFunction: () => void | Promise<void>, loadingText?: string): Promise<void>;示例
<template>
<FaTable ref="componentRef" />
<button type="button" @click="handleExample">调用方法</button>
</template>
<script setup lang="ts">
import { ref } from "vue";
import { FaTable } from "fast-element-plus";
const componentRef = ref<InstanceType<typeof FaTable>>();
const saveData = async () => Promise.resolve();
async function handleExample() {
const result = await componentRef.value?.doLoading(async () => saveData(), "保存中");
console.log(result);
}
</script>输入
| 输入值 | 输入值类型 | 必填/默认值 | 输入值说明 |
|---|---|---|---|
loadingFunction | () => void | Promise<void> | 是 | 需要在加载状态中执行的同步或异步任务。 |
loadingText | string | undefined | 否 | 加载遮罩显示的可选文字。 |
返回
| 返回值 | 返回值类型 | 返回值说明 |
|---|---|---|
result | Promise<void> | 异步完成后的结果;Promise 拒绝时由调用方处理。 |
FaTableColumnsSettingDialog 实例方法
以下代码为调用片段。行、选项和字段应对应实际数据。
open 打开
打开
签名
open(): Promise<void>;示例
<template>
<Component ref="componentRef" />
<button type="button" @click="handleExample">调用方法</button>
</template>
<script setup lang="ts">
import { ref } from "vue";
import { FaTable } from "fast-element-plus";
const Component = FaTable.TableColumnsSettingDialog;
const componentRef = ref<InstanceType<typeof Component>>();
async function handleExample() {
const result = await componentRef.value?.open();
console.log(result);
}
</script>输入
该方法没有输入参数。
返回
| 返回值 | 返回值类型 | 返回值说明 |
|---|---|---|
result | Promise<void> | 异步完成后的结果;Promise 拒绝时由调用方处理。 |
change 变更
列改变
签名
change(): Promise<void>;示例
<template>
<Component ref="componentRef" />
<button type="button" @click="handleExample">调用方法</button>
</template>
<script setup lang="ts">
import { ref } from "vue";
import { FaTable } from "fast-element-plus";
const Component = FaTable.TableColumnsSettingDialog;
const componentRef = ref<InstanceType<typeof Component>>();
async function handleExample() {
const result = await componentRef.value?.change();
console.log(result);
}
</script>输入
该方法没有输入参数。
返回
| 返回值 | 返回值类型 | 返回值说明 |
|---|---|---|
result | Promise<void> | 异步完成后的结果;Promise 拒绝时由调用方处理。 |
状态与生命周期
组件高度由容器和传入的表格高度决定,移动端不会附加最小高度;容器尺寸变化时会持续同步宽高,但仅在宽度变化时重新计算自动列宽,避免移动端软键盘引起的纯高度变化中断输入;卡片边框颜色沿用 Element Plus 主题。
数据请求、自动列宽和 doLoading 分别持有 Loading。手动写入 loading=false 只释放手动所有权。卸载取消待执行渲染/列布局任务,等待 doRender 的调用正常结束;迟到请求结果不再写入状态。ResizeObserver 在 watcher 清理时断开。
展开列、选择列与序号列(2.0.23)
FaTable 统一管理这三类内置列,启用后的顺序为展开列、选择列、序号列,再接业务列。三列均固定在左侧,不参与业务列设置;配置 props.span 时,也会按指定字段合并相同行。
| 配置 | 默认值 | 行为 |
|---|---|---|
#expand | 未提供时不显示 | 提供插槽即创建宽度为 35px 的展开列 |
selection-column | false | 显式启用勾选列,可配合 single、row-click-selection 和 row-selectable |
index-column | true | 显示序号列;设置 :index-column="false" 可隐藏 |
#expand 参数包含 row、column、$index,以及 FaTableDefaultSlotsResult 的表格上下文。展开状态仍由 expand-change、expand-row-keys、default-expand-all 和 toggleRowExpansion 控制。
展开内容使用独立的 .fa-table__expand-wrapper 容器。2.0.25 源码已将其样式统一放入 table.scss,使用 position: sticky; left: 0 保持横向位置,并清除外层 .el-table__expanded-cell 的默认内边距。容器采用 box-sizing: border-box 和 width: var(--fa-table-expand-width, 100cqw);可以在 FaTable 上设置 style="--fa-table-expand-width: 720px",也可传入 calc(...) 等合法 CSS 宽度值。未设置变量时,宽度跟随表格主容器,而非所有列的总宽度;此默认值不自动扣除表格边框或原生纵向滚动条宽度。默认内边距为 12px 16px,组件尺寸为 small 时为 8px 12px,通常无需在展开插槽中重复添加外层内边距。未提供 #expand 时,不创建展开容器,也不启用主容器的 inline-size 尺寸容器。
FaTableColumnType 不再接受 selection、index、expand。升级时,原先默认显示勾选框的表格需要补上 selection-column;将 columns 或 FaTableColumn 中的特殊列移除,分别使用表格 Props 和 #expand。展开列原有的 render 或命名插槽内容迁入 #expand,不要继续使用 <FaTableColumn type="expand">。
<FaTable :data="rows" selection-column :index-column="false">
<template #expand="{ row }">
<div>{{ row["description"] }}</div>
</template>
<FaTableColumn prop="name" label="名称" />
</FaTable>示例依赖与源码版本
在线示例与下方自动 API 表均使用 fast-element-plus 2.0.27。
行数据类型
DefaultRow 是 FaTable 默认公开行类型,允许业务接口返回未预先声明的字段。已知数据结构可以继承该类型,并通过 FaTableColumnCtx<T> 和 PagedResult<T> 获得更精确的列配置与分页数据提示。
import type { DefaultRow, FaTableColumnCtx, PagedResult } from "fast-element-plus";
interface UserRow extends DefaultRow {
id: number;
name: string;
}
const columns: FaTableColumnCtx<UserRow>[] = [{ prop: "name", label: "姓名" }];
const result: PagedResult<UserRow> = {
rows: [{ id: 1, name: "Fast" }],
totalRows: 1,
};