Table 表格

用于展示多条结构类似的数据，可对数据进行排序、筛选、对比或其他自定义操作。

基础表格

基础表格仅用于展示数据。

当 el-table 元素中注入 data 对象数组后，在 el-table-column 中用 prop 属性来对应对象中的键名即可填入数据，用 label 属性来定义表格列名。可以使用 width 属性来定义列宽。

带斑马纹表格

使用斑马纹表格可以更容易区分不同的行。

属性 stripe 接受一个 Boolean 值。如果设置为 true，表格将带有斑马纹。

带边框表格

默认情况下，Table 组件没有垂直方向的边框。如果需要，可以通过设置 border 属性为 true 来添加。

带状态的表格

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

在 el-table 中使用 row-class-name 属性可以为特定的行添加自定义类名。之后你可以通过自定义类名为其设置样式。

当内容过长时，会自动换行。如果你希望内容保持在一行，可以使用 show-overflow-tooltip 属性。

属性 show-overflow-tooltip 接受一个 Boolean 值。设置为 true 时，多出的内容会在鼠标悬停于单元格上时以文字提示（tooltip）的形式显示。

当表格行数较多时，可以固定表头。

通过设置 el-table 的 height 属性，即可固定表头，无需其他额外代码。

固定列

当表格列数较多时，可以固定部分列。

属性 fixed 用于 el-table-column，接受一个 Boolean 值。如果设置为 true，该列将固定在左侧。它还接受两个字符串常量：'left' 和 'right'，分别表示将该列固定在对应的方向。

同时固定表头和列

当你有大量数据需要放入表格时，可以同时固定表头和部分列。

结合以上两个示例，可以同时固定列和表头。

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

通过设置 el-table 的 max-height 属性，可以固定表头。表格主体仅在行高超过最大高度值时才会滚动。

多级表头

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

只需将 el-table-column 嵌套放置在 el-table-column 内部，即可实现多级表头。

固定多级表头

支持固定多级表头

多级表头的 fixed 属性由最外层的 el-table-column 决定。

单选

支持单行选择。

Table 组件支持单行选择。你可以通过添加 highlight-current-row 属性来启用该功能。当行选择改变时，会触发 current-change 事件，其参数是此次改变后的行 currentRow 和改变前的行 oldCurrentRow。如果需要显示行索引，可以添加一个新的 el-table-column，将其 type 属性设置为 index，即可看到从 1 开始的索引。

多选

你也可以选择多行。

在 2.8.3 版本后，toggleRowSelection 支持第三个参数 ignoreSelectable，用于确定是否忽略 selectable 属性。

启用多选非常简单：只需添加一个 type 属性设置为 selection 的 el-table-column 即可。

vue

<template>
  <el-table
    ref="multipleTableRef"
    :data="tableData"
    row-key="id"
    style="width: 100%"
    @selection-change="handleSelectionChange"
  >
    <el-table-column type="selection" :selectable="selectable" width="55" />
    <el-table-column label="Date" width="120">
      <template #default="scope">{{ scope.row.date }}</template>
    </el-table-column>
    <el-table-column property="name" label="Name" width="120" />
    <el-table-column property="address" label="Address" />
  </el-table>
  <div style="margin-top: 20px">
    <el-button @click="toggleSelection([tableData[1], tableData[2]])">
      Toggle selection status of second and third rows
    </el-button>
    <el-button @click="toggleSelection([tableData[1], tableData[2]], false)">
      Toggle selection status based on selectable
    </el-button>
    <el-button @click="toggleSelection()">Clear selection</el-button>
  </div>
</template>

<script lang="ts" setup>
import { ref } from 'vue'

import type { TableInstance } from 'element-plus'

interface User {
  id: number
  date: string
  name: string
  address: string
}

const multipleTableRef = ref<TableInstance>()
const multipleSelection = ref<User[]>([])

const selectable = (row: User) => ![1, 2].includes(row.id)
const toggleSelection = (rows?: User[], ignoreSelectable?: boolean) => {
  if (rows) {
    rows.forEach((row) => {
      multipleTableRef.value!.toggleRowSelection(
        row,
        undefined,
        ignoreSelectable
      )
    })
  } else {
    multipleTableRef.value!.clearSelection()
  }
}
const handleSelectionChange = (val: User[]) => {
  multipleSelection.value = val
}

const tableData: User[] = [
  {
    id: 1,
    date: '2016-05-03',
    name: 'Tom',
    address: 'No. 189, Grove St, Los Angeles',
  },
  {
    id: 2,
    date: '2016-05-02',
    name: 'Tom',
    address: 'No. 189, Grove St, Los Angeles',
  },
  {
    id: 3,
    date: '2016-05-04',
    name: 'Tom',
    address: 'No. 189, Grove St, Los Angeles',
  },
  {
    id: 4,
    date: '2016-05-01',
    name: 'Tom',
    address: 'No. 189, Grove St, Los Angeles',
  },
  {
    id: 5,
    date: '2016-05-08',
    name: 'Tom',
    address: 'No. 189, Grove St, Los Angeles',
  },
  {
    id: 6,
    date: '2016-05-06',
    name: 'Tom',
    address: 'No. 189, Grove St, Los Angeles',
  },
  {
    id: 7,
    date: '2016-05-07',
    name: 'Tom',
    address: 'No. 189, Grove St, Los Angeles',
  },
]
</script>

排序

对数据进行排序，以便快速查找或对比数据。

在特定列中设置 sortable 属性可以基于该列对数据进行排序。它接受 Boolean 值，默认值为 false。设置表格属性 default-sort 可以确定默认的排序列和顺序。如需应用自定义排序规则，请使用 sort-method 或 sort-by。如果需要从后端进行远程排序，请将 sortable 设置为 custom，并监听 Table 的 sort-change 事件。在事件处理函数中，你可以访问排序的列和排序顺序，从而通过 API 获取排序后的表格数据。在本示例中，我们使用了另一个名为 formatter 的属性来格式化特定列的值。它接受一个函数，该函数有两个参数：row 和 column。你可以根据自己的需求进行处理。

筛选

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

在 el-table-column 中设置 filters 和 filter-method 属性即可使该列可筛选。 filters 是一个数组，filter-method 是一个决定显示哪些行的函数。它有三个参数：value、row 和 column。

vue

<template>
  <el-button @click="resetDateFilter">reset date filter</el-button>
  <el-button @click="clearFilter">reset all filters</el-button>
  <el-table ref="tableRef" row-key="date" :data="tableData" style="width: 100%">
    <el-table-column
      prop="date"
      label="Date"
      sortable
      width="180"
      column-key="date"
      :filters="[
        { text: '2016-05-01', value: '2016-05-01' },
        { text: '2016-05-02', value: '2016-05-02' },
        { text: '2016-05-03', value: '2016-05-03' },
        { text: '2016-05-04', value: '2016-05-04' },
      ]"
      :filter-method="filterHandler"
    />
    <el-table-column prop="name" label="Name" width="180" />
    <el-table-column prop="address" label="Address" :formatter="formatter" />

    <el-table-column
      prop="tag"
      label="Tag"
      width="100"
      :filters="[
        { text: 'Home', value: 'Home' },
        { text: 'Office', value: 'Office' },
      ]"
      :filter-method="filterTag"
      filter-placement="bottom-end"
    >
      <template #default="scope">
        <el-tag
          :type="scope.row.tag === 'Home' ? 'primary' : 'success'"
          disable-transitions
          >{{ scope.row.tag }}</el-tag
        >
      </template>
    </el-table-column>
  </el-table>
</template>

<script lang="ts" setup>
import { ref } from 'vue'

import type { TableColumnCtx, TableInstance } from 'element-plus'

interface User {
  date: string
  name: string
  address: string
  tag: string
}

const tableRef = ref<TableInstance>()

const resetDateFilter = () => {
  tableRef.value!.clearFilter(['date'])
}
const clearFilter = () => {
  tableRef.value!.clearFilter()
}
const formatter = (row: User, column: TableColumnCtx<User>) => {
  return row.address
}
const filterTag = (value: string, row: User) => {
  return row.tag === value
}
const filterHandler = (
  value: string,
  row: User,
  column: TableColumnCtx<User>
) => {
  const property = column['property']
  return row[property] === value
}

const tableData: User[] = [
  {
    date: '2016-05-03',
    name: 'Tom',
    address: 'No. 189, Grove St, Los Angeles',
    tag: 'Home',
  },
  {
    date: '2016-05-02',
    name: 'Tom',
    address: 'No. 189, Grove St, Los Angeles',
    tag: 'Office',
  },
  {
    date: '2016-05-04',
    name: 'Tom',
    address: 'No. 189, Grove St, Los Angeles',
    tag: 'Home',
  },
  {
    date: '2016-05-01',
    name: 'Tom',
    address: 'No. 189, Grove St, Los Angeles',
    tag: 'Office',
  },
]
</script>

自定义列模板

自定义表格列，以便与其他组件集成。

你可以通过插槽 (slot) 访问以下数据：row、column、$index 和 store（Table 的状态管理）。

vue

<template>
  <el-table :data="tableData" style="width: 100%">
    <el-table-column label="Date" width="180">
      <template #default="scope">
        <div style="display: flex; align-items: center">
          <el-icon><timer /></el-icon>
          <span style="margin-left: 10px">{{ scope.row.date }}</span>
        </div>
      </template>
    </el-table-column>
    <el-table-column label="Name" width="180">
      <template #default="scope">
        <el-popover effect="light" trigger="hover" placement="top" width="auto">
          <template #default>
            <div>name: {{ scope.row.name }}</div>
            <div>address: {{ scope.row.address }}</div>
          </template>
          <template #reference>
            <el-tag>{{ scope.row.name }}</el-tag>
          </template>
        </el-popover>
      </template>
    </el-table-column>
    <el-table-column label="Operations">
      <template #default="scope">
        <el-button size="small" @click="handleEdit(scope.$index, scope.row)">
          Edit
        </el-button>
        <el-button
          size="small"
          type="danger"
          @click="handleDelete(scope.$index, scope.row)"
        >
          Delete
        </el-button>
      </template>
    </el-table-column>
  </el-table>
</template>

<script lang="ts" setup>
import { Timer } from '@element-plus/icons-vue'

interface User {
  date: string
  name: string
  address: string
}

const handleEdit = (index: number, row: User) => {
  console.log(index, row)
}
const handleDelete = (index: number, row: User) => {
  console.log(index, row)
}

const tableData: User[] = [
  {
    date: '2016-05-03',
    name: 'Tom',
    address: 'No. 189, Grove St, Los Angeles',
  },
  {
    date: '2016-05-02',
    name: 'Tom',
    address: 'No. 189, Grove St, Los Angeles',
  },
  {
    date: '2016-05-04',
    name: 'Tom',
    address: 'No. 189, Grove St, Los Angeles',
  },
  {
    date: '2016-05-01',
    name: 'Tom',
    address: 'No. 189, Grove St, Los Angeles',
  },
]
</script>

自定义表头

自定义表格头部，使其更具个性化。

你可以通过表头插槽 (slots) 自定义表头外观。

展开行

当行内容过长且你不希望显示横向滚动条时，可以使用展开行功能。

在 2.9.7 版本后，新增了 preserve-expanded-content 属性，用于控制折叠时是否在 DOM 中保留展开行的内容。

通过添加 type="expand" 和插槽来启用展开行功能。 el-table-column 的模板将作为展开行的内容进行渲染，你可以访问与自定义列模板中使用 slot 时相同的属性。

切换父表格边框

切换子表格边框

保留展开内容

vue

<template>
  switch parent border: <el-switch v-model="parentBorder" /> switch child
  border: <el-switch v-model="childBorder" /> preserve expanded:
  <el-switch v-model="preserveExpanded" />
  <el-table
    :data="tableData"
    :border="parentBorder"
    :preserve-expanded-content="preserveExpanded"
    style="width: 100%"
  >
    <el-table-column type="expand">
      <template #default="props">
        <div m="4">
          <p m="t-0 b-2">State: {{ props.row.state }}</p>
          <p m="t-0 b-2">City: {{ props.row.city }}</p>
          <p m="t-0 b-2">Address: {{ props.row.address }}</p>
          <p m="t-0 b-2">Zip: {{ props.row.zip }}</p>
          <h3>Family</h3>
          <el-table :data="props.row.family" :border="childBorder">
            <el-table-column label="Name" prop="name" />
            <el-table-column label="State" prop="state" />
            <el-table-column label="City" prop="city" />
            <el-table-column label="Address" prop="address" />
            <el-table-column label="Zip" prop="zip" />
          </el-table>
        </div>
      </template>
    </el-table-column>
    <el-table-column label="Date" prop="date" />
    <el-table-column label="Name" prop="name" />
  </el-table>
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const parentBorder = ref(false)
const childBorder = ref(false)
const preserveExpanded = ref(false)
const tableData = [
  {
    date: '2016-05-03',
    name: 'Tom',
    state: 'California',
    city: 'San Francisco',
    address: '3650 21st St, San Francisco',
    zip: 'CA 94114',
    family: [
      {
        name: 'Jerry',
        state: 'California',
        city: 'San Francisco',
        address: '3650 21st St, San Francisco',
        zip: 'CA 94114',
      },
      {
        name: 'Spike',
        state: 'California',
        city: 'San Francisco',
        address: '3650 21st St, San Francisco',
        zip: 'CA 94114',
      },
      {
        name: 'Tyke',
        state: 'California',
        city: 'San Francisco',
        address: '3650 21st St, San Francisco',
        zip: 'CA 94114',
      },
    ],
  },
  {
    date: '2016-05-02',
    name: 'Tom',
    state: 'California',
    city: 'San Francisco',
    address: '3650 21st St, San Francisco',
    zip: 'CA 94114',
    family: [
      {
        name: 'Jerry',
        state: 'California',
        city: 'San Francisco',
        address: '3650 21st St, San Francisco',
        zip: 'CA 94114',
      },
      {
        name: 'Spike',
        state: 'California',
        city: 'San Francisco',
        address: '3650 21st St, San Francisco',
        zip: 'CA 94114',
      },
      {
        name: 'Tyke',
        state: 'California',
        city: 'San Francisco',
        address: '3650 21st St, San Francisco',
        zip: 'CA 94114',
      },
    ],
  },
  {
    date: '2016-05-04',
    name: 'Tom',
    state: 'California',
    city: 'San Francisco',
    address: '3650 21st St, San Francisco',
    zip: 'CA 94114',
    family: [
      {
        name: 'Jerry',
        state: 'California',
        city: 'San Francisco',
        address: '3650 21st St, San Francisco',
        zip: 'CA 94114',
      },
      {
        name: 'Spike',
        state: 'California',
        city: 'San Francisco',
        address: '3650 21st St, San Francisco',
        zip: 'CA 94114',
      },
      {
        name: 'Tyke',
        state: 'California',
        city: 'San Francisco',
        address: '3650 21st St, San Francisco',
        zip: 'CA 94114',
      },
    ],
  },
  {
    date: '2016-05-01',
    name: 'Tom',
    state: 'California',
    city: 'San Francisco',
    address: '3650 21st St, San Francisco',
    zip: 'CA 94114',
    family: [
      {
        name: 'Jerry',
        state: 'California',
        city: 'San Francisco',
        address: '3650 21st St, San Francisco',
        zip: 'CA 94114',
      },
      {
        name: 'Spike',
        state: 'California',
        city: 'San Francisco',
        address: '3650 21st St, San Francisco',
        zip: 'CA 94114',
      },
      {
        name: 'Tyke',
        state: 'California',
        city: 'San Francisco',
        address: '3650 21st St, San Francisco',
        zip: 'CA 94114',
      },
    ],
  },
  {
    date: '2016-05-08',
    name: 'Tom',
    state: 'California',
    city: 'San Francisco',
    address: '3650 21st St, San Francisco',
    zip: 'CA 94114',
    family: [
      {
        name: 'Jerry',
        state: 'California',
        city: 'San Francisco',
        address: '3650 21st St, San Francisco',
        zip: 'CA 94114',
      },
      {
        name: 'Spike',
        state: 'California',
        city: 'San Francisco',
        address: '3650 21st St, San Francisco',
        zip: 'CA 94114',
      },
      {
        name: 'Tyke',
        state: 'California',
        city: 'San Francisco',
        address: '3650 21st St, San Francisco',
        zip: 'CA 94114',
      },
    ],
  },
  {
    date: '2016-05-06',
    name: 'Tom',
    state: 'California',
    city: 'San Francisco',
    address: '3650 21st St, San Francisco',
    zip: 'CA 94114',
    family: [
      {
        name: 'Jerry',
        state: 'California',
        city: 'San Francisco',
        address: '3650 21st St, San Francisco',
        zip: 'CA 94114',
      },
      {
        name: 'Spike',
        state: 'California',
        city: 'San Francisco',
        address: '3650 21st St, San Francisco',
        zip: 'CA 94114',
      },
      {
        name: 'Tyke',
        state: 'California',
        city: 'San Francisco',
        address: '3650 21st St, San Francisco',
        zip: 'CA 94114',
      },
    ],
  },
  {
    date: '2016-05-07',
    name: 'Tom',
    state: 'California',
    city: 'San Francisco',
    address: '3650 21st St, San Francisco',
    zip: 'CA 94114',
    family: [
      {
        name: 'Jerry',
        state: 'California',
        city: 'San Francisco',
        address: '3650 21st St, San Francisco',
        zip: 'CA 94114',
      },
      {
        name: 'Spike',
        state: 'California',
        city: 'San Francisco',
        address: '3650 21st St, San Francisco',
        zip: 'CA 94114',
      },
      {
        name: 'Tyke',
        state: 'California',
        city: 'San Francisco',
        address: '3650 21st St, San Francisco',
        zip: 'CA 94114',
      },
    ],
  },
]
</script>

树形数据与懒加载

你可以展示树形结构的数据。当行包含 children 字段时，它将被视为嵌套数据。为渲染嵌套数据，必须指定 row-key 属性。此外，子行数据可以异步加载。将 Table 的 lazy 属性设置为 true，并设置 load 函数。在行中指定 hasChildren 属性以确定哪些行包含子节点。 children 和 hasChildren 都可以通过 tree-props 进行配置。

vue

<template>
  <div>
    <el-table
      :data="tableData"
      style="width: 100%; margin-bottom: 20px"
      row-key="id"
      border
      default-expand-all
    >
      <el-table-column prop="date" label="Date" sortable />
      <el-table-column prop="name" label="Name" sortable />
      <el-table-column prop="address" label="Address" sortable />
    </el-table>

    <el-table
      :data="tableData1"
      style="width: 100%"
      row-key="id"
      border
      lazy
      :load="load"
      :tree-props="{ children: 'children', hasChildren: 'hasChildren' }"
    >
      <el-table-column prop="date" label="Date" />
      <el-table-column prop="name" label="Name" />
      <el-table-column prop="address" label="Address" />
    </el-table>
  </div>
</template>

<script lang="ts" setup>
interface User {
  id: number
  date: string
  name: string
  address: string
  hasChildren?: boolean
  children?: User[]
}

const load = (
  row: User,
  treeNode: unknown,
  resolve: (data: User[]) => void
) => {
  setTimeout(() => {
    resolve([
      {
        id: 31,
        date: '2016-05-01',
        name: 'wangxiaohu',
        address: 'No. 189, Grove St, Los Angeles',
      },
      {
        id: 32,
        date: '2016-05-01',
        name: 'wangxiaohu',
        address: 'No. 189, Grove St, Los Angeles',
      },
    ])
  }, 1000)
}

const tableData: User[] = [
  {
    id: 1,
    date: '2016-05-02',
    name: 'wangxiaohu',
    address: 'No. 189, Grove St, Los Angeles',
  },
  {
    id: 2,
    date: '2016-05-04',
    name: 'wangxiaohu',
    address: 'No. 189, Grove St, Los Angeles',
  },
  {
    id: 3,
    date: '2016-05-01',
    name: 'wangxiaohu',
    address: 'No. 189, Grove St, Los Angeles',
    children: [
      {
        id: 31,
        date: '2016-05-01',
        name: 'wangxiaohu',
        address: 'No. 189, Grove St, Los Angeles',
      },
      {
        id: 32,
        date: '2016-05-01',
        name: 'wangxiaohu',
        address: 'No. 189, Grove St, Los Angeles',
      },
    ],
  },
  {
    id: 4,
    date: '2016-05-03',
    name: 'wangxiaohu',
    address: 'No. 189, Grove St, Los Angeles',
  },
]

const tableData1: User[] = [
  {
    id: 1,
    date: '2016-05-02',
    name: 'wangxiaohu',
    address: 'No. 189, Grove St, Los Angeles',
  },
  {
    id: 2,
    date: '2016-05-04',
    name: 'wangxiaohu',
    address: 'No. 189, Grove St, Los Angeles',
  },
  {
    id: 3,
    date: '2016-05-01',
    name: 'wangxiaohu',
    hasChildren: true,
    address: 'No. 189, Grove St, Los Angeles',
  },
  {
    id: 4,
    date: '2016-05-03',
    name: 'wangxiaohu',
    address: 'No. 189, Grove St, Los Angeles',
  },
]
</script>

可选树 2.8.0

当 treeProps.checkStrictly 为 true 时，父子节点的选中状态不再关联，即选中父节点时，其子节点不会被选中；当 treeProps.checkStrictly 为 false 时，父子节点的选中状态将与子节点的选中状态关联，即选中父节点时，其所有子节点都将被选中。

truefalse

表尾合计行

对于数值类型的表格，你可以在表尾添加一个额外的行来显示各列的总和。

通过将 show-summary 设置为 true，可以添加合计行。默认情况下，对于合计行，第一列不进行任何求和，而是始终显示“合计”（你可以使用 sum-text 配置显示的文本），而其他列则对该列中的每个数字进行求和并显示。当然，你也可以定义自己的合计行为。为此，向 summary-method 传递一个方法，该方法返回一个数组，返回数组中的每个元素将显示在合计行的各列中，它可以是 VNode 或字符串。本示例的第二个表格是一个详细的演示。

vue

<template>
  <el-table :data="tableData" border show-summary style="width: 100%">
    <el-table-column prop="id" label="ID" width="180" />
    <el-table-column prop="name" label="Name" />
    <el-table-column prop="amount1" sortable label="Amount 1" />
    <el-table-column prop="amount2" sortable label="Amount 2" />
    <el-table-column prop="amount3" sortable label="Amount 3" />
  </el-table>

  <el-table
    :data="tableData"
    border
    height="200"
    :summary-method="getSummaries"
    show-summary
    style="width: 100%; margin-top: 20px"
  >
    <el-table-column prop="id" label="ID" width="180" />
    <el-table-column prop="name" label="Name" />
    <el-table-column prop="amount1" label="Cost 1 ($)" />
    <el-table-column prop="amount2" label="Cost 2 ($)" />
    <el-table-column prop="amount3" label="Cost 3 ($)" />
  </el-table>
</template>

<script lang="ts" setup>
import { h } from 'vue'

import type { VNode } from 'vue'
import type { TableColumnCtx } from 'element-plus'

interface Product {
  id: string
  name: string
  amount1: string
  amount2: string
  amount3: number
}

interface SummaryMethodProps<T = Product> {
  columns: TableColumnCtx<T>[]
  data: T[]
}

const getSummaries = (param: SummaryMethodProps) => {
  const { columns, data } = param
  const sums: (string | VNode)[] = []
  columns.forEach((column, index) => {
    if (index === 0) {
      sums[index] = h('div', { style: { textDecoration: 'underline' } }, [
        'Total Cost',
      ])
      return
    }
    const values = data.map((item) => Number(item[column.property]))
    if (!values.every((value) => Number.isNaN(value))) {
      sums[index] = `$ ${values.reduce((prev, curr) => {
        const value = Number(curr)
        if (!Number.isNaN(value)) {
          return prev + curr
        } else {
          return prev
        }
      }, 0)}`
    } else {
      sums[index] = 'N/A'
    }
  })

  return sums
}

const tableData: Product[] = [
  {
    id: '12987122',
    name: 'Tom',
    amount1: '234',
    amount2: '3.2',
    amount3: 10,
  },
  {
    id: '12987123',
    name: 'Tom',
    amount1: '165',
    amount2: '4.43',
    amount3: 12,
  },
  {
    id: '12987124',
    name: 'Tom',
    amount1: '324',
    amount2: '1.9',
    amount3: 9,
  },
  {
    id: '12987125',
    name: 'Tom',
    amount1: '621',
    amount2: '2.2',
    amount3: 17,
  },
  {
    id: '12987126',
    name: 'Tom',
    amount1: '539',
    amount2: '4.1',
    amount3: 15,
  },
]
</script>

合并行或列

配置 rowspan 和 colspan 允许你合并单元格。

使用 span-method 属性来配置 rowspan 和 colspan。它接受一个方法，并将包含当前行 row、当前列 column、当前行索引 rowIndex 和当前列索引 columnIndex 的对象传递给该方法。该方法应返回一个包含两个数字的数组，第一个数字是 rowspan，第二个是 colspan。它也可以返回一个带有 rowspan 和 colspan 属性的对象。

vue

<template>
  <div>
    <el-table
      :data="tableData"
      :span-method="arraySpanMethod"
      border
      style="width: 100%"
    >
      <el-table-column prop="id" label="ID" width="180" />
      <el-table-column prop="name" label="Name" />
      <el-table-column prop="amount1" sortable label="Amount 1" />
      <el-table-column prop="amount2" sortable label="Amount 2" />
      <el-table-column prop="amount3" sortable label="Amount 3" />
    </el-table>

    <el-table
      :data="tableData"
      :span-method="objectSpanMethod"
      border
      style="width: 100%; margin-top: 20px"
    >
      <el-table-column prop="id" label="ID" width="180" />
      <el-table-column prop="name" label="Name" />
      <el-table-column prop="amount1" label="Amount 1" />
      <el-table-column prop="amount2" label="Amount 2" />
      <el-table-column prop="amount3" label="Amount 3" />
    </el-table>
  </div>
</template>

<script lang="ts" setup>
import type { TableColumnCtx } from 'element-plus'

interface User {
  id: string
  name: string
  amount1: string
  amount2: string
  amount3: number
}

interface SpanMethodProps {
  row: User
  column: TableColumnCtx<User>
  rowIndex: number
  columnIndex: number
}

const arraySpanMethod = ({
  row,
  column,
  rowIndex,
  columnIndex,
}: SpanMethodProps) => {
  if (rowIndex % 2 === 0) {
    if (columnIndex === 0) {
      return [1, 2]
    } else if (columnIndex === 1) {
      return [0, 0]
    }
  }
}

const objectSpanMethod = ({
  row,
  column,
  rowIndex,
  columnIndex,
}: SpanMethodProps) => {
  if (columnIndex === 0) {
    if (rowIndex % 2 === 0) {
      return {
        rowspan: 2,
        colspan: 1,
      }
    } else {
      return {
        rowspan: 0,
        colspan: 0,
      }
    }
  }
}

const tableData: User[] = [
  {
    id: '12987122',
    name: 'Tom',
    amount1: '234',
    amount2: '3.2',
    amount3: 10,
  },
  {
    id: '12987123',
    name: 'Tom',
    amount1: '165',
    amount2: '4.43',
    amount3: 12,
  },
  {
    id: '12987124',
    name: 'Tom',
    amount1: '324',
    amount2: '1.9',
    amount3: 9,
  },
  {
    id: '12987125',
    name: 'Tom',
    amount1: '621',
    amount2: '2.2',
    amount3: 17,
  },
  {
    id: '12987126',
    name: 'Tom',
    amount1: '539',
    amount2: '4.1',
    amount3: 15,
  },
]
</script>

自定义索引

你可以在 type=index 的列中自定义行索引。

如需自定义行索引，请在 type=index 的 el-table-column 上使用 index 属性。如果赋值为一个数字，所有索引都将基于该数字进行偏移。它还接受一个以各索引（从 0 开始）作为参数的方法，其返回值将作为索引显示。

表格布局

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

fixed自动 (auto)

你可以使用 tooltip-formatter 来自定义提示内容。

vue

<template>
  <el-table
    :data="tableData"
    show-overflow-tooltip
    :tooltip-formatter="tableRowFormatter"
    style="width: 100%"
  >
    <el-table-column
      prop="address"
      label="extends table formatter"
      width="240"
    />
    <el-table-column
      prop="tags"
      label="formatter object"
      width="240"
      :tooltip-formatter="({ row }) => row.tags.join(', ')"
    >
      <template #default="{ row }">
        <el-tag
          v-for="tag in row.tags"
          :key="tag"
          class="tag-item"
          type="primary"
        >
          {{ tag }}
        </el-tag>
      </template>
    </el-table-column>
    <el-table-column
      prop="url"
      label="with vnode"
      width="240"
      :tooltip-formatter="withVNode"
    />
  </el-table>
</template>

<script lang="ts" setup>
import { h } from 'vue'
import { ElLink, type TableTooltipData } from 'element-plus'

type TableData = {
  address: string
  tags: string[]
  url: string
}

const tableData: TableData[] = [
  {
    address: 'Lohrbergstr. 86c, Süd Lilli, Saarland',
    tags: ['Office', 'Home', 'Park', 'Garden'],
    url: 'https://github.com/element-plus/element-plus/issues',
  },
  {
    address: '760 A Street, South Frankfield, Illinois',
    tags: ['error', 'warning', 'success', 'info'],
    url: 'https://github.com/element-plus/element-plus/pulls',
  },
  {
    address: 'Arnold-Ohletz-Str. 41a, Alt Malinascheid, Thüringen',
    tags: ['one', 'two', 'three', 'four', 'five'],
    url: 'https://github.com/element-plus/element-plus/discussions',
  },
  {
    address: '23618 Windsor Drive, West Ricardoview, Idaho',
    tags: ['blue', 'white', 'dark', 'gray', 'red', 'bright'],
    url: 'https://github.com/element-plus/element-plus/actions',
  },
]

const tableRowFormatter = (data: TableTooltipData<TableData>) => {
  return `${data.cellValue}: table formatter`
}

const withVNode = (data: TableTooltipData<TableData>) => {
  return h(ElLink, { type: 'primary', href: data.cellValue }, () =>
    h('span', null, data.cellValue)
  )
}
</script>

<style scoped>
p {
  margin: 10px;
  padding: 0;
}
.tag-item + .tag-item {
  margin-left: 5px;
}
</style>

Table API

Table 属性

名称	描述	类型	默认值
data	表格数据	`array`	[]
高度	表格的高度。默认高度为 `auto`。如果值为数字，则单位为像素；如果值为字符串，则该值将分配给元素的 style.height，高度受外部样式影响	`string` / `number`	—
max-height	表格的最大高度。合法值为数字或以 px 为单位的高度	`string` / `number`	—
是否为斑马纹	表格是否带有斑马纹	`boolean`	false
边框	表格是否带有纵向边框	`boolean`	false
size	表格的尺寸	`枚举`	—
fit	列宽是否自适应容器	`boolean`	true
显示表头	表头是否可见	`boolean`	true
高亮当前行	当前行是否高亮	`boolean`	false
当前行 Key	当前行的 key，这是一个只写属性	`string` / `number`	—
行类名	为行返回自定义类名的函数，或为每一行分配类名的字符串	`Function` / `string`	—
行样式	为行返回自定义样式的函数，或为每一行分配自定义样式的对象	`Function` / `object`	—
单元格类名	为单元格返回自定义类名的函数，或为每个单元格分配类名的字符串	`Function` / `string`	—
单元格样式	为单元格返回自定义样式的函数，或为每个单元格分配自定义样式的对象	`Function` / `object`	—
表头行类名	为表头行返回自定义类名的函数，或为表头每一行分配类名的字符串	`Function` / `string`	—
表头行样式	为表头行返回自定义样式的函数，或为表头每一行分配自定义样式的对象	`Function` / `object`	—
表头单元格类名	为表头单元格返回自定义类名的函数，或为表头每个单元格分配类名的字符串	`Function` / `string`	—
表头单元格样式	为表头单元格返回自定义样式的函数，或为表头每个单元格分配自定义样式的对象	`Function` / `object`	—
row-key	行数据的 Key，用于优化渲染。如果启用了 `reserve-selection` 或展示树形数据，则该属性是必选的。当其类型为 String 时，支持多级访问，例如 `user.info.id`，但不支持 `user.info[0].id`，此种情况应使用 `Function`	`function` / `string`	—
empty-text	数据为空时显示的文本。你可以使用 `#empty` 插槽自定义此区域	`string`	无数据
default-expand-all	是否默认展开所有行，在表格有 type="expand" 的列或包含树形结构数据时生效	`boolean`	false
展开行 Key	通过此属性设置展开的行，其值为展开行的 key 数组，使用前应先设置 row-key。	`array`	—
默认排序	设置默认的排序列和顺序。属性 `prop` 用于设置默认排序字段，属性 `order` 用于设置默认排序顺序	`object`	如果设置了 `prop` 而未设置 `order`，则 `order` 默认为升序 (ascending)
提示效果	溢出文字提示的 `effect`	`枚举`	暗黑模式
提示配置 2.2.28	溢出文字提示的选项，参见下方的文字提示组件	`object`	`object`
筛选面板挂载至 2.8.4	筛选面板追加到的元素	`string`	—
显示合计行	是否显示合计行	`boolean`	false
合计行文本	合计行第一列显示的文本	`string`	合计
合计方法	自定义合计方法	`Function`	—
合并方法	返回 rowspan 和 colspan 的方法	`Function`	—
半选时选择行为	在多选表格中，当仅选中部分行（而非全部）时，控制全选复选框的行为。如果为 true，则会选中所有行，否则取消全选	`boolean`	true
indent	树形数据的水平缩进	`number`	16
lazy	是否启用懒加载	`boolean`	false
load	加载子行数据的方法，仅在 `lazy` 为 true 时有效	`Function`	—
树形属性	渲染嵌套数据的配置	`object`	`object`
表格布局	设置用于布局表格单元格、行和列的算法	`枚举`	fixed
scrollbar-always-on	总是显示滚动条	`boolean`	false
显示溢出提示	当内容过长溢出时，是否隐藏内容并在悬停单元格时以文字提示形式显示。这将影响所有表格列，请参考表格的 tooltip-options	`boolean` / `object` 2.3.7	—
弹性布局 2.2.1	确保主轴最小尺寸不随内容改变	`boolean`	false
滚动条 Tab 索引 2.8.3	表格主体滚动条包裹容器的 tabindex	`string` / `number`	—
允许拖拽最后一列 2.9.2	是否允许拖拽最后一列的宽度	`boolean`	true
提示内容格式化器 2.9.4	使用 `show-overflow-tooltip` 时自定义文字提示的内容	`Function`	—
保留展开内容 2.9.7	折叠时是否在 DOM 中保留展开行的内容	`boolean`	false
原生滚动条 2.10.5	是否使用原生滚动条	`boolean`	false
行可展开 2.13.2	启用可展开行，在表格具有 type="expand" 的列时生效	`Function`	—

Table 事件

名称	描述	类型
select	当用户点击某行中的复选框时触发	`Function`
全选	当用户点击表头中的复选框时触发	`Function`
选择改变	当选择项发生变化时触发	`Function`
单元格鼠标移入	当鼠标移入单元格时触发	`Function`
单元格鼠标移出	当鼠标移出单元格时触发	`Function`
单元格点击	当点击单元格时触发	`Function`
单元格双击	当双击单元格时触发	`Function`
单元格右键菜单	当用户在单元格上点击鼠标右键时触发	`Function`
行点击	当点击行时触发	`Function`
行右键菜单	当用户在行上点击鼠标右键时触发	`Function`
行双击	当双击行时触发	`Function`
表头点击	当点击列头时触发	`Function`
表头右键菜单	当用户在列头上点击鼠标右键时触发	`Function`
排序改变	当表格的排序条件发生变化时触发	`Function`
筛选改变	当表格的筛选条件发生变化时触发	`Function`
current-change	当前行发生变化时触发	`Function`
表头拖拽结束	拖动列头边界更改列宽后触发	`Function`
expand-change	当用户展开或折叠行时触发（对于可展开表格，第二个参数是 expandedRows；对于树形表格，第二个参数是 expanded）	`Function`
滚动 2.9.0	滚动后调用	`Function`

Table 插槽

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

Table 暴露的方法

方法	描述	类型
清除选择	用于多选表格，清除用户的选择	`Function`
获取选中的行	返回当前选中的行	`Function`
切换行选择	用于多选表格，切换某一行的选中状态。通过第二个参数，你可以直接设置该行是否被选中	`Function`
切换全选	用于多选表格，切换全选和取消全选的状态	`Function`
切换行展开	用于可展开表格或树形表格，切换某一行的展开状态。通过第二个参数，你可以直接设置该行是展开还是折叠	`Function`
设置当前行	用于单选表格，设置特定的一行为选中行。如果不带任何参数调用，它将清除选择	`Function`
清除排序	清除排序，将数据恢复到原始顺序	`Function`
清除筛选	清除传入的 `columnKey` 对应列的筛选。如果没有参数，则清除所有筛选	`Function`
重新布局	刷新 Table 的布局。当 Table 的可见性发生变化时，你可能需要调用此方法以获得正确的布局	`Function`
排序	手动对 Table 进行排序。属性 `prop` 用于设置排序字段，属性 `order` 用于设置排序顺序	`Function`
scrollTo	滚动到一组特定坐标	`Function`
setScrollTop	设置垂直滚动位置	`Function`
setScrollLeft	设置水平滚动位置	`Function`
列 2.7.6	获取表格列的上下文。	`array`
更新键子节点 2.8.4	用于懒加载表格，必须设置 `rowKey`，用于更新键子节点	`Function`

Table-column API

Table-column 属性

名称	描述	类型	默认值
type	列的类型。如果设置为 `selection`，则该列显示复选框。如果设置为 `index`，则该列显示行的索引（从 1 开始）。如果设置为 `expand`，则该列显示展开图标	`枚举`	default
索引	自定义每行的索引，在 `type=index` 的列上生效	`number` / `Function`	—
label	列标题	`string`	—
列 Key	列的 key。如果你需要使用 filter-change 事件，则需要该属性来标识正在筛选哪一列	`string`	—
prop	字段名。你也可以使用其别名：`property`	`string`	—
width	列宽	`string` / `number`	''
min-width	列最小宽度。具有 `width` 的列具有固定宽度，而具有 `min-width` 的列具有按比例分配的宽度	`string` / `number`	''
fixed	列是否固定在左侧/右侧。如果为 `true`，将固定在左侧	`enum` / `boolean`	false
渲染表头	该列头部标题的渲染函数	`Function`	—
sortable	列是否可以排序。通过将此属性设置为 'custom' 并监听 Table 的 `sort-change` 事件，可以实现远程排序	`boolean` / `string`	false
排序方法	排序方法，在 `sortable` 为 `true` 时生效。应返回一个数字，类似于 Array.sort	`Function`	—
sort-by	指定按哪个属性排序，在 `sortable` 为 `true` 且 `sort-method` 未定义时生效。如果设置为数组，则在当前属性相等时，列将依次按下一个属性排序	`Function` / `string` / `array`	—
排序顺序	排序时使用的排序策略顺序，在 `sortable` 为 `true` 时生效。接受一个数组，当用户点击表头时，列按数组中元素的顺序进行排序	`object`	['ascending', 'descending', null]
resizable	列宽是否可以调整，在 `el-table` 的 `border` 为 `true` 时生效	`boolean`	true
格式化程序	格式化单元格内容的函数	`函数 (function)`	—
显示溢出提示	当内容过长溢出时，是否隐藏内容并在悬停单元格时以文字提示形式显示	`boolean` / `object` 2.2.28	undefined
align	对齐方式	`枚举`	left
表头对齐方式	表头的对齐方式。如果省略，则将应用上述 `align` 属性的值	`枚举`	left
class-name	列中单元格的类名	`string`	—
label-class-name	该列标题的类名	`string`	—
是否可选	决定某行是否可以被选中的函数，在 `type` 为 'selection' 时生效	`Function`	—
保留选择	数据刷新后是否保留选择状态，在 `type` 为 'selection' 时生效。请注意，为此必须设置 `row-key`	`boolean`	false
筛选器	数据筛选选项数组。数组中的每个元素都必须包含 `text` 和 `value`	`array`	—
筛选器弹出位置	筛选器下拉菜单的弹出位置	`枚举`	—
筛选器类名 2.5.0	筛选器下拉菜单的类名	`string`	—
筛选器多选	数据筛选是否支持多选	`boolean`	true
filter-method	数据筛选方法。如果启用了 `filter-multiple`，则此方法将对每行调用多次，如果其中一次调用返回 `true`，则显示该行	`函数 (function)`	—
已筛选值	选定数据的筛选值，当使用 `render-header` 渲染表头时可能很有用	`array`	—
提示内容格式化器 2.9.4	使用 `show-overflow-tooltip` 时自定义文字提示的内容	`Function`	—

Table-column 插槽

名称	描述	类型
default	自定义表格列的内容	`object`
header	自定义表格头部的内容	`object`
筛选图标 2.7.8	自定义筛选图标的内容	`object`
展开 2.10.0	自定义展开列的内容。从 v2.13.2 开始支持 `expandable` 属性。	`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>