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 时，当鼠标悬停在单元格上时，额外的内容将显示在工具提示中。

当行数很多时，可以使用固定表头。

通过设置 el-table 的 height 属性，你可以无需任何其他代码，就可固定表头。

固定列

当列数很多时，可以固定某些列。

在 el-table-column 中使用 fixed 属性，它接受一个 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 属性。

激活多选很容易：只需添加一个 el-table-column，其 type 设置为 selection。

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>

自定义列模板

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

你可以通过插槽访问以下数据：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>

自定义表头

自定义表头，使其更加个性化。

您可以通过表头插槽自定义表头的外观。

展开行

当行内容太长且不想显示水平滚动条时，可以使用展开行功能。

在 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 的列中自定义行索引。

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

表格布局

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

fixed自动

您可以使用 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`	—
条纹	是否为斑马纹 table	`boolean`	false
边框	是否带有纵向边框	`boolean`	false
size	Table 的尺寸	`枚举`	—
fit	列的宽度是否自动撑开	`boolean`	true
show-header	是否显示表头	`boolean`	true
highlight-current-row	是否要高亮当前行	`boolean`	false
current-row-key	当前行的 key，只写属性	`string` / `number`	—
row-class-name	行的 className 的回调方法，也可以使用字符串为所有行设置一个固定的 className。	`Function` / `string`	—
row-style	行的 style 的回调方法，也可以使用一个固定的 Object 为所有行设置一样的 Style。	`Function` / `object`	—
单元格类名	单元格的 className 的回调方法，也可以使用字符串为所有单元格设置一个固定的 className	`Function` / `string`	—
cell-style	单元格的 style 的回调方法，也可以使用一个固定的 Object 为所有单元格设置一样的 Style	`Function` / `object`	—
header-row-class-name	表头行的 className 的回调方法，也可以使用字符串为所有表头行设置一个固定的 className	`Function` / `string`	—
header-row-style	表头行的 style 的回调方法，也可以使用一个固定的 Object 为所有表头行设置一样的 Style	`Function` / `object`	—
header-cell-class-name	表头单元格的 className 的回调方法，也可以使用字符串为所有表头单元格设置一个固定的 className	`Function` / `string`	—
header-cell-style	表头单元格的 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
expand-row-keys	可以通过该属性设置 Table 目前的展开行，需要设置 row-key 属性才能使用，该属性为展开行的 keys 数组。	`object`	—
default-sort	默认的排序列和顺序。它的 `prop` 属性指定默认的排序的列，`order` 指定默认的排序顺序。	`object`	如果设置了 `prop`，但没有设置 `order`，那么 `order` 将默认为升序
tooltip-effect	溢出提示的 `effect`	`枚举`	暗黑模式
tooltip-options 2.2.28	溢出提示的选项，参见 tooltip 组件	`object`	`object`
append-filter-panel-to 2.8.4	筛选面板附加到的元素	`string`	—
show-summary	是否在表尾显示合计行	`boolean`	false
sum-text	合计行第一列的文本	`string`	合计
summary-method	自定义的合计计算方法	`Function`	—
span-method	合并行或列的计算方法	`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-options	`boolean` / `object` 2.3.7	—
flexible 2.2.1	确保主轴的最小尺寸不跟随内容	`boolean`	false
scrollbar-tabindex 2.8.3	主体滚动条的包裹容器的 tabindex	`string` / `number`	—
allow-drag-last-column 2.9.2	是否允许拖动最后一列	`boolean`	true
tooltip-formatter 2.9.4	使用 `show-overflow-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 Exposes

方法	描述	类型
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`，更新 key 的子节点	`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	此列的表头的渲染函数	`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` 时生效。接受一个数组，当用户单击表头时，该列将按数组中元素的顺序进行排序	`object`	['ascending', 'descending', null]
resizable	列宽是否可调整大小，当 `el-table` 的 `border` 为 `true` 时生效	`boolean`	true
格式化程序	格式化单元格内容的函数	`函数`	—
show-overflow-tooltip	是否在单元格内容超出时隐藏多余内容并在鼠标悬停时显示为工具提示	`boolean` / `object` 2.2.28	undefined
align	对齐方式	`枚举`	left
header-align	表头的对齐方式。如果省略，将应用上述 `align` 属性的值	`枚举`	left
class-name	列中单元格的类名	`string`	—
label-class-name	此列标签的类名	`string`	—
selectable	决定某行是否可选的函数，当 `type` 为 'selection' 时生效	`Function`	—
reserve-selection	数据刷新后是否保留选择，当 `type` 为 'selection' 时生效。请注意，这需要 `row-key` 才能正常工作	`boolean`	false
filters	数据筛选选项的数组。对于此数组中的每个元素，都需要 `text` 和 `value`	`array`	—
filter-placement	筛选下拉菜单的位置	`枚举`	—
filter-class-name 2.5.0	筛选下拉菜单的类名	`string`	—
filter-multiple	数据筛选是否支持多个选项	`boolean`	true
filter-method	数据筛选方法。如果 `filter-multiple` 开启，则此方法将对每行调用多次，如果其中一次调用返回 `true`，则该行将显示	`函数`	—
filtered-value	已选数据的筛选值，当表头使用 `render-header` 渲染时可能有用	`object`	—
tooltip-formatter 2.9.4	使用 `show-overflow-tooltip` 时自定义工具提示内容	`Function`	—

Table-column Slots

名称	描述	类型
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>