ProTable - 高级表格

ProTable 的诞生是为了解决项目中需要写很多 table 的样板代码的问题，所以在其中封装了很多常用的逻辑。这些封装可以简单的分类为预设行为与预设逻辑。

图片来源 Antd ProTable (opens new window)

基础用法

API

ProTable 在 el-form 和 el-table 上进行了一层封装，支持了一些预设。这里只列出与 el-table 不同的 API。

ProTable Attributes

参数	说明	类型	默认值
search	搜索表单，传入对象时为搜索表单的配置	boolean | searchConfig	true
className	el-table 的类名	string	-
dataSource	el-table 的数据	Array	-
loading	表格数据请求加载状态	boolean	-
total	数据总条数	number	0
tableProps	el-table attributes 的配置	TableProps	-
tableEvents	el-table events 的配置，默认添加了 sort-change 事件	TableEvents	-
columns	列定义	columnsConfig[]	-
paginationProps	el-pagination attributes 的配置	PaginationProps	defaultPaginationProps
paginationMapping	分页参数字段映射配置	paginationMapping	-
initialValues	表单默认值	object	-
defaultSize	默认的 size	medium | small | mini	-
manualRequest	是否需要手动触发首次请求。配置为 true 时不可隐藏搜索表单	boolean	false
columnSettings	列设置	boolean | columnSettingsConfig	true

ProTable Events

参数	说明	类型	默认值
onParams	查询、重置、分页、排序 触发，获取查询参数	(params) => Promise<void> | void	-
onSubmit	提交表单时触发	(params) => void	-
onReset	重置表单时触发	() => void	-
onCollapse	展开、收起搜索表单	(collapsed: boolean) => void	-
onKeyChange	列设置（排序、重置）导致的表格重新渲染完成的回调	() => void	-

ProTable Methods

参数	说明	类型	默认值
setFieldsValue	手动更新表单数据	(values) => void	-
setFieldValue	手动更新单个字段数据	(key, value) => void	-
reload	刷新，接收一个参数：是否重置页码，resetPageIndex 默认 true	(resetPageIndex: boolean) => void	-
getTableRef	获取 el-table 的 ref	() => ref	-

标题栏 slot

name	描述
-	高级筛选栏 和 表格区域之间的区域

searchConfig

参数	说明	类型	默认值
searchText	查询按钮的文本	string	查询
resetText	重置按钮的文本	string	重置
labelWidth	标签的宽度	string	80px
labelPosition	标签的位置	left | right	right
rowProps	el-row attributes 的配置	RowProps	{ gutter: 8 }
colProps	el-col attributes 的配置	ColProps	defaultColConfig
className	组件内 el-form 的类名	string	-
defaultCollapsed	默认是否收起	boolean	true
collapsed	是否收起	boolean	-
defaultExpandedRows	默认展开的行数	number	2

defaultColConfig

const defaultColConfig = {
  xs: 24, // <768px
  sm: 24, // >=768px
  md: 12, // >=992px
  lg: 8,  // ≥1200px
  xl: 6,  // ≥1920px
}

columnsConfig 列定义

下面列出了与 el-table-column attributes 不同的 API。

参数	说明	类型	默认值
formItemProps	el-form-item attributes 的配置。rules 配置不生效	FormItemProps	-
renderLabel	自定义 el-form-item 的 label，不支持 slot 写法	() => jsx	-
valueType	表单元素类型，会生成不同的渲染器。设置 slot 表示自定义，可选	valueType | slot	-
renderField	自定义表单元素，可选	({ form, formItem }) => jsx	-
fieldProps	表单元素的 attributes。如果渲染出来的是 el-input，则对应 el-input 的 attributes	object	-
fieldEvents	表单元素的 events。如果渲染出来的是 el-input，则对应 el-input 的 events	object	-
options	选择器、单选框组、多选框组 的数据	Array	-
valueEnum	选择器枚举，方便自动生成选项	valueEnum	-
optionLoader	异步生成 选择器、级联选择器 下拉数据	() => Promise<any>	-
initialValue	表单默认值，优先级高于 initialValues	any	-
order	查询表单中的权重，权重大排序在前	number	-
hideInSearch	在查询表单中不展示此项	boolean	-
hideInTable	在表格中不展示此项	boolean	-
renderCellHeader	自定义表格标题	({ column, $index }) => jsx	-
renderCell	自定义表格内容	(scope) => jsx | jsx[]	-
disabled	当前列在列设置中是否可被勾选	boolean	-
key	vue 需要的 key，如果是 type: index|selection|expand 或已经设置了唯一的 prop，可以忽略这个属性	string	-

如果表格和表单的 prop 是同一个，则只需要配置表格的 prop 字段。同理 label 字段。

renderField 自定义渲染是值的传递。如果 prop 存在，则默认进行了初始化；反之则需要在 initialValues 添加默认值。

配置 valueEnum 在表格中会自动回显 label 值，注意 Map 类型取值需要匹配类型。

valueType slot

name	描述
[prop]	自定义表单元素，参数为 ({ form, formItem })

defaultPaginationProps

{
  "page-sizes": [10, 20, 30, 50],
  layout: "total, sizes, prev, pager, next, jumper",
  "hide-on-single-page": true,
}

paginationMapping

参数	说明	类型	默认值
pageKey	页码字段	string	pageNum
sizeKey	页数字段	string	pageSize

通过 Vue.extends 方法，可以全局配置这两个字段，参考下方示例代码。

import Vue from 'vue'
import { ProTable as ElProTable } from 'element-ui-pro-components'

const ProTable = Vue.extend({
  name: 'ProTable',
  extends: ElProTable,
  props: {
    // 分页字段映射配置
    paginationMapping: {
      type: Object,
      default: () => ({
        pageKey: 'page',
        sizeKey: 'size'
      })
    }
  }
})

Vue.component(ProTable.name, ProTable)
/* 或写为
 * Vue.use(ProTable)
 */

columnSettingsConfig

列设置功能提供了灵活、可配置的表格列管理能力，支持动态显示/隐藏列、列排序、固定列等功能，适用于复杂的数据展示场景。

参数	说明	类型	默认值
columnSetting	列设置文本	string	列设置
columnDisplay	列展示文本	string	列展示
resetText	重置按钮文本	string	重置
draggable	是否支持拖拽排序	boolean	true
checkable	显示/隐藏列	boolean	true

列设置中标题取 columnsConfig.label 字段。

显示/隐藏列取 columnsConfig.prop || columnsConfig.key。

列设置排除了 columnsConfig.type 字段。

拖拽排序遵循的是先排序，后分组，目的是保证列是整体有序的。

举个例子：

[
  { label: '标题1', prop: 'title1' }, // 不固定
  { label: '标题2', prop: 'title2', fixed: 'right' }, // 固定在右侧
  { label: '标题3', prop: 'title3', fixed: 'left' }, // 固定在左侧
  { label: '标题4', prop: 'title4' } // 不固定
]

当拖拽 prop = title4 到 prop = title1 上方的位置时，固定列的位置也会发生变化。

[
  { label: '标题4', prop: 'title4' }, // 不固定
  { label: '标题1', prop: 'title1' } // 不固定
  { label: '标题2', prop: 'title2', fixed: 'right' }, // 固定在右侧
  { label: '标题3', prop: 'title3', fixed: 'left' }, // 固定在左侧
]