Ant Design DatePicker 佛历（特殊纪年）格式支持指南：通过 locale 配置自定义年历显示

本指南讲解如何在 Ant Design 的 DatePicker 中通过 locale 配置支持特殊纪年历法（以泰国佛历 Buddhist Era 为典型场景），实现输入框、时间选择与年份面板全部显示自定义纪年年份的效果。读完本文将掌握 locale.lang 中 fieldDateFormat、yearFormat、cellYearFormat 等格式化令牌的作用，以及组件级 locale 与 ConfigProvider 全局 locale 两种配置注入方式，并结合 buddhist-era.tsx 与相关源码理解其底层运行机制。

场景背景：为什么需要自定义年历格式

Ant Design 的 DatePicker 默认按公历（Gregorian，即公元纪年 YYYY）展示日期。但在泰国等信奉佛教的国家，官方与民间普遍使用佛历（Buddhist Era，缩写 BE），其年份通常在公历基础上增加 543 年。例如公历 2024 年对应佛历 2567 年。若业务系统面向这些地区，日期输入框、日历面板中年份一栏若仍显示 2024，会与当地用户习惯冲突。

Ant Design 官方 demo buddhist-era 给出的方案是：不必新增日期组件，只需通过 locale 配置覆盖若干年号格式化令牌（源码见 buddhist-era.tsx），即可让 DatePicker 完整呈现佛历年号，因此也适用于任意需要特殊纪年的历法。

核心机制：日期格式由 locale.lang 中的令牌驱动

DatePicker 渲染日期字符串时，使用的格式并非硬编码，而是来自 Picker locale 对象 lang 下的格式化字段。下方以 antd 内置英文 locale 的完整基线为例（参见 date-picker/locale/en_US.ts 以及注释中引用的字段清单 example.json）：

locale.lang 字段	默认值（en_US 基线）	控制位置
fieldDateFormat	M/D/YYYY	日期输入框的回显格式（非 showTime 时）
fieldDateTimeFormat	M/D/YYYY HH:mm:ss	开启 showTime 后输入框回显格式
yearFormat	YYYY	面板头部与年视图中的年份显示格式
cellYearFormat	依赖底层 picker 默认	年份面板单元格内年份文本格式
monthFormat	MMMM	月份显示格式
fieldWeekFormat	YYYY-wo	周选择模式下的输入框格式

因此，要显示佛历年份，只需把这些字段中的 YYYY 换成佛历纪年令牌 BBBB。值得注意的是，DatePicker 早期曾提供过 dateFormat、dateTimeFormat、weekFormat 等顶层字段，如今在 interface.ts 中已标记为 @deprecated 且 Useless，统一迁移到 lang.fieldDateFormat、lang.fieldDateTimeFormat、lang.fieldWeekFormat 等 lang 内部字段，自定义 locale 时应直接落在 lang 下。

第一步：引入 dayjs 的 buddhistEra 插件

BBBB 令牌并不是 dayjs 的默认能力，它来自 dayjs 官方插件 buddhistEra，需要在应用入口处显式加载并扩展：

import dayjs from 'dayjs';
import buddhistEra from 'dayjs/plugin/buddhistEra';

dayjs.extend(buddhistEra);

扩展之后，dayjs 才认识 BBBB 格式串：格式化为字符串时输出佛历年份（公历 +543），解析 2567-01-01 这类输入时也能正确映射回内部时间。该插件属于 dayjs 依赖链，与 Ant Design 组件本身解耦——antd 只负责把格式令牌原样交给底层日期生成器。

第二步：构造组件级佛历 locale 对象

以 DatePicker 的英文 locale（antd/es/date-picker/locale/en_US）为基底，通过对象展开保留其余全部文案（placeholder、星期、月份缩写等），仅覆盖 lang 中的年号相关字段：

import type { DatePickerProps } from 'antd';
import en from 'antd/es/date-picker/locale/en_US';

// Component level locale
const buddhistLocale: typeof en = {
  ...en,
  lang: {
    ...en.lang,
    fieldDateFormat: 'BBBB-MM-DD',
    fieldDateTimeFormat: 'BBBB-MM-DD HH:mm:ss',
    yearFormat: 'BBBB',
    cellYearFormat: 'BBBB',
  },
};

说明：

• fieldDateFormat/fieldDateTimeFormat 控制输入框内的回显，同时会作为 onChange 第二参数字符串的格式基准。
• yearFormat 让面板切换年份时的按钮文本、cellYearFormat 让年份面板的每个单元格均呈现佛历年号，避免"公历输入框 + 佛历面板"相互打架。
• 完整字段结构为 { lang: {...}, timePickerLocale: {...} }，见 PickerLocale 的类型定义；typeof en 约束可以保证扩展后对象不遗漏必需结构，属于推荐写法。

第三步：按需注入并验证

将 locale 通过 locale prop 传给单个 DatePicker，即可让该组件独立呈现佛历。官方 demo 同时覆盖了普通日期与带时间两种形态：

const defaultValue = dayjs('2024-01-01');

const onChange: DatePickerProps['onChange'] = (_, dateStr) => {
  console.log('onChange:', dateStr);
};

<DatePicker defaultValue={defaultValue} locale={buddhistLocale} onChange={onChange} />
<DatePicker
  defaultValue={defaultValue}
  showTime
  locale={buddhistLocale}
  onChange={onChange}
/>

运行效果：两个输入框分别回显 2567-01-01 与 2567-01-01 00:00:00；展开面板后年份视图显示 2567 年；选择日期触发 onChange 时，第二参数 dateStr 输出为 BBBB-MM-DD 形态的字符串。由此可见，defaultValue 仍按内部时间构造，只是"对外显示"被本地化。

全局启用：通过 ConfigProvider 注入佛历 locale

组件级 locale 只影响单个实例。若希望整个应用（或某子树）内所有 DatePicker 默认采用佛历，则应在 ConfigProvider 层级覆盖全局 locale 中 DatePicker 段。antd 的全局 locale 文件（形如 locale/en_US.ts）均按组件名组织，DatePicker 段内部同样为 { lang, timePickerLocale }：

import { ConfigProvider, DatePicker, Space } from 'antd';
import enUS from 'antd/es/locale/en_US';

// ConfigProvider level locale
const globalBuddhistLocale: typeof enUS = {
  ...enUS,
  DatePicker: {
    ...enUS.DatePicker!,
    lang: buddhistLocale.lang, // 复用上一步构造的 lang
  },
};

<ConfigProvider locale={globalBuddhistLocale}>
  <DatePicker defaultValue={defaultValue} onChange={onChange} />
  <DatePicker defaultValue={defaultValue} showTime onChange={onChange} />
</ConfigProvider>

此时子树内的 DatePicker 无需再写 locale prop，即可全局呈现佛历年号。需要强调的是：全局 locale 的对象形状与组件级 picker locale 不同——全局 locale 是"组件名 → 各组件 locale 段"的映射（形如 { DatePicker: { lang, timePickerLocale }, ... }），二者不可混用；demo 中通过 DatePicker: { ...enUS.DatePicker!, lang: buddhistLocale.lang } 仅替换年份相关 lang，其余组件与 DatePicker 的其他文案不受影响。

源码视角：自定义 locale 是如何被消费与合并的

以单日期选择器为例，在 generateSinglePicker.tsx 中可以看到完整链路：

1. 通过 useLocale('DatePicker', enUS) 从 ConfigProvider 读取全局 DatePicker locale（读不到时回退到 antd 内置英文 en_US）。
2. 调用 merge(contextLocale, props.locale) 将全局 locale 与组件 locale prop 合并——组件级 prop 拥有更高优先级，这与上文"组件级只影响单个实例"的行为一致。
3. 最终 locale.lang 被透传给底层 RCPicker 渲染，placeholder 等文案也取自合并后的 locale（对应 getPlaceholder(locale, mergedPicker, placeholder) 分支）。

也就是说，无论佛历 locale 从 ConfigProvider 还是从 locale prop 注入，最终都收敛到同一个 lang 对象再交给底层 picker 解析令牌，因此 fieldDateFormat、yearFormat、cellYearFormat 等字段在两套注入方式下语义完全一致。三种 DatePicker 变体（DatePicker/TimePicker/RangePicker）均由同一套 generatePicker 工厂产出，RangePicker 的 rangePlaceholder、fieldDateFormat 等字段也遵循相同合并规则，需要特殊纪年时可类比扩展。

易错点与最佳实践

• 令牌依赖 dayjs 插件：不执行 dayjs.extend(buddhistEra) 时，BBBB 会被当作普通字符原样输出，输入框将显示 BBBB-01-01 而非 2567-01-01。
• 覆盖字段必须落在 lang 内：旧版顶层字段（dateFormat 等）已废弃失效，覆盖到 lang.fieldDateFormat、lang.fieldDateTimeFormat 才生效，具体见 interface.ts 的迁移提示。
• 两种注入的优先级：同一组件同时配置 ConfigProvider 全局 locale 与组件 locale prop 时，后者覆盖前者，便于做"整体佛历 + 局部公历"的例外场景。
• onChange 的字符串参数随之变化：开启佛历 locale 后，onChange 第二参数与格式化回显基于同一令牌集输出，若后端按公历存储，需在回调中自行换算或使用 dayjs 对象做二次格式化，不要直接持久化字符串。
• 保持 lang 内部各字段风格统一：建议同时覆盖 fieldDateFormat、fieldDateTimeFormat、yearFormat、cellYearFormat，避免输入框显示佛历而面板头部仍为公历的割裂体验。

小结

佛历/特殊纪年支持并不需要改动 DatePicker 组件本身，只需两件事：先在 dayjs 侧扩展 buddhistEra 之类的纪年插件获得 BBBB 令牌能力，再通过 locale 覆盖 lang 内的格式化字段。官方 demo buddhist-era.tsx 给出了"组件级 locale prop"与"ConfigProvider 全局 locale"两套可复制的完整代码；源码 generateSinglePicker.tsx、interface.ts 则揭示了 locale 合并与字段迁移的底层规则。掌握这套"令牌 + locale"机制后，公历、佛历乃至其他自定义纪年格式都能在 DatePicker 体系中平滑落地。