antd Calendar 的 showWeek 详解：在日历中显示周数的实现与原理

本文聚焦 antd Calendar 组件的 showWeek 属性，讲解如何通过一个开关在全屏日历与迷你日历中显示 ISO 周数列，并结合 calendar 演示、生成器源码 与 样式实现 说明周数从属性传入到像素渲染的完整链路，读完后你能理解该特性的版本要求、默认行为以及在 fullscreen / mode 等不同形态下的表现。

一、demo 的核心结论：一行 showWeek 打开周数列

该示例的描述文档 week.md 原文只有两句话（中英文各一句），核心内容如下：

通过将 showWeek 属性设置为 true，在全屏日历中显示周数。 Show week number in fullscreen calendar by setting showWeek prop to true.

对应的可运行示例代码 week.tsx 完整地给出了两种形态的用法：

import React from 'react';
import { Calendar } from 'antd';

const App: React.FC = () => (
  <>
    <Calendar fullscreen showWeek />
    <br />
    <Calendar fullscreen={false} showWeek />
  </>
);

export default App;

从示例代码可以确认两个要点：

• showWeek 是 Calendar 的一个可选布尔属性，只需传入布尔字面量 true 即可，没有周数起始日、周数格式等附加配置项；
• 该属性对 fullscreen（全屏）与 fullscreen={false}（迷你）两种形态都生效，但视觉呈现依赖形态对应的样式规则（下文第四节展开）。

二、showWeek 在 API 中的定义与版本前提

Calendar API 文档 中对该属性的完整定义为：

属性名	说明	类型	默认值	版本	支持键盘
showWeek	是否显示周数列	boolean	false	5.23.0	×

即该特性自 5.23.0 起提供，当前仓库 package.json 中版本为 6.6.2，默认不显示周数，不启用时无任何附加开销。

在类型层面，showWeek 被声明在通用的 CalendarProps 接口中（generateCalendar.tsx 第 82 行）：

export interface CalendarProps<DateType> {
  // ...
  fullscreen?: boolean;
  showWeek?: boolean;
  // ...
}

由于 Calendar 组件是由 generateCalendar<Dayjs>(dayjsGenerateConfig) 生成的（见 index.tsx），这个接口同时服务于默认导出与 Calendar.generateCalendar 高阶用法，因此任何自定义 generateConfig 的日历都同样支持 showWeek。

三、源码链路：属性如何一路传到底层面板

在 generateCalendar.tsx 中，showWeek 的处理链路非常直接：

1. 解构接收：第 130 行从 props 中解构出 showWeek；
2. 参与语义合并：第 147–152 行将其并入 mergedProps，与 mode、fullscreen 一起作为 classNames / styles 函数式回调的 info.props 输入，意味着自定义语义化样式可以感知当前是否开启了周数列；
3. 透传到底层面板：第 413–429 行，showWeek 被直接透传给 @rc-component/picker 提供的 RCPickerPanel：

<RCPickerPanel
  value={mergedValue}
  prefixCls={prefixCls}
  locale={locale?.lang}
  generateConfig={generateConfig}
  cellRender={mergedCellRender}
  onSelect={(nextDate) => {
    onInternalSelect(nextDate, panelMode);
  }}
  mode={panelMode}
  picker={panelMode}
  disabledDate={mergedDisabledDate}
  hideHeader
  showWeek={showWeek}   // 关键：透传给面板
/>

从源码结构看，周数格的实际计算与渲染（按 ISO 周数规则生成每行第一列的周号）由底层 @rc-component/picker 的 PickerPanel 完成（当前仓库依赖版本为 ~1.12.2，见 package.json），Calendar 本身只负责透传开关并套用外层样式。这也解释了为什么 showWeek 同时出现在 Calendar 与 DatePicker 面板相关的类型体系中——它们共享同一套面板组件。

四、样式层：周数列在全屏与迷你形态下的呈现

showWeek 打开后，面板每行多出的周数格使用 -cell-week 类名。其样式规则位于 style/index.ts：

• 全屏形态（${calendarCls}${calendarCls}-full 选择器内，第 152–163 行）：

[`${componentCls}-cell-week ${componentCls}-cell-inner`]: {
  display: 'block',
  borderRadius: 0,
  borderTop: `${unit(token.lineWidthBold)} ${token.lineType} ${token.colorSplit}`,
  width: '100%',
  height: token
    .calc(token.dateValueHeight)
    .add(token.dateContentHeight)
    .add(token.calc(token.paddingXS).div(2))
    .add(token.lineWidthBold)
    .equal(),
},

可以看到全屏日历的周数格高度是按「日期值高度 + 日期内容高度 + 半份 paddingXS + 加粗分隔线」动态计算的，保证周数格与同行日期格严格等高，顶部的粗分隔线（lineWidthBold）则用于视觉区分周数列与日期主体。

• 迷你形态（-mini 选择器内，第 112–132 行）：周数格沿用面板通用 cell 布局，表头高度由 weekHeight token 控制（lineHeight: unit(token.weekHeight)，第 126 行）。weekHeight 的默认值来自第 264 行的主题计算：calc(token.controlHeightSM).mul(0.75)，即小型控件高度的 75%。

这与文档描述的「在全屏日历中显示周数」一致：全屏形态下周数列有专门的高度对齐与分隔线样式，是视觉上最完整、最典型的呈现场景。

五、实战要点与可验证的检查清单

结合 demo 目录 中的其他示例（basic、select、lunar 等），使用 showWeek 时建议注意以下几点：

• 与 mode 配合：Calendar 的 mode 支持 'month' / 'year'（见 generateCalendar.tsx 的 CalendarMode 类型），面板渲染时会被映射为 'date' / 'month' 两种 panelMode。开启周数后，日期面板（mode="month"）每行首列即显示周数；如需固定展示某形态，可显式传入 mode；
• 与 disabledDate / validRange 组合：周数格只承载编号信息，不可点击选中，不影响禁用规则。禁用逻辑统一由 mergedDisabledDate 合并 validRange 区间判断与自定义 disabledDate 后传入面板（generateCalendar.tsx），可与 event-range 示例 中的事件标注思路结合；
• 自定义单元格时注意：若实现了 fullCellRender，它会接管整个格子（含周数行的视觉区域），此时周数格的展示效果取决于你自己的实现；cellRender 只影响日期格内容区；
• 版本前提：showWeek 自 5.23.0 起可用（API 文档），低于该版本的项目升级前请确认日期库与 rc-picker 版本满足要求。

六、小结

showWeek 是 antd Calendar 中一个低门槛、高实用性的开关属性：在业务上它让日历按 ISO 周对齐排期，在实现上它仅是一条「属性解构 → 语义合并 → 透传 RCPickerPanel」的短链路，而周数格的高度对齐与分隔线则由 components/calendar/style/index.ts 中的 token 化样式保证。围绕 week 演示 与 生成器源码，你可以快速验证：默认关闭、显式开启后全屏与迷你两种形态均生效、且与 mode、disabledDate 等既有能力互不冲突。