ProTable 表格

面向后台数据列表的高级表格，支持列配置、字典、分页、工具栏和扩展渲染。

基础示例

展示本地数据表格和状态列。

示例使用本地演示数据；上传、校验和提交不会连接业务后端。

<script setup lang="ts">
import { ref, } from "vue";
import { ProTable } from "@/components/pro/table";

const columns = [{ prop: "name", label: "名称" }, { prop: "status", label: "状态", el: "el-tag", options: [{ label: "启用", value: 1, tagType: "success" }, { label: "停用", value: 0, tagType: "danger" }] }];
const data = [{ name: "材料库", status: 1 }, { name: "报价单", status: 0 }];
</script>

<template>
  <ClientOnly>
    <div class="demo-surface">
      <ProTable :columns="columns" :data="data" :tool-button="false" />
    </div>
  </ClientOnly>
</template>

隐藏源代码

请求与操作列

使用 mock 请求、分页、选择列和操作插槽。

示例使用本地演示数据；上传、校验和提交不会连接业务后端。

<script setup lang="ts">
import { ref } from "vue";
import { ProTable } from "@/components/pro/table";

const selectedText = ref("未选择数据");
const source = [
  { id: 1, name: "材料库", status: 1, owner: "采购组" },
  { id: 2, name: "报价单", status: 0, owner: "成本组" },
  { id: 3, name: "合同台账", status: 1, owner: "项目组" },
];

const columns = [
  { type: "selection", width: 48 },
  { prop: "name", label: "名称" },
  { prop: "owner", label: "负责人" },
  {
    prop: "status",
    label: "状态",
    el: "el-tag",
    options: [
      { label: "启用", value: 1, tagType: "success" },
      { label: "停用", value: 0, tagType: "danger" },
    ],
  },
  { prop: "operation", label: "操作", width: 140 },
];

const requestApi = async () => ({ total: source.length, list: source });

const handleSelectionChange = (state: { selectedList?: unknown[] }) => {
  selectedText.value = `已选择 ${state.selectedList?.length ?? 0} 条`;
};
</script>

<template>
  <ClientOnly>
    <div class="demo-surface">
      <ProTable
        :columns="columns"
        :request-api="requestApi"
        request-immediate
        :tool-button="['refresh']"
        @selection-change="handleSelectionChange"
      >
        <template #operation="{ row }">
          <el-button link type="primary">查看 {{ row.name }}</el-button>
        </template>
      </ProTable>
      <p class="table-tip">{{ selectedText }}</p>
    </div>
  </ClientOnly>
</template>

<style scoped>
.table-tip {
  margin: 12px 0 0;
  color: #667085;
}
</style>

隐藏源代码

引入方式

import { ProTable, ProTableMain, ElDisplay } from "@/components/pro/table";

Props

参数	说明	类型	默认值	必填
editable	是否开启编辑功能，或指定编辑功能触发方式	MaybeRefOrGetter<boolean | "click" | "dblclick">	-	否
optionsMap	字典枚举	OptionsMapType	-	否
data	表格数据	object[]	[]	否
rowKey	行主键	TableProps<object>["rowKey"]	"id"	否
operationProp	操作列的 prop	string	"operation"	否
operationProps	操作列 props	Partial<OperationNamespace.Props>	{}	否
pageInfo	分页信息	Partial<PageInfo>	() => defaultTablePageInfo	否
pageScope	是否开启分页功能，可以指定客户端（前端）分页还是服务端（后端）分页，当为 true 时，默认为客户端（前端）分页	boolean | Environment | \${Environment}``	false	否
paginationProps	分页组件 props	MaybeRef<Partial<PaginationProps>>	{}	否
filterScope	过滤规则，可以指定客户端（前端）过滤还是服务端（后端）过滤，当为 true 时，默认为客户端（前端）过滤	Environment | \${Environment}``	"client"	否
headerCellStyle	ElTable 的 headerCellStyle 配置项	TableProps<object>["headerCellStyle"]	{}	否
headerBackground	是否显示表头背景。	boolean	true	否
emptyText	表格无数据时显示的文字	string	"暂无数据"	否
selectedRadio	默认选中的 radio，传入 rowKey 对应的值	TableColumnTypeNamespace.Props["selectedRadio"]	""	否
radioProps	ElRadio 单选框 props	TableColumnTypeNamespace.Props["radioProps"]	{}	否
preventCellEditClass	当单元格根元素存在某个 class 时，点击不会进入编辑模式	string[]	[]	否
initNativeRowField	是否初始化部分加强属性到 scope.row 里	boolean	false	否
toolButton	按钮显示数组	boolean | (ToolButtonEnum | \${ToolButtonEnum}`)[]`	undefined	否
disabledToolButton	按钮禁用数组	(ToolButtonEnum | \${ToolButtonEnum}`)[]`	[]	否
size	表格密度	TableSizeEnum | \${TableSizeEnum}``	() => TableSizeEnum.Default	否
sizeStyle	自定义不同尺寸的 rowStyle、cellStyle、headerCellStyle	Partial<Record<TableSizeEnum, SizeStyle>>	{}	否
title	表格标题	string	""	否
exportProps	表格导出配置	ExportProps	undefined	否
tooltipProps	ElTable Props	Partial<ElTooltipProps>	() => defaultTooltipProps	否
columnSetting	表格列配置	ColumnSetting	{}	否
baseSetting	表格基础配置	BaseSetting	{}	否
columns	列配置项	MaybeRef<LooseTableColumn[]>	[]	否
requestApi	请求表格数据的请求	(params: Recordable) => Promise<unknown>	undefined	否
defaultRequestParams	默认请求参数（请求一定会携带）	MaybeRef<Recordable>	{}	否
requestParams	请求参数	MaybeRef<Recordable>	{}	否
initRequestParams	初始化请求参数（重置时恢复为初始化参数）	MaybeRef<Recordable>	{}	否
requestImmediate	是否立即执行请求	boolean	true	否
beforeSearch	查询数据前的回调函数，可以对查询参数进行处理或禁止查询	(searchParams: Recordable) => false | Recordable	undefined	否
requestError	请求失败回调	(error: unknown) => void	undefined	否
transformData	对请求成功的数据进行处理	(data: Recordable[], result?: unknown) => unknown	undefined	否
hideHead	是否隐藏表格顶部栏	boolean	false	否
controlHeadColumn	是否显示控制表格顶部栏的图标列	boolean	false	否
controlHeadColumnProps	控制表格顶部栏图标列（ElTableColumn）的 Props	LooseTableColumn	{}	否
card	是否使用卡片样式	boolean	false	否
pageField	分页信息 key 名配置	PageField	{}	否
rowStyle	ElTable 的 rowStyle 配置项	TableProps<object>["rowStyle"]	{}	否
cellStyle	ElTable 的 cellStyle 配置项	TableProps<object>["cellStyle"]	{}	否
headerRowStyle	ElTable 的 headerRowStyle 配置项	TableProps<object>["headerRowStyle"]	{}	否
border	ElTable 的 border 配置项	TableProps<object>["border"]	false	否
stripe	ElTable 的 stripe 配置项	TableProps<object>["stripe"]	false	否
showHeader	ElTable 的 showHeader 配置项	TableProps<object>["showHeader"]	true	否
highlightCurrentRow	ElTable 的 highlightCurrentRow 配置项	TableProps<object>["highlightCurrentRow"]	true	否

Events

事件名	说明	回调参数
formChange	表单值改变事件	fromValue: unknown, prop: NonNullable<TableColumn["prop"]>, scope: TableScope
filterClear	清空事件，返回输入的 prop	prop: string
filterReset	重置所有表单事件	-
buttonClick	操作按钮点击时触发	params: OperationNamespace.ButtonsCallBackParams
buttonConfirm	二次确认的确定按钮点击时触发	params: OperationNamespace.ButtonsCallBackParams
buttonCancel	二次确认的取消按钮点击时触发	params: OperationNamespace.ButtonsCallBackParams
selectionChange	多选框勾选事件	useSelectReturn: SelectState, index?: number
paginationChange	分页触发事件	pageInfo: PageInfo
radioChange	单选框选中事件	row: Recordable, index: number
dragSortEnd	拖拽排序结束事件	newIndex: number, oldIndex: number
cellClick	单元格点击事件	row: TableRow, column: TableColumn, cell: HTMLTableCellElement, event: Event,
cellDblClick	单元格双击事件	row: TableRow, column: TableColumn, cell: HTMLTableCellElement, event: Event,
leaveCellEdit	离开单元格编辑事件	row: TableRow, column: TableColumn
filter	过滤事件，返回输入的值以及 prop	filterModel: Recordable, filterValue: unknown, prop: string
refresh	刷新按钮点击事件	-
sizeChange	密度选择事件	size: TableSizeEnum, sizeStyle: SizeStyle
printer	打印按钮点击事件	selectedList?: Recordable[], selectedListIds?: string[]
register	注册组件实例	proTableInstance: ComponentPublicInstance | null, elTableInstance: TableInstance | null

Slots

插槽名	说明	参数
动态插槽(slot)	动态转发当前组件收到的同名插槽。	-

Expose

名称	说明	类型
tableData	当前表格数据。	-
pageInfo	当前分页信息。	-
searchParams	当前查询参数。	-
searchInitParams	初始查询参数。	-
fetch	重新请求数据。	-
search	按当前条件查询数据。	-
reset	重置组件状态。	-
handlePagination	处理分页变化。	-
setProps	动态设置组件属性。	-
setColumn	动态设置列配置。	-
addColumn	动态新增列配置。	-
delColumn	动态删除列配置。	-
tableHeadInstance	表格头部组件实例。	-
tableMainInstance	表格主体组件实例。	-
getElTableInstance	获取 Element Plus 表格实例。	-
getElFormInstance	获取查询表单实例。	-
getElFormItemInstance	获取查询表单项实例。	-
getElInstance	获取内部组件实例。	-

Module API

名称	说明	类型
ProTable	导出 ProTable 供业务侧复用。	useInstall(index)
ProTableMain	导出 ProTableMain 供业务侧复用。	useInstall(tableMain)

Types

PageInfo

导出 PageInfo 供业务侧复用。

字段	说明	类型	默认值	必填
pageNum	当前页	number	-	是
pageSizes	页码数组	number[]	-	否
pageSize	一页显示多少条数据	number	-	是

PaginationProps

导出 PaginationProps 供业务侧复用。

字段	说明	类型	默认值	必填
autoScroll	切换页数，是否自动滚动到最上面	boolean	true	否
hidden	是否隐藏分页	boolean	false	否
reset	切换 pageSize，pageNum 是否重置为 1	boolean	true	否
total	总数	number	0	否
align	分页对齐方式	"left" | "right"	'right'	否
layoutConfig	分页布局配置	string	'total, sizes, prev, pager, next, jumper'	否

SizeStyle

表格样式属性

字段	说明	类型	默认值	必填
rowStyle	配置 rowStyle。	CSSProperties	-	否
cellStyle	配置 cellStyle。	CSSProperties	-	否
headerRowStyle	配置 headerRowStyle。	CSSProperties	-	否
headerCellStyle	配置 headerCellStyle。	CSSProperties	-	否

ExportProps

表格导出类型

字段	说明	类型	默认值	必填
mode	导出时的表头配置	ExportKey | \${ExportKey}``	'label'	否
fileName	导出的文件名	string	'export-table-时间戳'	否
title	ElMessageBox.confirm 的 title	string	'请选择导出列'	否
options	ElMessageBox.confirm 的 options	ElMessageBoxOptions	-	否
appContext	ElMessageBox.confirm 的 appContext	AppContext | null	-	否
exportFile	自定义导出为文件	(data?: Recordable[]) => void | Promise<void>	-	否

ColumnSetting

表格列配置的配置项

字段	说明	类型	默认值	必填
hideDragSort	是否禁用拖拽显示	boolean	false	否
hideHidden	是否禁用隐藏显示	boolean	false	否
hideSortable	是否禁用排序显示	boolean	false	否
hideFilter	是否禁用筛选显示	boolean	false	否
disabledDragSort	是否禁用拖拽排序选择	boolean	false	否
disabledHidden	是否禁用隐藏选择	boolean	false	否
disabledSortable	是否禁用排序选择	boolean	false	否
disabledFilter	是否禁用筛选选择	boolean	false	否

BaseSetting

表格基础配置项

字段	说明	类型	默认值	必填
border	是否开启边框	boolean	true	否
stripe	是否开启斑马纹	boolean	false	否
headerBackground	是否开启表头背景色	boolean	true	否
highlightCurrentRow	是否开启单击高亮当前行	boolean	true	否
showHeader	是否开启显示表头	boolean	true	否
disabledBorder	是否开启禁用边框选择	boolean	false	否
disabledStripe	是否开启禁用斑马纹选择	boolean	false	否
disabledHeaderBackground	是否开启禁用表格高亮选择	boolean	false	否
disabledHighlightCurrentRow	是否开启禁用单击高亮当前行选择	boolean	false	否
disabledShowHeader	是否开启禁用单显示表头选择	boolean	false	否
stickyHeader	是否开启固定表头	boolean	true	否
disabledStickyHeader	是否禁用固定表头选择	boolean	false	否

LooseTableColumn

组件边界使用的宽松表格列配置，擦除具体业务行模型。

字段	说明	类型	默认值	必填
children	多级表头列配置。	LooseTableColumn[]	-	否
renderHeader	表头渲染回调，组件内部按实际列配置收窄后调用。	unknown	-	否
renderHeaderHTML	表头 HTML 渲染回调，组件内部按实际列配置收窄后调用。	unknown	-	否
formatLabel	表头格式化回调，组件内部按实际列配置收窄后调用。	unknown	-	否
render	单元格渲染回调，组件内部按实际列配置收窄后调用。	unknown	-	否
renderHTML	单元格 HTML 渲染回调，组件内部按实际列配置收窄后调用。	unknown	-	否
formatValue	单元格格式化回调，组件内部按实际列配置收窄后调用。	unknown	-	否
elSlots	组件插槽回调，组件内部按实际列配置收窄后调用。	unknown	-	否
elProps	展示组件属性，组件内部按实际列配置收窄后调用。	unknown	-	否
transformOption	字典选项转换回调，组件内部按实际列配置收窄后调用。	unknown	-	否
beforeFilter	过滤前置回调，组件内部按实际列配置收窄后调用。	unknown	-	否

PageField

导出 PageField 供业务侧复用。

字段	说明	类型	默认值	必填
pageNum	当前页数字段	string	'pageNum'	否
pageSize	每页数量字段	string	'pageSize'	否
pageSizes	分页选择器字段	string	'pageSizes'	否
total	总页数字段	string	'total'	否

TableColumn

表格列配置

字段	说明	类型	默认值	必填
buttons	操作按钮集合	MaybeRefOrGetter<ButtonRaw[]>	-	否
showNumber	显示出来的按钮个数	number | ((row: TableRow, index: number) => number)	3	否
confirm	二次确认配置	| boolean<br> | Recordable<br> | Confirm<OperationConfirmEl.ElPopconfirm | \${OperationConfirmEl.ElPopconfirm}`> | Confirm<OperationConfirmEl.ElMessageBox | `${OperationConfirmEl.ElMessageBox}`>`	-	否
width	表头宽度	MaybeRefOrGetter<string | number>	-	否
label	列名称	MaybeRefOrGetter<string>	-	否
type	列类型	TableColumnTypeEnum | \${TableColumnTypeEnum}``	-	否
hidden	是否隐藏在表格当中	MaybeRefOrGetter<boolean>	false	否
disabledHidden	列配置中是否禁用列隐藏选择	MaybeRefOrGetter<boolean>	false	否
options	字典数据	FormItemColumnProps["options"]	-	否
optionsProp	指定 Options 的 key，如果设置了则优先从缓存获取对于 key 的 Options 数据	string	-	否
optionCache	是否缓存字典数据	boolean	true	否
optionField	字典指定 label && value && children 的 key 值	FormItemColumnProps["optionField"]	'{ label: "label", value: "value", children: "children", disabled: "disabled" }'	否
isFilterOptions	当前单元格值是否根据 options 格式化（根据 value 找 label）	MaybeRefOrGetter<boolean>	true	否
ignoreOptionIfAbsent	如果 options 里找不到对应的 label，则使用 value 作为 label	MaybeRefOrGetter<boolean>	false	否
transformOption	自定义当前 option 选项	(<br> value: unknown,<br> options: ElOption[],<br> row: Recordable,<br> ) => ElOption | undefined	-	否
renderHeader	自定义表头内容渲染（tsx 语法）	BivariantCallback<[scope: TableRenderParams<T>], RenderTypes>	-	否
renderHeaderHTML	自定义表头内容渲染（返回 HTML），优先级低于 render，高于插槽	BivariantCallback<[scope: TableRenderParams<T>], string>	-	否
formatLabel	自定义表头内容	BivariantCallback<<br> [label: unknown, scope: TableRenderParams<T>],<br> string | number<br> >	-	否
render	自定义单元格内容渲染（tsx 语法）	BivariantCallback<[scope: TableRenderParams<T>], RenderTypes>	-	否
renderHTML	自定义单元格内容渲染（返回 HTML），优先级低于 render，高于插槽	BivariantCallback<[scope: TableRenderParams<T>], string>	-	否
formatValue	自定义单元格内容	BivariantCallback<<br> [value: unknown, scope: TableRenderParams<T>],<br> string | number<br> >	-	否
children	多级表头	TableColumn<T>[]	-	否
tooltip	表头右侧 ElToolTip 提示	FormItemColumnProps["tooltip"]	-	否
filter	是否开启 filter 功能	MaybeRefOrGetter<boolean>	false	否
disabledFilter	列配置中是否禁用 filter 功能选择	MaybeRefOrGetter<boolean>	false	否
filterProps	表头筛选配置项	TableFilterProps	-	否
beforeFilter	过滤前置处理，可以返回新的过滤值或者 false 来阻止过滤	(<br> filterValue: unknown,<br> filterModel: Recordable,<br> prop: string | undefined,<br> ) => unknown | false | undefined	-	否
disabledSortable	列配置中是否禁用列排序选择	MaybeRefOrGetter<boolean>	false	否
disabledDragSort	列配置中是否禁用列拖拽排序	MaybeRefOrGetter<boolean>	false	否
editable	是否开启编辑功能	MaybeRefOrGetter<boolean>	-	否
editProps	编辑功能配置项	TableEditProps	-	否
elSlots	el 组件的插槽	{<br> [slotName: string]: BivariantCallback<<br> [data: TableRenderParams<T> & Recordable],<br> RenderTypes<br> >;<br> }	-	否

TableScope

表格行 Scope

字段	说明	类型	默认值	必填
$index	表格行索引	number	-	是
row	表格行数据	TableRow<T>	-	是
column	表格列数据	TableColumn<T>	-	是
rowIndex	表格行索引	number	-	否
cellIndex	表格列索引	number	-	是
store	表格store	Recordable	-	是
expanded	表格 expanded	boolean	-	是
_self	表格 _self	Recordable	-	是

API 根据当前组件源码生成；同步版本与验证记录见维护说明。