Table 表格

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

基础表格

基础的表格展示用法。

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

带斑马纹表格

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

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

带边框表格

默认情况下，表格没有垂直边框。如果你需要它，你可以设置 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 决定。

单选

支持单行选择。

表格支持单行选择。你可以通过添加 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，并监听表格上的 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 属性是必需的。此外，子行数据可以异步加载。将表格的 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自动

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

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
show-header	表格的表头是否可见	`boolean`	true
highlight-current-row	当前行是否高亮	`boolean`	false
current-row-key	当前行的 key，一个仅可设置的属性	`string` / `number`	—
row-class-name	返回行的自定义类名的函数，或为每一行分配类名的字符串	`Function` / `string`	—
row-style	返回行的自定义样式的函数，或为每一行分配自定义样式的对象	`Function` / `object`	—
单元格类名	返回单元格自定义类名的函数，或为每个单元格分配类名的字符串	`Function` / `string`	—
cell-style	返回单元格自定义样式的函数，或为每个单元格分配自定义样式的对象	`Function` / `object`	—
header-row-class-name	返回表头中行的自定义类名的函数，或为表头中每行分配类名的字符串	`Function` / `string`	—
header-row-style	返回表头中行的自定义样式的函数，或为表头中每行分配自定义样式的对象	`Function` / `object`	—
header-cell-class-name	返回表头中单元格自定义类名的函数，或为表头中每个单元格分配类名的字符串	`Function` / `string`	—
header-cell-style	返回表头中单元格自定义样式的函数，或为表头中每个单元格分配自定义样式的对象	`Function` / `object`	—
row-key	行数据的 key，用于优化渲染。如果 `reserve-selection` 开启或显示树形数据，则为必填项。当其类型为字符串时，支持多级访问，例如 `user.info.id`，但不支持 `user.info[0].id`，这种情况下应使用 `Function`	`function` / `string`	—
empty-text	数据为空时显示的文本。您可以使用 `#empty` 自定义该区域	`string`	无数据
default-expand-all	是否默认展开所有行，当表格包含 type="expand" 的列或包含树形结构数据时生效	`boolean`	false
expand-row-keys	通过此属性设置展开的行，属性值为展开行的 key。在使用此属性前应设置 row-key。	`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	返回 rowspan 和 colspan 的方法	`Function`	—
select-on-indeterminate	控制多选表格中主复选框在仅部分行被选中（但非全部）时的行为。如果为 true，则所有行将被选中，否则取消选中	`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	当用户点击行中的复选框时触发	`Function`
select-all	当用户点击表头中的复选框时触发	`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	用于多选表格，切换某一行是否被选中。使用第二个参数，您可以直接设置该行是否被选中	`Function`
toggleAllSelection	用于多选表格，切换全选和全不选	`Function`
toggleRowExpansion	用于可展开表格或树形表格，切换某一行是否展开。使用第二个参数，您可以直接设置该行是展开还是折叠	`Function`
setCurrentRow	用于单选表格，设置某行为选中行。如果不带任何参数调用，将清除选择	`Function`
clearSort	清除排序，将数据恢复到原始顺序	`Function`
clearFilter	清除传入 `columnKey` 的列的筛选器。如果没有参数，则清除所有筛选器	`Function`
doLayout	刷新表格的布局。当表格的可见性发生变化时，您可能需要调用此方法以获得正确的布局	`Function`
sort	手动对表格进行排序。属性 `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' 并监听表格的 `sort-change` 事件可以实现远程排序	`boolean` / `string`	false
sort-method	排序方法，在 `sortable` 为 `true` 时生效。应返回一个数字，就像 Array.sort 一样	`Function`	—
sort-by	指定按哪个属性排序，在 `sortable` 为 `true` 且 `sort-method` 未定义时生效。如果设置为数组，当上一个属性相等时，该列将按下一个属性顺序排序	`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	筛选下拉菜单的 className	`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 插槽

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