- 组件总览
- 通用
- 布局
- 导航
- 数据录入
- 数据展示
- 反馈
- 其他
当用户需要输入一个日期,可以点击标准输入框,弹出日期面板进行选择。
通用属性参考:通用属性
日期类组件包括以下五种形式。
默认配置为 en-US,如果你需要设置其他语言,推荐在入口处使用我们提供的国际化组件,详见:ConfigProvider 国际化。
如有特殊需求(仅修改单一组件的语言),请使用 locale 参数,参考:默认配置。
在搭配 Nextjs 的 App Router 使用时,注意在引入 dayjs 的 locale 文件时加上 'use client'
。
这是由于 Ant Design 的组件都是客户端组件,在 RSC 中引入 dayjs 的 locale 文件将不会在客户端生效。
import locale from 'antd/es/date-picker/locale/zh_CN';import 'dayjs/locale/zh-cn';<DatePicker locale={locale} />;
// 默认语言为 en-US,如果你需要设置其他语言,推荐在入口文件全局设置 localeimport locale from 'antd/locale/zh_CN';import dayjs from 'dayjs';import 'dayjs/locale/zh-cn';<ConfigProvider locale={locale}><DatePicker defaultValue={dayjs('2015-01-01', 'YYYY-MM-DD')} /></ConfigProvider>;
以下 API 为 DatePicker、 RangePicker 共享的 API。
参数 | 说明 | 类型 | 默认值 | 版本 |
---|---|---|---|---|
allowClear | 自定义清除按钮 | boolean | { clearIcon?: ReactNode } | true | 5.8.0: 支持对象类型 |
autoFocus | 自动获取焦点 | boolean | false | |
bordered | 是否有边框 | boolean | true | |
className | 选择器 className | string | - | |
dateRender | 自定义日期单元格的内容,5.4.0 起用 cellRender 代替 | function(currentDate: dayjs, today: dayjs) => React.ReactNode | - | < 5.4.0 |
changeOnBlur | 失去焦点时触发 change 事件,例如 datetime 下不再需要点击确认按钮 | boolean | false | 5.5.0 |
cellRender | 自定义单元格的内容 | (current: dayjs, info: { originNode: React.ReactElement,today: DateType, range?: 'start' | 'end', type: PanelMode, locale?: Locale, subType?: 'hour' | 'minute' | 'second' | 'meridiem' }) => React.ReactNode | - | 5.4.0 |
disabled | 禁用 | boolean | false | |
disabledDate | 不可选择的日期 | (currentDate: dayjs) => boolean | - | |
format | 设置日期格式,为数组时支持多格式匹配,展示以第一个为准。配置参考 dayjs#format。示例:自定义格式 | formatType | rc-picker | |
popupClassName | 额外的弹出日历 className | string | - | 4.23.0 |
getPopupContainer | 定义浮层的容器,默认为 body 上新建 div | function(trigger) | - | |
inputReadOnly | 设置输入框为只读(避免在移动设备上打开虚拟键盘) | boolean | false | |
locale | 国际化配置 | object | 默认配置 | |
mode | 日期面板的状态(设置后无法选择年份/月份?) | time | date | month | year | decade | - | |
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 | 额外的弹出日历样式 | CSSProperties | {} | |
prevIcon | 自定义上一个图标 | ReactNode | - | 4.17.0 |
presets | 预设时间范围快捷选择, 自 5.8.0 起 value 支持函数返回值 | { label: React.ReactNode, value: Dayjs | (() => Dayjs) }[] | - | |
size | 输入框大小,large 高度为 40px,small 为 24px,默认是 32px | large | middle | small | - | |
status | 设置校验状态 | 'error' | 'warning' | - | 4.19.0 |
style | 自定义输入框样式 | CSSProperties | {} | |
suffixIcon | 自定义的选择框后缀图标 | ReactNode | - | |
superNextIcon | 自定义 >> 切换图标 | ReactNode | - | 4.17.0 |
superPrevIcon | 自定义 << 切换图标 | ReactNode | - | 4.17.0 |
onOpenChange | 弹出日历和关闭日历的回调 | function(open) | - | |
onPanelChange | 日历面板切换的回调 | function(value, mode) | - |
名称 | 描述 | 版本 |
---|---|---|
blur() | 移除焦点 | |
focus() | 获取焦点 |
参数 | 说明 | 类型 | 默认值 | 版本 |
---|---|---|---|---|
defaultValue | 默认日期,如果开始时间或结束时间为 null 或者 undefined ,日期范围将是一个开区间 | dayjs | - | |
disabledTime | 不可选择的时间 | function(date) | - | |
format | 展示的日期格式,配置参考 dayjs#format。 | formatType | YYYY-MM-DD | |
renderExtraFooter | 在面板中添加额外的页脚 | (mode) => React.ReactNode | - | |
showNow | 当设定了 showTime 的时候,面板是否显示“此刻”按钮 | boolean | - | 4.4.0 |
showTime | 增加时间选择功能 | Object | boolean | TimePicker Options | |
showTime.defaultValue | 设置用户选择日期时默认的时分秒,例子 | dayjs | dayjs() | |
showToday | 是否展示“今天”按钮 | boolean | true | |
value | 日期 | dayjs | - | |
onChange | 时间发生变化的回调 | function(date: dayjs, dateString: string) | - | |
onOk | 点击确定按钮的回调 | function() | - | |
onPanelChange | 日期面板变化时的回调 | function(value, mode) | - |
参数 | 说明 | 类型 | 默认值 | 版本 |
---|---|---|---|---|
defaultValue | 默认日期 | dayjs | - | |
format | 展示的日期格式,配置参考 dayjs#format。 | formatType | YYYY | |
renderExtraFooter | 在面板中添加额外的页脚 | () => React.ReactNode | - | |
value | 日期 | dayjs | - | |
onChange | 时间发生变化的回调,发生在用户选择时间时 | function(date: dayjs, dateString: string) | - |
4.1.0
新增。
参数 | 说明 | 类型 | 默认值 | 版本 |
---|---|---|---|---|
defaultValue | 默认日期 | dayjs | - | |
format | 展示的日期格式,配置参考 dayjs#format。 | formatType | YYYY-\QQ | |
renderExtraFooter | 在面板中添加额外的页脚 | () => React.ReactNode | - | |
value | 日期 | dayjs | - | |
onChange | 时间发生变化的回调,发生在用户选择时间时 | function(date: dayjs, dateString: string) | - |
参数 | 说明 | 类型 | 默认值 | 版本 |
---|---|---|---|---|
defaultValue | 默认日期 | dayjs | - | |
format | 展示的日期格式,配置参考 dayjs#format。 | formatType | YYYY-MM | |
renderExtraFooter | 在面板中添加额外的页脚 | () => React.ReactNode | - | |
value | 日期 | dayjs | - | |
onChange | 时间发生变化的回调,发生在用户选择时间时 | function(date: dayjs, dateString: string) | - |
参数 | 说明 | 类型 | 默认值 | 版本 |
---|---|---|---|---|
defaultValue | 默认日期 | dayjs | - | |
format | 展示的日期格式,配置参考 dayjs#format。 | formatType | YYYY-wo | |
renderExtraFooter | 在面板中添加额外的页脚 | (mode) => React.ReactNode | - | |
value | 日期 | dayjs | - | |
onChange | 时间发生变化的回调,发生在用户选择时间时 | function(date: dayjs, dateString: string) | - |
参数 | 说明 | 类型 | 默认值 | 版本 |
---|---|---|---|---|
allowEmpty | 允许起始项部分为空 | [boolean, boolean] | [false, false] | |
dateRender | 自定义日期单元格的内容,5.4.0 起用 cellRender 代替 | function(currentDate: dayjs, today: dayjs) => React.ReactNode | - | < 5.4.0 |
cellRender | 自定义单元格的内容。 | (current: dayjs, info: { originNode: React.ReactElement,today: DateType, range?: 'start' | 'end', type: PanelMode, locale?: Locale, subType?: 'hour' | 'minute' | 'second' | 'meridiem' }) => React.ReactNode | - | 5.4.0 |
defaultValue | 默认日期 | dayjs[] | - | |
disabled | 禁用起始项 | [boolean, boolean] | - | |
disabledTime | 不可选择的时间 | function(date: dayjs, partial: start | end ) | - | |
format | 展示的日期格式,配置参考 dayjs#format。 | formatType | YYYY-MM-DD HH:mm:ss | |
presets | 预设时间范围快捷选择,自 5.8.0 起 value 支持函数返回值 | { label: React.ReactNode, value: (Dayjs | (() => Dayjs))[] }[] | - | |
renderExtraFooter | 在面板中添加额外的页脚 | () => React.ReactNode | - | |
separator | 设置分隔符 | React.ReactNode | <SwapRightOutlined /> | |
showTime | 增加时间选择功能 | Object|boolean | TimePicker Options | |
showTime.defaultValue | 设置用户选择日期时默认的时分秒,例子 | dayjs[] | [dayjs(), dayjs()] | |
value | 日期 | dayjs[] | - | |
onCalendarChange | 待选日期发生变化的回调。info 参数自 4.4.0 添加 | function(dates: [dayjs, dayjs], dateStrings: [string, string], info: { range:start |end }) | - | |
onChange | 日期范围发生变化的回调 | function(dates: [dayjs, dayjs], dateStrings: [string, string]) | - |
import type { Dayjs } from 'dayjs';type Generic = string;type GenericFn = (value: Dayjs) => string;export type FormatType = Generic | GenericFn | Array<Generic | GenericFn>;
Token 名称 | 描述 | 类型 | 默认值 |
---|---|---|---|
activeBg | 输入框激活状态时背景颜色 | string | |
activeBorderColor | 激活态边框色 | string | #1677ff |
activeShadow | 激活态阴影 | string | 0 0 0 2px rgba(5, 145, 255, 0.1) |
addonBg | 前/后置标签背景色 | string | rgba(0, 0, 0, 0.02) |
cellActiveWithRangeBg | 选取范围内的单元格背景色 | string | #e6f4ff |
cellBgDisabled | 单元格禁用态背景色 | string | rgba(0, 0, 0, 0.04) |
cellHeight | 单元格高度 | number | 24 |
cellHoverBg | 单元格悬浮态背景色 | string | rgba(0, 0, 0, 0.04) |
cellHoverWithRangeBg | 选取范围内的单元格悬浮态背景色 | string | #c8dfff |
cellRangeBorderColor | 选取范围时单元格边框色 | string | #7cb3ff |
cellWidth | 单元格宽度 | number | 36 |
errorActiveShadow | 错误状态时激活态阴影 | string | 0 0 0 2px rgba(255, 38, 5, 0.06) |
hoverBg | 输入框hover状态时背景颜色 | string | |
hoverBorderColor | 悬浮态边框色 | string | #4096ff |
paddingBlock | 输入框纵向内边距 | number | 4 |
paddingBlockLG | 大号输入框纵向内边距 | number | 7 |
paddingBlockSM | 小号输入框纵向内边距 | number | 0 |
paddingInline | 输入框横向内边距 | number | 11 |
paddingInlineLG | 大号输入框横向内边距 | number | 11 |
paddingInlineSM | 小号输入框横向内边距 | number | 7 |
presetsMaxWidth | 预设区域最大宽度 | number | 200 |
presetsWidth | 预设区域宽度 | number | 120 |
textHeight | 单元格文本高度 | number | 40 |
timeCellHeight | 时间单元格高度 | number | 28 |
timeColumnHeight | 时间列高度 | number | 224 |
timeColumnWidth | 时间列宽度 | number | 56 |
warningActiveShadow | 警告状态时激活态阴影 | string | 0 0 0 2px rgba(255, 215, 5, 0.1) |
withoutTimeCellHeight | 十年/年/季/月/周单元格高度 | number | 66 |
zIndexPopup | 弹窗 z-index | number | 1050 |
请参考常见问答
当用户选择完年份后,系统会直接切换至日期面板,而非显式提供月份选择。这样做的设计在于用户只需进行一次点击即可完成年份修改,无需再次点击进入月份选择界面,从而减少了用户的操作负担,同时也避免需要额外感知月份的记忆负担。
请参考《使用自定义日期库》
参考 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。