Table 表格

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

基础表格

最简单的数据展示用法。

为 u-table 的 data 属性传入一个对象数组，并在 u-table-column 中用 prop 对应对象键名即可渲染列数据；用 label 定义列标题，也可用 width 定义列宽。

带斑马纹表格

斑马纹便于区分相邻行。

stripe 接受布尔值。设为 true 时表格会显示斑马纹间隔背景。

带边框表格

默认表格不带竖向边框；将 border 设为 true 可显示完整单元格边框。

带状态表格

可将行样式区分为成功、信息、警告、危险等状态。

在 u-table 上使用 row-class-name 为指定行添加自定义 class，再用 CSS 控制样式。

固定表头显示省略

内容过长时会折行，可用 show-overflow-tooltip 将单元格内容单行展示并在悬停时通过气泡提示完整内容。

show-overflow-tooltip 接受布尔值。为 true 时，超出部分在鼠标悬停单元格时以 Tooltip 展示。

固定表头

数据行数很多时，可固定表头以便浏览。

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

固定列

列数过多时，可固定左侧或右侧若干列。

在 u-table-column 上设置 fixed。为 true 时列固定在左侧；也可传入字符串 'left' 或 'right' 指定固定方向。

固定列和表头

数据量很大时，可同时固定表头与列。

结合上面「固定表头」与「固定列」的用法即可同时固定。

流体高度与固定表头（及列）

数据高度动态变化时，可限制表格最大高度并在超出时出现滚动条。

设置 u-table 的 max-height 可固定表头；仅当行总高度超过 max-height 时表体区域滚动。

多级表头

数据结构复杂时，可用分组表头体现层级。

将 u-table-column 嵌套在另一个 u-table-column 内即可实现多级表头。

固定多级表头

支持固定分组表头。

分组表头是否固定由最外层 u-table-column 的 fixed 决定。

单选

支持单行高亮选择。

设置 highlight-current-row 可开启当前行高亮。行变化时会触发 current-change，参数为 currentRow 与 oldCurrentRow。需要显示行号时，可新增 type 为 index 的 u-table-column，索引从 1 开始。

多选

支持多行勾选。

toggleRowSelection 支持第三个参数 ignoreSelectable，用于是否忽略行的 selectable 限制。

增加一列 u-table-column，并将其 type 设为 selection 即可开启多选。

vue

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

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

import type { TableInstance } from 'uniboot-ui'

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 即可按该列排序，类型为布尔，默认 false。在表格上设置 default-sort 可指定默认排序列与顺序。自定义排序可使用 sort-method 或 sort-by。若需服务端排序，将 sortable 设为 'custom' 并监听表格的 sort-change 事件，在回调中根据列与排序顺序请求数据。本例还使用 formatter 格式化单元格，其签名为 (row, column)。

筛选

按条件过滤表格数据。

在 u-table-column 上设置 filters 与 filter-method 可开启列筛选。filters 为选项数组，filter-method 为 (value, row, column) => boolean，决定行是否显示。

vue

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

    <u-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">
        <u-tag
          :type="scope.row.tag === 'Home' ? 'primary' : 'success'"
          disable-transitions
          >{{ scope.row.tag }}</u-tag
        >
      </template>
    </u-table-column>
  </u-table>
</template>

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

import type { TableColumnCtx, TableInstance } from 'uniboot-ui'

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（详见 Vue 插槽）。

自定义表头

自定义表头展示。

使用表头相关插槽自定义表头渲染（详见 Vue 插槽）。

在 #header 插槽中组合列标题与 u-tooltip，可在表头旁增加图标，悬停展示字段说明。

vue

<template>
  <u-table :data="tableData" style="width: 100%">
    <u-table-column prop="project" label="Project" min-width="140" />
    <u-table-column prop="admin" label="Administrator" min-width="160" />
    <u-table-column prop="amount" align="right" min-width="160">
      <template #header>
        <span class="header-with-tooltip">
          <span>Amount (CNY)</span>
          <u-tooltip effect="dark" placement="top">
            <template #content>
              Includes prepaid card balance usage and time-card entitlement
              usage (CNY).
            </template>
            <span
              class="header-with-tooltip__trigger"
              tabindex="0"
              role="button"
              aria-label="Amount column description"
            >
              <u-icon :size="14"><Question /></u-icon>
            </span>
          </u-tooltip>
        </span>
      </template>
    </u-table-column>
    <u-table-column label="Actions" width="160" align="center">
      <template #default="scope">
        <u-button size="small" @click="handleEdit(scope.$index, scope.row)">
          Edit
        </u-button>
        <u-button
          size="small"
          type="danger"
          @click="handleDelete(scope.$index, scope.row)"
        >
          Delete
        </u-button>
      </template>
    </u-table-column>
  </u-table>
</template>

<script lang="ts" setup>
import { Question } from '@uniboot/icons-vue'

interface Row {
  project: string
  admin: string
  amount: number
}

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

const tableData: Row[] = [
  { project: 'Project 123', admin: 'Alice, Bob', amount: 100.5 },
  { project: 'Project 456', admin: 'Carol', amount: 0 },
]
</script>

<style scoped>
.header-with-tooltip {
  display: inline-flex;
  align-items: center;
  gap: 4px;
  vertical-align: middle;
}
.header-with-tooltip__trigger {
  display: inline-flex;
  align-items: center;
  cursor: default;
  color: var(--u-text-color-secondary);
  outline: none;
}
.header-with-tooltip__trigger:hover,
.header-with-tooltip__trigger:focus-visible {
  color: var(--u-color-primary);
}
</style>

展开行

行内容过长且不希望出现横向滚动条时，可使用展开行。

可通过 preserve-expanded-content 控制折叠后是否在 DOM 中保留展开区域内容。

设置 type="expand" 并配合插槽即可；展开区域模板与自定义列插槽可用的数据一致。

switch parent border:

switch child border:

preserve expanded:

vue

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

    <u-table
      :data="tableData1"
      style="width: 100%"
      row-key="id"
      border
      lazy
      :load="load"
      :tree-props="{ children: 'children', hasChildren: 'hasChildren' }"
    >
      <u-table-column prop="date" label="Date" />
      <u-table-column prop="name" label="Name" />
      <u-table-column prop="address" label="Address" />
    </u-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 时，父子勾选互不关联；为 false 时，选中父节点会联动选中其全部子节点。

truefalse

合计行

数值表可在表尾增加合计行。

将 show-summary 设为 true 开启合计。默认首列显示「合计」文案（可用 sum-text 配置），其余列对该列数值求和。也可通过 summary-method 自定义，返回数组，每项对应该列展示内容（可为字符串或 VNode）。本例第二个表格为更完整示例。

vue

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

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

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

import type { VNode } from 'vue'
import type { TableColumnCtx } from 'uniboot-ui'

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>

合并行与列

通过 span-method 合并单元格。

span-method 接收 (row, column, rowIndex, columnIndex)，返回 [rowspan, colspan] 或 { rowspan, colspan }。

vue

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

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

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

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 的 u-table-column 上使用 index：传入数字表示整体偏移；也可传入函数 (index) => 展示值。

表格布局

table-layout 控制表格单元格、行和列的布局算法。

fixedauto

空值占位

单元格值为空（null / undefined / ''）时，可显示一个占位符，避免出现空白格。

通过 empty-cell-text 设置空单元格占位文案；默认为空字符串（不显示占位）。可在 u-table-column 上单独覆盖表级配置。使用自定义作用域插槽的列不受影响。

默认不显示占位

empty-cell-text 默认为空字符串，值为 null、undefined 或空字符串时单元格留空。

显示连字符 `-`

设置 empty-cell-text="-" 后，空值统一显示为 -。

自定义占位文案

例如 empty-cell-text="N/A"。

列级覆盖

表格级 empty-cell-text="-"，仅在「管理员」列使用 empty-cell-text="—"。

vue

<template>
  <div class="demo-table-empty-cell">
    <section class="demo-block">
      <h4 class="demo-block__title">默认不显示占位</h4>
      <p class="demo-block__desc">
        <code class="demo-code">empty-cell-text</code> 默认为空字符串，值为
        <code class="demo-code">null</code>、<code class="demo-code"
          >undefined</code
        >
        或空字符串时单元格留空。
      </p>
      <div class="demo-block__table">
        <u-table :data="tableData" border style="width: 100%">
          <u-table-column prop="name" label="项目名称" />
          <u-table-column prop="admin" label="管理员" />
          <u-table-column prop="createTime" label="创建时间" width="200" />
        </u-table>
      </div>
    </section>

    <section class="demo-block">
      <h4 class="demo-block__title">
        显示连字符 <code class="demo-code">-</code>
      </h4>
      <p class="demo-block__desc">
        设置
        <code class="demo-code">empty-cell-text="-"</code> 后，空值统一显示为
        <code class="demo-code">-</code>。
      </p>
      <div class="demo-block__table">
        <u-table
          :data="tableData"
          border
          empty-cell-text="-"
          style="width: 100%"
        >
          <u-table-column prop="name" label="项目名称" />
          <u-table-column prop="admin" label="管理员" />
          <u-table-column prop="createTime" label="创建时间" width="200" />
        </u-table>
      </div>
    </section>

    <section class="demo-block">
      <h4 class="demo-block__title">自定义占位文案</h4>
      <p class="demo-block__desc">
        例如 <code class="demo-code">empty-cell-text="N/A"</code>。
      </p>
      <div class="demo-block__table">
        <u-table
          :data="tableData"
          border
          empty-cell-text="N/A"
          style="width: 100%"
        >
          <u-table-column prop="name" label="项目名称" />
          <u-table-column prop="admin" label="管理员" />
          <u-table-column prop="createTime" label="创建时间" width="200" />
        </u-table>
      </div>
    </section>

    <section class="demo-block">
      <h4 class="demo-block__title">列级覆盖</h4>
      <p class="demo-block__desc">
        表格级
        <code class="demo-code">empty-cell-text="-"</code>，仅在「管理员」列使用
        <code class="demo-code">empty-cell-text="—"</code>。
      </p>
      <div class="demo-block__table">
        <u-table
          :data="tableData"
          border
          empty-cell-text="-"
          style="width: 100%"
        >
          <u-table-column prop="name" label="项目名称" />
          <u-table-column prop="admin" label="管理员" empty-cell-text="—" />
          <u-table-column prop="createTime" label="创建时间" width="200" />
        </u-table>
      </div>
    </section>
  </div>
</template>

<script lang="ts" setup>
const tableData = [
  {
    name: '项目 A',
    admin: 'caixukun',
    createTime: '2023-02-20 14:30:20',
  },
  {
    name: '项目 B',
    admin: '',
    createTime: null,
  },
  {
    name: '项目 C',
    admin: undefined,
    createTime: '2023-02-22 09:12:00',
  },
]
</script>

<style scoped>
.demo-table-empty-cell {
  display: flex;
  flex-direction: column;
  gap: 28px;
}

.demo-block__title {
  margin: 0 0 8px;
  font-size: 15px;
  font-weight: 600;
  line-height: 1.4;
  color: var(--u-text-color-primary);
}

.demo-block__desc {
  margin: 0 0 14px;
  font-size: 13px;
  line-height: 1.65;
  color: var(--u-text-color-secondary);
}

.demo-block__table {
  border-radius: 6px;
  overflow: hidden;
}

.demo-code {
  display: inline-block;
  padding: 1px 7px;
  margin: 0 2px;
  font-size: 12px;
  font-weight: 500;
  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
  vertical-align: baseline;
  color: var(--u-text-color-regular);
  background-color: var(--u-fill-color-light);
  border: 1px solid var(--u-border-color-extra-light);
  border-radius: 4px;
}

.demo-block__title .demo-code {
  font-weight: 600;
}
</style>

气泡内容格式化

使用 tooltip-formatter 自定义溢出省略时的气泡内容。

vue

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

<script lang="ts" setup>
import { h } from 'vue'
import { type TableTooltipData, ULink } from 'uniboot-ui'

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://gitlab.in.whatspos.cn/cq/dev/fe/uniboot-ui/-/issues',
  },
  {
    address: '760 A Street, South Frankfield, Illinois',
    tags: ['error', 'warning', 'success', 'info'],
    url: 'https://gitlab.in.whatspos.cn/cq/dev/fe/uniboot-ui/-/merge_requests',
  },
  {
    address: 'Arnold-Ohletz-Str. 41a, Alt Malinascheid, Thüringen',
    tags: ['one', 'two', 'three', 'four', 'five'],
    url: 'https://gitlab.in.whatspos.cn/cq/dev/fe/uniboot-ui/-/issues',
  },
  {
    address: '23618 Windsor Drive, West Ricardoview, Idaho',
    tags: ['blue', 'white', 'dark', 'gray', 'red', 'bright'],
    url: 'https://gitlab.in.whatspos.cn/cq/dev/fe/uniboot-ui/-/pipelines',
  },
]

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

const withVNode = (data: TableTooltipData<TableData>) => {
  return h(ULink, { 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>

表格 API

表格属性

名称	说明	类型	默认值
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	当前行的键，仅写入	`string` / `number`	—
row-class-name	行的 className，可为函数或字符串	`Function` / `string`	—
row-style	行的内联样式，可为函数或对象	`Function` / `object`	—
cell-class-name	单元格的 className	`Function` / `string`	—
cell-style	单元格的内联样式	`Function` / `object`	—
header-row-class-name	表头行的 className	`Function` / `string`	—
header-row-style	表头行的内联样式	`Function` / `object`	—
header-cell-class-name	表头单元格的 className	`Function` / `string`	—
header-cell-style	表头单元格的内联样式	`Function` / `object`	—
row-key	行数据的唯一键，用于优化渲染；开启保留选中或树形数据时必填。为字符串时支持多级如 `user.info.id`，不支持 `user.info[0].id` 时需用函数形式	`function` / `string`	—
empty-text	空数据时显示的文案，可用 `#empty` 插槽自定义	`string`	No Data
default-expand-all	是否默认展开所有行（展开列或树形数据时）	`boolean`	false
expand-row-keys	展开行的 keys，需先设置 `row-key`	`array`	—
default-sort	默认排序列与顺序，`prop` 指定列，`order` 指定顺序	`object`	若设置 `prop` 且未设置 `order`，则 `order` 默认为升序
tooltip-effect	溢出提示的主题 `effect`	`enum`	dark
tooltip-options	溢出提示配置，见 Tooltip 属性	`object`	`object`
append-filter-panel-to	筛选面板挂载到的元素	`string`	—
show-summary	是否在表尾显示合计行	`boolean`	false
sum-text	合计行第一列的合计文案	`string`	Sum
summary-method	自定义合计方法	`Function`	—
span-method	合并行/列的方法	`Function`	—
select-on-indeterminate	多选表头半选时点击全选框的行为：为 `true` 则全选，否则取消全选	`boolean`	true
indent	树形数据水平缩进像素	`number`	16
lazy	是否懒加载子节点数据	`boolean`	false
load	懒加载子节点的方法，仅 `lazy` 为 `true` 时生效	`Function`	—
tree-props	渲染嵌套数据的字段配置	`object`	`object`
table-layout	表格布局算法	`enum`	fixed
scrollbar-always-on	是否始终显示滚动条	`boolean`	false
show-overflow-tooltip	是否隐藏溢出并在悬停时以 Tooltip 展示；影响所有列，详见 tooltip-options	`boolean` / `object`	—
flexible	主轴最小尺寸是否不受内容撑开影响	`boolean`	false
scrollbar-tabindex	表体滚动容器 wrap 的 tabindex	`string` / `number`	—
allow-drag-last-column	是否允许拖拽调整最后一列宽度	`boolean`	true
tooltip-formatter	使用 `show-overflow-tooltip` 时自定义气泡内容	`Function`	—
preserve-expanded-content	折叠展开行时是否在 DOM 中保留展开内容	`boolean`	false
native-scrollbar	是否使用原生滚动条	`boolean`	false
row-expandable	是否允许展开行，需存在 `type="expand"` 列	`Function`	—
empty-cell-text	单元格值为空（`null` / `undefined` / `''`）时显示的占位文案；空字符串表示不显示占位。影响所有列，可在列级别覆盖	`string`	''

表格事件

事件名	说明	类型
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	滚动后触发	`Function`

表格插槽

名称	说明	子标签
default	默认内容，放置列定义	表格列
append	插入在最后一行之后，可用于无限滚动等；若存在合计行，该插槽显示在合计行上方	—
empty	无数据时自定义内容	—

表格方法

名称	说明	类型
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	获取列上下文数组	`array`
updateKeyChildren	懒加载表格更新子节点，需设置 `row-key`	`Function`

表格列 API

表格列属性

名称	说明	类型	默认值
type	列类型：`selection` 多选、`index` 序号、`expand` 展开	`enum`	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` / `array`	—
sort-orders	排序轮转顺序，`sortable` 为 `true` 时有效	`object`	['ascending', 'descending', null]
resizable	是否可拖拽调宽，需 `u-table` 的 `border` 为 `true`	`boolean`	true
formatter	格式化单元格内容	`function`	—
show-overflow-tooltip	是否单行省略并用 Tooltip 展示溢出	`boolean` / `object`	undefined
align	对齐方式	`enum`	left
header-align	表头对齐；缺省则同 `align`	`enum`	left
class-name	列单元格 className	`string`	—
label-class-name	列表头 className	`string`	—
selectable	`type` 为 `selection` 时决定该行是否可选	`Function`	—
reserve-selection	`type` 为 `selection` 时是否在数据更新后保留选中，需设置 `row-key`	`boolean`	false
filters	筛选项数组，元素需包含 `text` 与 `value`	`array`	—
filter-placement	筛选下拉出现位置	`enum`	—
filter-class-name	筛选面板的 className	`string`	—
filter-multiple	筛选是否多选	`boolean`	true
filter-method	筛选方法；`filter-multiple` 为 true 时对每行可能多次调用，任一返回 `true` 即显示	`function`	—
filtered-value	已选中的筛选值，自定义 `render-header` 时可能有用	`array`	—
tooltip-formatter	使用 `show-overflow-tooltip` 时自定义气泡内容	`Function`	—
empty-cell-text	单元格值为空时显示的占位文案；未设置时继承 `u-table` 的 `empty-cell-text`	`string`	—

表格列插槽

名称	说明	类型
default	自定义列内容	`object`
header	自定义表头	`object`
filter-icon	自定义筛选图标	`object`
expand	自定义展开列内容；自 v2.13.2 起支持 `expandable` 属性	`object`

类型声明

展开类型声明

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

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

type DefaultRow = Record<PropertyKey, any>

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

常见问题

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

vue

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

使用 DOM 模板时列为什么不渲染？

典型讨论：#5046 #5862 #6919

HTML 规范只允许少数元素省略闭合标签（常见如 <input>、<img>）。其它元素若省略闭合标签，原生解析器会认为开始标签未结束。

更多说明见 Vue 文档：自闭合标签

Skeleton 骨架屏

Virtualized Table 虚拟化表格

Table 表格 ​

基础表格 ​

带斑马纹表格 ​

带边框表格 ​

带状态表格 ​

固定表头显示省略 ​

固定表头 ​

固定列 ​

固定列和表头 ​

流体高度与固定表头（及列） ​

多级表头 ​

固定多级表头 ​

单选 ​

多选 ​

排序 ​

筛选 ​

自定义列模板 ​

自定义表头 ​

展开行 ​

树形数据与懒加载 ​

可选择树 ​

合计行 ​

合并行与列 ​

自定义索引 ​

表格布局 ​

空值占位 ​