TDesign MiniProgram Table 表格组件完全指南:从基础用法到固定列、合并单元格与样式定制
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 中找到完整依据,便于二次开发与排障。