Skip to content

Table 表格

表格整体设计

设计

基础用法

配置columns表头和table-data表格数据。

自适应内容区高度

v0.1.17

表格配置 adaptive 可实现自适应内容区高度,adaptive 的默认值是 falseadaptive 的类型是

ts
boolean | {
  /** 表格距离页面底部的偏移量,默认值为 `20` */
  offsetBottom?: number
  /** 页面 `resize` 时的防抖时间,默认值为 `60` ms */
  timeout?: number
}

注意

表格设置height属性后, adaptive属性将不在生效

数据多级显示

columns中的 prop支持 x.y.z形式的 多(无限)级数据形式。

注意

数据级不宜过多,可能会影响性能

自定义状态

配置项中valueTypeselectradiocheckbox 时, 配置columns中的options,表格会自动显示 value 对应的状态label

默认的逻辑是 表格的tableData中的实际值optionsvalue 对比 严格相等的话,会取当前项的 label 显示在表格中,想自定义显示逻辑的话,只需配置columnscustomGetStatus即可。

表格列样式简单修改

配置columns中的 fieldProps,不仅会作用于表单单项,也会作用于表格单项。使用 fieldProps可以做简单的样式修改,更强大的自定义样式,请使用自定义表格项

操作栏

默认不显示。配置actionBar 即可。 actionBar 中的type 支持 buttoniconlink,对应element plusElButtonElIconElLink 组件。

配置 confirm 即可实现二次确认。配置 show 即可实现权限和动态显示。

操作栏actionBar 配置详情参考 ActionBarButtonsRow

操作栏事件

操作栏除了支持PlusTable Event中的clickActionclickActionConfirmCancel外,v0.1.8版本开始支持自身的事件。

ActionBarButtonsRow支持以下事件。

事件名类型触发说明
onClickv0.1.8ActionBarButtonsRow['onClick']点击当前按钮的时触发,可与 PlusTable 的事件 clickAction 同时触发;操作需要二次确认时:PlusTable 的事件 clickAction会在确认时触发,而当前的 onClick 是在点击时触发;
onConfirmv0.1.8ActionBarButtonsRow['onConfirm']操作需要二次确认时,点击确认时触发
onCancelv0.1.8ActionBarButtonsRow['onCancel'] 操作需要二次确认时,点击取消时触发, 可与 PlusTable 的事件 clickActionConfirmCancel 同时触发

操作栏权限控制

小于v0.1.7版本

可使用 ActionBarButtonsRow 中的 show 字段控制。

大于等于v0.1.7版本

可使用 ActionBarButtonsRow 中的 showdirectives指令字段控制。参考 vue 渲染函数自定义指令

操作栏二次确认类型

v0.1.17 版本新增气泡确认框 ElPopconfirm

设置表格属性 actionBar.confirmTypepopconfirm 即可生效,示例: <PlusTable :action-bar="{ confirmType: 'popconfirm'}" />

操作栏二次确认类型配置confirmType默认值为messageBoxElMessageBox.confirm

标题栏

标题栏默认显示右侧工具栏, 可以使用titletoolbar插槽定制。不需要的的话配置 <PlusTable :title-bar="false" />即可。

拖动排序行

注意

拖动排序行对应的 el-table-column 的 props,使用dragSortableTableColumnProps 属性配置。

配置drag-sortable,同时配合dragSortEnd使用。

列设置拖拽排序列

配置 TitleBar中的columnSetting中的dragSort属性,默认为 true 可拖拽。

不需要可以给 false: <PlusTable :title-bar="{ columnSetting: { dragSort: false } }" />

如下示例, 点击 表格右上角列设置 图标,即可通过列设置拖拽排序列。

分页栏

默认不显示,配置pagination属性即可。

序号栏

注意

序号栏对应的 el-table-column 的 props,使用indexTableColumnProps 属性配置。

默认不显示。配置hasIndexColumntrue即可。 配置indexContentStyle 可定制序号栏样式。使用indexTableColumnProps 为序号栏配置el-table-column属性。

多选

注意

多选栏对应的 el-table-column 的 props,使用selectionTableColumnProps 属性配置。

配置is-selection属性为true,即可显示表格多选框。默认值false。配合 el-table selection-change 事件使用。

展开行

注意

展开行栏对应的el-table-column 的 props,使用expandTableColumnProps 属性配置。

配置has-expand属性 true 可显示展开行,默认值 false。配合插槽 expand 使用。

树形结构

配置tree-props树形为children: 'children',数据结构中有 children 即可。 树形懒加载表格还需设置lazyload

注意

数据中 children中的id和表格id不能重复。row-key默认为id

多级表头

v0.1.7

数据结构比较复杂的时候,可使用多级表头来展现数据的层次关系。

只需要将 el-table-column 放置于el-table-column 中,就可以实现组头。

v0.1.19 新增

columns 配置添加 children 属性, 即可实现无限极表头。

表格显示单项插槽配置

组件提供 fieldSlots 对象可以简易配置表格显示单项插槽, fieldSlots 的插槽配置是根据表格的 valueType 自动进行匹配的, 如:

  • valueTypeimgfieldSlots的插槽就是给 ElImage的。
  • valueTypelink时,fieldSlots的插槽就是给 ElLink的。
  • valueTypetag时,fieldSlots的插槽就是给 ElTag的。
  • 其他以此类推

要实现更强大的自定义,请使用自定义表格项

注意

valueType 的值对应的组件不是 element-plus 组件时,fieldSlots不生效,或者组件本身没有插槽时也不生效。

可编辑表格 (整体)

注意

表格中表单数据不会主动和表格数据同步,需要结合 formChange 事件手动同步。

v0.1.4 更新 更新整体可编辑
v0.1.6 更新表格数据变更后新数据也可编辑

表格配置editabletrue即可实现整体可编辑, columns中的 editable 优先级会更高。

可编辑表格 (单行)

注意

表格中表单数据不会主动和表格数据同步,需要结合 formChange 事件手动同步。

v0.1.6 更新表格数据变更后新数据也可编辑

可编辑和校验单行,也可以控制单行的每一个单元格的编辑状态和校验。核心方法是 调用 formRefs 里的startCellEdit()方法。

可编辑表格 (单元格)

注意

表格中表单数据不会主动和表格数据同步,需要结合 formChange 事件手动同步。

v0.1.6 更新表格数据变更后新数据也可编辑

可编辑和校验单元格。核心方法是 调用 formRefs 里的startCellEdit()方法。

可编辑表格 (手动控制)

注意

表格中表单数据不会主动和表格数据同步,需要结合 formChange 事件手动同步。

v0.1.6 更新表格数据变更后新数据也可编辑

手动控制表格编辑

可编辑表格 (点击单元格)

注意

表格中表单数据不会主动和表格数据同步,需要结合 formChange 事件手动同步。

v0.1.4
v0.1.6 更新表格数据变更后新数据也可编辑

表格属性editable支持 boolean'click''dblclick'

  • 当值为true 时:表格都是编辑状态,
  • 当值为false(默认) 时 :表格都是显示状态,
  • 当值为'click'(点击) 或 'dblclick'(双击) 时 :全部表格都是显示状态,同时携带编辑 icon,需要点击或双击才能打开编辑状态,当点击表格外退出编辑状态,同时触发edited事件,当点击其他单元格时会退出当前单元格的编辑状态,不会触发edited事件。

提示

PlusColumn 配置中的 editable 仅支持 boolean,优先级高于表格整体的editable配置。

自定义表格项和表单项 ( 插槽 )

注意

插槽 的优先级低于 render,高于数据

  • 自定义表格项

    PlusTable 组件会自动根据配置项的 prop 生成对应的插槽,例如下面的配置项,则会自动生成两个名称叫做 [ plus-cell-name ]和 [ plus-cell-status] 的两个插槽,插槽的生成规则就是 固定 key 值 [ plus-cell- ] 然后加上 配置项的 prop

    ts
    import { PlusColumn } from 'plus-pro-components'
    
    const tableConfig: PlusColumn[] = [
      {
        label: '名称',
        // 自动生成对应的插槽 'plus-cell-name'
        prop: 'name'
      },
      {
        label: '状态',
        // 自动生成对应的插槽 'plus-cell-status'
        prop: 'status'
      }
    ]

    插槽作用域中会返回 scoped 参数,scoped 中 包含 proplabelvalueTypecolumn等参数可供使用。

  • 自定义表单项

    参考自定义表单项(插槽) ( 表格中需要开启 editable

自定义表格项和表单项 (render)

提示

render 的优先级高于插槽

  • 自定义表格项 (格式化表格显示)

    使用 render 函数自定义表格项。 render 方法需要返回一个 VNodestring,返回一个string时可以用来格式化表格显示。

    自定义表格项还支持 renderHTML方法,需要返回一个 HTML 字符串。谨慎使用,确保 HTML 字符串可信。

  • 自定义表单项

    参考自定义表单项-renderField ( 表格中需要开启 editable

自定义表格项和表单项 (jsx/tsx)

注意

jsx/tsx 的使用需要将 vue 单文件组件的script的属性 lang设置为jsx或者tsxjsx 中值使用单花括号{}绑定。

html
<script lang="tsx" setup></script>
  • 自定义表格项

    jsx/tsx 的支持本质是jsx/tsx解析出来是VNode, 使用 render 函数自定义表格项。

  • 自定义表单项

    参考自定义表单项-jsx-tsx ( 表格中需要开启 editable

自定义表格表头 (插槽)

注意

插槽 的优先级低于 renderHeader,高于 label

PlusTable 组件会自动根据配置项的 prop 生成对应的插槽,例如下面的配置项,则会自动生成两个名称叫做 [ plus-header-name ]和 [ plus-header-status] 的两个插槽,插槽的生成规则就是 固定 key 值 [ plus-header- ] 然后加上 配置项的 prop

ts
import { PlusColumn } from 'plus-pro-components'

const tableConfig: PlusColumn[] = [
  {
    label: '名称',
    // 自动生成对应的插槽 'plus-header-name'
    prop: 'name'
  },
  {
    label: '状态',
    // 自动生成对应的插槽 'plus-header-status'
    prop: 'status'
  }
]

插槽作用域中会返回 scoped 参数,scoped 中 包含 proplabelvalueTypecolumn等参数可供使用。

自定义表格表头 (renderHeader)

注意

renderHeader 的优先级高于插槽

  • 使用 renderHeader 函数自定义表格项。 renderHeader 方法需要返回一个 VNodeString

自定义表格表头 (jsx/tsx)

注意

jsx/tsx 的使用需要将 vue 单文件组件的script的属性 lang设置为jsx或者tsxjsx 中值使用单花括号{}绑定。

html
<script lang="tsx" setup></script>

jsx/tsx 的支持本质是jsx/tsx解析出来是VNode, 使用 renderHeader 函数自定义表格表头。

自定义 icon

v0.0.3

组件提供了以下插槽可以自定义 icon

插槽名说明
action-bar-more-icon操作栏更多旁边的 icon
tooltip-icon表格表头 tooltip icon
drag-sort-icon表格拖拽行 和 列设置里拖拽 icon
column-settings-icon表格表头 列设置 icon
density-icon表格表头 密度 icon

表格显示格式化

表格显示可通过以下三种方式格式化

方式一说明PlusColumn[valueType]是否生效版本支持
PlusColumn[render]返回一个字符串时完全自定义表格行,PlusColumn[valueType]不再生效。v0.0.1
PlusColumn[fieldSlots]定义PlusColumn[valueType]对应的组件的插槽v0.0.1
PlusColumn[formatter]仅仅格式化显示的值v0.1.13

PlusColumn[render] 使用示例

PlusColumn[fieldSlots] 使用示例

以下是PlusColumn[formatter] 的示例

v0.1.13

综合表格

Table API

Table Attributes

名称说明类型默认值是否必须
columns表格配置信息array PlusColumn[][]
tableData表格数据array[]
defaultSize默认密度(size)string'default'
pagination分页参数 (默认 false 给参数就显示)false / (object PlusPaginationProps )false
actionBar操作栏参数 (默认 false 给参数就显示)false / (objectActionBarProps )false
titleBar标题栏boolean/ (objectTitleBar)true
hasIndexColumn是否需要序号booleanfalse
isSelection是否是多选表格booleanfalse
dragSortable表格拖拽配置 (默认 false 给参数就显示)false / (objectSortableOptions )false
hasExpand是否需要展开行booleanfalse
loadingStatus加载状态booleanfalse
height表格高度string
editablev0.1.4表格整体可编辑boolean / string false
headerCellStyle表格表头样式object CSSProperties{'background-color': 'var(--el-fill-color-light)'}
indexContentStyle序号栏样式(object CSSProperties ) / function {}
dragSortableTableColumnProps拖拽栏 el-table-column 的 propsobject ElTableColumnProps{}
indexTableColumnProps序号栏 el-table-column 的 propsobject ElTableColumnProps{}
selectionTableColumnProps选择栏 el-table-column 的 propsobject ElTableColumnProps{width: 40}
expandTableColumnProps展开栏 el-table-column 的 propsobject ElTableColumnProps{}
adaptive v0.1.17表格高度自适应内容区域配置boolean|objectfalse
...............

...表示同时支持所有ElTable Attributes

提示

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

示例:

html
<PlusTable :stripe="true" :border="true" :fit="false" />

Table Events

名称说明类型
paginationChange分页改变触发function
clickAction点击操作栏触发(需要二次确认的,点击确认时触发)function ButtonsCallBackParams
clickActionConfirmCancel点击操作栏需要二次确认的取消时触发function ButtonsCallBackParams
dragSortEnd拖拽排序行触发function
formChange表格中有可以编辑的表单项目改变时触发function FormChangeCallBackParams
editedv0.1.4表格中点击编辑单元格退出时触发function
.........

...表示同时支持所有ElTable 事件

提示

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

示例:

模板中

html
<PlusTable @select="handleSelect" @select-all="handleSelectAll" />

setup 中

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

Table Slots

插槽名说明作用域插槽参数
title表格标题
toolbar工具栏左侧
expand展开行
pagination-leftv0.0.2分页器左侧内容 (默认生效,align 属性默认是 right
pagination-rightv0.0.2分页器右侧内容 (align 属性是 left时生效)
action-bar-more-iconv0.0.3操作栏更多旁边的 icon
tooltip-iconv0.0.3表格表头 tooltip icon
drag-sort-iconv0.0.3表格拖拽行 和 列设置里拖拽 icon
column-settings-iconv0.0.3表格表头 列设置 icon
density-iconv0.0.3表格表头 密度 icon
edit-iconv0.1.4表格处于编辑状态时的 icon
plus-cell-*自定义表格项,组件会自动根据配置项的 prop 生成对应的插槽object
plus-header-*自定义表格项 header,组件会自动根据配置项的 prop 生成对应的插槽object
plus-field-*PlusForm 的自定义表单项,组件会自动根据配置项的 prop 生成对应的插槽 ,需要开启属性 PlusColumn['editable']object
plus-extra-*PlusForm的自定义渲染 el-form-item 下一行额外的内容,组件会自动根据配置项的 prop 生成对应的插槽,需要开启属性 PlusColumn['editable']{column,row}
.........

...表示同时支持所有ElTable 插槽

提示

el-table 的其他插槽 如 append,emptyv0.1.7 开始支持 default 插槽。

Table Exposes

名称说明类型
tableInstanceel-table的实例object import('element-plus')['TableInstance']
formRefs表格中所有 form 的实例,可以用来控制表格是否可编辑,以及表格表单检验等object

拿到 tableInstance 后支持所有ElTable 方法

提示

clearSelection,getSelectionRows