TDesign MiniProgram Table 表格组件完全指南:从基础用法到固定列、合并单元格与样式定制

原创2026-10-14 21:36:131,908 阅读
文章标签:UI组件设计系统小程序前端移动开发跨平台

TDesign MiniProgram Table 表格组件完全指南:从基础用法到固定列、合并单元格与样式定制

Table 表格组件用于展示同类结构下的多种数据,便于组织、对比与分析,并支持对数据进行搜索、筛选、排序等操作,一般由表头、数据行和表尾三部分组成。本文以 tdesign-miniprogram 仓库中 Table 官方文档 为主线,结合组件源码、类型定义、样式与测试深入展开,帮助你掌握 Table 组件在小程序中的引入方式、全部 Props/Events/Slots/External Classes 配置,以及斑马纹、边框、固定行、横向滚动、合并单元格等进阶实战方案。

版本与渲染框架前提

  • 该组件于 1.14.0 版本 上线,使用时请留意项目版本是否满足要求;
  • 渲染框架支持情况:WebView(即常规小程序渲染环境,非 Skyline 专用组件)。

组件引入方式

Table 组件的引入方式与其余 tdesign-miniprogram 组件一致,支持全局引入与局部引入两种方式。

全局引入:在 miniprogram 根目录下的 app.json 中配置:

"usingComponents": {
  "t-table": "tdesign-miniprogram/table/table"
}

局部引入:在需要引入的页面或组件的 index.json 中配置同样的代码。示例项目中的页面即采用局部引入方式,见 _example/base/index.json。

组件内部依赖 t-loading 加载组件(见 table.json 的 usingComponents 配置),引入 Table 时其加载组件依赖会一并解析。

代码演示:五种典型场景

基础表格

基础表格只需提供 columns(列配置)、data(数据源)与必传的 row-key 即可,参考 _example/base/index.wxml:

<t-table
  row-key="id"
  columns="{{columns}}"
  data="{{data}}"
  show-header="{{true}}"
  cell-empty-content="-"
  bind:row-click="handleRowClick"
  bind:cell-click="handleCellClick"
/>

对应数据与列配置(_example/base/index.js):

data: {
  columns: [
    { colKey: 'applicant', title: '标题', ellipsis: true },
    { colKey: 'status', title: '标题', ellipsis: true },
    { colKey: 'channel', title: '标题', ellipsis: true },
    // colKey 支持嵌套字段路径
    { colKey: 'detail.email', title: '标题', ellipsis: true },
  ],
  data: [],
},
lifetimes: {
  attached() {
    const data = [];
    const total = 10;
    for (let i = 0; i < total; i += 1) {
      data.push({
        id: i + 1,
        index: i + 1,
        applicant: ['内容', '内容', '内容'][i % 3],
        status: ['内容', '内容', '内容'][i % 3],
        channel: ['内容', '内容', '内容'][i % 3],
        detail: { email: ['内容', '内容', '内容'][i % 3] },
      });
    }
    this.setData({ data });
  },
},

从该示例可以总结出两个实用细节:

  • colKey 支持点路径嵌套取值,如 detail.email。组件底层通过 get(obj, path) 工具按 . 拆解路径逐层读取字段值,见 utils.ts;
  • cell-empty-content 用于兜底空单元格。源码逻辑为:当字段值为 undefined/null/'' 时,若配置了 cellEmptyContent 则渲染该占位内容,见 table.ts。

横向平铺可滚动表格

当列较多或列宽固定时,可设置 table-content-width 使内容总宽度超过容器宽度,配合 scroll-view 的横向滚动实现"横向平铺不省略"效果,参考 _example/scroll/index.wxml:

<t-table
  row-key="id"
  columns="{{columns}}"
  data="{{data}}"
  table-content-width="720px"
  show-header="{{true}}"
  cell-empty-content="-"
  bind:row-click="handleRowClick"
  bind:cell-click="handleCellClick"
/>

该示例的每列都显式指定 width: 180(_example/scroll/index.js)。源码中,当列设置了 width 时,列样式会额外附加 flex: 0 0 auto,防止 flex 布局压缩列宽,从而保证横向滚动时列宽不收缩(table.ts)。同时 tableElementStyles 会被设置为 table-content-width 的宽度值,见 updateTable 实现(table.ts)。

带斑马纹表格样式

设置 stripe="{{true}}" 开启斑马纹,参考 _example/stripe/index.wxml:

<t-table
  row-key="id"
  fixed-rows="{{[1, 2]}}"
  columns="{{columns}}"
  data="{{data}}"
  stripe="{{true}}"
  max-height="{{400}}"
  show-header="{{true}}"
  cell-empty-content="-"
  ...
/>

斑马纹样式通过 &--striped 规则实现:奇数行使用 --td-table-stripe-bg-color(默认 @bg-color-secondarycontainer)着色,同时固定列单元格会跟随斑马纹背景色(见 table.less)。注意源码注释指出:小程序端表头与数据行位于不同容器,因此无论是否有固定表头,都以 odd 对第 1 行着色(table.less)。

带边框表格样式

设置 bordered="{{true}}" 开启表格边框,参考 _example/bordered/index.wxml。边框模式下,表格外边框为 2rpx 实线,表头与单元格添加右侧边框,末列不重复绘制(见 table.less 的 &--bordered 规则)。

带合并单元格的表格

合并单元格通过 rowspan-and-colspan 函数属性实现,参考 _example/rowspan-colspan/index.wxml:

<t-table
  row-key="id"
  columns="{{columns}}"
  data="{{data}}"
  bordered="{{true}}"
  rowspan-and-colspan="{{rowspanAndColspan}}"
  cell-empty-content="-"
/>

合并规则在 _example/rowspan-colspan/index.js 中定义,注意小程序中该属性需要以函数形式传递,且函数需在 attached 生命周期中通过 setData 设置:

rowspanAndColspan: null,
lifetimes: {
  attached() {
    this.setData({
      rowspanAndColspan: ({ rowIndex, colIndex }) => {
        // 第1行第2列(部门):向下合并2行
        if (rowIndex === 0 && colIndex === 2) return { rowspan: 2, colspan: 1 };
        // 第2行第2列(部门):被上面合并,不渲染
        if (rowIndex === 1 && colIndex === 2) return { rowspan: 0, colspan: 0 };
        // 第3行第1列(姓名):向右合并2列
        if (rowIndex === 2 && colIndex === 1) return { rowspan: 1, colspan: 2 };
        // 第3行第2列(部门):被左边合并,不渲染
        if (rowIndex === 2 && colIndex === 2) return { rowspan: 0, colspan: 0 };
        return {};
      },
    });
  },
},

合并单元格的实现原理(源码级):组件会调用 getSkipSpansMap 遍历数据与列配置,根据 rowspanAndColspan 返回的 { rowspan, colspan } 构建"跳过映射表",把被合并覆盖的单元格标记为 skipped(见 utils.ts)。当存在合并时,表体切换为 CSS Grid 布局,通过 grid-column: colIndex+1 / span colspan 与 grid-row: rowIndex+1 / span rowspan 实现跨行跨列(table.ts),被跳过的单元格在模板中通过 wx:if="{{!cell.skipped}}" 不渲染(table.wxml)。同时,合并场景下表体通过 grid-template-columns 保持列宽与表头 flex 布局一致(table.ts)。

API 详解

BaseTable Props

名称 类型 默认值 描述 必传
style Object - 样式 N
custom-style Object - 样式,一般用于开启虚拟化组件节点场景 N
bordered Boolean false 是否显示表格边框 N
cell-empty-content String - 单元格数据为空时呈现的内容 N
columns Array [] 列配置,泛型 T 指表格数据类型。TS 类型:Array<BaseTableCol<T>> N
data Array [] 数据源,泛型 T 指表格数据类型。TS 类型:Array<T> N
empty String '' 空表格呈现样式,支持全局配置 GlobalConfigProvider N
fixed-rows Array - 固定行(冻结行),示例:[M, N],表示冻结表头 M 行和表尾 N 行。M 和 N 值为 0 时,表示不冻结行。TS 类型:Array<number> N
footer-summary String - 表尾总结行 N
height String / Number - 表格高度,超出后会出现滚动条。示例:100, '30%', '300'。值为数字类型,会自动加上单位 px。如果不是绝对固定表格高度,建议使用 maxHeight N
loading Boolean undefined 加载中状态。值为 true 会显示默认加载中样式,可以通过 Function 和插槽自定义加载状态呈现内容和样式;值为 false 则会取消加载状态 N
loading-props Object - 透传加载组件全部属性。TS 类型:Partial<LoadingProps>,详见 Loading 组件文档 N
max-height String / Number - 表格最大高度,超出后会出现滚动条。示例:100, '30%', '300'。值为数字类型,会自动加上单位 px N
row-key String 'id' 必需。唯一标识一行数据的字段名,来源于 data 中的字段;字段嵌套多层时,可设置形如 item.a.id 的路径 Y
rowspan-and-colspan Function - 用于自定义合并单元格。示例:({ row, col, rowIndex, colIndex }) => { rowspan: 2, colspan: 3 }。TS 类型:TableRowspanAndColspanFunc<T>,详见 type.ts N
show-header Boolean true 是否显示表头 N
stripe Boolean false 是否显示斑马纹 N
table-content-width String - 表格内容的总宽度(注意不是表格可见宽度)。主要应用于 table-layout: auto 模式下的固定列显示,其值必须大于表格可见宽度 N
table-layout String fixed 表格布局方式。可选项:auto/fixed N
vertical-align String middle 行内容上下方向对齐。可选项:top/middle/bottom N

关键属性的源码级说明:

  • height / max-height 的单位处理:源码通过 formatCSSUnit 将纯数字自动补上 px 单位,非数字(如 '30%'、'300')则原样保留,见 utils.ts 与 table.ts;
  • 固定表头触发条件:hasFixedHeader = showHeader && (maxHeight || height),即同时设置了表头显示与高度(或最大高度)时,表头会启用 position: sticky 冻结(table.ts);
  • fixed-rows 冻结行:<a href="https://link.gitcode.com/i/667e0f97d7156c28f1b9de2a72bc7e8a" target="_blank">M, N] 表示冻结表头 M 行和表尾 N 行,源码为顶部行追加 __row--fixed-top、底部行追加 __row--fixed-bottom 类,并使用 position: sticky + 动态测量的 top/bottom 实现([table.ts)。由于行高需实际渲染后才能确定,组件在 setData 回调中通过 createSelectorQuery 测量表头与各行的实际高度,再回写修正 top/bottom 值,见 measureAndFixStickyPositions(table.ts);
  • 固定列自动宽度:当存在固定列但未设置 table-content-width 时,组件会自动按各列 width(缺省按 80px)之和计算表格总宽度,保证固定列可正常工作(table.ts);
  • loading 状态:loading 为 true 时显示默认 t-loading 加载样式,可通过 loading 插槽自定义;加载遮罩背景色由 --td-table-loading-bg-color 控制(见 table.wxml)。

BaseTable Events

名称 参数 描述
cell-click (detail: BaseTableCellEventContext<T>) 单元格点击时触发。interface BaseTableCellEventContext<T extends TableRowData = TableRowData> { row: T; col: BaseTableCol<T>; rowIndex: number; colIndex: number; }(详见 type.ts)
row-click (detail: RowEventContext<T>) 行点击时触发,泛型 T 指表格数据类型。interface RowEventContext<T extends TableRowData = TableRowData> { row: T; index: number; }(详见 type.ts)

源码实现中,onCellClick 通过 e.currentTarget.dataset 中的 rowIndex/colIndex 从 data 与 columns 中取出对应行与列并触发 cell-click;onRowClick 同理触发 row-click(table.ts)。注意一个细节:在合并单元格(grid 布局)场景下没有 __tr 行容器,tap 不会冒泡到 onRowClick,因此源码在 onCellClick 中会手动补触发 row-click(table.ts)。

BaseTable Slots

名称 描述
cell-empty-content 自定义 cell-empty-content 显示内容
empty 自定义 empty 显示内容
footer-summary 自定义 footer-summary 显示内容
loading 自定义 loading 显示内容

其中 empty 与 loading 插槽的渲染逻辑见 table.wxml:空数据时优先显示 empty 属性文本或 globalConfig.empty(来自全局配置),否则渲染 empty 插槽;加载中时默认渲染 t-loading,也可用 loading 插槽替换。

BaseTable External Classes

类名 描述
t-class 根节点样式类
t-class-footer 表尾总结行样式类
t-class-header 表头行样式类

外部样式类在组件中声明为 ${prefix}-class、${prefix}-class-header、${prefix}-class-footer(见 table.ts),对应模板中的根节点、表头、表尾总结行(table.wxml)。

BaseTableCol 列配置

列配置项在 columns 数组中逐列声明,完整类型定义见 type.ts:

名称 类型 默认值 描述 必传
align String left 列横向对齐方式。可选项:left/right/center N
cell String / Function - 自定义单元格渲染。默认使用 colKey 的值作为自定义当前列的插槽名称。如果 cell 值类型为 Function,表示以函数形式渲染单元格(回调参数含 { row, rowIndex, col, colIndex });值类型为 string 表示使用插槽渲染,插槽名称为 cell 的值。优先级高于 render。TS 类型:string | ((params: BaseTableCellParams<T>) => string)(详见 type.ts) N
class-name String / Object / Array / Function - 列类名。值类型是 Function 时使用返回值作为列类名;值类型不为 Function 时,值用于整列类名(含表头)。TS 类型:TableColumnClassName<T> | TableColumnClassName<T><a href="https://link.gitcode.com/i/8d29a5657548c1b0674102ba39478a56" target="_blank">],其中 interface CellData<T> extends BaseTableCellParams<T> { type: 'th' | 'td' }(通用类型定义见 [common.ts,详细类型定义见 type.ts) N
col-key String - 渲染列所需字段,值为 serial-number 表示当前列为「序号」列 N
fixed String left 固定列显示位置。可选项:left/right N
min-width String / Number - 透传 CSS 属性 min-width 到 <col> 元素。⚠️ 仅少部分浏览器支持,如使用 TablesNG 渲染的 Chrome 浏览器支持 minWidth N
width String / Number - 列宽,可以作为最小宽度使用。当列宽总和小于 table 元素时,浏览器根据宽度设置情况自动分配宽度;当列宽总和大于 table 元素时,表现为定宽。可以同时调整 table 元素的宽度来达到想要的效果 N

列配置的源码级说明:

  • 序号列:当 col.colKey === 'serial-number' 时,单元格内容直接渲染为 rowIndex + 1,无需在数据中提供该字段(table.ts);
  • 函数渲染:当 col.cell 为函数时,直接调用 col.cell({ row, col, rowIndex, colIndex }) 得到单元格内容(table.ts);
  • 固定列偏移计算:源码遍历列配置,为 fixed: 'left' 的列累计左侧偏移、为 fixed: 'right' 的列累计右侧偏移(缺省宽度按 80px 计),并通过 left: Xpx / right: Xpx 内联样式配合 position: sticky 实现固定列(table.ts)。最后一个左固定列与第一个右固定列会额外追加边界类,用于滚动时显示阴影指示器(table.ts);
  • 列类名函数:class-name 为函数时,组件会以 { row, col, rowIndex, colIndex, type: 'th' | 'td' } 为上下文调用它,type 区分表头与单元格,见 getColumnClassName(utils.ts)。

CSS Variables:自定义样式

组件在 table.less 中声明了以下 CSS 变量,可通过覆盖变量值定制表格外观:

名称 默认值 描述
--td-table-body-text-color @text-color-primary 表体文字颜色
--td-table-border-color @component-border 边框颜色
--td-table-fixed-cell-border-color @component-border 固定列边界(阴影)颜色
--td-table-font-size @font-body-medium 字体大小
--td-table-header-bg-color @bg-color-container 表头背景色
--td-table-header-text-color @text-color-placeholder 表头文字颜色
--td-table-loading-bg-color rgba(255, 255, 255, 0.55) 加载遮罩背景色
--td-table-row-height 82rpx 行高基准
--td-table-stripe-bg-color @bg-color-secondarycontainer 斑马纹背景色
--td-table-td-padding @spacer @spacer-1 单元格内边距
--td-table-th-padding @spacer @spacer-1 表头单元格内边距

从源码可见,表格内容的滚动容器同时定制了滚动条样式(12rpx 宽、圆角 thumb),并可自定义滚动条颜色(table.less)。

组件运行机制与测试保障

Table 组件继承 SuperComponent 并混入 usingConfig 行为(支持 GlobalConfigProvider 全局配置,见 table.ts)。其核心更新逻辑由 updateTable 方法统一承担:组件通过 observers 监听 bordered、stripe、verticalAlign、loading、rowspanAndColspan、tableLayout、height、maxHeight、tableContentWidth、showHeader、columns、data、cellEmptyContent、rowKey、fixedRows 这些属性的变化,任一变化即触发整表重算与 setData(table.ts),attached 生命周期中也会执行一次初始化更新。

滚动交互方面,onScroll 会在滚动时触发 scroll 事件;当存在固定列时,通过测量滚动位置与容器宽度动态切换 __content--scrollable-to-left / __content--scrollable-to-right 类,控制固定列边界阴影的出现与消失(table.ts);当滚动接近底部(scrollHeight - scrollTop - clientHeight <= 50)时触发 scroll-to-bottom 事件,可用于实现分页加载(table.ts)。

仓库通过 demo.test.js 对 base、bordered、rowspan-colspan、scroll、stripe 五个示例分别进行渲染快照测试,使用 miniprogram-simulate 模拟渲染并比对快照,保障五种展示形态的渲染稳定性。

小结

Table 组件以 columns + data + row-key 为最小可用组合,在此之上通过 bordered、stripe、height/max-height、fixed-rows、rowspan-and-colspan 等属性即可快速构建带边框、斑马纹、固定表头/行、合并单元格等各类数据表格;遇到更精细的渲染需求,可借助 cell 函数渲染、col-key 嵌套取值、class-name 列类名、四个插槽以及一套完整的 CSS Variables 进行定制。无论是文档中列出的全部 API,还是固定列偏移、合并单元格 grid 布局、冻结行动态测高等底层实现细节,都可以在本仓库的 table.ts、utils.ts、type.ts 与 table.less 中找到完整依据,便于二次开发与排障。

登录后查看全文
tdesign-miniprogram