CodeBox

Appearance

Table 表格

浏览量：

Table 表格组件是基于 Element Plus 的 el-table 和 el-table-column 组件封装而成，提供了更简洁的配置方式，支持通过 columns-props 数组快速生成表格列，同时完全兼容 Element Plus Table 的所有功能。

INFO

Table 组件完全继承了 Element Plus Table 组件的所有属性和事件，因此支持所有 Element Plus Table 组件的功能，包括排序、筛选、合并单元格、自定义索引、工具提示等高级特性。

基础用法 ​

通过 data 属性传入表格数据，通过 columns-props 数组配置表格列。组件会自动将 columns-props 数组渲染为表格列。

方式一：直接传递属性 ​

可以直接在组件上传递 Element Plus Table 的所有属性，如 data、border、stripe 等。

loading

方式二：通过 table-props 配置 ​

也可以通过 table-props 属性统一传递 Element Plus Table 的所有属性。这种方式适合需要动态配置表格属性的场景。

loading

自定义列内容 ​

组件支持三种方式自定义列的显示内容：

方式一：通过插槽（推荐） ​

在 columns-props 中为某个列设置 slotName 属性，然后在模板中使用对应的插槽。插槽会接收一个作用域参数 { scope }，包含当前行的数据。

TIP

  • 插槽名称必须与 columns-props 中配置的 slotName 一致
  • 插槽会接收 { scope } 作为作用域参数，可以通过 scope.row 访问行数据，通过 scope.$index 访问行索引
  • scope.row 是响应式的，可以直接在模板中使用
loading

方式二：通过 h 函数 ​

在 columns-props 中为某个列设置 h 函数，使用 Vue 渲染函数完全自定义列的渲染逻辑。h 函数接收两个参数：scope（作用域对象）和 h（Vue 的渲染函数）。

TIP

  • h 函数适合需要完全控制渲染逻辑的场景
  • 如果同时设置了 slotName 和 h 函数，slotName 的优先级更高
loading

方式三：使用 formatter ​

在 columns-props 中为某个列设置 formatter 函数，用于格式化显示内容。这是 Element Plus Table 的原生功能。

vue
<script setup>
const columnsProps = [
  {
    label: '日期',
    prop: 'date',
    formatter: (row, column, cellValue) => {
      return cellValue ? new Date(cellValue).toLocaleDateString() : '-'
    },
  },
]
</script>

合并单元格 ​

通过 table-props 传递 span-method 属性可以实现单元格合并功能。span-method 是一个函数，返回一个包含 rowspan 和 colspan 的对象，或者返回 [rowspan, colspan] 数组。

loading

工具提示 ​

通过 table-props 传递 show-overflow-tooltip 属性可以显示溢出内容的工具提示，通过 tooltip-formatter 可以自定义工具提示的显示内容。

loading

表格布局 ​

通过 table-props 传递 table-layout 属性可以控制表格的布局方式。fixed 表示固定布局，auto 表示自动布局。

loading

属性说明 ​

属性名类型默认值说明
dataArray[]表格数据，数组中的每个对象对应一行数据
table-propsObject{}Element Plus Table 的所有属性，详见下方 table-props 配置
columns-propsArray[]表格列配置数组，每个元素对应一列，详见下方 columns-props 配置

table-props 配置 ​

table-props 对象支持 Element Plus el-table 组件的所有属性，包括但不限于：

属性名类型默认值说明
dataArray[]表格数据
heightString | Numberundefined表格高度
max-heightString | Numberundefined表格最大高度
stripeBooleanfalse是否为斑马纹表格
borderBooleanfalse是否带有纵向边框
sizeStringundefined表格尺寸，可选值：large、default、small
fitBooleantrue列的宽度是否自撑开
show-headerBooleantrue是否显示表头
highlight-current-rowBooleanfalse是否要高亮当前行
row-keyString | Functionundefined行数据的 Key，用于优化表格的渲染
empty-textString'暂无数据'空数据时显示的文本内容
default-expand-allBooleanfalse是否默认展开所有行，当表格包含展开行时有效
expand-row-keysArray[]可以通过该属性设置 Table 目前的展开行，需要设置 row-key 属性才能使用
default-sortObjectundefined默认的排序列的 prop 和顺序
tooltip-effectString'dark'tooltip effect 属性
show-overflow-tooltipBooleanfalse当内容过长被隐藏时显示 tooltip
tooltip-optionsObject{}tooltip 的配置项
tooltip-formatterFunctionundefined自定义 tooltip 的显示内容
span-methodFunctionundefined合并行或列的计算方法
summary-methodFunctionundefined自定义的合计计算方法
row-class-nameString | Functionundefined行的 className 的回调方法，也可以使用字符串为所有行设置一个固定的 className
row-styleObject | Functionundefined行的 style 的回调方法，也可以使用一个固定的 Object 为所有行设置一样的 Style
cell-class-nameString | Functionundefined单元格的 className 的回调方法
cell-styleObject | Functionundefined单元格的 style 的回调方法
header-row-class-nameString | Functionundefined表头行的 className 的回调方法
header-row-styleObject | Functionundefined表头行的 style 的回调方法
header-cell-class-nameString | Functionundefined表头单元格的 className 的回调方法
header-cell-styleObject | Functionundefined表头单元格的 style 的回调方法
tree-propsObject{ hasChildren: 'hasChildren', children: 'children' }渲染嵌套数据的配置选项
lazyBooleanfalse是否懒加载子节点数据
loadFunctionundefined加载子节点数据的函数，lazy 为 true 时生效
table-layoutString'fixed'设置表格单元、行和列的布局方式，可选值：fixed、auto
其他属性--支持透传 Element Plus el-table 组件的所有属性

TIP

  • 组件完全兼容 Element Plus Table 的所有属性和功能
  • 可以参考 Element Plus Table 文档 了解更多高级用法
  • table-props 中的属性会与直接传递的属性合并，直接传递的属性优先级更高
  • 事件可以通过 onXxx 格式在 table-props 中配置，例如 onRowClick、onSelectionChange 等

columns-props 配置 ​

columns-props 数组中的每个列对象支持以下属性：

属性名类型必填说明
labelString是显示的标题
propString否对应列内容的字段名，也可以使用 property 属性
slotNameString否自定义列的内容，需要通过插槽实现，详见 自定义列内容
hFunction否自定义列的内容，使用渲染函数实现，详见 自定义列内容
typeString否对应列的类型，可选值：selection（多选框）、index（索引）、expand（展开行）
widthString | Number否对应列的宽度
min-widthString | Number否对应列的最小宽度
fixedString | Booleanfalse列是否固定，可选值：true、'left'、'right'
sortableBoolean | Stringfalse对应列是否可以排序，可选值：true、'custom'
sort-methodFunctionundefined对数据进行排序的时候使用的方法
sort-byString | Array | Functionundefined指定数据按照哪个属性进行排序
sort-ordersArray['ascending', 'descending', null]数据在排序时所使用排序策略的轮转顺序
resizableBooleantrue对应列是否可以通过拖动改变宽度
formatterFunctionundefined用来格式化内容
show-overflow-tooltipBooleanundefined当内容过长被隐藏时显示 tooltip
tooltip-formatterFunctionundefined自定义该列 tooltip 的显示内容
alignString'left'对齐方式，可选值：left、center、right
header-alignStringundefined表头对齐方式，可选值：left、center、right
class-nameStringundefined列的 className
label-class-nameStringundefined当前列标题的自定义类名
selectableFunctionundefined仅对 type=selection 的列有效，类型为 Function，Function 的返回值用来决定这一行的 CheckBox 是否可以勾选
reserve-selectionBooleanfalse仅对 type=selection 的列有效，类型为 Boolean，为 true 则会在数据更新之后保留之前选中的数据（需指定 row-key）
filtersArrayundefined数据过滤的选项，数组格式，数组中的元素需要有 text 和 value 属性
filter-placementStringundefined过滤弹出框的定位
filter-multipleBooleantrue数据过滤的选项是否多选
filter-methodFunctionundefined数据过滤使用的方法
filtered-valueArrayundefined选中的数据过滤项，如果需要自定义表头过滤的渲染方式，可能会需要此属性
indexNumber | Functionundefined如果设置了 type=index，可以通过传递 index 属性来自定义索引
其他属性--支持透传 Element Plus el-table-column 组件的所有属性

TIP

  • prop 和 property 都可以用来指定列对应的字段名，两者功能相同
  • 如果设置了 slotName，必须提供对应的插槽，否则会抛出错误
  • 如果同时设置了 slotName 和 h 函数，slotName 的优先级更高
  • h 函数接收两个参数：scope（作用域对象）和 h（Vue 的渲染函数）
  • 除了上述属性外，columns-props 中的每个列对象还支持透传 Element Plus el-table-column 组件的所有属性

插槽说明 ​

组件支持通过插槽自定义列的显示内容。插槽名称与 columns-props 中配置的 slotName 一致。

插槽名说明作用域参数
{slotName}自定义列的内容，slotName 对应 columns-props 中配置的 slotName{ scope } - 作用域对象，包含 scope.row（行数据）、scope.column（列信息）、scope.$index（行索引）等

TIP

  • 插槽名称必须与 columns-props 中配置的 slotName 完全一致
  • 插槽会接收 { scope } 作为作用域参数
  • scope.row 是响应式的，可以直接在模板中使用
  • 可以通过 scope.$index 访问行索引
  • 可以通过 scope.column 访问列信息

事件说明 ​

组件支持 Element Plus Table 的所有事件。事件可以通过以下两种方式使用：

方式一：直接在组件上监听 ​

vue
<template>
  <LxTable
    :data="tableData"
    :columns-props="columnsProps"
    @row-click="handleRowClick"
    @selection-change="handleSelectionChange"
  />
</template>

方式二：通过 table-props 配置 ​

vue
<script setup>
const tableProps = {
  data: tableData,
  onRowClick: handleRowClick,
  onSelectionChange: handleSelectionChange,
}
</script>

<template>
  <LxTable :table-props="tableProps" :columns-props="columnsProps" />
</template>

常用事件列表：

事件名说明回调参数触发时机
select当用户手动勾选数据行的 Checkbox 时触发selection, row - selection 为已选择的数据，row 为当前选中的行数据用户勾选 Checkbox 时触发
select-all当用户手动勾选全选 Checkbox 时触发selection - 已选择的数据用户勾选全选 Checkbox 时触发
selection-change当选择项发生变化时会触发该事件selection - 已选择的数据选择项发生变化时触发
cell-mouse-enter当单元格 hover 进入时会触发该事件row, column, cell, event - 行数据、列信息、单元格、事件对象鼠标进入单元格时触发
cell-mouse-leave当单元格 hover 退出时会触发该事件row, column, cell, event - 行数据、列信息、单元格、事件对象鼠标离开单元格时触发
cell-click当某个单元格被点击时会触发该事件row, column, cell, event - 行数据、列信息、单元格、事件对象点击单元格时触发
cell-dblclick当某个单元格被双击击时会触发该事件row, column, cell, event - 行数据、列信息、单元格、事件对象双击单元格时触发
row-click当某一行被点击时会触发该事件row, column, event - 行数据、列信息、事件对象点击行时触发
row-contextmenu当某一行被鼠标右键点击时会触发该事件row, column, event - 行数据、列信息、事件对象右键点击行时触发
row-dblclick当某一行被双击时会触发该事件row, column, event - 行数据、列信息、事件对象双击行时触发
header-click当某一列的表头被点击时会触发该事件column, event - 列信息、事件对象点击表头时触发
header-contextmenu当某一列的表头被鼠标右键点击时触发该事件column, event - 列信息、事件对象右键点击表头时触发
sort-change当表格的排序条件发生变化的时候会触发该事件{ column, prop, order } - 列信息、排序字段、排序顺序排序条件变化时触发
filter-change当表格的筛选条件发生变化的时候会触发该事件filters - 筛选条件筛选条件变化时触发
current-change当表格的当前行发生变化的时候会触发该事件，如果要高亮当前行，请打开表格的 highlight-current-row 属性currentRow, oldCurrentRow - 当前行数据、之前选中的行数据当前行变化时触发
header-dragend当拖动表头改变了列的宽度的时候会触发该事件newWidth, oldWidth, column, event - 新宽度、旧宽度、列信息、事件对象拖动表头改变列宽时触发
expand-change当用户对某一行展开或者关闭的时候会触发该事件（展开行时，回调的第二个参数为 expandedRows；树形表格时，回调的第二个参数为 expanded）row, expandedRows - 行数据、展开的行数据展开或关闭行时触发

TIP

  • 组件完全兼容 Element Plus Table 的所有事件
  • 可以参考 Element Plus Table 文档 了解更多事件
  • 在 table-props 中配置事件时，需要使用 onXxx 格式，例如 onRowClick、onSelectionChange 等
  • 直接在组件上监听事件时，使用 @xxx 格式，例如 @row-click、@selection-change 等

高级功能 ​

由于组件完全继承了 Element Plus Table 的所有功能，因此支持以下高级特性：

多选 ​

通过 columns-props 配置 type="selection" 可以显示多选框列，通过 @selection-change 事件可以监听选择变化。

排序 ​

通过 columns-props 配置 sortable 属性可以启用列排序功能，通过 @sort-change 事件可以监听排序变化。

筛选 ​

通过 columns-props 配置 filters 和 filter-method 可以实现列筛选功能，通过 @filter-change 事件可以监听筛选变化。

合并单元格 ​

通过 table-props 传递 span-method 属性可以实现单元格合并功能。

展开行 ​

通过 columns-props 配置 type="expand" 可以显示展开行，通过插槽自定义展开行的内容。

树形数据 ​

通过 table-props 传递 tree-props 和 row-key 属性可以显示树形数据，支持懒加载。

固定列 ​

通过 columns-props 配置 fixed 属性可以固定列，支持固定左侧或右侧。

自定义表头 ​

通过 columns-props 配置 render-header 属性可以自定义表头内容。

注意事项 ​

  1. 数据绑定：

    • 使用 data 属性传入表格数据，数组中的每个对象对应一行数据
    • data 可以是响应式数据，组件会自动响应数据变化

  2. 列配置：

    • columns-props 数组不能为空，至少需要配置一列
    • 每个列对象必须包含 label 属性
    • 如果设置了 slotName，必须提供对应的插槽，否则会抛出错误

  3. 插槽使用：

    • 插槽名称必须与 columns-props 中配置的 slotName 完全一致
    • 插槽会接收 { scope } 作为作用域参数
    • scope.row 是响应式的，可以直接在模板中使用

  4. 属性优先级：

    • 直接在组件上传递的属性优先级高于 table-props 中的属性
    • 如果同时设置了 slotName 和 h 函数，slotName 的优先级更高

  5. Element Plus 兼容性：

    • 组件完全兼容 Element Plus Table 的所有功能和 API
    • 可以参考 Element Plus Table 文档 了解更多高级用法
    • 支持透传 Element Plus el-table 和 el-table-column 的所有属性和事件

  6. 性能优化：

    • 如果表格数据量很大（超过 1000 行），建议使用虚拟滚动或分页来优化性能
    • 对于复杂的自定义列内容，建议使用插槽而不是 h 函数，插槽的性能更好
    • 如果表格列很多，建议使用 table-layout="fixed" 来优化渲染性能

  7. 响应式数据：

    • data 和 columns-props 都支持响应式数据
    • 当数据发生变化时，表格会自动更新
    • 插槽中的 scope.row 是响应式的，可以直接在模板中使用

最佳实践 ​

  1. 使用 columns-props 配置列：这是推荐的方式，代码更简洁，维护更方便

  2. 合理使用插槽：对于需要自定义显示内容的列，使用插槽比 h 函数更直观，性能也更好

  3. 统一管理表格属性：如果表格属性较多，建议使用 table-props 统一管理，代码更清晰

  4. 性能优化：对于大数据量的表格，使用虚拟滚动或分页来优化性能

  5. 响应式设计：使用百分比或响应式单位来设置列宽，适配不同屏幕尺寸

  6. 事件处理：根据实际需求选择使用组件级别的事件或通过 table-props 配置事件

  7. 类型安全：在 TypeScript 项目中，建议为 data 和 columns-props 定义类型，提供更好的类型提示和错误检查