Ant Design DatePicker 日期选择框实战指南：完整 API、国际化配置与源码级原理

本篇技术指南以 Ant Design 中 DatePicker（日期选择框）组件为核心，系统讲解其「五种 picker 形态 + RangePicker」的组件家族结构、完整的共享/专属 API、国际化（locale）配置、格式与语义化 DOM 定制，并结合仓库源码（index.tsx、generatePicker）剖析其底层生成机制与常用属性（multiple、needConfirm、presets、formatType 等）的实现原理。阅读完本文，你将能够在不翻阅全部文档的情况下，正确选型、配置并深度定制 Ant Design 的日期选择能力，也能理解 FAQ 中若干疑难问题的成因。

何时使用 DatePicker

当用户需要一个标准化的日期输入时，DatePicker 允许其点击标准输入框、弹出日期面板进行选择，在保证输入格式统一的同时，避免了手工键入可能带来的格式错误。它适用于几乎所有需要采集「某一天 / 某段时间 / 某月 / 某年 / 某季度 / 某周」的场景，例如任务截止日期、订单起止时间、报表周期等。

五种形态：从 picker 属性理解 DatePicker 家族

Ant Design 的日期类组件在 DatePicker 这一个命名空间下，通过 picker 属性派生出多种形态。原文档定义如下五种形式：

• DatePicker
• DatePicker[picker="month"]
• DatePicker[picker="week"]
• DatePicker[picker="year"]
• DatePicker[picker="quarter"]（4.1.0 新增）
• RangePicker

各形态的默认 format 与选择粒度均不同，见下表（均以 dayjs 格式串表示）：

形态	picker 值	默认 format	典型 value 示例
单日期	date	YYYY-MM-DD	2025-01-15
年	year	YYYY	2025
季度	quarter	YYYY-\QQ	2025-Q1
月	month	YYYY-MM	2025-01
周	week	YYYY-wo	2025-03

基础使用见 demo/basic.tsx，同一组件内通过 picker 在日期/周/月/季度/年之间切换，并统一走 onChange 回调：

import { DatePicker } from 'antd';

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

<DatePicker onChange={onChange} />
<DatePicker onChange={onChange} picker="week" />
<DatePicker onChange={onChange} picker="month" />
<DatePicker onChange={onChange} picker="quarter" />
<DatePicker onChange={onChange} picker="year" />

范围选择的 RangePicker 支持同样的 picker 粒度（date/week/month/quarter/year），并可通过 showTime 叠加时间维度，参见 demo/range-picker.tsx。

源码视角：generatePicker 如何生成整个组件家族

从源码结构看，DatePicker 并非逐个手写，而是由工厂函数统一生成。入口文件 先将 dayjs 的日期生成配置注入工厂：

import dayjsGenerateConfig from '@rc-component/picker/generate/dayjs';
import generatePicker from './generatePicker';

const DatePicker = generatePicker<Dayjs>(dayjsGenerateConfig);

而 generatePicker/index.tsx 中的工厂会一次性产出 DatePicker / WeekPicker / MonthPicker / YearPicker / TimePicker / QuarterPicker 六种子组件，并把它们挂到主组件上（MergedDatePicker.WeekPicker = WeekPicker 等）。这就是「五种形态」在实现层面的根基：

• 它依赖 @rc-component/picker 提供的底层 Picker 交互，以及 GenerateConfig<DateType> 这一日期引擎抽象；
• 只要替换 generateConfig（例如换成 moment、date-fns 的实现），工厂就能生成基于其他日期库的整套组件——这正是文档 FAQ 中「如何在 DatePicker 中使用自定义日期库」的由来，详见《使用自定义日期库》。

默认形态下 generateSinglePicker 还会在组件内部完成 placeholder 派生。查看 util.ts：当开发者未传 placeholder 时，会依据 picker 从 locale 中依次读取 yearPlaceholder / quarterPlaceholder / monthPlaceholder / weekPlaceholder 或默认的 lang.placeholder，范围选择则对应读取 rangeYearPlaceholder 等键——也就是说，placeholder 文案本身就是语言包的一部分。

国际化（locale）配置

DatePicker 的默认语言为 en-US。如果需要全局切换语言，推荐在应用入口使用 ConfigProvider 的国际化能力，参见 ConfigProvider 国际化文档。

// 默认语言为 en-US，如果你需要设置其他语言，推荐在入口文件全局设置 locale
// 确保还导入相关的 dayjs 文件，否则所有文本的区域设置都不会更改（例如范围选择器月份）
import locale from 'antd/locale/zh_CN';
import dayjs from 'dayjs';

import 'dayjs/locale/zh-cn';

dayjs.locale('zh-cn');

<ConfigProvider locale={locale}>
  <DatePicker defaultValue={dayjs('2015-01-01', 'YYYY-MM-DD')} />
</ConfigProvider>;

需要注意两个易错点：

1. dayjs locale 必须同步加载。Ant Design 的日期组件渲染时同时依赖组件自身的 locale 文案（来自 antd/locale/zh_CN）与 dayjs 的国际化数据（例如月份、星期名称、周起始日），两者缺一不可。
2. Next.js App Router 下需加 'use client'。由于 Ant Design 组件均为客户端组件，在 RSC（React Server Component）中引入 dayjs 的 locale 文件不会在客户端生效，因此请把「导入 locale 文件」的语句放入带 'use client' 的模块中。

若仅需修改单个组件的语言，可给组件传入 locale 参数，其结构与 locale/example.json 定义的默认配置一致——lang 部分存放面板文案（如 placeholder、today、ok、shortWeekDays、shortMonths、fieldDateFormat），timePickerLocale 部分存放时间选择文案。各语言包就位于 locale 目录（如 en_US.ts、zh_CN.ts 等 69 个语言文件）。

API 总览

日期类组件共享通用属性集，官方统一定义见通用属性文档。下面按「共享 API → 各自专属 API → 类型定义」三层展开完整参数表。

DatePicker 与 RangePicker 共享的 API

下表为两者通用参数，最后一列 全局配置 表示该参数是否可经由 ConfigProvider 的 component 级全局配置 统一设置（值为版本号表示自该版本起支持全局配置，× 表示不支持）：

参数	说明	类型	默认值	版本	全局配置
allowClear	自定义清除按钮	boolean | { clearIcon?: ReactNode }	true	5.8.0 起支持对象类型	6.4.0
bordered	是否带边框，已废弃，请使用 variant 替代	boolean	true	-	×
className	选择器 className	string	-	-	DatePicker: 5.7.0 / RangePicker: 5.11.0
classNames	自定义组件内部各语义化结构的 class，支持对象或函数	Record<SemanticDOM, string> | (info: { props }) => Record<SemanticDOM, string>	-	-	DatePicker: 5.25.0 / RangePicker: 5.25.0
dateRender	自定义日期单元格内容，5.4.0 起用 cellRender 代替	(currentDate: dayjs, today: dayjs) => React.ReactNode	-	< 5.4.0	×
cellRender	自定义单元格内容	(current, info: { originNode, today, range?: 'start' | 'end', type: PanelMode, locale?, subType?: 'hour' | 'minute' | 'second' | 'meridiem' }) => React.ReactNode	-	5.4.0	×
components	自定义面板	Record<Panel | 'input', React.ComponentType>	-	5.14.0	×
defaultOpen	是否默认展开弹层	boolean	-	-	×
disabled	禁用	boolean	false	-	×
disabledDate	不可选择的日期	(currentDate: dayjs, info: { from?: dayjs, type: Picker }) => boolean	-	info 参数：5.14.0	×
dropdownClassName	弹出日历的 className，已废弃，请使用 classNames.popup.root	string	-	-	×
format	日期格式；为数组时支持多格式解析（展示以第一个为准）。格式占位符参考 dayjs#format	formatType	见各形态默认值	-	×
order	多选、范围时是否自动排序	boolean	true	5.14.0	×
preserveInvalidOnBlur	失焦时是否保留输入框中的无效内容而不清空	boolean	false	5.14.0	×
popupClassName	额外弹出日历 className，使用 classNames.popup.root 替代	string	-	4.23.0	×
getPopupContainer	浮层挂载容器，默认为 body 下新建 div	(trigger) => HTMLElement	-	-	×
inputReadOnly	输入框只读（避免移动端弹出虚拟键盘）	boolean	false	-	×
locale	国际化配置	object	参考默认配置 example.json	-	×
minDate	最小日期，同样会限制面板的切换范围	dayjs	-	5.14.0	×
maxDate	最大日期，同样会限制面板的切换范围	dayjs	-	5.14.0	×
mode	日期面板状态（指定后无法点击切换年份/月份？见 FAQ）	'time' | 'date' | 'month' | 'year' | 'decade'	-	-	×
needConfirm	是否需要确认按钮；为 false 时失去焦点即代表选择。设置 multiple 时默认 false	boolean	-	5.14.0	×
nextIcon	自定义下一个图标	ReactNode	-	4.17.0	×
open	受控弹层开关	boolean	-	-	×
panelRender	自定义渲染面板	(panelNode) => ReactNode	-	4.5.0	×
picker	选择器类型	'date' | 'week' | 'month' | 'quarter' | 'year'	'date'	quarter: 4.1.0	×
placeholder	输入框提示文字	string | [string, string]	-	-	×
placement	弹层位置	bottomLeft / bottomRight / topLeft / topRight	bottomLeft	-	×
popupStyle	额外弹出日历样式，使用 styles.popup.root 替代	CSSProperties	{}	-	×
prefix	自定义前缀	ReactNode	-	5.22.0	×
prevIcon	自定义上一个图标	ReactNode	-	4.17.0	×
previewValue	悬停候选项时，输入框值是否随之临时变化	false | 'hover'	'hover'	6.0.0	×
presets	预设快捷选项；自 5.8.0 起 value 支持返回值的函数	{ label: React.ReactNode, value: Dayjs | (() => Dayjs) }[]	-	-	×
size	输入框大小：large 高 40px、small 高 24px，默认 32px	'large' | 'medium' | 'small'	-	-	×
status	校验状态	'error' | 'warning'	-	4.19.0	×
style	自定义输入框样式	CSSProperties	{}	-	DatePicker: 5.7.0 / RangePicker: 5.11.0
styles	自定义各语义化结构的行内 style，支持对象或函数	Record<SemanticDOM, CSSProperties> | (info: { props }) => ...	-	-	DatePicker: 5.25.0 / RangePicker: 5.25.0
suffixIcon	自定义选择框后缀图标	ReactNode	-	-	DatePicker: 6.3.0 / RangePicker: 6.4.0
superNextIcon	自定义 >> 切换图标	ReactNode	-	4.17.0	×
superPrevIcon	自定义 << 切换图标	ReactNode	-	4.17.0	×
clearIcon	自定义清除图标（仅支持全局配置）	ReactNode	-	-	6.4.0
variant	形态变体	'outlined' | 'borderless' | 'filled' | 'underlined'	'outlined'	5.13.0；underlined: 5.24.0	DatePicker: 5.19.0 / RangePicker: 5.19.0
onClear	点击清除按钮时的回调	() => void	-	6.5.0	×
onOpenChange	弹层打开/关闭回调	(open: boolean) => void	-	-	×
onPanelChange	日历面板切换回调	(value, mode) => void	-	-	×
onSelect	选中日期回调，已废弃，请使用 onCalendarChange	(value) => void	-	-	×

上述若干「废弃替换」关系都能在源码层找到对应告警：在 generateSinglePicker.tsx 中，开发环境下会通过 devUseWarning 对 dropdownClassName → classNames.popup.root、popupStyle → styles.popup.root、bordered → variant、onSelect → onCalendarChange 等给出 deprecated 提示，帮助使用旧版 API 的项目平稳迁移。

共享的实例方法

名称	描述	版本
blur()	移除焦点	-
focus()	获取焦点	-

DatePicker（picker="date"）专属 API

参数	说明	类型	默认值	版本
defaultPickerValue	默认面板日期；每次面板打开时会被重置到该日期	dayjs	-	5.14.0
defaultValue	默认日期。若范围的起点或终点为 null/undefined，日期范围将是开区间	dayjs	-	-
disabledTime	不可选择的时间	(date) => ...	-	-
format	展示格式	formatType	YYYY-MM-DD	-
multiple	是否多选；不支持 showTime	boolean	false	5.14.0
pickerValue	面板日期，可受控切换面板所在日期，常配合 onPanelChange	dayjs	-	5.14.0
renderExtraFooter	面板底部附加内容	(mode) => React.ReactNode	-	-
showNow	显示「此刻」快捷选择	boolean	-	4.4.0
showTime	增加时间选择	Object | boolean	参考 TimePicker Options	-
showTime.defaultValue	已废弃，请使用 showTime.defaultOpenValue	dayjs	dayjs()	5.27.3
showTime.defaultOpenValue	用户选择日期时的默认时分秒	dayjs	dayjs()	-
showWeek	DatePicker 下展示当前周	boolean	false	5.14.0
value	受控日期	dayjs	-	-
onChange	值变化回调	(date: dayjs | null, dateString: string | null) => void	-	-
onOk	点击「确定」回调	() => void	-	-
onPanelChange	面板变化回调	(value, mode) => void	-	-

关于 multiple 的典型用法可参考 demo/multiple.tsx：开启后 value/defaultValue 变为数组，配合 maxTagCount="responsive" 可让已选日期以 Tag 形式自适应折叠；同时其类型也会被泛型收紧为 DatePickerProps<Dayjs, true>['onChange']。而 needConfirm 的对比用法见 demo/needConfirm.tsx：为 true 时必须有确认动作才提交选择。

DatePicker[picker="year"] 专属 API

参数	说明	类型	默认值	版本
defaultValue	默认日期	dayjs	-	-
format	展示格式	formatType	YYYY	-
multiple	是否多选	boolean	false	5.14.0
renderExtraFooter	面板底部附加内容	() => React.ReactNode	-	-
tagRender	自定义已选项 tag 渲染，仅 multiple 生效	(props) => ReactNode	-	6.4.0
value	日期	dayjs	-	-
onChange	变化回调	(date: dayjs | null, dateString: string | null) => void	-	-

DatePicker[picker="quarter"] 专属 API（4.1.0 新增）

参数	说明	类型	默认值	版本
defaultValue	默认日期	dayjs	-	-
format	展示格式	formatType	YYYY-\QQ	-
multiple	是否多选	boolean	false	5.14.0
renderExtraFooter	面板底部附加内容	() => React.ReactNode	-	-
tagRender	自定义已选项 tag 渲染，仅 multiple 生效	(props) => ReactNode	-	6.4.0
value	日期	dayjs	-	-
onChange	变化回调	(date: dayjs | null, dateString: string | null) => void	-	-

DatePicker[picker="month"] 专属 API

参数	说明	类型	默认值	版本
defaultValue	默认日期	dayjs	-	-
format	展示格式	formatType	YYYY-MM	-
multiple	是否多选	boolean	false	5.14.0
renderExtraFooter	面板底部附加内容	() => React.ReactNode	-	-
tagRender	自定义已选项 tag 渲染，仅 multiple 生效	(props) => ReactNode	-	6.4.0
value	日期	dayjs	-	-
onChange	变化回调	(date: dayjs | null, dateString: string | null) => void	-	-

DatePicker[picker="week"] 专属 API

参数	说明	类型	默认值	版本
defaultValue	默认日期	dayjs	-	-
format	展示格式	formatType	YYYY-wo	-
multiple	是否多选	boolean	false	5.14.0
renderExtraFooter	面板底部附加内容	(mode) => React.ReactNode	-	-
tagRender	自定义已选项 tag 渲染，仅 multiple 生效	(props) => ReactNode	-	6.4.0
value	日期	dayjs	-	-
onChange	变化回调	(date: dayjs | null, dateString: string | null) => void	-	-
showWeek	DatePicker 下展示当前周	boolean	true	5.14.0

RangePicker 专属 API

参数	说明	类型	默认值	版本	全局配置
allowEmpty	允许起始项部分为空	[boolean, boolean]	[false, false]	-	×
cellRender	自定义单元格内容	同共享 API 签名（含 range?: 'start' | 'end'）	-	5.4.0	×
dateRender	自定义日期单元格，5.4.0 起用 cellRender	(currentDate, today) => ReactNode	-	< 5.4.0	×
defaultPickerValue	默认面板日期（每次打开重置）	[dayjs, dayjs]	-	5.14.0	×
defaultValue	默认日期区间	[dayjs, dayjs]	-	-	×
disabled	分别禁用起点/终点	[boolean, boolean]	-	-	×
disabledTime	不可选择的时间	(date: dayjs, partial: 'start' | 'end', info: { from?: dayjs }) => ...	-	info.from: 5.17.0	×
format	展示格式	formatType	YYYY-MM-DD HH:mm:ss	-	×
id	输入框 id	{ start?: string, end?: string }	-	5.14.0	×
pickerValue	受控面板日期	[dayjs, dayjs]	-	5.14.0	×
presets	预设范围快捷项；5.8.0 起 value 支持函数	{ label, value: [(Dayjs | (() => Dayjs)), (Dayjs | (() => Dayjs))] }[]	-	-	×
renderExtraFooter	面板底部附加内容	() => React.ReactNode	-	-	×
separator	起始项与结束项的分隔符	React.ReactNode	<SwapRightOutlined />	-	6.3.0
showTime	增加时间选择	Object | boolean	参考 TimePicker Options	-	×
showTime.defaultValue	已废弃，改用 showTime.defaultOpenValue	[dayjs, dayjs]	[dayjs(), dayjs()]	5.27.3	×
showTime.defaultOpenValue	默认选中日期对应时分秒	[dayjs, dayjs]	[dayjs(), dayjs()]	-	×
value	受控日期区间	[dayjs, dayjs]	-	-	×
onCalendarChange	待选日期变化回调，info 自 4.4.0 提供	(dates, dateStrings, info: { range: 'start' | 'end' }) => void	-	-	×
onChange	日期范围变化回调	(dates: [dayjs, dayjs] | null, dateStrings: [string, string] | null) => void	-	-	×
onFocus	聚焦回调	(event, { range: 'start' | 'end' }) => void	-	range: 5.14.0	×
onBlur	失焦回调	(event, { range: 'start' | 'end' }) => void	-	range: 5.14.0	×

RangePicker 可通过 id 与 onFocus/onBlur 的 info.range 区分当前操作的是起点还是终点输入框，这一模式在 demo/range-picker.tsx 中有直观示例。

formatType 类型详解

format 字段并非简单的字符串，其完整类型（5.14.0 起支持 mask 配置）如下：

import type { Dayjs } from 'dayjs';

type Generic = string;
type GenericFn = (value: Dayjs) => string;

export type FormatType =
  | Generic
  | GenericFn
  | Array<Generic | GenericFn>
  | {
      format: string;
      type?: 'mask';
    };

要点解读：

• string：最常见的写法，如 "YYYY-MM-DD HH:mm:ss"；
• 函数：(value: Dayjs) => string，允许按值动态决定展示格式；
• 数组：支持多种格式同时解析用户输入，但展示始终以第一个为准，适合宽容地接收多种输入习惯（对应 format 演示）；
• { format, type: 'mask' }：type: 'mask' 为 5.14.0 新增的「格式对齐」能力——输入时按 format 模板自动补全分隔符等字符，让输入过程呈现占位掩码效果，对应 mask 演示。

格式占位符完整清单参考 dayjs#format（如 YYYY 年份、MM 月份、DD 日、HH:mm:ss 时间、wo 周序号）。

设计补充：多选与预设范围

• 多选（multiple）：把 DatePicker 从「单选一天」扩展为「Tag 式多选」。value 变为 Dayjs[]，设置 multiple 后 needConfirm 默认为 false（失去焦点即提交）；同时该模式下不支持 showTime。tagRender（6.4.0）可自定义已选项标签的渲染。
• 预设范围（presets）：为输入框提供一列快捷入口。单日期示例 { label: 'Yesterday', value: dayjs().add(-1, 'd') }；范围选择示例见 demo/preset-ranges.tsx：

const rangePresets: TimeRangePickerProps['presets'] = [
  { label: 'Last 7 Days', value: [dayjs().add(-7, 'd'), dayjs()] },
  { label: 'Last 14 Days', value: [dayjs().add(-14, 'd'), dayjs()] },
];

<RangePicker presets={rangePresets} onChange={onRangeChange} />

自 5.8.0 起 value 支持函数形式，可动态计算「相对当前时刻」的范围，例如 value: () => [dayjs(), dayjs().endOf('day')]，非常适合搭配 showTime 做「此刻至当日结束」这类随时间变化的快捷项。

Semantic DOM：语义化结构与样式定制

classNames / styles 允许针对组件内部语义化节点逐一定制样式或类名（支持传对象或接收 { props } 的函数，以便读取当前 props 决策）。根据 interface.ts 中 DatePickerSemanticType 的定义，可用节点如下：

root  prefix  input  suffix
popup
├── root
├── header
├── body
├── content
├── item
├── footer
└── container

即顶层：选择器根节点、前缀、输入框、后缀图标、弹层；弹层内部细分为页头（header）、主体（body）、内容（content）、单元格（item）、页脚（footer）与容器（container）。示例代码见 demo/_semantic.tsx。这也是 dropdownClassName / popupClassName / popupStyle 等旧属性被废弃后的推荐替代路径：请分别改写到 classNames.popup.root 与 styles.popup.root。

主题变量（Design Token）

DatePicker 的面板、单元格、图标等视觉细节均可通过主题变量（Design Token）做全局或局部调整，例如日期单元格尺寸、选中态颜色、弹层阴影等。仓库通过 <ComponentTokenTable component="DatePicker" /> 自动渲染组件级 Token 表（见原文档「主题变量」章节），具体可定制 Token 会随版本持续扩展，建议以文档站渲染结果为准。若需自定义主题，请参考 定制主题文档。

FAQ 深度问答

1. 指定了 mode 后，点击无法选择年份/月份？

mode 会锁定面板的层级状态。例如指定 mode="date" 后面板始终停留在日期粒度，表头用于切换月份/年份的点击将不再生效。mode 更适合搭配 panelRender 或做纯展示型受控面板，详见常见问答。受控面板场景可参考 mode 演示。

2. 为何选择年份后返回的是日期面板而不是月份面板？

设计如此：用户点击切换年份后，系统会直接进入日期面板而非停留在月份层级。这样用户只需一次点击即可完成「修改年份」这件事——若停留在月份选择界面，用户还需要再点一次进入日期，造成额外操作与记忆负担。

3. 如何换用 Moment.js 等自定义日期库？

DatePicker 的日期引擎被抽象为 GenerateConfig，入口 index.tsx 默认注入 dayjs 实现。换用其他库的完整指南见《使用自定义日期库》。

4. 为什么时间类组件的 locale 设置不生效？

时间类组件的国际化同时依赖组件 locale 与 dayjs locale（月份、星期等文本来自 dayjs）。仅设置 ConfigProvider 而忘记 import 'dayjs/locale/zh-cn'; dayjs.locale('zh-cn') 时，面板文案仍是英文。详细解释见常见问答。

5. 如何修改一周的起始日？

方式一：选用包含正确周起始约定的语言包。方式二：直接修改 dayjs 的 locale：

import dayjs from 'dayjs';
import 'dayjs/locale/zh-cn';
import updateLocale from 'dayjs/plugin/updateLocale';

dayjs.extend(updateLocale);
dayjs.updateLocale('zh-cn', {
  weekStart: 0, // 0 = 周日作为一周第一天
});

6. 使用 panelRender 后，面板无法切换？

panelRender 每次渲染若改变层级结构（例如包裹新的节点），会使原本的 Panel 被当作新节点卸载重建，导致其内部状态（如当前浏览的年月）被重置。解决方式是保持包裹结构稳定，不要在渲染过程中动态增删外层节点。

7. 如何理解「禁用日期 / 时间」的边界？

disabledDate 控制面板中可点选的日期范围，disabledTime 进一步控制具体时刻；配合 showTime.defaultOpenValue 可以控制用户选择某日后默认带入的时分秒。RangePicker 场景还支持基于「已选起点」动态禁用终点（disabledDate 的 info.from、disabledTime 的 info.from）。其背后隐藏了诸多细节（如禁用与面板切换、开区间语义等），欢迎阅读仓库博客《为什么禁用日期这么难？》深入了解设计取舍。

小结

Ant Design DatePicker 的本质是一个「以 dayjs 为默认引擎、由 generatePicker 工厂统一生成」的日期组件家族：通过 picker 属性可在日/周/月/季/年之间切换，配合 RangePicker 覆盖范围选择，multiple、presets、showTime、needConfirm 等特性则让其从「选一天」扩展到「选多天、选区间、带时间、带快捷入口」的完整输入能力。掌握 locale 配置 与 dayjs locale 的同步加载、Semantic DOM 的节点层级以及 formatType 的四种形态，即可在生产项目中完成从基础使用到深度定制的全部工作。