Ant Design Table 组件 Token 定制指南：基于 ConfigProvider 深度自定义表格样式
【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/ant/ant-design
导读
本文围绕 Ant Design 中 Table 组件的组件 Token（Component Token）定制能力展开，讲解如何通过ConfigProvider的theme.components.Table配置项，在不写一行 CSS 的情况下对表格的表头、行、单元格、过滤下拉、展开按钮、Footer 等数十个维度进行主题化定制。读完本文，你将掌握 Table 全部组件 Token 的含义、默认值与三档尺寸（large / middle / small）的映射关系，并可以直接将文中的完整示例复制到你的 React 项目中运行。
一、什么是组件 Token
在 Ant Design 的 Design Token 体系中，Token 分为两层：
- 全局 Token（Global Token）：如
colorPrimary、borderRadius、fontSize等，影响所有组件； - 组件 Token（Component Token）：以组件为单位定义的样式变量，如 Table 的
headerBg、cellPaddingBlock，只作用于该组件内部。
组件 Token 通过ConfigProvider的theme.components注入，是官方推荐的主题定制入口。在 theme 的接口定义 中，每个组件都导出了自己的ComponentToken类型，Table 的组件 Token 定义位于 components/table/style/index.ts。
仓库中对应的演示文档与源码是：
- 文档说明：components/table/demo/component-token.md（"组件 Token / Component Token"）
- 完整演示代码：components/table/demo/component-token.tsx
二、Table 组件 Token 完整清单与默认值
Table 的组件 Token 全部定义在 components/table/style/index.ts 的ComponentToken接口中。默认值由prepareComponentToken函数（components/table/style/index.ts）基于全局 Token 计算得出。
| Token 名称 | 说明 | 默认值（来自prepareComponentToken） |
|---|---|---|
headerBg | 表头背景 | colorFillAlter叠加到容器色后的实色 |
headerColor | 表头文字颜色 | colorTextHeading |
headerSortActiveBg | 表头排序激活态背景 | colorFillSecondary实色化 |
headerSortHoverBg | 表头排序激活态悬浮背景 | colorFillContent实色化 |
bodySortBg | 排序列单元格背景 | colorFillAlter实色化 |
rowHoverBg | 行悬浮背景 | colorFillAlter实色化 |
rowSelectedBg | 行选中背景 | controlItemBgActive |
rowSelectedHoverBg | 行选中且悬浮背景 | controlItemBgActiveHover |
rowExpandedBg | 展开行背景 | colorFillAlter |
cellPaddingBlock | 单元格纵向内边距（默认大尺寸） | padding（16） |
cellPaddingInline | 单元格横向内边距（默认大尺寸） | padding（16） |
cellPaddingBlockMD | 中等尺寸纵向内边距 | paddingSM（12） |
cellPaddingInlineMD | 中等尺寸横向内边距 | paddingXS（8） |
cellPaddingBlockSM | 小尺寸纵向内边距 | paddingXS（8） |
cellPaddingInlineSM | 小尺寸横向内边距 | paddingXS（8） |
borderColor | 表格边框/分割线颜色 | colorBorderSecondary |
headerBorderRadius | 表头圆角 | borderRadiusLG |
footerBg | Footer 背景 | colorFillAlter实色化 |
footerColor | Footer 文字颜色 | colorTextHeading |
cellFontSize | 单元格文字大小（大尺寸） | fontSize（14） |
cellFontSizeMD | 单元格文字大小（中等尺寸） | fontSize（14） |
cellFontSizeSM | 单元格文字大小（小尺寸） | fontSize（14） |
headerSplitColor | 表头分割线颜色 | colorBorderSecondary |
fixedHeaderSortActiveBg | 固定表头排序激活态背景 | colorFillSecondary实色化 |
headerFilterHoverBg | 表头过滤按钮悬浮背景 | colorFillContent |
filterDropdownMenuBg | 过滤下拉菜单项背景 | colorBgContainer |
filterDropdownBg | 过滤下拉菜单背景 | colorBgContainer |
expandIconBg | 展开按钮背景 | colorBgContainer |
selectionColumnWidth | 选择列宽度 | controlHeight |
stickyScrollBarBg | Sticky 模式滚动条背景 | colorTextPlaceholder |
stickyScrollBarBorderRadius | Sticky 模式滚动条圆角 | 100 |
此外源码中还有一组带@internal标记的内部 Token（expandIconMarginTop、expandIconHalfInner、expandIconSize、expandIconScale、headerIconColor、headerIconHoverColor），它们用于展开图标与表头图标的内部计算，属于实现细节，不建议在业务中直接覆写。
说明：源码中
prepareComponentToken使用TinyColor.onBackground()将半透明填充色叠到容器背景上得到"实色化"默认值，因此即使你只修改全局 Token，Table 的默认外观也会联动变化——组件 Token 是全局 Token 的"派生层"。
三、实战：用 ConfigProvider 一键换肤 Table
仓库演示 components/table/demo/component-token.tsx 展示了最典型的用法：用ConfigProvider包裹Table，在theme.components.Table中覆写需要的 Token。
import { ConfigProvider, Table } from 'antd'; const App = () => ( <ConfigProvider theme={{ components: { Table: { colorBgContainer: '#e6f4ff', headerBg: '#1677ff', headerColor: '#fff', headerSortActiveBg: '#0958d9', headerSortHoverBg: '#69b1ff', bodySortBg: '#1677ff10', rowHoverBg: '#1677ff10', rowSelectedBg: '#bae0ff', rowSelectedHoverBg: '#91caff', rowExpandedBg: '#1677ff10', cellPaddingBlock: 20, cellPaddingInline: 20, cellPaddingBlockMD: 16, cellPaddingInlineMD: 16, cellPaddingBlockSM: 12, cellPaddingInlineSM: 12, borderColor: '#e6f4ff', headerBorderRadius: 0, footerBg: '#1677ff', footerColor: '#fff', cellFontSize: 16, cellFontSizeMD: 16, cellFontSizeSM: 14, headerSplitColor: '#fff', headerFilterHoverBg: 'rgba(0, 0, 0, 0.12)', filterDropdownMenuBg: '#fff', filterDropdownBg: '#fff', expandIconBg: '#e6f4ff', }, }, }} > <Table columns={columns} dataSource={data} pagination={{ position: ['none', 'bottomRight'] }} /> </ConfigProvider> );运行后可以看到：表头变为蓝色主色（#1677ff）、白色文字，行悬浮/选中/展开呈现统一色系，单元格内边距增大，Footer 反色，过滤下拉与展开按钮背景也同步调整。这正是组件 Token 的价值——一次配置，全表生效，无需任何 CSS。
关键要点
- Token 放在
theme.components.Table下，而不是theme.token。前者是组件级，后者是全局级； - 颜色支持任意合法 CSS 颜色值，包括
#1677ff10这样的 8 位十六进制（带透明度）以及rgba(...)； - 数值类 Token 直接传数字，如
cellPaddingBlock: 20，无需带单位； ConfigProvider可嵌套，内层配置会覆盖外层，便于做局部区域的差异化定制。
四、三档尺寸（size）与 Token 的映射关系
Table 的size属性（large/middle/small）与填充、字号 Token 一一对应：
| size 属性 | 纵向内边距 | 横向内边距 | 字号 |
|---|---|---|---|
large（默认） | cellPaddingBlock | cellPaddingInline | cellFontSize |
middle | cellPaddingBlockMD | cellPaddingInlineMD | cellFontSizeMD |
small | cellPaddingBlockSM | cellPaddingInlineSM | cellFontSizeSM |
这层映射在源码中通过mergeToken完成：genStyleHooks将组件 Token 合并进TableToken（如tablePaddingVertical: cellPaddingBlock），见 components/table/style/index.ts。随后 size.ts 中的getSizeStyle根据table-${size}类名将对应内边距应用到title、footer、cell、thead、tbody等元素上：
const getSizeStyle = (size, paddingVertical, paddingHorizontal, fontSize) => ({ [`${componentCls}${componentCls}-${size}`]: { fontSize, [` ${componentCls}-title, ${componentCls}-footer, ${componentCls}-cell, ${componentCls}-thead > tr > th, ${componentCls}-tbody > tr > th, ${componentCls}-tbody > tr > td, tfoot > tr > th, tfoot > tr > td `]: { padding: `${paddingVertical} ${paddingHorizontal}`, }, }, });因此定制时要注意：如果业务中同时使用多种size，应分别覆写对应的 MD / SM Token，否则middle/small尺寸仍会走默认值。演示代码中即同时设置了三种尺寸的 padding 与 fontSize。
五、演示中的其他配套能力
为了更直观地验证 Token 效果，component-token.tsx 还在表格上方提供了一组控制项（Form+Switch/Radio.Group），可以动态切换：
- Bordered：开关边框样式（对应
bordered属性）； - loading：加载态；
- Title / Column Header / Footer：开关标题、表头、Footer 的显示；
- Expandable：展开行渲染（
expandedRowRender）； - Checkbox：行选择列（
rowSelection）； - Fixed Header / Table Scroll：纵向
scroll.y = 240固定表头、横向scroll.x滚动或固定列； - Ellipsis：单元格文本省略；
- Size：large / middle / small 三档切换，可直接观察上一节 Token 映射效果；
- Pagination Top / Bottom：分页位置控制（
pagination.position）。
这些开关覆盖了 Table 最常用的交互状态，配合 Token 配置即可一次性验收表头、行悬浮、行选中、展开行、Footer、过滤、排序等全部视觉状态，适合作为主题联调的参考脚手架。
六、在官方文档中查阅 Token
Table 的 index.zh-CN.md 在"主题变量（Design Token）"章节通过<ComponentTokenTable component="Table" />动态渲染 Token 表格，展示每个 Token 的说明与当前主题下的默认值，是查阅完整清单的最直接入口。当你修改 Token 后刷新页面，该表会实时反映新值，便于对照调试。
七、总结
- 组件 Token 是 Table 主题定制的官方入口，通过
ConfigProvider theme.components.Table注入，覆盖表头、行、单元格、过滤、展开、Footer、Sticky 滚动条等全部视觉维度； - Token 按尺寸分档：
cellPaddingBlock/Inline、cellFontSize对应 large，MD / SM 后缀对应 middle / small，混用多种尺寸时需分别覆写； - Token 从全局 Token 派生，改全局色板会联动默认外观，覆写组件 Token 可实现精确的局部控制；
- 完整可运行的示例见 component-token.tsx，Token 定义与默认值见 components/table/style/index.ts。
通过组件 Token，你可以在不引入任何 CSS 文件的前提下，将 Table 的外观完全纳入项目的主题体系，实现品牌化、统一化、可维护的表格样式管理。
【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/ant/ant-design
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
