TUI

0.3.7
Table 表格

提供灵活的数据渲染能力，支持基础表格、内容省略处理、自定义列渲染、展开行等多种形式。 相较于传统 UI 框架，配置更简洁，插槽更灵活。

常用的表格渲染，可拓展，优势：相较于Element Plus 不需要在写繁琐杂乱的slot插槽来渲染。

基础用法
最基本的数据渲染，使用 columns 和 dataSource 完成表格结构渲染。
name
age
address
John Brown
32
New York No. 1 Lake Park
Jim Green
42
London No. 1 Lake Park
Joe Black
32
Sydney No. 1 Lake Park
示例代码
vue
<template>
  <TsTable :columns="data.columns" :dataSource="data.dataSource" />
</template>

<script setup lang="ts">
  const data = {
    columns: [
      { title: 'name', key: 'name' },
      { title: 'age', key: 'age' },
      { title: 'address', key: 'address' },
    ],
    dataSource: [
      { name: 'John Brown', age: 32, address: 'New York No. 1 Lake Park' },
      { name: 'Jim Green', age: 42, address: 'London No. 1 Lake Park' },
      { name: 'Joe Black', age: 32, address: 'Sydney No. 1 Lake Park' },
    ]
  }
</script>
多行文本展示展示
支持多行文本内容的展示，适用于字段内容较长的场景。内容会自动换行显示，保证表格布局的整洁性和可读性。
name
age
address
John Brown
32
New York No. 1 Lake Park
Jim Green
42
London No. 1 Lake Park
Joe Black is a good name
32
Sydney No. 1 Lake Park, Sydney No. 1 Lake Park, Sydney No. 1 Lake Park, Sydney No. 1 Lake Park, Sydney No. 1 Lake Park, Sydney No. 1 Lake Park
示例代码
vue
<template>
  <TsTable :columns="data.columns" :dataSource="data.dataSource" />
</template>

<script setup lang="ts">
  const data = {
    columns: [
      { title: 'name', key: 'name' },
      { title: 'age', key: 'age' },
      { title: 'address', key: 'address' },
    ],
    dataSource: [
      { name: 'John Brown', age: 32, address: 'New York No. 1 Lake Park' },
      { name: 'Jim Green', age: 42, address: 'London No. 1 Lake Park' },
      { name: 'Joe Black', age: 32, address: 'Sydney No. 1 Lake Park, Sydney No. 1 Lake Park, Sydney No. 1 Lake Park' },
    ]
  }
</script>
自动省略展示
使用 showOverflowTooltip 属性，当单元格内容超出列宽时，自动显示省略号，并在悬浮时展示完整内容。 适用于无需自定义内容的列，配置简单高效。
name
age
address
John Brown
32
New York No. 1 Lake Park
Jim Green
42
London No. 1 Lake Park
Joe Black is a good name
32
Sydney No. 1 Lake Park, Sydney No. 1 Lake Park, Sydney No. 1 Lake Park, Sydney No. 1 Lake Park, Sydney No. 1 Lake Park, Sydney No. 1 Lake Park
示例代码
vue
<template>
  <TsTable :columns="data.columns" :dataSource="data.dataSource" />
</template>

<script setup lang="ts">
  const data = {
    columns: [
      { title: 'name', key: 'name' },
      { title: 'age', key: 'age' },
      { title: 'address', key: 'address', showOverflowTooltip: true },
    ],
    dataSource: [
      { name: 'John Brown', age: 32, address: 'New York No. 1 Lake Park' },
      { name: 'Jim Green', age: 42, address: 'London No. 1 Lake Park' },
      { name: 'Joe Black', age: 32, address: 'Sydney No. 1 Lake Park, Sydney No. 1 Lake Park, Sydney No. 1 Lake Park' },
    ]
  }
</script>
自定义内容 + 悬浮展示
通过 slot 接管列渲染，并手动使用 tooltip 组件展示完整信息。适用于内容结构复杂、需定制格式的场景。
name
age
address
John Brown
32 -- 我接管了这里的内容来超出悬浮展示，你看不到我，你看不到我，你看不到我
New York No. 1 Lake Park
Jim Green
42 -- 我接管了这里的内容来超出悬浮展示，你看不到我，你看不到我，你看不到我
London No. 1 Lake Park
Joe Black
32 -- 我接管了这里的内容来超出悬浮展示，你看不到我，你看不到我，你看不到我
Sydney No. 1 Lake Park
示例代码
vue
<template>
  <TsTable :columns="data.columns" :dataSource="data.dataSource">
    <template #age="{ row }">
      <TsTooltip :content="row.age" :placement="['top-center', 'top-start', 'top-end', 'left-top', 'right-top', 'right-center']">
        <span style="white-space: nowrap; overflow: hidden; text-overflow: ellipsis; display: inline-block; width: 100%">
          {{ row.age }} -- 我接管了这里的内容来超出悬浮展示，你看不到我，你看不到我，你看不到我
        </span>
      </TsTooltip>
    </template>
  </TsTable>
</template>

<script setup lang="ts">
  const data = {
    columns: [
      { title: 'name', key: 'name' },
      { title: 'age', key: 'age', custom: true },
      { title: 'address', key: 'address' },
    ],
    dataSource: [
      { name: 'John Brown', age: 32, address: 'New York No. 1 Lake Park' },
      { name: 'Jim Green', age: 42, address: 'London No. 1 Lake Park' },
      { name: 'Joe Black', age: 32, address: 'Sydney No. 1 Lake Park' },
    ]
  }
</script>
注意：使用 slot 自定义渲染内容时，请确保自行处理 overflow 样式，避免内容溢出遮挡其他列。
展开行（expand）
使用特殊 key 为 expand 的列配置项，即可开启每行的展开功能。也可以通过 slot 渲染自定义的展开内容。 可用于显示详情、操作项等拓展数据。
name
age
address
操作
John Brown
32
New York No. 1 Lake Park
Jim Green
42
London No. 1 Lake Park
Joe Black is a good name
32
Sydney No. 1 Lake Park, Sydney No. 1 Lake Park, Sydney No. 1 Lake Park, Sydney No. 1 Lake Park, Sydney No. 1 Lake Park, Sydney No. 1 Lake Park
示例代码
vue
<template>
  <TsTable :columns="data.columns" :dataSource="data.dataSource">
    // 或者使用自定义方案
    // <template #expand="{ row }">
    //   <div class="expand-wrap">
    //     <div class="expand-item"><div class="expand-item-text">查看</div></div>
    //     <div class="expand-item"><div class="expand-item-text">编辑</div></div>
    //     <div class="expand-item danger"><div class="expand-item-text">删除</div></div>
    //     <div class="expand-item"><div class="expand-item-text">驳回</div></div>
    //     <div class="expand-item"><div class="expand-item-text">提交</div></div>
    //   </div>
    // </template>
  </TsTable>
</template>

<script setup lang="ts">

  const expandList = [{ name: '查看' }, { name: '编辑' }, { name: '删除', type: 'danger' }, { name: '驳回' }, { name: '提交' }, { name: '预览' }, { name: '下载' }];

  const data = {
    columns: [
      { title: 'name', key: 'name' },
      { title: 'age', key: 'age' },
      { title: 'address', key: 'address' },
      { title: '操作', key: 'expand', expandList, custom: true },
    ],
    dataSource: [
      { name: 'John Brown', age: 32, address: 'New York No. 1 Lake Park' },
      { name: 'Jim Green', age: 42, address: 'London No. 1 Lake Park' },
      { name: 'Joe Black', age: 32, address: 'Sydney No. 1 Lake Park, Sydney No. 1 Lake Park, Sydney No. 1 Lake Park' },
    ]
  }
</script>
边框控制
通过设置 border 属性控制表格边框样式。支持 Boolean / String / null，默认为 false。
可选值如 true、"horizontal"、"vertical"，用于满足不同的表格样式需求。
name
age
address
John Brown
32
New York No. 1 Lake Park
Jim Green
42
London No. 1 Lake Park
Joe Black
32
Sydney No. 1 Lake Park
示例代码
vue
<template>
  <TsTable border :headerBg="true" :columns="data.columns" :dataSource="data.dataSource" />
</template>

<script setup lang="ts">
  const data = {
    columns: [
      { title: 'name', key: 'name' },
      { title: 'age', key: 'age' },
      { title: 'address', key: 'address' },
    ],
    dataSource: [
      { name: 'John Brown', age: 32, address: 'New York No. 1 Lake Park' },
      { name: 'Jim Green', age: 42, address: 'London No. 1 Lake Park' },
      { name: 'Joe Black', age: 32, address: 'Sydney No. 1 Lake Park' },
    ]
  }
</script>
序号列
设置列 key 为 index，即可快速展示当前行的序号。可与 render 配合自定义显示内容。
index
name
age
address
1
John Brown
32
New York No. 1 Lake Park
2
Jim Green
42
London No. 1 Lake Park
3
Joe Black
32
Sydney No. 1 Lake Park
示例代码
vue
<template>
  <TsTable :columns="data.columns" :dataSource="data.dataSource" />
</template>

<script setup lang="ts">
  const data = {
    columns: [
        { title: 'index', key: 'index' },
        { title: 'name', key: 'name' },
        { title: 'age', key: 'age' },
        { title: 'address', key: 'address' },
    ],
    dataSource: [
      { name: 'John Brown', age: 32, address: 'New York No. 1 Lake Park' },
      { name: 'Jim Green', age: 42, address: 'London No. 1 Lake Park' },
      { name: 'Joe Black', age: 32, address: 'Sydney No. 1 Lake Park' },
    ]
  }
</script>
多选列 + 禁用条件
设置列 key 为 selection 可启用多选功能，配合 disabled 函数可控制某些行无法选择。 常用于状态为“已处理”等不允许用户修改的场景。
name
age
address
John Brown
32
New York No. 1 Lake Park
Jim Green
42
London No. 1 Lake Park
Joe Black
32
Sydney No. 1 Lake Park
示例代码
vue
<template>
  <TsTable :columns="data.columns" :dataSource="data.dataSource" />
</template>

<script setup lang="ts">
  const data = {
    columns: [
      { title: 'selection', key: 'selection', disabled: (row:any)=> { return row.name === 'John Brown' } },
      { title: 'name', key: 'name' },
      { title: 'age', key: 'age' },
      { title: 'address', key: 'address' },
    ],
    dataSource: [
      { name: 'John Brown', age: 32, address: 'New York No. 1 Lake Park' },
      { name: 'Jim Green', age: 42, address: 'London No. 1 Lake Park' },
      { name: 'Joe Black', age: 32, address: 'Sydney No. 1 Lake Park' },
    ]
  }
</script>
函数渲染列
使用 render 函数可自定义列内容渲染方式，适用于不依赖插槽、需动态生成结构的场景。
name
age
address
John Brown
32岁
New York No. 1 Lake Park
Jim Green
42岁
London No. 1 Lake Park
Joe Black
32岁
Sydney No. 1 Lake Park
示例代码
vue
<template>
  <TsTable :columns="data.columns" :dataSource="data.dataSource" />
</template>

<script setup lang="ts">
  const data = {
    columns: [
      { title: 'name', key: 'name' },
      { title: 'age', key: 'age', render: (row: any) => row.age + '岁' },
      { title: 'address', key: 'address' },
    ],
    dataSource: [
      { name: 'John Brown', age: 32, address: 'New York No. 1 Lake Park' },
      { name: 'Jim Green', age: 42, address: 'London No. 1 Lake Park' },
      { name: 'Joe Black', age: 32, address: 'Sydney No. 1 Lake Park' },
    ]
  }
</script>
表格内滚动效果
autoFit 为 false 或者min-winth 超出容器, 使用 scrollInline 可开启表格可视区域内横向滚动效果。
name
age
address
操作
John Brown
32
New York No. 1 Lake Park
Jim Green
42
London No. 1 Lake Park
Joe Black
32
Sydney No. 1 Lake Park
示例代码
vue
<template>
  <TsTable :autoFit="false" :singleLine="true" :scrollInline="true" :columns="data.columns" :dataSource="data.dataSource">
    <template #expand="{ row }">
      <div class="ts-table-expand-wrap ts-select-none">
        <div class="table-expand-item"><div class="expand-item-text">查看</div></div>
        <div class="table-expand-item">
          <div class="expand-item-text">预览</div>
        </div>
        <div class="table-expand-item danger">
          <div class="expand-item-text">删除</div>
        </div>
      </div>
    </template>
  </TsTable>
</template>

<script setup lang="ts">
  const data = {
    columns: [
      { title: 'name', key: 'name' },
      { title: 'age', key: 'age' },
      { title: 'address', key: 'address', width: '1500px' },
      { title: '操作', key: 'expand', custom: true, fixed: 'right' },
    ],
    dataSource: [
      { name: 'John Brown', age: 32, address: 'New York No. 1 Lake Park' },
      { name: 'Jim Green', age: 42, address: 'London No. 1 Lake Park' },
      { name: 'Joe Black', age: 32, address: 'Sydney No. 1 Lake Park' },
    ]
  }
</script>
动态渲染计算
根据dataSource动态计算表格宽度
name
age
address
John Brown
32
New York No. 1 Lake Park
示例代码
vue
<template>
  <div style="display: flex; align-items: center; column-gap: 12px">
    <TsButton @click="autoFitOnDataChange=!autoFitOnDataChange">{{ autoFitOnDataChange ? '关闭动态计算' : '开启动态计算' }}</TsButton>
    <TsButton @click="handleAddDataSource">增加数据数据</TsButton>
  </div>
  <TsTable :columns="data.columns" :autoFitOnDataChange="autoFitOnDataChange" singleLine :autoFit="false" :dataSource="data.dataSource" />
</template>

<script setup lang="ts">
  const autoFitOnDataChange = ref(false);

  const data = ref({
    columns: [
      { title: 'name', key: 'name' },
      { title: 'age', key: 'age' },
      { title: 'address', key: 'address' },
    ],
    dataSource: [
      { name: 'John Brown', age: 32, address: 'New York No. 1 Lake Park' },
    ]
  })

  const handleAddDataSource = () => {
    data.value.dataSource.push({
      name: 'Joe Black is a good name',
      age: 32,
      address: 'Sydney No. 1 Lake Park, Sydney No. 1 Lake Park, Sydney No. 1 Lake Park, Sydney No. 1 Lake Park, Sydney No. 1 Lake Park, Sydney No. 1 Lake Park',
    });
  };

</script>
表格数据为空
根据 responsive 动态响应表格数据的变化，并展示空缺效果。
name
age
address
操作
暂无数据
示例代码
vue
<template>
  <TsTable :columns="data.columns" :dataSource="data.dataSource" />
</template>

<script setup lang="ts">
  const data = {
    columns: [
        { title: 'name', key: 'name' },
        { title: 'age', key: 'age', width: 'auto' },
        { title: 'address', key: 'address', width: 200 },
        { title: 'action', key: 'action', width: 100 }
    ],
    dataSource: [
      { name: 'John Brown', age: 32, address: 'New York No. 1 Lake Park' },
      {
        name: 'Jim Green',
        age: 42,
        address: 'London No. 1 Lake Park',
        children: [
          { name: 'his brother', age: 32, address: 'Sydney No. 1 Lake Park' },
          { name: 'his sister', age: 30, address: 'Sydney No. 1 Lake Park' },
        ],
      },
      {
        name: 'Joe Black',
        age: 32,
        address: 'Sydney No. 1 Lake Park',
      }
    ]
  }
</script>
children 数据的表格
提供一级子级children数据。
name
age
address
action
John Brown
32
New York No. 1 Lake Park
Jim Green
42
London No. 1 Lake Park
his brother
32
Sydney No. 1 Lake Park
his sister
30
Sydney No. 1 Lake Park
Joe Black
32
Sydney No. 1 Lake Park
示例代码
vue
<template>
  <TsTable :columns="data.columns" :dataSource="data.dataSource" />
</template>

<script setup lang="ts">
  const data = {
    columns: [
        { title: 'name', key: 'name' },
        { title: 'age', key: 'age', width: 'auto' },
        { title: 'address', key: 'address', width: 200 },
        { title: 'action', key: 'action', width: 100 }
    ],
    dataSource: [
      { name: 'John Brown', age: 32, address: 'New York No. 1 Lake Park' },
      {
        name: 'Jim Green',
        age: 42,
        address: 'London No. 1 Lake Park',
        children: [
          { name: 'his brother', age: 32, address: 'Sydney No. 1 Lake Park' },
          { name: 'his sister', age: 30, address: 'Sydney No. 1 Lake Park' },
        ],
      },
      {
        name: 'Joe Black',
        age: 32,
        address: 'Sydney No. 1 Lake Park',
      }
    ]
  }
</script>
内部横向滚动效果
通过设置 scrollInline 为 true 当表格宽度超出容器宽度时，开启横向滚动效果。
产品编号
产品名称
供应商ID
供应商密钥
库存数量
保质期(天)
支持配送区域
是否热销
是否新品
是否包邮
是否限购
商品类型
上架时间
更新时间
操作
PRD-001
智能手表 X1
SUP-100
sec-abc123xyz82abc123xyz82881881
120
365
华东
华南
西南
是
否
是
否
电子产品
2025-01-15 10:22:33
2025-03-20 15:10:12
PRD-002
蓝牙耳机 AirLite
SUP-101
sec-xyz789qwxyz789qweisiajakkeisiajakk
50
180
华北
东北
否
是
否
是
音频设备
2025-02-01 09:12:45
2025-03-21 11:00:00
PRD-003
空气净化器 Pro
SUP-102
sec-555aaa7770555aaa77708s82jskak8s82jskak
300
720
全国
是
是
是
否
家用电器
2025-02-10 14:35:20
2025-03-22 13:25:56
PRD-004
运动水杯 Max
SUP-103
sec-999bbb3999bbb333sajslalallsl33sajslalallsl
200
1095
华东
华中
否
否
是
是
生活用品
2025-03-01 08:50:05
2025-03-23 18:45:33
示例代码
vue
<template>
  <TsTable :columns="data.columns" :dataSource="data.dataSource" />
</template>

<script setup lang="ts">
  const data = {
    columns: [
      { title: 'name', key: 'name' },
      { title: 'age', key: 'age' },
      { title: 'address', key: 'address' },
    ],
    dataSource: [
      { name: 'John Brown', age: 32, address: 'New York No. 1 Lake Park' },
      { name: 'Jim Green', age: 42, address: 'London No. 1 Lake Park' },
      { name: 'Joe Black', age: 32, address: 'Sydney No. 1 Lake Park' },
    ]
  }
</script>
属性 Props
属性名
说明
类型
可选值
默认值
版本说明
listQuery
分页数据
ListPaginationQuery
{page: number; pageSize: number;}
{page: 1, pageSize: 15;}
columns
表格列数据
Array<ColumnsType>
-
[]
dataSource
表格数据
Array
-
[]
autoFit
自适应宽度, 当 cloumns 中出现width 配置将失效
Boolean
-
true
0.3.6 deprecated
autoFitOnDataChange
动态计算宽度
Boolean | null | String
-
true
align
表格对齐方式
String
left / center / right
left
scrollInline
是否横向滚动
Boolean
-
false
singleLine
cell 是否单行文本显示
Boolean | null | String
-
false
responsive
是否响应式
Boolean
-
false
skeleton
是否默认骨架屏
Boolean
-
false
clickable
是否可点击
Boolean
-
true
tooltipOffset
tooltip偏移量
[Number,Number]
-
[-10, 0]
border
是否显示表格边框
Boolean / String / null
-
false
headerBg
表头颜色
Boolean, / String / null]
-
false
ColumnsType
属性名
说明
类型
可选值
默认值
版本说明
title
表格标题
String
-
key
表格key, selection 会提供多项操作, index 会提供序号, expand 会提供展开操作
String
- | selection | index | expand
width
表格列宽配置，支持以下类型： - **Number**：固定宽度（单位 px）。 - **'auto'**：自动填充剩余空间，列宽可不等。 - **'min-content'**：按内容最小宽度自动分配。 - **null 或不设置**：默认行为等同于 'auto'，自动填充剩余空间。 注意： - 不支持百分比单位。 - 结合不同列的 width 设置，可灵活实现固定、最小和自适应列宽。
String | Number | null
-
'' (等同于 'auto')
0.3.6 变更
minWidth
表格最小宽度
String | Number
40px
maxWidth
表格最大宽度
String | Number
-
300px
custom
是否自定义
Boolean
-
false
expandVisible
expand 的交互按钮是否一直显示
Boolean
-
true
expandPosition
展开位置
String
-
[]
expandList
展开列表
Array<TableExpandItem>
left/right/center
right
showOverflowTooltip
是否超出隐藏
Boolean
-
false
disabled
是否禁用, 用于多选, 仅在 key: selection 时生效
Function
-
-
render
函数渲染
Function
-
-
TableExpandItem
属性名
说明
类型
可选值
默认值
name
展开项名称, 必要项
String
-
type
展开项类型, 非必要项
String
onClick
展开项点击事件, 非必要项
Function
-
插槽 Slots
插槽名
说明
expand
展开项插槽
[Key in dataSource]
数据插槽