何时使用

当用户需要输入一个日期，可以点击标准输入框，弹出日期面板进行选择。

代码演示

API

通用属性参考：通用属性

日期类组件包括以下五种形式。

• DatePicker
• DatePicker[picker="month"]
• DatePicker[picker="week"]
• DatePicker[picker="year"]
• DatePicker[picker="quarter"] (4.1.0 新增)
• RangePicker

国际化配置

默认配置为 en-US，如果你需要设置其他语言，推荐在入口处使用我们提供的国际化组件，详见：ConfigProvider 国际化。

如有特殊需求（仅修改单一组件的语言），请使用 locale 参数，参考：默认配置。

// 默认语言为 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>;

共同的 API

以下 API 为 DatePicker、 RangePicker 共享的 API。

共同的方法

DatePicker

DatePicker[picker=year]

DatePicker[picker=quarter]

4.1.0 新增。

DatePicker[picker=month]

DatePicker[picker=week]

RangePicker

formatType

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';
    };

注意：type 定义为 5.14.0 新增。

主题变量（Design Token）

FAQ

当我指定了 DatePicker/RangePicker 的 mode 属性后，点击后无法选择年份/月份？

请参考常见问答

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

当用户选择完年份后，系统会直接切换至日期面板，而非显式提供月份选择。这样做的设计在于用户只需进行一次点击即可完成年份修改，无需再次点击进入月份选择界面，从而减少了用户的操作负担，同时也避免需要额外感知月份的记忆负担。

如何在 DatePicker 中使用自定义日期库（如 Moment.js ）？

请参考《使用自定义日期库》

为什么时间类组件的国际化 locale 设置不生效？

参考 FAQ 为什么时间类组件的国际化 locale 设置不生效？。

如何修改周的起始日？

请使用正确的语言包（#5605），或者修改 dayjs 的 locale 配置：https://codesandbox.io/s/dayjs-day-of-week-x9tuj2?file=/demo.tsx

import dayjs from 'dayjs';

import 'dayjs/locale/zh-cn';

import updateLocale from 'dayjs/plugin/updateLocale';

dayjs.extend(updateLocale);
dayjs.updateLocale('zh-cn', {
  weekStart: 0,
});

为何使用 panelRender 时，原来面板无法切换？

当你通过 panelRender 动态改变层级结构时，会使得原本的 Panel 被当做新的节点删除并创建。这使得其原本的状态会被重置，保持结构稳定即可。详情请参考 #27263。

如何理解禁用时间日期？

欢迎阅读博客《为什么禁用日期这么难？》了解如何使用。