配置项

Columns 配置项

属性名	说明	类型	默认值
prop	列字段名，对应数据的 key	string	—
label	列名称，表头显示内容	string / number	—
width	列宽度	string / number	—
type	列类型（如 index、selection、expand、radio、operation）	string	—
hidden	是否隐藏列	boolean	false
disabledHidden	列配置中是否禁用列隐藏选择	boolean	false
options	字典数据，配置 options 后可自动格式化 value 为 label	array	—
optionsProp	指定 options 的 key，优先从缓存获取对应 key 的 options 数据	string	—
optionField	指定 options 的 label、value、children、disabled 的 key	object
isFilterOptions	当前单元格值是否根据 options 格式化（根据 value 找 label）	boolean	true
ignoreOptionIfAbsent	options 里找不到 label 时，是否使用 value 作为 label	boolean	false
transformOption	自定义当前 option 选项的查找逻辑	function	—
render	自定义单元格内容渲染（tsx 语法）	function	—
renderHTML	自定义单元格内容渲染（返回 HTML 字符串）	function	—
formatValue	自定义单元格内容格式化	function	—
renderHeader	自定义表头内容渲染（tsx 语法）	function	—
renderHeaderHTML	自定义表头内容渲染（返回 HTML 字符串）	function	—
formatLabel	自定义表头内容格式化	function	—
children	多级表头，子列配置	array	—
tooltip	表头右侧 ElToolTip 提示	string / object	—
filter	是否开启 filter 功能	boolean	false
disabledFilter	是否禁用 filter 功能选择	boolean	false
filterProps	表头筛选配置项	object	—
beforeFilter	过滤前置处理，可以返回新的过滤值或 false 阻止过滤	function	false
disabledSortable	是否禁用列排序选择	boolean	false
disabledDragSort	是否禁用列拖拽排序	boolean	false
editable	是否开启编辑功能	boolean	false
editProps	编辑功能配置项	object	—
el	指定组件进行修饰（如 ElTag、ElLink  等）	string	—
elProps	指定 el 组件的 props	object / function	—
elSlots	el 组件的插槽	object	—
buttons	操作按钮集合（仅 operation 类型列）	array	—
showNumber	显示出来的按钮个数（仅 operation 类型列）	number / function	3
confirm	二次确认配置（仅 operation 类型列）	boolean / object	false
...	其他扩展属性，支持所有ElTableColumn Attributes	—	—

El 组件类型

el 属性除了输入大驼峰 Camel-Case 语法，也支持输入烤肉串 Kebab-Case 语法，例如：输入 ElTag，也可以输入 el-tag。

El 字面量	对应 ElementPlus 组件	对应内置组件	说明
ElText	el-text
ElTag	el-tag
ElCheckTag	el-check-tag
ElLink	el-link
ElProgress	el-progress
ElImage	el-image
Date		span	格式化为日期
Money		span	格式化为金钱
Copy		span	文本后出现复制按钮

自定义 El 组件类型

除了上述的 El 组件类型，你可以自定义一些 El 组件，然后通过字面量快速使用。

在 pro/table/src/helper/components.ts 文件中添加自定义 El 组件。

在 TableComponentEnum 新增 El 字面量，Key 要求全大写，使用 _ 连接单词，Value 要求大驼峰命名，如：

export enum TableComponentEnum {
  MY_COMPONENT = "MyComponent",
}

在 tableElComponentsMap 实现 El 组件，组件引入的命名和上方 TableComponentEnum 新增 Value 一致。

实现 El 组件的方式有两种。

组件形式

单独创建一个 Vue 组件，然后传入 tableElComponentsMap 里，如：

import { MyComponent } from "@/components/core/point-tag";

const tableElComponentsMap: Record<
  TablePascalCaseComponentName,
  Omit<Component, keyof ComponentConfig> | ComponentConfig
> = {
  MyComponent, // 和 TableComponentEnum 的 Value 命名一致
};

columns 配置项的 elProps 会传入 MyComponent 组件的 props 中，elSlots 会传入 MyComponent 组件的 slots 中。

对象形式

通过 is 属性或者 renderEl 属性传入组件，两个不可以同时生效，如果都有存在，则 renderEl 优先级高于 is。

NOTE

renderEl 需要搭配 h 函数直接构建一个组件，适合简单灵活的组件。如果是复杂的组件，建议在外部先写好组件，然后再引入。

is 属性

import { MyComponent } from "@/components/myComponent";

const tableElComponentsMap: Record<
  TablePascalCaseComponentName,
  Omit<Component, keyof ComponentConfig> | ComponentConfig
> = {
  MyComponent: {
    is: MyComponent,
  },
};

renderEl 属性

import { h } from "vue";

const tableElComponentsMap: Record<
  TablePascalCaseComponentName,
  Omit<Component, keyof ComponentConfig> | ComponentConfig
> = {
  MyComponent: {
    renderEl: h(), // 使用 h 函数自定义组件，适合简单灵活的组件
  },
};

Props 处理

如果想处理 elProps 后再传入 MyComponent 组件，或者传入一些默认的 Props，则使用对象形式传入，如：

import { MyComponent } from "@/components/myComponent";

const tableElComponentsMap: Record<
  TablePascalCaseComponentName,
  Omit<Component, keyof ComponentConfig> | ComponentConfig
> = {
  MyComponent: {
    is: MyComponent,
    props: (elRenderParams: ElRenderParams) => {
      return {
        /** 处理后的 Props*/
      };
    },
  },
};

ElRenderParams 参数类型如下：

export interface ElRenderParams {
  /** 未经过处理的原始值 */
  originValue: unknown;
  /** 经过处理的单元格值，如 originValue 为 0，displayValue 为男 */
  displayValue: unknown;
  /** format 函数处理后的值 */
  formatValue: unknown;
  /** 置项的 elProps */
  props: Record<string, any>;
  /** 配置项的 options（已经处理拿到的实际值） */
  options: ElDisplayProps["options"];
  /** 配置项的 optionField */
  optionField: ElDisplayProps["optionField"];
}

单元格值处理

某些场景下，需要对单元格的值进行格式化，如日期转为 YYYY-MM-DD 格式，或者数字转为 ￥1000.00 格式，则可以使用 format 函数进行格式化。

import { MyComponent } from "@/components/myComponent";

const tableElComponentsMap: Record<
  TablePascalCaseComponentName,
  Omit<Component, keyof ComponentConfig> | ComponentConfig
> = {
  MyComponent: {
    is: MyComponent,
    format: (value, props) => {
      console.log("当前单元格值：", value);
      console.log("经过 props 函数处理或者 elProps 传入的值：", props);

      return transform(value); // 返回格式化后的值
    },
  },
};

隐藏单元格

默认情况下，如果单元格的值为空，则依然会渲染单元格元素，因此如果希望隐藏整个单元格元素，通过 hidden 函数返回 true，如：

import { MyComponent } from "@/components/myComponent";

const tableElComponentsMap: Record<
  TablePascalCaseComponentName,
  Omit<Component, keyof ComponentConfig> | ComponentConfig
> = {
  MyComponent: {
    is: MyComponent,
    hidden: (value, props) => {
      console.log("当前单元格值：", value);
      console.log("经过 props 函数处理或者 elProps 传入的值：", props);

      return value === null || value === undefined;
    },
  },
};

如果您熟读 pro/table/src/plugins/el-display.vue 组件，则可以更改传入对象形式的参数。

ProTable 配置项

Attributes

属性名	说明	类型	默认值
columns	表格配置信息	TableColumn[]	[]
data	表格数据	array	[]
requestApi	请求表格数据的请求	function	—
defaultRequestParams	默认请求参数（请求一定会携带）	object	—
requestParams	请求参数	object	—
initRequestParams	是否立即执行请求	object	—
requestImmediate	分页参数 （默认 false 给参数就显示）	boolean	false
beforeSearch	查询数据前的回调函数，可以对查询参数进行处理或禁止查询	function	—
requestError	请求失败回调	function	—
transformData	对请求成功的数据进行处理	function	—
hideHead	是否隐藏表格顶部栏	boolean	false
controlHeadColumn	是否显示控制表格顶部栏的图标列	boolean	false
controlHeadColumnProps	控制表格顶部栏图标列（ElTableColumn）的 Props	object	—
card	是否使用卡片样式	boolean	false
pageInfo	分页信息	object PageInfo	—
pageField	分页信息 key 名配置	object PageField	—
pageScope	是否开启分页功能，pageMode 可以指定客户端（前端）分页还是服务端（后端）分页，当为 true 时，默认为客户端（前端）分页	boolean / string	false
filterScope	过滤规则，可以指定客户端（前端）过滤还是服务端（后端）过滤，当为 true 时，默认为客户端（前端）过滤	string	client
operationProp	操作列的 prop	string	operation
operationProps	操作列 props	object OperationProps	—
rowStyle	ElTable 的 rowStyle 配置项	object CSSProperties	—
cellStyle	ElTable 的 cellStyle 配置项	object CSSProperties	—
headerRowStyle	ElTable 的 headerRowStyle 配置项	object CSSProperties	—
headerCellStyle	ElTable 的 headerCellStyle 配置项	object CSSProperties	—
border	ElTable 的 border 配置项	boolean	false
stripe	ElTable 的 stripe 配置项	boolean	false
showHeader	ElTable 的 showHeader 配置项	boolean	true
highlightCurrentRow	ElTable 的 highlightCurrentRow 配置项	boolean	false
rowKey	ElTable 的 rowKey 配置项	string / function	id
headerBackground	是否显示表头背景	boolean	true
paginationProps	分页组件 props	object	—
emptyText	表格无数据时显示的文字	string	暂无数据
selectedRadio	默认选中的 radio，传入 rowKey 对应的值	string />	—
radioProps	ElRadio 单选框 props	object	—
preventCellEditClass	当单元格根元素存在某个 class 时，点击不会进入编辑模式	array	el-icon
editable	是否开启编辑功能，或指定编辑功能触发方式	boolean / string	—
toolButton	按钮显示数组	boolean / array	—
disabledToolButton	按钮禁用数组	array	[]
size	表格密度	string	default
sizeStyle	自定义不同尺寸的 rowStyle、cellStyle、headerCellStyle	array	—
title	表格标题	string	—
exportProps	表格导出配置	object	—
tooltipProps	ElTable Props	object	—
columnSetting	表格列配置	object ColumnSetting	—
baseSetting	表格基础配置	object BaseSetting	—
initNativeRowField	是否初始化部分加强属性到 scope.row 里	boolean	false
...	其他扩展属性，支持所有 ElTable Attributes	...	...

提示

el-table 的其他属性写法示例 如 stripe, border, fit 等

示例：

<ProTable :stripe="true" :border="true" :fit="false" />

Events

名称	说明	类型
register	注册 ProTable 组件实例和 ElTable 实例	function
selectionChange	多选框勾选事件	function
paginationChange	分页触发事件	function
dragSortEnd	拖拽排序结束事件	function
cellClick	单元格点击事件	function
cellDblClick	单元格双击事件	function
leaveCellEdit	离开单元格编辑事件	function
filter	过滤事件，返回输入的值以及 prop	function
filterClear	清空事件，返回输入的 prop	function
filterReset	重置所有表单事件	function
formChange	表单值改变事件	function
buttonClick	操作按钮点击时触发	function
buttonConfirm	二次确认的确定按钮点击时触发	function
buttonCancel	二次确认的取消按钮点击时触发	function
refresh	刷新按钮点击事件	function
sizeChange	密度选择事件	function
...	其他扩展属性，支持所有 ElTable 事件	...

提示

el-table 的其他事件写法示例 如 select, select-all, row-click 等

示例：

模板中

<ProTable @select="handleSelect" @select-all="handleSelectAll" />

setup 中

const handleSelect = (selection: any[], row: any) => {
  console.log(selection, row);
};
const handleSelectAll = (selection: any[]) => {
  console.log(selection);
};

Slots

插槽名	说明	作用域插槽参数
default	ElTable  的  default 插槽
head-left	表格顶部左侧插槽	object
head-right	表格顶部右侧插槽，覆盖工具栏	object
head-tool-before	表格顶部工具栏前侧插槽	object
head-tool-after	表格顶部工具栏后侧插槽	object
pagination-left	分页器左侧内容 （当 paginationProps.align  属性为  right 时生效）
pagination-right	分页器右侧内容  （当 paginationProps.align  属性为  left 时生效）
header-before	所有表头内容前
header-right	所有表头标签后
refresh-icon	表格顶部工具栏刷新按钮 icon
size-icon	表格顶部工具栏密度按钮 icon
export-icon	表格顶部工具栏导出按钮 icon
column-setting-icon	表格顶部工具栏列配置按钮 icon
base-setting-icon	表格顶部工具栏基础配置按钮 icon
tooltip-icon	表格表头提示 icon
operation-more-icon	操作按钮的更多 icon
filter-icon	表格表头筛选器 icon
filter-button	表格表头筛选器内按钮	object
drag-sort-icon	表格拖拽行  icon
'prop'	自定义表格单元格，自动根据配置项的 prop 生成对应的插槽	object
'prop-header'	自定义表格项 header，自动根据配置项的 prop 生成对应的插槽	object
...	当 el 指定组件类型后，支持传入该组件的插槽，如 el-tag 组件的 default 插槽	...
...	其他扩展属性，支持所有 ElTable 插槽	...

提示

el-table 的其他插槽 如 append, empty。

Exposes

名称	说明	类型
tableData	表格数据	array
pageInfo	分页信息	object
searchParams	查询参数	object
searchInitParams	查询参数（初始化参数）	object
getTableList	重新请求表格数据（使用旧的查询参数），当传入 request-api 配置生效	function
search	重新请求表格数据（使用新的查询参数），当传入 request-api 配置生效	function
reset	重置查询参数为 searchInitParams，并请求表格数据，当传入 request-api 配置生效	function
setProps	设置 ProTable 组件的 props	function
setColumn	设置 column	function
addColumn	添加 column	function
delColumn	删除 column	function
tableHeadInstance	TableHead 组件实例	object
tableMainInstance	TableMain 组件实例	object
getElTableInstance	获取 ElTable 组件实例	function
getElFormInstance	获取 ElForm 组件实例，当开启编辑态后获取不为空	function
getElFormItemInstance	获取 ElFormItem 组件实例，当开启编辑态后获取不为空	function
getElFormItemInstance	获取指定 prop 的 ElFormItem 实例	function
getElInstance	获取表单组件实例	function

拿到 tableInstance 后支持所有 ElTable 方法

提示

如 clearSelection, getSelectionRows 等