Table 表格

基于 Element Plus Table 增强的表格组件。

以类似格式展示多条数据。你可以在表格中对数据进行排序、筛选、对比等操作。

基本用法

通过原始数据和列配置实现基础表格展示。

在每一个 Table 组件中，需要使用 raw-data 提供表格数据，使用 bk-table-column 组件定义表格结构，也可通过 items 属性以配置化方式定义表格结构。每列支持配置 prop、label 及相关字段属性等选项。

斑马纹表格

斑马纹表格更容易区分不同行数据。

stripe 属性接受布尔值，设置为 true 时表格将显示斑马纹效果。

带边框的表格

默认情况下表格无垂直边框，如需显示可将 border 属性设置为 true。

带状态的表格

你可以通过高亮表格内容来区分「成功、信息、警告、危险」等状态。

使用 bk-table 的 row-class-name 为指定行添加自定义类名，然后通过自定义类名实现样式高亮。

当单元格内容过长时会自动换行，你可以使用 show-overflow-tooltip 使其单行显示并在溢出时展示 tooltip。

show-overflow-tooltip 属性接受布尔值，设置为 true 时，鼠标悬浮在单元格上会通过 tooltip 显示完整内容。

固定表头

当表格行数过多时，可固定表头方便查看。

只需为 bk-table 设置 height 属性，即可固定表头，无需额外代码。

固定列

当表格列数过多时，可固定指定列在左侧/右侧。

固定列需要使用 fixed 属性，它接受 Boolean 值。如果为 true, 列将被左侧固定. 它还接受传入字符串，left 或 right，表示左边固定还是右边固定。

固定列和表头

当表格数据量极大时，可同时固定表头和指定列。

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

流体高度表格（固定表头/列）

当数据动态变化时，你可能希望表格有最大高度限制，超出时显示滚动条而非固定高度。

为 bk-table 设置 max-height 属性，表头将固定，仅当行高总和超过最大高度时，表格主体才会出现滚动条。

表头分组

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

只需要将表格列放置于表格列中，你可以实现组头。

单选

支持单行选中功能。

表格支持单行选中，添加 highlight-current-row 属性即可激活。选中行变化时会触发 current-change 事件，参数为变化后的当前行 currentRow 和变化前的行 oldCurrentRow。如需显示行索引，只需为表格列配置 type 属性值为 index 的列配置，索引将从 1 开始显示。

多选

支持多行选择，包含默认选中、禁用指定行选择等功能。

通过 default-selection 设置初始选中行（设为 true 选中所有行，或传入行 ID 数组）；通过 disabled-selection 禁用指定行选择（设为 true 禁用所有行，或传入行 ID 数组）。注意：使用这些功能时必须设置 row-key 属性。

toggleRowSelection 方法支持第三个参数 ignoreSelectable，用于控制是否忽略行的可选状态。

激活多选功能只需为表格列配置 type 属性为 selection 即可。

vue

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

<script lang="ts" setup>
import { ref } from "vue"
import type { TableInstance } from "vue-business-kit"

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

const multipleTableRef = ref<TableInstance>()
const multipleSelection = ref<User[]>([])
const disabledSelection = ref<number[]>([1, 2])
const defaultSelection = ref<number[]>([7])

const toggleSelection = (rows?: User[], ignoreSelectable?: boolean) => {
  if (rows) {
    rows.forEach((row) => {
      multipleTableRef.value!.elTableRef!.toggleRowSelection(row, undefined, ignoreSelectable)
    })
  } else {
    multipleTableRef.value!.elTableRef!.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 属性可基于该列排序，接受布尔值（默认 false）。设置表格的 default-sort 属性可指定默认排序列和排序方式。如需自定义排序规则，可使用 sort-method 或 sort-by。若需后端远程排序，将 sortable 设置为 custom，并监听表格的 sort-change 事件，在事件处理函数中获取排序列和排序方式，从接口获取排序后的数据。本示例中还使用了 formatter 属性格式化列值，该属性接受一个函数，参数为 row（行数据）和 column（列配置），可按需处理。

筛选

筛选表格数据，快速找到目标内容。

为表格列配置 filters 和 filter-method 属性可启用列筛选功能。filters 为筛选选项数组，filter-method 为筛选方法，参数为 value（筛选值）、row（行数据）、column（列配置），用于判断行是否显示。

vue

<template>
  <bk-button @click="resetDateFilter">reset date filter</bk-button>
  <bk-button @click="clearFilter">reset all filters</bk-button>
  <bk-table ref="tableRef" row-key="date" :raw-data="tableData" style="width: 100%">
    <bk-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"
    />
    <bk-table-column prop="name" label="Name" width="180" />
    <bk-table-column prop="address" label="Address" :formatter="formatter" />

    <bk-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>
    </bk-table-column>
  </bk-table>
</template>

<script lang="ts" setup>
import { ref } from "vue"
import type { TableColumnCtx, TableInstance } from "vue-business-kit"

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

const tableRef = ref<TableInstance>()

const resetDateFilter = () => {
  tableRef.value!.elTableRef!.clearFilter(["date"])
}
const clearFilter = () => {
  tableRef.value!.elTableRef!.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"] as string
  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>

或者为 bk-table 设置 show-search 属性可启用筛选功能 @columns

自定义列模板

自定义表格列内容，支持集成其他组件。

通过插槽可访问以下数据：row（行数据）、column（列配置）、$index（行索引）、store（表格状态管理）。

自定义表头

自定义表头样式，实现更个性化的展示。

通过表头 Slot 自定义表头展示形式。

可展开行

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

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

为表格列配置 type 属性为expand即可启用展开行功能，展开行可访问的属性与使用自定义列模板时的 slot 相同。

switch parent border:

switch child border:

preserve expanded:

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" />
  <bk-table
    :raw-data="tableData"
    :border="parentBorder"
    :preserve-expanded-content="preserveExpanded"
    style="width: 100%"
  >
    <bk-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>
          <bk-table :data="props.row.family" :border="childBorder">
            <bk-table-column label="Name" prop="name" />
            <bk-table-column label="State" prop="state" />
            <bk-table-column label="City" prop="city" />
            <bk-table-column label="Address" prop="address" />
            <bk-table-column label="Zip" prop="zip" />
          </bk-table>
        </div>
      </template>
    </bk-table-column>
    <bk-table-column label="Date" prop="date" />
    <bk-table-column label="Name" prop="name" />
  </bk-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>
    <bk-table
      :raw-data="tableData"
      style="width: 100%; margin-bottom: 20px"
      row-key="id"
      border
      default-expand-all
    >
      <bk-table-column prop="date" label="Date" sortable />
      <bk-table-column prop="name" label="Name" sortable />
      <bk-table-column prop="address" label="Address" sortable />
    </bk-table>

    <bk-table
      :raw-data="tableData1"
      style="width: 100%"
      row-key="id"
      border
      lazy
      :load="load"
      :tree-props="{ children: 'children', hasChildren: 'hasChildren' }"
    >
      <bk-table-column prop="date" label="Date" />
      <bk-table-column prop="name" label="Name" />
      <bk-table-column prop="address" label="Address" />
    </bk-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>

可选择的树形表格

当 treeProps.checkStrictly 为 true 时，父子节点的选中状态不再关联（父节点选中时子节点不会被选中）；当 treeProps.checkStrictly 为 false 时，父子节点选中状态关联（父节点选中时所有子节点均被选中）。

truefalse

合计行

针对数值型表格，可在表格底部添加合计行，展示每列的求和结果。

设置 show-summary 为 true 即可显示合计行。默认情况下，合计行第一列显示「合计」（可通过 sum-text 配置显示文本），其余列显示对应列的数值总和。你也可以通过 summary-method 自定义合计逻辑：该方法返回一个数组，数组每个元素将作为合计行对应列的内容（支持 VNode 或字符串）。本示例的第二个表格展示了自定义合计的详细用法。

vue

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

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

<script lang="ts" setup>
import { h } from "vue"
import type { VNode } from "vue"
import type { TableColumnCtx } from "vue-business-kit"

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

interface SummaryMethodProps<T = Product> {
  columns: TableColumnCtx[]
  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 as string]))
    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 属性配置合并规则，该属性接受一个方法，参数为包含 row（当前行）、column（当前列）、rowIndex（当前行索引）、columnIndex（当前列索引）的对象；方法需返回一个包含两个数字的数组（第一个为 rowspan，第二个为 colspan），或返回包含 rowspan 和 colspan 属性的对象。

vue

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

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

<script lang="ts" setup>
import type { TableColumnCtx } from "vue-business-kit"

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>

也可使用 merge-columns 属性，自动合并指定列中值相同的单元格。

自定义索引

自定义 type=index 列的行索引展示规则。

为列配置 type: "index" 并设置 index 属性即可自定义索引：若为数字，所有索引将偏移该数值；若为函数（参数为原始索引，从 0 开始），返回值将作为显示的索引。

表格布局

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

fixedauto

使用 tooltip-formatter 自定义 tooltip 内容。

vue

<template>
  <bk-table
    :raw-data="tableData"
    show-overflow-tooltip
    :tooltip-formatter="tableRowFormatter"
    style="width: 100%"
  >
    <bk-table-column prop="address" label="extends table formatter" width="240" />
    <bk-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>
    </bk-table-column>
    <bk-table-column prop="url" label="with vnode" width="240" :tooltip-formatter="withVNode" />
  </bk-table>
</template>

<script lang="ts" setup>
import { h } from "vue"
import { ElLink, type TableTooltipData } from "vue-business-kit"

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>

工具栏

自定义表格工具栏，包含操作按钮。

使用 show-refresh 和 show-export 属性显示内置操作按钮，或通过 toolbar-left 插槽完全自定义工具栏内容；监听 refresh 和 export 事件处理用户操作。

分页

内置分页功能，适配大数据集展示。

设置 pagination 为 true 启用基础分页，或传入配置对象自定义分页行为。

Total 50

Go to

数字格式化 @columns

自动格式化表格单元格中的数值。

启用 number-format 可自动为数字添加千分位分隔符和指定小数位数（基于 formatNumber 实现）。

编辑数据 @columns

表格组件支持数据编辑，包含自定义编辑模式和编辑位置。

设置 enable-edit 为 true 启用编辑功能；通过 edit-mode 配置编辑模式（默认：'dialog' 对话框），edit-position 配置编辑位置（默认：'outside' 外部）；每列可通过 edit 属性配置是否启用编辑。

vue

<template>
  <bk-form label-width="auto" :model="configForm" :items="configFormItems" style="max-width: 600px">
  </bk-form>
  <bk-table
    :raw-data="tableData"
    :columns="columns"
    enable-edit
    show-batch
    :editMode="configForm.editMode"
    :editPosition="configForm.editPosition"
    rowKey="id"
    highlight-current-row
    @add="handleEvent"
    @edit="handleEvent"
    @delete="handleEvent"
    @batch="handleEvent"
  >
  </bk-table>
</template>

<script setup lang="ts">
import { ref } from "vue"
import type { FormItem, TableColumnItem } from "vue-business-kit"

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

const configForm = ref<{
  editMode?: "dialog" | "drawer"
  editPosition?: "outside" | "inline"
}>({
  editMode: "dialog",
  editPosition: "outside"
})
const tableData = ref<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"
  }
])

const columns: TableColumnItem[] = [
  { type: "selection" },
  {
    prop: "id",
    label: "ID",
    width: 100,
    edit: {
      type: "input",
      componentProps: {
        disabled: true
      }
    }
  },
  {
    prop: "date",
    label: "Date",
    width: 180,
    edit: {
      type: "date-picker",
      componentProps: {
        valueFormat: "YYYY-MM-DD"
      }
    }
  },
  {
    prop: "name",
    label: "Name",
    width: 180
  },
  {
    prop: "address",
    label: "Address"
  }
]

const configFormItems: FormItem[] = [
  {
    label: "Edit Mode",
    type: "radio-group",
    prop: "editMode",
    labelPosition: "right",
    componentProps: {
      type: "button"
    },
    children: [
      { label: "Dialog", value: "dialog" },
      { label: "Drawer", value: "drawer" }
    ]
  },
  {
    label: "Edit Position",
    type: "radio-group",
    prop: "editPosition",
    componentProps: {
      type: "button"
    },
    children: [
      { label: "Outside", value: "outside" },
      { label: "Inline", value: "inline" }
    ]
  }
]

const handleEvent = (params: { action: string; data: any }) => {
  switch (params.action) {
    case "add":
      handleAdd([params.data])
      break
    case "edit":
      const targetIndex = tableData.value.findIndex((user) => user.id === params.data.id)
      tableData.value[targetIndex] = params.data
      break
    case "delete":
      handleDelete(params.data)
      break
    case "batch_add":
      handleAdd(params.data)
      break
    case "batch_delete":
      handleDelete(params.data)
      break
  }
  function handleAdd(users: User[]) {
    users.map((user) => {
      tableData.value.push({
        ...user,
        id: tableData.value.length + 1
      })
    })
  }
  function handleDelete(users: User[]) {
    const delIdList = users.map((row) => row.id)
    tableData.value = tableData.value.filter((user) => !delIdList.includes(user.id))
  }
}
</script>

Table API

Table 属性

属性名	说明	类型	默认值
raw-data	表格数据源	`array`	`[]`
columns	列配置项	`array`	`[]`
merge-columns	需要合并的列名数组	`array`	`[]`
show-search @columns	是否显示搜索功能	`boolean`	`false`
search-value	默认搜索值	`string`	`''`
search-columns	默认选中的搜索列	`array`	`[]`
show-refresh	是否显示刷新按钮	`boolean`	`false`
show-export	是否显示导出按钮	`boolean`	`false`
pagination	是否启用分页	`boolean` \| `object`	`false`
number-format	是否启用数字格式化	`boolean` \| `object`	`false`
edit-mode	编辑模式（对话框/抽屉）	`enum`	`'dialog'`
edit-position	编辑位置（外部/行内）	`enum`	`'outside'`
enable-edit @columns	是否启用编辑功能	`boolean`	`false`
show-add	是否显示新增按钮	`boolean`	`true`
show-batch	是否显示批量操作按钮	`boolean`	`false`
show-edit	是否显示编辑按钮	`boolean`	`true`
show-delete	是否显示删除按钮	`boolean`	`true`

Element Plus Table 原生属性

属性名	说明	类型	默认值
data	表格数据	`array`	[]
height	表格高度。默认自动高度；若为数字，单位为像素；若为字符串，直接赋值给 style.height，高度受外部样式影响	`string` / `number`	—
max-height	表格最大高度，合法值为数字或带 px 单位的高度字符串	`string` / `number`	—
stripe	是否为斑马纹表格	`boolean`	false
border	是否带有纵向边框	`boolean`	false
size	表格尺寸	`enum`	—
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`	—
cell-class-name	单元格的自定义类名，支持字符串或函数	`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	行数据的唯一标识，用于优化渲染；使用 `reserve-selection` 或树形数据时必填；若为字符串，支持多级访问（如 `user.info.id`），不支持 `user.info[0].id`（需使用函数）	`function` / `string`	—
empty-text	空数据时显示的文本，可通过 `#empty` 插槽自定义	`string`	暂无数据
default-expand-all	是否默认展开所有行（仅对含展开列或树形数据的表格生效）	`boolean`	false
expand-row-keys	展开行的 key 数组，使用前需设置 row-key	`object`	—
default-sort	默认排序配置，`prop` 为默认排序列，`order` 为默认排序方式	`object`	若设置了 `prop` 但未设置 `order`，则默认升序
tooltip-effect	溢出提示的主题样式	`enum`	dark
tooltip-options	溢出提示的配置项，参考 tooltip 组件	`object`	`object`
append-filter-panel-to	筛选面板挂载的目标元素（选择器）	`string`	—
show-summary	是否显示合计行	`boolean`	false
sum-text	合计行第一列显示的文本	`string`	合计
summary-method	自定义合计方法，返回值为合计行各列内容（支持 VNode 或字符串）	`Function`	—
span-method	合并单元格方法，返回值为 [rowspan, colspan] 或	`Function`	—
select-on-indeterminate	多选表格中，当仅部分行被选中时，全选框的行为：true 表示选中所有行，false 表示取消选中	`boolean`	true
indent	树形数据的缩进距离（像素）	`number`	16
lazy	是否开启懒加载	`boolean`	false
load	懒加载加载子行数据的方法（仅 lazy 为 true 时生效），参数：row（当前行）、treeNode（树形节点）、resolve（加载完成的回调，需传入子行数据）	`Function`	—
tree-props	树形数据配置，`hasChildren` 为是否有子节点的字段名，`children` 为子节点字段名，`checkStrictly` 为是否取消父子节点选中关联	`object`	`object`
table-layout	表格布局算法	`enum`	fixed
scrollbar-always-on	是否始终显示滚动条	`boolean`	false
show-overflow-tooltip	是否在单元格内容溢出时显示 tooltip，将影响所有列，参考表格 tooltip-options	`boolean` / `object`	—
flexible	确保主轴最小尺寸不跟随内容变化	`boolean`	false
scrollbar-tabindex	表格主体滚动容器的 tabindex 属性	`string` / `number`	—
allow-drag-last-column	是否允许拖动最后一列调整宽度	`boolean`	true
tooltip-formatter	自定义 `show-overflow-tooltip` 启用时的 tooltip 内容，参数：	`Function`	—
preserve-expanded-content	折叠时是否保留展开行内容在 DOM 中	`boolean`	false
native-scrollbar	是否使用原生滚动条	`boolean`	false

TableColumnItem

继承所有 Element Plus TableColumnCtx 属性，并新增以下增强功能：

属性名	说明	类型	默认值
slots	自定义插槽配置：设为 `true` 时，自动生成 `{prop}`（列内容）、`{prop}-header`（表头）、`{prop}-filterIcon`（筛选图标）、`{prop}-expand`（展开按钮）插槽；设为对象时，每个属性支持布尔值（true 启用并使用自动生成名称）或字符串（自定义插槽名称）	`boolean` \| `object`	-
number-format	数字格式化配置：设为 `true` 时使用默认数字格式化；设为对象时传入自定义格式化选项，优先级高于表格级的 `numberFormat` 设置	`boolean` \| `object`	-
children	表头分组的子列数组，子列可嵌套 `children` 实现多级分组，用于创建多层级表头	`array`	-
edit	编辑表单配置（用于行内编辑）：设为 `FormItem` 时启用该列编辑功能，`FormItem` 接口继承 Element Plus FormItemProps，包含额外属性：`type`（组件类型字符串）、`componentProps`（组件额外属性）、`children`（嵌套表单项配置）	`object`	-

Table 事件

事件名	说明	类型
refresh	点击刷新按钮时触发	`Function`
export	点击导出按钮时触发	`Function`
search	执行搜索操作时触发	`Function`
pagination-change	分页状态变化时触发	`Function`
add	执行新增操作时触发	`Function`
edit	执行编辑操作时触发	`Function`
delete	执行删除操作时触发	`Function`
batch	执行批量操作时触发	`Function`

Element Plus 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	展开/折叠行时触发（展开行表格：第二个参数为展开行数组；树形表格：第二个参数为是否展开）	`Function`
scroll	表格滚动时触发	`Function`

Table 插槽

插槽名	说明
toolbar-left	工具栏左侧自定义内容

Element Plus Table 原生插槽

插槽名	说明	子标签
default	表格主体自定义内容	Table-column
append	插入到表格最后一行之后的内容，如需实现表格无限滚动可使用此插槽；若存在合计行，该插槽内容将显示在合计行上方	—
empty	空数据时的自定义内容	—

Table Exposes

Element Plus Table Exposes

名称	说明	类型
clearSelection	多选表格专用，清空用户选中的行	`Function`
getSelectionRows	返回当前选中的行数据数组	`Function`
toggleRowSelection	多选表格专用，切换指定行的选中状态；第二个参数可直接设置行是否选中（true 选中，false 取消）	`Function`
toggleAllSelection	多选表格专用，切换全选/取消全选状态	`Function`
toggleRowExpansion	展开行表格/树形表格专用，切换指定行的展开状态；第二个参数可直接设置行是否展开（true 展开，false 折叠）	`Function`
setCurrentRow	单选表格专用，设置指定行为当前选中行；无参数时清空选中	`Function`
clearSort	清空排序状态，恢复数据原始顺序	`Function`
clearFilter	清空筛选状态：传入 columnKey 数组时清空指定列筛选，无参数时清空所有列筛选	`Function`
doLayout	刷新表格布局，当表格可见性变化时，可能需要调用此方法确保布局正确	`Function`
sort	手动触发表格排序：`prop` 为排序列字段名，`order` 为排序方式（'ascending' 升序，'descending' 降序）	`Function`
scrollTo	滚动表格到指定坐标位置	`Function`
setScrollTop	设置表格垂直滚动位置（像素）	`Function`
setScrollLeft	设置表格水平滚动位置（像素）	`Function`
columns	获取表格列配置上下文数组	`array`
updateKeyChildren	懒加载表格专用（需设置 row-key），更新指定 key 对应的子行数据	`Function`

TableColumn API

TableColumn 属性

Element Plus TableColumn 原生属性

属性名	说明	类型	默认值
type	列类型：`selection`（复选框列）、`index`（索引列）、`expand`（展开按钮列）、`default`（默认列）	`enum`	default
index	索引列自定义索引：支持数字（索引偏移量）或函数（参数为原始索引，返回自定义索引），仅对 `type=index` 的列生效	`number` / `Function`	—
label	列标题	`string`	—
column-key	列的唯一标识，使用 `filter-change` 事件时需通过该属性识别列	`string`	—
prop	列对应的行数据字段名，别名：`property`	`string`	—
width	列宽度	`string` / `number`	''
min-width	列最小宽度：`width` 为固定宽度，`min-width` 为自适应宽度（按比例分配剩余空间）	`string` / `number`	''
fixed	列固定位置：`true`/`left`（固定在左侧）、`right`（固定在右侧）	`enum` / `boolean`	false
render-header	表头自定义渲染函数，参数：	`Function`	—
sortable	是否支持排序：`true`（启用默认排序）、`custom`（远程排序，需监听表格 `sort-change` 事件）	`boolean` / `string`	false
sort-method	自定义排序方法（`sortable` 为 `true` 时生效），返回值规则同 `Array.sort`（负数：a 在 b 前，正数：a 在 b 后，0：位置不变）	`Function`	—
sort-by	排序依据字段（`sortable` 为 `true` 且未设置 `sort-method` 时生效）：支持字符串（单个字段）、数组（多字段排序，前字段相等时按后字段排序）、函数（参数：row 行数据、index 行索引，返回排序字段值）	`Function` / `string` / `object`	—
sort-orders	排序顺序选项（`sortable` 为 `true` 时生效）：数组元素为 `'ascending'`（升序）、`'descending'`（降序）、`null`（取消排序），用户点击表头时按数组顺序切换	`object`	['ascending', 'descending', null]
resizable	是否允许拖动列宽（仅表格 `border` 为 `true` 时生效）	`boolean`	true
formatter	单元格内容格式化函数，参数：row（行数据）、column（列配置）、cellValue（单元格原始值）、index（行索引），返回值支持 VNode 或字符串	`function`	—
show-overflow-tooltip	单元格内容溢出时是否显示 tooltip，优先级高于表格级配置	`boolean` / `object`	undefined
align	单元格内容对齐方式：`left`（左对齐）、`center`（居中）、`right`（右对齐）	`enum`	left
header-align	表头内容对齐方式，未设置时继承 `align` 属性值	`enum`	left
class-name	单元格自定义类名	`string`	—
label-class-name	表头标题自定义类名	`string`	—
selectable	多选列专用，控制行是否可选中（`type` 为 `selection` 时生效），参数：row（行数据）、index（行索引），返回布尔值	`Function`	—
reserve-selection	多选列专用，数据刷新后是否保留选中状态（`type` 为 `selection` 时生效），使用前需设置表格 `row-key`	`boolean`	false
filters	列筛选选项数组，每个元素需包含 `text`（显示文本）和 `value`（筛选值）	`array`	—
filter-placement	筛选下拉框挂载位置，可选值：`top`/`top-start`/`top-end`/`bottom`/`bottom-start`/`bottom-end`/`left`/`left-start`/`left-end`/`right`/`right-start`/`right-end`	`enum`	—
filter-class-name	筛选下拉框自定义类名	`string`	—
filter-multiple	筛选是否支持多选	`boolean`	true
filter-method	筛选方法：`filter-multiple` 为 `true` 时，每行将多次调用该方法（每个筛选值一次），只要有一次返回 `true` 该行即显示；参数：value（筛选值）、row（行数据）、column（列配置）	`function`	—
filtered-value	筛选选中值（表头自定义渲染时可能需要用到）	`object`	—
tooltip-formatter	自定义 `show-overflow-tooltip` 启用时的 tooltip 内容，参数：	`Function`	—

TableColumn 插槽

Element Plus TableColumn 原生插槽

插槽名	说明	类型
default	列内容自定义	`object`
header	表头内容自定义	`object`
filter-icon	筛选图标自定义	`object`
expand	展开按钮自定义	`object`

常见问题（FAQ）

如何在表格中实现图片预览？

vue

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

Table 表格 ​

基本用法 ​

斑马纹表格 ​

带边框的表格 ​

带状态的表格 ​

内容溢出时显示 tooltip ​

固定表头 ​

固定列 ​

固定列和表头 ​

流体高度表格（固定表头/列） ​

表头分组 ​

单选 ​

多选 ​

排序 ​

筛选 ​

自定义列模板 ​

自定义表头 ​

可展开行 ​

树形数据与懒加载 ​

可选择的树形表格 ​

合计行 ​

合并单元格 ​

自定义索引 ​

表格布局 ​

Tooltip 格式化器 ​

工具栏 ​

分页 ​

数字格式化 @columns ​

编辑数据 @columns ​

Table API ​

Table 属性 ​

TableColumnItem ​

Table 事件 ​

Table 插槽 ​

Table Exposes ​

TableColumn API ​

TableColumn 属性 ​

TableColumn 插槽 ​

常见问题（FAQ） ​

如何在表格中实现图片预览？ ​