Table 表格

用于展示多条结构类似的数据，可对数据进行排序、筛选、对比等操作。

基础表格

基础的表格展示用法。

带斑马纹表格

使用带斑马纹的表格，可以更容易区分出不同行的数据。

带边框表格

带状态的表格

您可以高亮显示您的表格内容，以区分“成功、信息、警告、危险”和其他状态。

当内容过长被隐藏时显示 tooltip。

当数据过多时，可以固定表头。

固定列

当数据过多时，可以固定列。

固定列和表头

当数据量巨大时，可以同时固定列和表头。

当数据动态变化时，您可能希望表格具有最大高度而不是固定高度，并在需要时显示滚动条。

多级表头

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

固定多级表头

支持固定多级表头。

单选

支持单行选择。

多选

您也可以选择多行。

在 2.8.3 之后，toggleRowSelection 支持第三个参数 ignoreSelectable 来决定是否忽略 selectable 属性。

排序

对表格进行排序，可快速查找或对比数据。

筛选

筛选表格以查找所需数据。

自定义列模板

自定义列的显示内容，可组合其他组件使用。

自定义表头

自定义表头，使其可以被进一步定制。

可展开行

当行内容过多并且不想显示横向滚动条时，可以使用可展开行功能。

在 2.9.7 之后，添加了 preserve-expanded-content 来控制折叠时是否保留已展开行的内容在 DOM 中。

树形数据与懒加载

可选择的树 2.8.0

表尾合计行

对于数字表格，您可以在表格页脚添加一个额外的行来显示每一列的总和。

合并行或列

配置 rowspan 和 colspan 可以让你合并单元格。

自定义索引

您可以自定义 type=index 列的行索引。

表格布局

table-layout 属性设置了用于布局表格单元格、行和列的算法。

您可以使用 tooltip-formatter 来自定义 tooltip 的内容。

Table API

Table 属性

名称	描述	类型	默认值
data	表格数据	`array`	[]
高度	Table 的高度，默认为自动高度。如果 height 为 number 类型，单位 px；如果 height 为 string 类型，则这个高度会设置为 Table 的 style.height，Table 的高度会受外部样式影响	`string` / `number`	—
max-height	Table 的最大高度。合法的值为数字或者单位为 px 的高度。	`string` / `number`	—
带斑马纹	是否为带斑马纹的表格	`boolean`	false
边框	是否带有纵向边框	`boolean`	false
size	Table 的尺寸	`枚举`	—
fit	列的宽度是否自撑开	`boolean`	true
显示表头	是否显示表头	`boolean`	true
高亮当前行	是否要高亮当前行	`boolean`	false
当前行 key	当前行的 key，只写属性	`string` / `number`	—
行类名	行的 className 的回调方法，也可以使用字符串为所有行设置一个固定的 className。	`Function` / `string`	—
行样式	行的 style 的回调方法，也可以使用一个固定的 Object 为所有行设置一样的 Style。	`Function` / `object`	—
单元格类名	单元格的 className 的回调方法，也可以使用字符串为所有单元格设置一个固定的 className。	`Function` / `string`	—
单元格样式	单元格的 style 的回调方法，也可以使用一个固定的 Object 为所有单元格设置一样的 Style。	`Function` / `object`	—
表头行类名	表头行的 className 的回调方法，也可以使用字符串为所有表头行设置一个固定的 className。	`Function` / `string`	—
表头行样式	表头行的 style 的回调方法，也可以使用一个固定的 Object 为所有表头行设置一样的 Style。	`Function` / `object`	—
表头单元格类名	表头单元格的 className 的回调方法，也可以使用字符串为所有表头单元格设置一个固定的 className。	`Function` / `string`	—
表头单元格样式	表头单元格的 style 的回调方法，也可以使用一个固定的 Object 为所有表头单元格设置一样的 Style。	`Function` / `object`	—
row-key	行数据的 Key，用来优化 Table 的渲染。在使用 `reserve-selection` 功能或显示树形数据时，该属性是必填的。类型为 String 时，支持多层访问：`user.info.id`，但不支持 `user.info[0].id`，此种情况请使用 `Function`。	`function` / `string`	—
empty-text	空数据时显示的文本内容，也可以通过 `#empty` 插槽设置	`string`	无数据
default-expand-all	是否默认展开所有行，当 Table 中存在 `type="expand"` 的 Column 或含有树形结构数据时有效	`boolean`	false
展开行 keys	可以通过该属性设置 Table 目前的展开行，需要设置 row-key 属性才能使用，该属性为展开行的 keys 数组。	`object`	—
默认排序	默认的排序列的 `prop` 和顺序。`prop` 属性指定默认的排序的列，`order` 指定默认排序的顺序	`object`	如果 `prop` 已设置，但 `order` 未设置，则 `order` 默认为升序
tooltip-effect	溢出 tooltip 的 `effect`	`枚举`	暗黑模式
tooltip-options 2.2.28	溢出 tooltip 的选项，参见下方的 tooltip 组件	`object`	`object`
append-filter-panel-to 2.8.4	筛选面板要追加到的元素	`string`	—
显示合计行	是否在表尾显示合计行	`boolean`	false
合计行文本	合计行第一列的文本	`string`	合计
合计方法	自定义的合计计算方法	`Function`	—
合并方法	合并行或列的计算方法	`Function`	—
select-on-indeterminate	在多选表格中，当仅有部分行被选中时，点击表头的多选框时的行为。若为 `true`，则选中所有行；若为 `false`，则取消选择所有行	`boolean`	true
indent	展示树形数据时，树节点的缩进	`number`	16
lazy	是否懒加载子节点数据	`boolean`	false
load	加载子节点数据的函数，`lazy` 为 `true` 时生效	`Function`	—
tree-props	渲染嵌套数据的配置选项	`object`	`object`
table-layout	设置表格单元格、行和列的布局算法	`枚举`	fixed
scrollbar-always-on	总是显示滚动条	`boolean`	false
show-overflow-tooltip	当单元格内容过长时，是否隐藏多余内容并悬浮显示 tooltip。它会影响所有表格列，请参阅表格 tooltip-options	`boolean` / `object` 2.3.7	—
flexible 2.2.1	确保主轴的最小尺寸不跟随内容	`boolean`	false
scrollbar-tabindex 2.8.3	主体滚动条的 wrap 容器 tabindex	`string` / `number`	—
allow-drag-last-column 2.9.2	是否允许拖拽最后一列	`boolean`	true
tooltip-formatter 2.9.4	在使用 `show-overflow-tooltip` 时自定义 tooltip 内容	`Function`	—
preserve-expanded-content 2.9.7	折叠时是否在 DOM 中保留已展开行的内容	`boolean`	false
native-scrollbar 2.10.5	是否使用原生滚动条	`boolean`	false

Table 事件

名称	描述	类型
select	当用户手动勾选数据行的 Checkbox 时触发的事件	`Function`
select-all	当用户手动勾选全选 Checkbox 时触发的事件	`Function`
selection-change	当选择项发生变化时会触发该事件	`Function`
cell-mouse-enter	当鼠标悬停在单元格上时触发	`Function`
cell-mouse-leave	当鼠标离开单元格时触发	`Function`
cell-click	当某个单元格被点击时会触发该事件	`Function`
cell-dblclick	当某个单元格被双击时会触发该事件	`Function`
cell-contextmenu	当用户在单元格上右击时触发	`Function`
row-click	当某一行被点击时会触发该事件	`Function`
row-contextmenu	当某一行被鼠标右键点击时会触发该事件	`Function`
row-dblclick	当某一行被双击时会触发该事件	`Function`
header-click	当某一列的表头被点击时会触发该事件	`Function`
header-contextmenu	当某一列的表头被鼠标右键点击时会触发该事件	`Function`
sort-change	当表格的排序条件发生变化的时候会触发该事件	`Function`
filter-change	当表格的筛选条件发生变化的时候会触发该事件	`Function`
current-change	当表格的当前行发生变化的时候会触发该事件	`Function`
header-dragend	当拖动表头改变了列的宽度的时候会触发该事件	`Function`
expand-change	当用户对某一行进行展开或关闭操作时触发的事件（展开行时，回调的第二个参数为 expandedRows；树形表格时第二参数为 expanded）	`Function`
scroll 2.9.0	在滚动后调用	`Function`

Table 插槽

名称	描述	子标签
default	自定义默认内容	Table-column
append	插入至最后一行后的内容。如果您想在表格中实现无限滚动，您可能需要这个插槽。如果有合计行，该插槽将显示在合计行之上。	—
empty	当数据为空时，您可以自定义内容。	—

Table 暴露的属性和方法

方法	描述	类型
clearSelection	用于多选表格，清空用户的选择	`Function`
getSelectionRows	返回当前选定的行	`Function`
toggleRowSelection	用于多选表格，切换某一行的选中状态，如果使用了第二个参数，则是设置这一行选中与否（selected 为 true 则选中）	`Function`
toggleAllSelection	用于多选表格，切换所有行的选中状态	`Function`
toggleRowExpansion	用于可展开表格或树形表格，切换某一行的展开状态，如果使用了第二个参数，则是设置这一行展开与否（expanded 为 true 则展开）	`Function`
setCurrentRow	用于单选表格，设定某一行为选中行，如果调用时不加参数，则会取消目前高亮行的选中状态。	`Function`
clearSort	清除排序，将表格数据恢复为初始状态	`Function`
clearFilter	清除指定 `columnKey` 列的筛选。如果未传入参数，则清除所有筛选	`Function`
doLayout	对 Table 进行重新布局。当 Table 或其祖先元素由隐藏切换为显示时，可能需要调用此方法	`Function`
sort	手动对 Table 进行排序。参数 `prop` 用于指定排序列，`order` 用于指定排序顺序	`Function`
scrollTo	滚动到一组特定坐标	`Function`
setScrollTop	设置竖向滚动位置	`Function`
setScrollLeft	设置横向滚动位置	`Function`
columns 2.7.6	获取表格列的上下文。	`array`
updateKeyChildren 2.8.4	用于懒加载表格，必须设置 `rowKey`，更新键的子节点	`Function`

Table-column API

Table-column 属性

名称	描述	类型	默认值
type	对应列的类型。如果设置了 `selection` 则显示多选框；如果设置了 `index` 则显示该行的索引（从 1 开始计算）；如果设置了 `expand` 则显示为一个可展开的按钮	`枚举`	default
index	自定义每一行的索引，适用于 `type=index` 的列	`number` / `Function`	—
label	列标签	`string`	—
column-key	列的 key。如果需要使用 filter-change 事件，就需要此属性来标识是哪个列的筛选	`string`	—
prop	字段名称。您也可以使用它的别名 `property`	`string`	—
width	列宽	`string` / `number`	''
min-width	列最小宽度。 `width` 的列为固定宽度，而 `min-width` 的列会根据比例进行分布	`string` / `number`	''
fixed	列是否固定在左侧或者右侧。`true` 表示固定在左侧	`enum` / `boolean`	false
render-header	列标题 `Label` 区域渲染使用的 `Function`	`Function`	—
sortable	对应列是否可以排序，如果设置为 'custom'，则代表用户希望远程排序，需要监听 Table 的 `sort-change` 事件	`boolean` / `string`	false
sort-method	排序方法，在 `sortable` 设置为 `true` 的情况下有效。应该返回一个数字，和 `Array.sort` 相同	`Function`	—
sort-by	指定数据按照哪个属性进行排序，仅当 `sortable` 设置为 `true` 且 `sort-method` 未设置为 `undefined` 时有效。如果设置为一个数组，则当第一项相等时，会按照第二项进行排序	`Function` / `string` / `object`	—
sort-orders	数据在排序时所使用排序策略的先后顺序，仅当 `sortable` 设置为 `true` 时有效。接受一个数组，数组中的元素依次为 `ascending` 和 `descending`	`object`	['ascending', 'descending', null]
resizable	对应列是否可以通过拖动改变宽度（需要 `el-table` 的 `border` 属性为 `true`）	`boolean`	true
格式化程序	用来格式化内容	`function`	—
show-overflow-tooltip	当内容过长被隐藏时显示 tooltip	`boolean` / `object` 2.2.28	undefined
align	对齐方式	`枚举`	left
header-align	表头对齐方式，若不设置该项，则使用表格的 `align` 属性	`枚举`	left
class-name	列的 className	`string`	—
label-class-name	当前列标题的 `className`	`string`	—
selectable	仅对 `type=selection` 的列有效，类型为 `Function`，`Function` 的返回值用来决定这一行的 `CheckBox` 是否可以勾选	`Function`	—
reserve-selection	仅对 `type=selection` 的列有效，类型为 `Boolean`，为 `true` 则会在数据更新之后保留之前选中的数据（需要 `row-key`）	`boolean`	false
filters	数据过滤的选项，数组格式，数组中的元素需要有 `text` 和 `value` 属性。	`array`	—
filter-placement	过滤弹出框的定位	`枚举`	—
filter-class-name 2.5.0	过滤弹出框的类名	`string`	—
filter-multiple	数据过滤的选项是否多选	`boolean`	true
filter-method	数据过滤使用的方法，如果是多选的筛选项，对每一条数据会执行多次，任意一次返回 `true` 就会显示。	`function`	—
filtered-value	选中的数据过滤项，如果需要自定义表头过滤的渲染，可能会用到此属性。	`object`	—
tooltip-formatter 2.9.4	在使用 `show-overflow-tooltip` 时自定义 tooltip 内容	`Function`	—

Table-column 插槽

名称	描述	类型
default	自定义列的内容	`object`
header	自定义表头的内容	`object`
filter-icon 2.7.8	筛选图标的自定义内容	`object`
expand 2.10.0	可展开列的自定义内容	`object`

类型声明

显示声明

interface Sort {
  prop: string
  order: 'ascending' | 'descending'
  init?: any
  silent?: any
}

interface TreeNode {
  expanded?: boolean
  loading?: boolean
  noLazyChildren?: boolean
  indent?: number
  level?: number
  display?: boolean
}

type DefaultRow = Record<PropertyKey, any>

type TableColumnCtx<T extends DefaultRow = DefaultRow> = {
  id: string
  realWidth: number | null
  type: string
  label: string
  className: string
  labelClassName: string
  property: string
  prop: string
  width?: string | number
  minWidth: string | number
  renderHeader: (data: CI<T>) => VNode
  sortable: boolean | string
  sortMethod: (a: T, b: T) => number
  sortBy: string | ((row: T, index: number, array?: T[]) => string) | string[]
  resizable: boolean
  columnKey: string
  rawColumnKey: string
  align: string
  headerAlign: string
  showOverflowTooltip?: boolean | TableOverflowTooltipOptions
  tooltipFormatter?: TableOverflowTooltipFormatter<T>
  fixed: boolean | string
  formatter: (
    row: T,
    column: TableColumnCtx<T>,
    cellValue: any,
    index: number
  ) => VNode | string
  selectable: (row: T, index: number) => boolean
  reserveSelection: boolean
  filterMethod: FilterMethods<T>
  filteredValue: string[]
  filters: Filters
  filterPlacement: string
  filterMultiple: boolean
  filterClassName: string
  index: number | ((index: number) => number)
  sortOrders: (TableSortOrder | null)[]
  renderCell: (data: any) => VNode | VNode[]
  colSpan: number
  rowSpan: number
  children?: TableColumnCtx<T>[]
  level: number
  filterable: boolean | FilterMethods<T> | Filters
  order: TableSortOrder | null
  isColumnGroup: boolean
  isSubColumn: boolean
  columns: TableColumnCtx<T>[]
  getColumnIndex: () => number
  no: number
  filterOpened?: boolean
  renderFilterIcon?: (scope: any) => VNode
  renderExpand?: (scope: any) => VNode
}

常见问题

如何在表格中使用图片预览？

vue

<template>
  <el-table-column width="180">
    <template #default="scope">
      <el-image preview-teleported :preview-src-list="srcList" />
    </template>
  </el-table-column>
</template>