Ant Design Calendar 组件 Token 主题定制实战：从调试 Demo 到样式源码的全链路解析

本文以 Ant Design 官方 Calendar 组件的「组件 Token」调试示例为骨架，完整讲解如何通过 ConfigProvider 的 theme.components.Calendar 覆盖 fullBg、fullPanelBg、itemActiveBg 等组件级 Design Token；并深入 日历样式源码，说明每个 Token 的默认值来源、在 CSS-in-JS 生成链路中的具体作用位置，以及组件从 DatePicker 复用的面板 Token 体系。

1. 官方示例做了什么：component-token 调试 Demo

Calendar 文档中的「组件 Token」示例以 debug 属性挂载（见 日历组件文档 第 27 行的 <code src="./demo/component-token.tsx" debug>），debug 会在页面中渲染出该组件完整的 Token 取值表，便于开发时核对每一个设计变量的实际值。

示例本体只有 30 行，位于 component-token.tsx，核心结构如下（与仓库源码一致）：

import React from 'react';
import { Calendar, ConfigProvider } from 'antd';
import type { CalendarProps } from 'antd';
import type { Dayjs } from 'dayjs';

/** Test usage. Do not use in your production. */
export default () => {
  const onPanelChange = (value: Dayjs, mode: CalendarProps<Dayjs>['mode']) => {
    console.log(value.format('YYYY-MM-DD'), mode);
  };

  return (
    <ConfigProvider
      theme={{
        components: {
          Calendar: {
            fullBg: 'red',
            fullPanelBg: 'green',
            itemActiveBg: 'black',
          },
        },
      }}
    >
      <Calendar onPanelChange={onPanelChange} />
      <br />
      <Calendar onPanelChange={onPanelChange} fullscreen={false} />
    </ConfigProvider>
  );
};

这个 Demo 有三个关键信息：

1. 定制入口：通过 ConfigProvider 的 theme.components.Calendar 字段覆盖组件级 Token，这是 Ant Design 主题系统「种子 Token → 全局映射 Token → 组件级 Token」三级体系中最细粒度的一级；
2. 双形态覆盖：同一个 Provider 下同时渲染了全屏模式（默认 fullscreen）与迷你模式（fullscreen={false}）两个日历，验证 Token 覆盖对两种形态同时生效；
3. 刻意的「刺眼」取值：示例头部注释写明 Test usage. Do not use in your production.，red/green/black 是为了在调试时一眼看出 Token 是否命中对应区域——真正落项目时应替换为主题色板中的语义色。

配套的 component-token.md 只提供了 Component Token Debug. 的简短说明，具体的 Token 语义与取值需要从组件样式源码中补全，这正是下一节的内容。

2. Calendar 组件 Token 完整清单与默认值

Calendar 的组件级 Token 接口定义在 style/index.ts 的 ComponentToken 中，共 6 个自有变量；另有若干变量来自 PickerPanelToken 与 PanelComponentToken 的接口继承（见 CalendarToken extends FullToken<'Calendar'>, PickerPanelToken, PanelComponentToken）。

2.1 组件自有 Token

Token	说明	默认值	定义位置
yearControlWidth	年选择器宽度	80	style/index.ts#L19
monthControlWidth	月选择器宽度	70	style/index.ts#L24
miniContentHeight	迷你日历内容高度	256	style/index.ts#L29
fullBg	完整日历背景色	colorBgContainer	style/index.ts#L34
fullPanelBg	完整日历面板背景色	colorBgContainer	style/index.ts#L39
itemActiveBg	日期项选中背景色	controlItemBgActive	style/index.ts#L44

其中 number | string 类型的 Token（如 yearControlWidth）既可传数字（按 px 处理）也可传 CSS 字符串，适配 calc()、vw 等场景。

2.2 从 DatePicker 复用的面板 Token

Calendar 与日期选择器共享同一套面板单元格体系。prepareComponentToken 在组装默认值时显式展开了 initPanelComponentToken(token)（style/index.ts#L246-L254）：

export const prepareComponentToken: GetDefaultToken<'Calendar'> = (token) => ({
  fullBg: token.colorBgContainer,
  fullPanelBg: token.colorBgContainer,
  itemActiveBg: token.controlItemBgActive,
  yearControlWidth: 80,
  monthControlWidth: 70,
  miniContentHeight: 256,
  ...initPanelComponentToken(token),
});

initPanelComponentToken 定义于 date-picker/style/token.ts，它从全局 Token 推导出一组面板变量，在 Calendar 中同样可被覆盖，常用的包括：

Token	说明	默认值推导（源出全局 Token）
cellHoverBg	单元格悬浮态背景色	controlItemBgHover
cellActiveWithRangeBg	选取范围内的单元格背景色	controlItemBgActive
cellHoverWithRangeBg	选取范围内的悬浮单元格背景色	colorPrimary 提亮 35%
cellRangeBorderColor	选取范围时单元格边框色	colorPrimary 提亮 20%
cellBgDisabled	单元格禁用态背景色	colorBgContainerDisabled
cellWidth / cellHeight	单元格宽 / 高	controlHeightSM * 1.5 / controlHeightSM
textHeight	单元格文本高度	controlHeightLG
timeColumnWidth / timeColumnHeight / timeCellHeight	时间列宽 / 高与时间单元格高度	controlHeightLG * 1.4 / 28 * 8 / 28
withoutTimeCellHeight	十年/年/季/月/周单元格高度	controlHeightLG * 1.65

从源码结构看，这一继承关系意味着：在 Calendar 的 theme.components.Calendar 中覆盖一个面板 Token（例如 cellHoverBg），与覆盖 DatePicker 面板 Token 走的是同一条样式生成链路，这解释了为什么日历面板的单元格交互色能跟随全局 colorPrimary 与控件高度自动伸缩。

3. 三个背景 Token 在样式生成中的落点

Demo 覆盖的 fullBg、fullPanelBg、itemActiveBg 分别对应日历的三层视觉区域。它们在 genCalendarStyles（style/index.ts#L70-L244）中的具体消费位置如下：

• fullBg → 日历根节点背景（L73-L76）：

[calendarCls]: {
  ...genPanelStyle(token),
  ...resetComponent(token),
  background: fullBg,   // .ant-picker-calendar 根节点背景

它覆盖的是 -full 全屏日历的整块底色；Demo 中把它设为 red，全屏日历的空白底便呈现红色。

• fullPanelBg → 面板容器背景（L97-L101）：

[`${calendarCls} ${componentCls}-panel`]: {
  background: fullPanelBg,   // 面板主体（星期表头 + 日期网格所在层）
  border: 0,
  borderTop: `${unit(token.lineWidth)} ${token.lineType} ${token.colorSplit}`,

注意它只作用于「非 -full」组合选择器下的面板；-full 模式下面板会显式 background: fullBg（L133-L139）覆盖回去，所以全屏形态的视觉底色主要由 fullBg 决定，而迷你形态的面板底色由 fullPanelBg 决定——Demo 同时渲染两种形态，正是为了把这两个 Token 的落点区分开。

• itemActiveBg → 当前视图内选中日期单元格（L176-L181）：

[`&-in-view${componentCls}-cell-selected`]: {
  [`${calendarCls}-date, ${calendarCls}-date-today`]: {
    background: itemActiveBg,
  },
},

选择器链 -in-view + -cell-selected 限定了「当前面板月内的选中格」，配合 hover 态（controlItemBgHover，见 L168-L172）共同构成日期项的交互反馈。Demo 将其设为 black，点击某一天即可直观看到选中格背景被替换。

除背景外，同一函数中还有若干不可通过组件 Token 直接覆盖的尺寸量，它们由全局 Token 在样式 hook 中动态计算（L258-L270），例如：

• dateValueHeight: token.controlHeightSM——日期数字行高；
• weekHeight: controlHeightSM * 0.75——周行高；
• dateContentHeight——单元格事件区高度，由字号、外边距与线宽合成。

从源码结构看，调整这类尺寸应优先走全局 controlHeightSM 等基础 Token，而非组件 Token，这是 Token 体系的分工：组件 Token 管「本组件专属」的变量，全局 Token 管跨组件共用的度量。

4. 可落地的最小实践

把 Demo 的调试取值替换为语义化颜色，即得到一个可直接用于生产的定制方案（以下示例基于仓库中实际存在的 Token 名，适用前提为项目已引入 ConfigProvider 主题能力）：

<ConfigProvider
  theme={{
    token: {
      // 可选：先调全局，组件默认值会随之联动
      colorBgContainer: '#fafafa',
      controlItemBgActive: '#e6f4ff',
    },
    components: {
      Calendar: {
        // 全屏日历底色 / 面板底色 / 选中格背景
        fullBg: 'transparent',
        fullPanelBg: '#fff',
        itemActiveBg: 'var(--my-active-bg)',
        // 迷你日历内容区高度，控制事件区可滚动区域
        miniContentHeight: 320,
      },
    },
  }}
>
  <Calendar fullscreen={false} />
</ConfigProvider>

几个实践要点：

1. 作用域：ConfigProvider 支持嵌套，内层 Provider 的 components.Calendar 只影响其子树，可做页面级乃至区块级定制，无需全局污染；
2. 联动优于硬编码：fullBg、fullPanelBg 默认值直接取 colorBgContainer，itemActiveBg 取 controlItemBgActive（见 prepareComponentToken）。如果业务只改主题色，优先覆盖全局 Token，组件会继承正确默认值；仅当日历需要与全局不同的独立配色时才显式覆盖组件 Token；
3. 调试核对：给文档式 Demo 加 debug 属性可渲染 Token 表；正式应用中可通过浏览器 DevTools 检查生成类名（如 .ant-picker-calendar 系列）上的实际值来验证覆盖是否生效；
4. 与语义化样式的边界：6.0 版本起 Calendar 另支持 classNames / styles 按语义 DOM 结构定制（见 Calendar API），它解决的是「针对特定 DOM 节点加类/内联样式」的问题；组件 Token 解决的是「参与主题计算的设计变量」问题，两者定位不同，不要混用。

5. 小结

关注点	结论	依据
定制入口	ConfigProvider theme.components.Calendar	component-token.tsx
组件自有 Token	yearControlWidth、monthControlWidth、miniContentHeight、fullBg、fullPanelBg、itemActiveBg	style/index.ts#L14-L45
默认值推导	全部由全局 Token（colorBgContainer、controlItemBgActive、controlHeightSM 等）计算	style/index.ts#L246-L254
面板 Token 复用	继承 DatePicker 的 PanelComponentToken / PickerPanelToken	date-picker/style/token.ts
调试手段	Demo 以 debug 属性渲染 Token 表	index.zh-CN.md 代码演示列表

一句话概括：Calendar 的组件 Token 是主题系统落到「日历」这一具体形态的开关——三个背景 Token 分别控制整块底色、面板底色与选中格，尺寸 Token 控制头部选择器与迷你内容区；理解 style/index.ts 中 Token 的消费位置后，即可在不写任何覆盖 CSS 的前提下完成日历的视觉定制。