跳到正文

FaTable 表格 ​

FaTable 在 Element Plus 表格上集成搜索表单、分页、远程请求、列设置和行选择。

自 2.0.28 起,style 应用于 FaTable 外层容器,#append 在传入时才渲染。empty-text 可替换内置空态文案。FaTableColumn 的 #filterIcon 可接收 filterOpened,#expand 可读取 expanded 和 expandable。列的 show-overflow-tooltip 支持透传配置对象。

常用示例 ​

基础用法 ​

本地数据、关键字搜索、复制、标签与日期列

可操作示例
查看代码
Vue
<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 是符合条件的总条数。实际接入可运行跨包分页示例,遇到问题可查阅排错步骤。

远程搜索、分页、列设置与响应式搜索表单

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

行选择 ​

单选、整行选择与禁用行

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

高级表格场景 ​

树形表格与默认展开

可操作示例
查看代码
Vue
<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 用于把分组数据的子项展开为普通表格行。

展开行、自定义内容与展开事件

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

固定列、状态筛选、远程排序与内容提示

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

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

更新懒加载节点 ​

懒加载并替换子行

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

属性来源说明类型默认值
dataFast 修改组件数据。ArrayFast[]EL[]
sizeFast 修改组件尺寸。StringFast—EL—
heightFast 修改组件高度。String / NumberFast—EL—
borderFast 全局增强是否显示表格边框。BooleanFasttrueELfalse
rowKeyFast 全局增强行或节点唯一键。String / FunctionFastidEL—
highlightCurrentRowFast 全局增强是否高亮当前行。BooleanFasttrueELfalse
tableKeyFast 新增表格实例及持久化配置使用的唯一标识。String运行时生成
requestApiFast 新增异步数据请求函数。(params?: PagedInput) => Promise<PagedResult<DefaultRow> | DefaultRow[]>—
dataCallbackFast 新增表格请求数据完成后的转换或回调函数。(data: PagedResult<DefaultRow> | DefaultRow[]) => void—
initParamFast 新增请求初始化参数。String / Number / Object—
columnsFast 新增表格列配置。Array / Booleanfalse
columnsChangeFast 新增列设置变化回调。Function—
searchFormColsFast 新增搜索表单响应式列数。String / Number / Object{"xs":2,"sm":3,"md":4,"lg":5,"xl":6}
collapsedSearchFast 新增是否默认折叠表格搜索条件。Booleantrue
advancedSearchDrawerFast 新增是否在 Drawer 中展示高级搜索条件。Booleanfalse
searchFormFast 新增搜索表单初始值。Booleantrue
headerCardFast 新增表格头部是否使用卡片容器样式。Booleantrue
refreshBtnFast 新增是否显示刷新按钮。Booleantrue
searchBtnFast 新增是否显示搜索按钮。Booleantrue
columnSettingBtnFast 新增是否显示列设置按钮。Booleanfalse
toolBtnFast 新增是否显示表格工具按钮区域。Booleantrue
hideSearchTimeFast 新增是否隐藏默认时间搜索项。Booleanfalse
futureSearchTimeFast 新增时间搜索是否允许选择未来日期。Booleanfalse
dataSearchRangeFast 新增表格默认时间搜索范围。StringPast3D
selectionColumnFast 新增是否显示内置选择列,默认 false(2.0.23 起)。Booleanfalse
indexColumnFast 新增是否显示内置序号列,默认 true(2.0.23 起)。Booleantrue
paginationFast 新增是否显示分页或分页配置。Booleantrue
pageSizesFast 新增分页可选每页数量。Array[20,30,50,100]
hideImageFast 新增是否隐藏图片列预览。Booleanfalse
singleFast 新增是否使用单选表格模式。Booleanfalse
rowClickSelectionFast 新增点击行时是否切换选择。Booleanfalse
treeDataFast 新增将每个父项的 children 展开为表格行,并把父项字段合并到子项;Element Plus 树表展开无需启用。Booleanfalse
propsFast 新增字段映射配置。Object{"children":"children"}
autoRefreshFast 新增是否按配置自动刷新。Booleantrue
rowSelectableFast 新增判断表格行是否允许选择的函数。Function—
widthEL 原生组件宽度。String / Number—
maxHeightEL 原生表格的最大高度,可传像素数值或带 px 单位的字符串。String / Number—
fitEL 原生内容如何适应容器。Booleantrue
stripeEL 原生是否显示斑马纹。Booleanfalse
showHeaderEL 原生是否显示表头。Booleantrue
showSummaryEL 原生是否在表尾显示合计行。Booleanfalse
sumTextEL 原生合计行第一列显示的文字。String—
summaryMethodEL 原生自定义合计行各列的计算方法。Function—
rowClassNameEL 原生为所有行指定类名,或通过回调逐行返回类名。String / Function—
rowStyleEL 原生为所有行指定样式,或通过回调逐行返回样式。Object / Function—
cellClassNameEL 原生为所有单元格指定类名,或通过回调逐格返回类名。String / Function—
cellStyleEL 原生为所有单元格指定样式,或通过回调逐格返回样式。Object / Function—
headerRowClassNameEL 原生表头行的类名,可统一指定或通过回调逐行返回。String / Function—
headerRowStyleEL 原生表头行的样式,可统一指定或通过回调逐行返回。Object / Function—
headerCellClassNameEL 原生表头单元格的类名,可统一指定或通过回调逐格返回。String / Function—
headerCellStyleEL 原生表头单元格的样式,可统一指定或通过回调逐格返回。Object / Function—
currentRowKeyEL 原生设置当前行的键,仅用于写入。String / Number—
emptyTextEL 原生空数据提示文字。String—
expandRowKeysEL 原生指定需要展开的行键。使用前需设置 row-key。Array—
rowExpandableEL 原生判断某行能否展开的回调,在启用展开列时生效。Function—
defaultExpandAllEL 原生是否默认展开全部节点。Booleanfalse
defaultSortEL 原生初始排序规则,prop 指定排序字段,order 指定排序方向。Object—
tooltipEffectEL 原生内容溢出提示的主题。String—
tooltipOptionsEL 原生内容溢出时的 Tooltip 配置。Object—
spanMethodEL 原生按单元格返回跨行和跨列数量的回调。FaTable 的合并行为以列配置为准。Function—
selectOnIndeterminateEL 原生部分行已选中时,点击表头复选框是否全选。为 false 时取消全选。Booleantrue
indentEL 原生相邻树层级之间的水平缩进像素。Number16
treePropsEL 原生树形行数据的字段映射配置。Object{"hasChildren":"hasChildren","children":"children","checkStrictly":false}
lazyEL 原生是否启用懒加载。Booleanfalse
loadEL 原生树节点懒加载函数。Function—
styleEL 原生表格单元格或表头单元格的自定义样式。Object{}
classNameEL 原生表格单元格或表头单元格的自定义类名。String""
tableLayoutEL 原生表格行、列和单元格使用的布局算法。Stringfixed
scrollbarAlwaysOnEL 原生是否始终显示表格滚动条。Booleanfalse
flexibleEL 原生避免表格在弹性布局的主轴上被内容最小尺寸撑开。Booleanfalse
showOverflowTooltipEL 原生内容溢出时在悬停提示中显示。表级配置应用到各列。Boolean / Objectfalse
tooltipFormatterEL 原生格式化溢出提示显示的内容。Function—
appendFilterPanelToEL 原生列筛选面板的挂载元素。String—
scrollbarTabindexEL 原生表格正文滚动容器的 tabindex。Number / String—
allowDragLastColumnEL 原生是否允许拖动调整最后一列的宽度。Booleantrue
preserveExpandedContentEL 原生折叠展开行后是否仍将其内容保留在 DOM 中。Booleanfalse
nativeScrollbarEL 原生是否使用浏览器原生滚动条。Booleanfalse

Events 事件

名称来源说明参数 / 类型
selectEL 原生选择行或选项时触发。—
selectAllEL 原生表格全选状态变化时触发,参数为当前选择行。—
selectionChangeEL 原生表格选择集合变化时触发。(newSelection: DefaultRow[])
cellMouseEnterEL 原生鼠标进入单元格时触发。—
cellMouseLeaveEL 原生鼠标离开单元格时触发。—
cellClickEL 原生点击单元格时触发,参数为行、列、单元格和原生事件。—
cellDblclickEL 原生双击单元格时触发。—
cellContextmenuEL 原生右键点击单元格时触发。—
rowClickEL 原生点击表格行时触发,参数与 ElTable row-click 一致。—
rowContextmenuEL 原生右键点击表格行时触发。—
rowDblclickEL 原生双击表格行时触发。—
headerClickEL 原生点击表头单元格时触发。—
headerContextmenuEL 原生右键点击表头单元格时触发。—
sortChangeEL 原生表格排序条件变化时触发。(data: { column: TableColumnCtx<DefaultRow>; prop: string; order: "" | "ascending" | "descending" })
filterChangeEL 原生表格筛选条件变化时触发。—
currentChangeEL 原生表格当前行、树当前节点或选择值变化时触发。—
headerDragendEL 原生拖动表头改变列宽结束时触发。—
expandChangeEL 原生表格行展开状态变化时触发。—
scrollEL 原生表格或选择器滚动时触发。—
refreshFast 新增刷新数据时触发。—
resetFast 新增重置搜索条件时触发。—
sizeChangeFast 新增表格每页条数变化时触发。—
paginationChangeFast 新增表格页码或每页条数变化时触发。—
customCellClickFast 新增点击 Fast 链接列时触发,参数为自定义事件名和当前单元格上下文。—

Slots 插槽

名称来源说明参数 / 类型
defaultEL 原生组件默认内容插槽。—
appendEL 原生在表格最后一行之后追加自定义内容。—
emptyEL 原生组件无数据时的自定义内容。—
topHeaderFast 新增自定义表格最顶部内容。—
headerFast 新增自定义头部内容或表格头部业务区域。—
toolButtonFast 新增自定义表格常用工具按钮区域。—
toolButtonAdvFast 新增自定义表格高级工具按钮区域。—
expand({ row, column, $index, ...tableContext })Fast 新增自定义展开行内容;提供插槽即启用展开列(2.0.23 起),参数包含 row、column、$index 和表格上下文。({ row, column, $index, ...tableContext })
operationFast 新增自定义表格操作列内容。—
paginationFast 新增自定义表格分页区域。—
footerFast 新增自定义底部操作区域;弹层中可获得 loading 和 close。—
columnSettingFast 新增自定义表格列设置区域。—
动态命名列/搜索插槽Fast 新增按列 slot、headerSlot 或搜索字段名动态生成的业务插槽。—

实例成员

名称来源说明参数 / 类型
clearSelectionEL 原生清除当前选择集合。—
getSelectionRowsEL 原生获取表格当前选中的行。—
getHalfSelectionRowsFast 新增获取树形表格中处于半选状态的行。—
toggleRowSelectionEL 原生切换指定表格行的选中状态。—
toggleAllSelectionEL 原生切换表格全选状态。—
toggleRowExpansionEL 原生切换指定表格行的展开状态。—
setCurrentRowEL 原生设置表格当前高亮行。—
clearSortEL 原生清除表格排序状态。—
clearFilterEL 原生清除表格列筛选条件。—
doLayoutEL 原生重新计算表格布局。—
sortEL 原生按指定列和顺序执行表格排序。—
scrollToEL 原生滚动表格或虚拟列表到指定位置。—
setScrollTopEL 原生设置表格纵向滚动位置。—
setScrollLeftEL 原生设置表格横向滚动位置。—
columnsEL 原生ElTable 当前渲染的列上下文集合。—
updateKeyChildrenEL 原生按节点 key 更新树或树形表格的子节点。—
loadingFast 新增Fast 业务加载状态。—
tableDataFast 新增表格当前渲染的数据集合。—
tablePaginationFast 新增表格当前分页状态。—
searchParamFast 新增表格当前提交给请求函数的搜索参数。—
selectedFast 新增表格是否存在选中行。—
selectedListFast 新增当前选中的完整数据对象集合。—
selectedListIdsFast 新增当前选中行的主键集合。—
indeterminateSelectedListIdsFast 新增树形表格中半选行的主键集合。—
tableWidthFast 新增表格计算后的可用宽度。—
tableHeightFast 新增表格计算后的可用高度。—
toggleRowIndeterminateSelectionFast 新增切换树形表格行的半选状态。—
refreshFast 新增重新执行组件数据请求或刷新业务内容。—
resetFast 新增重置表格搜索条件、分页和数据。—
doRenderFast 新增强制重新计算并渲染表格内容。—
doLoadingFast 新增在统一 Loading 和遮罩状态下执行同步或异步函数。—

FaTableColumn API ​

除 ElTableColumn 原生列能力外,提供图片、日期、时间、精度数值、千分位、复制、链接、标签、合并行和时间信息等业务列类型。

prop 支持使用点分隔的嵌套字段路径,例如 profile.name、profile.createdTime。默认、日期/时间、数值、链接、标签、枚举和图片列都会按完整路径读取行数据,本地排序也使用相同路径解析规则。

图片、链接、复制、数值、枚举与日期列

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

图片缩略图、原图预览、隐藏图片与空值占位

可操作示例
查看代码
Vue
<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" 关闭内置序号列。

相同数据合并与操作时间信息列

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

属性来源说明类型默认值
typeFast 修改Fast 业务列类型。StringFastdefaultELdefault
widthFast 修改组件宽度。String / NumberFastautoEL""
alignFast 修改当前列单元格的对齐方式。StringFastleftEL—
headerAlignFast 修改当前列表头的对齐方式,省略时使用 align。StringFastleftEL—
showFast 新增是否显示当前表格列或布局项。Booleanfalse
smallWidthFast 新增小尺寸模式下的表格列宽度。String / Number—
autoWidthFast 新增是否根据单元格内容自动计算表格列宽。Booleanfalse
slotFast 新增自定义表格单元格使用的命名插槽。String—
headerSlotFast 新增自定义表格列头使用的命名插槽。String—
headerRenderFast 新增使用 TSX 自定义表格列头的渲染函数。Function—
renderFast 新增使用 TSX 自定义表格单元格的渲染函数。Function—
_childrenFast 新增多级表头的子列配置。Array—
hideImageFast 新增是否隐藏图片列预览。Booleanfalse
copyFast 新增是否显示单元格复制操作。Booleanfalse
linkFast 新增将单元格显示为链接按钮。Booleanfalse
spanPropFast 新增计算表格纵向合并行时使用的字段名。String—
clickFast 新增链接列点击回调,参数包含当前行和行索引。Function—
clickEmitFast 新增链接列点击时触发的自定义事件名称。String—
originalImageFast 新增图片列是否使用原图地址进行展示和预览。Booleanfalse
dateFixFast 新增日期列是否同时显示相对时间标签。Booleanfalse
dateFormatFast 新增日期列的自定义格式化模板。String—
tagFast 新增将单元格显示为枚举标签。Booleanfalse
enumFast 新增枚举字典、字典名称或按行返回字典的函数。String / Array / Function—
dataDeleteFieldFast 新增标记逻辑删除状态的字段名,命中后单元格显示删除遮罩。String—
timeInfoFieldFast 新增时间信息列中用户名和时间字段的映射。Object{"userName":"createdUserName","time":"createdTime"}
labelEL 原生显示文本或同步标签值。String—
classNameEL 原生表格单元格或表头单元格的自定义类名。String—
labelClassNameEL 原生当前列表头的自定义类名。String—
propertyEL 原生表格列对应的数据字段,语义与 prop 相同。String—
propEL 原生此列读取的行字段,也可使用 property 指定。String—
minWidthEL 原生列的最小宽度。表格有剩余空间时可按比例分配给此类列。String / Number""
renderHeaderEL 原生自定义当前列的表头渲染函数。Function—
sortableEL 原生是否允许排序。使用 custom 并监听 sort-change 可接入远程排序。Boolean / Stringfalse
sortMethodEL 原生自定义比较函数,返回值规则与 Array.sort 一致。Function—
sortByEL 原生指定本地排序字段。使用数组时按字段顺序逐项比较。配置 sortMethod 后以比较函数为准。String / Function / Array—
resizableEL 原生是否允许调整 Drawer 尺寸。Booleantrue
columnKeyEL 原生用于标识列的键,筛选事件可用它定位被筛选的列。String—
showOverflowTooltipEL 原生当前列的单元格溢出时是否显示悬停提示。Boolean / Objectfalse
tooltipFormatterEL 原生格式化当前列溢出提示显示的内容。Function—
fixedEL 原生将列固定在左侧或右侧。设为 true 时固定在左侧。Boolean / Stringfalse
formatterEL 原生显示值格式化函数。Function—
selectableEL 原生判断某行能否勾选的回调,仅适用于选择列。Function—
reserveSelectionEL 原生刷新数据后是否保留选择,需设置 row-key,仅适用于选择列。Booleanfalse
filterMethodEL 原生本地筛选选项时调用的过滤函数。Function—
filteredValueEL 原生当前选中的筛选值。Array—
filtersEL 原生列筛选选项,每项需包含 text 和 value。Array—
filterPlacementEL 原生列筛选面板的弹出位置。String—
filterMultipleEL 原生列筛选是否允许多选。Booleantrue
filterClassNameEL 原生列筛选面板的自定义类名。String—
indexEL 原生自定义序号列的编号,仅适用于 type 为 index 的列。Number / Function—
sortOrdersEL 原生点击列头时依次切换的排序状态。Array["ascending","descending",null]

Events 事件

名称来源说明参数 / 类型
imagePreviewFast 新增打开图片预览时触发,参数为图片地址。—
customCellClickFast 新增点击 Fast 链接列时触发,参数为自定义事件名和当前单元格上下文。—

Slots 插槽

名称来源说明参数 / 类型
default(scope)EL 原生自定义表格单元格内容,参数包含行、列和行索引。(scope)
header(scope)EL 原生自定义表格列头,参数包含列和列索引。(scope)
filter-iconEL 原生 · 未透传自定义列筛选图标。{ filterOpened: boolean }
expandEL 原生 · 未透传自定义展开列内容,Element Plus 2.13.2 起支持 expandable 插槽参数。{ expanded: boolean, expandable: boolean }

FaTableColumnsSettingDialog ​

FaTable 内部的列设置弹窗,由 columnSettingBtn 控制显示。通过每行左侧的拖动手柄调整列顺序;触屏操作需要短按后拖动,避免滚动列表时误排序。它依赖 FaTable 提供的状态,只应通过 FaTable.TableColumnsSettingDialog 或 FaTable 内部流程使用。

Props 属性

属性来源说明类型默认值
changeFast 新增列配置发生变化后调用的保存回调。Function—

实例成员

名称来源说明参数 / 类型
openFast 新增执行 Fast 异步打开流程。—
changeFast 新增组件公开实例成员。—

FaTablePagination ​

FaTable 内部分页栏,读取表格分页状态并触发页码、每页条数变化。它依赖 FaTable 上下文,不作为独立分页组件使用。

Props 属性

属性来源说明类型默认值
pageSizesFast 新增分页可选每页数量。Array[20,30,50,100]

Events 事件

名称来源说明参数 / 类型
sizeChangeFast 新增表格每页条数变化时触发。—
currentChangeFast 新增表格当前行、树当前节点或选择值变化时触发。—

FaTableSearchForm ​

FaTable 的响应式搜索容器,负责基础搜索、高级搜索、折叠和重置操作。通常由 FaTable 根据列配置自动创建。

Props 属性

属性来源说明类型默认值
show必填Fast 新增是否显示当前表格列或布局项。Booleanfalse
collapsedSearchFast 新增是否默认折叠表格搜索条件。Booleantrue
advancedSearchDrawerFast 新增是否在 Drawer 中展示高级搜索条件。Booleanfalse
colsFast 新增各响应式断点的列数。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 勾选 ​

用于多选表格,清空用户的选择

签名 ​

ts
clearSelection(): void;

示例 ​

vue
<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 勾选 ​

返回当前选中的行

签名 ​

ts
getSelectionRows(): import("element-plus/es/components/table/src/table/defaults.mjs").DefaultRow[];

示例 ​

vue
<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>

输入 ​

该方法没有输入参数。

返回 ​

返回值返回值类型返回值说明
resultDefaultRow[]方法调用结果,具体数据与当前组件状态一致。

getHalfSelectionRows 勾选 ​

返回当前半选中的行。

签名 ​

ts
getHalfSelectionRows(): import("element-plus/es/components/table/src/table/defaults.mjs").DefaultRow[];

示例 ​

vue
<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>

输入 ​

该方法没有输入参数。

返回 ​

返回值返回值类型返回值说明
resultDefaultRow[]方法调用结果,具体数据与当前组件状态一致。

toggleRowSelection 勾选 ​

用于多选表格,切换某一行的选中状态, 如果使用了第二个参数,则可直接设置这一行选中与否

签名 ​

ts
toggleRowSelection(row: import("element-plus/es/components/table/src/table/defaults.mjs").DefaultRow, selected?: boolean, ignoreSelectable?: boolean): void;

示例 ​

vue
<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>

输入 ​

输入值输入值类型必填/默认值输入值说明
rowDefaultRow是目标表格行数据。
selectedboolean | undefined否是否选中目标行。
ignoreSelectableboolean | undefined否是否忽略 selectable 限制。

返回 ​

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

toggleAllSelection 勾选 ​

用于多选表格,切换全选和全不选

签名 ​

ts
toggleAllSelection(): void;

示例 ​

vue
<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 展开 ​

用于可扩展的表格或树表格,如果某行被扩展,则切换。 使用第二个参数,您可以直接设置该行应该被扩展或折叠。

签名 ​

ts
toggleRowExpansion(row: import("element-plus/es/components/table/src/table/defaults.mjs").DefaultRow, expanded?: boolean): void;

示例 ​

vue
<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>

输入 ​

输入值输入值类型必填/默认值输入值说明
rowDefaultRow是目标表格行数据。
expandedboolean | undefined否是否展开目标行。

返回 ​

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

setCurrentRow 当前项 ​

用于单选表格,设定某一行为选中行, 如果调用时不加参数,则会取消目前高亮行的选中状态。

签名 ​

ts
setCurrentRow(row?: import("element-plus/es/components/table/src/table/defaults.mjs").DefaultRow | undefined): void;

示例 ​

vue
<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>

输入 ​

输入值输入值类型必填/默认值输入值说明
rowDefaultRow | undefined否目标表格行数据。

返回 ​

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

clearSort 排序 ​

用于清空排序条件,数据会恢复成未排序的状态

签名 ​

ts
clearSort(): void;

示例 ​

vue
<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 组成的数组以清除指定列的过滤条件。 如果没有参数,清除所有过滤器

签名 ​

ts
clearFilter(columnKeys?: string[] | string): void;

示例 ​

vue
<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>

输入 ​

输入值输入值类型必填/默认值输入值说明
columnKeysstring | string[] | undefined否需要清除筛选条件的列 key;省略时清除全部。

返回 ​

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

doLayout 布局 ​

对 Table 进行重新布局。 当表格可见性变化时,您可能需要调用此方法以获得正确的布局

签名 ​

ts
doLayout(): void;

示例 ​

vue
<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 指定排序顺序。

签名 ​

ts
sort(prop: string, order: string): void;

示例 ​

vue
<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>

输入 ​

输入值输入值类型必填/默认值输入值说明
propstring是表单字段路径或表格排序字段名。
orderstring是排序方向,例如 ascending 或 descending。

返回 ​

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

scrollTo 滚动 ​

滚动到一组特定坐标

签名 ​

ts
scrollTo(options: ScrollToOptions | number, yCoord?: number): void;

示例 ​

vue
<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>

输入 ​

输入值输入值类型必填/默认值输入值说明
optionsnumber | ScrollToOptions是滚动距离或标准 ScrollToOptions。
yCoordnumber | undefined否纵向滚动坐标。

返回 ​

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

setScrollTop 滚动 ​

设置垂直滚动位置

签名 ​

ts
setScrollTop(top?: number): void;

示例 ​

vue
<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>

输入 ​

输入值输入值类型必填/默认值输入值说明
topnumber | undefined否纵向滚动距离。

返回 ​

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

setScrollLeft 滚动 ​

设置水平滚动位置

签名 ​

ts
setScrollLeft(left?: number): void;

示例 ​

vue
<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>

输入 ​

输入值输入值类型必填/默认值输入值说明
leftnumber | undefined否横向滚动距离。

返回 ​

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

updateKeyChildren 节点 ​

适用于 lazy Table, 需要设置 rowKey, 更新 key children

签名 ​

ts
updateKeyChildren(key: string, data: import("element-plus/es/components/table/src/table/defaults.mjs").DefaultRow[]): void;

示例 ​

展开懒加载子行示例中的父行,再点击「替换子行」。传入字符串行键和新的子行数组。

输入 ​

输入值输入值类型必填/默认值输入值说明
keystring是节点、行或列的唯一标识。
dataDefaultRow[]是要查询、插入、删除或替换的业务数据。

返回 ​

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

toggleRowIndeterminateSelection 勾选 ​

部分选中(样式不一样而已),用于多选表格,切换某一行的选中状态, 如果使用了第二个参数,则可直接设置这一行选中与否

签名 ​

ts
toggleRowIndeterminateSelection(row: DefaultRow, selected?: boolean): void;

示例 ​

vue
<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>

输入 ​

输入值输入值类型必填/默认值输入值说明
rowDefaultRow是目标表格行数据。
selectedboolean | undefined否是否选中目标行。

返回 ​

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

refresh 刷新 ​

异步方法,刷新表格

签名 ​

ts
refresh(): Promise<void>;

示例 ​

vue
<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>

输入 ​

该方法没有输入参数。

返回 ​

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

reset 重置 ​

异步方法,重置表格

签名 ​

ts
reset(): Promise<void>;

示例 ​

vue
<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>

输入 ​

该方法没有输入参数。

返回 ​

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

doRender 渲染 ​

对 Table 进行重新渲染。当 TableKey 发生变化的时候可以通过此方法重新渲染表格

签名 ​

ts
doRender(): Promise<void>;

示例 ​

vue
<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>

输入 ​

该方法没有输入参数。

返回 ​

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

doLoading 加载 ​

Table 加载

签名 ​

ts
doLoading(loadingFunction: () => void | Promise<void>, loadingText?: string): Promise<void>;

示例 ​

vue
<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>是需要在加载状态中执行的同步或异步任务。
loadingTextstring | undefined否加载遮罩显示的可选文字。

返回 ​

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

FaTableColumnsSettingDialog 实例方法 ​

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

open 打开 ​

打开

签名 ​

ts
open(): Promise<void>;

示例 ​

vue
<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>

输入 ​

该方法没有输入参数。

返回 ​

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

change 变更 ​

列改变

签名 ​

ts
change(): Promise<void>;

示例 ​

vue
<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>

输入 ​

该方法没有输入参数。

返回 ​

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

状态与生命周期 ​

组件高度由容器和传入的表格高度决定,移动端不会附加最小高度;容器尺寸变化时会持续同步宽高,但仅在宽度变化时重新计算自动列宽,避免移动端软键盘引起的纯高度变化中断输入;卡片边框颜色沿用 Element Plus 主题。

数据请求、自动列宽和 doLoading 分别持有 Loading。手动写入 loading=false 只释放手动所有权。卸载取消待执行渲染/列布局任务,等待 doRender 的调用正常结束;迟到请求结果不再写入状态。ResizeObserver 在 watcher 清理时断开。

展开列、选择列与序号列(2.0.23) ​

FaTable 统一管理这三类内置列,启用后的顺序为展开列、选择列、序号列,再接业务列。三列均固定在左侧,不参与业务列设置;配置 props.span 时,也会按指定字段合并相同行。

配置默认值行为
#expand未提供时不显示提供插槽即创建宽度为 35px 的展开列
selection-columnfalse显式启用勾选列,可配合 single、row-click-selection 和 row-selectable
index-columntrue显示序号列;设置 :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">。

vue
<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> 获得更精确的列配置与分页数据提示。

ts
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,
};