DatePicker

何时使用 {#when-to-use}

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

代码演示 {#examples}

<code src="./demo/basic.tsx">基本</code> <code src="./demo/range-picker.tsx">范围选择器</code> <code src="./demo/multiple.tsx" version="5.14.0">多选</code> <code src="./demo/multiple-debug.tsx" debug>多选 Debug</code> <code src="./demo/needConfirm.tsx" version="5.14.0">选择确认</code> <code src="./demo/switchable.tsx">切换不同的选择器</code> <code src="./demo/format.tsx">日期格式</code> <code src="./demo/time.tsx">日期时间选择</code> <code src="./demo/mask.tsx" version="5.14.0">格式对齐</code> <code src="./demo/date-range.tsx" version="5.14.0">日期限定范围</code> <code src="./demo/disabled.tsx">禁用</code> <code src="./demo/disabled-date.tsx">不可选择日期和时间</code> <code src="./demo/allow-empty.tsx">允许留空</code> <code src="./demo/select-in-range.tsx">选择不超过一定的范围</code> <code src="./demo/preset-ranges.tsx">预设范围</code> <code src="./demo/extra-footer.tsx">额外的页脚</code> <code src="./demo/size.tsx">三种大小</code> <code src="./demo/cell-render.tsx">定制单元格</code> <code src="./demo/components.tsx" version="5.14.0">定制面板</code> <code src="./demo/external-panel.tsx">外部使用面板</code> <code src="./demo/buddhist-era.tsx" version="5.14.0">佛历格式</code> <code src="./demo/status.tsx">自定义状态</code> <code src="./demo/variant.tsx" version="5.13.0">形态变体</code> <code src="./demo/style-class.tsx" version="6.0.0">自定义语义结构的样式和类</code> <code src="./demo/filled-debug.tsx" debug>Filled Debug</code> <code src="./demo/placement.tsx">弹出位置</code> <code src="./demo/mode.tsx" debug>受控面板</code> <code src="./demo/start-end.tsx" debug>自定义日期范围选择</code> <code src="./demo/suffix.tsx">前后缀</code> <code src="./demo/render-panel.tsx" debug>_InternalPanelDoNotUseOrYouWillBeFired</code> <code src="./demo/component-token.tsx" debug>组件 Token</code> <code src="./demo/suffixIcon-debug.tsx" debug>suffixIcon</code>

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

:::warning 在搭配 Next.js 的 App Router 使用时，注意在引入 dayjs 的 locale 文件时加上 'use client'。这是由于 Ant Design 的组件都是客户端组件，在 RSC 中引入 dayjs 的 locale 文件将不会在客户端生效。 :::

共同的 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 新增。

Semantic DOM

<code src="./demo/_semantic.tsx" simplify="true"></code>

主题变量（Design Token）{#design-token}

<ComponentTokenTable component="DatePicker"></ComponentTokenTable>

FAQ

当我指定了 DatePicker/RangePicker 的 mode 属性后，点击后无法选择年份/月份？ {#faq-mode-cannot-select}

请参考常见问答

为何日期选择年份后返回的是日期面板而不是月份面板？ {#faq-year-to-date-panel}

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

如何在 DatePicker 中使用自定义日期库（如 Moment.js ）？ {#faq-custom-date-library}

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

为什么时间类组件的国际化 locale 设置不生效？ {#faq-locale-not-work}

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

如何修改周的起始日？ {#faq-week-start-day}

请使用正确的语言包（#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 时，原来面板无法切换？ {#faq-panel-render-switch}

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

如何理解禁用时间日期？ {#faq-disabled-date-time}

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