输入类 · DatePicker
日期选择器
日期选择器用于帮助用户选择一个符合要求的、格式化的日期(时间)或日期(时间)范围

代码演示

如何引入

基本使用

小尺寸

使用 density 可以控制日期面板的尺寸,compact 为小尺寸,default 为默认尺寸。v1.17.0 后支持。

带内嵌标签

多个日期选择

multiple 设为 true,可以多选日期

日期与时间选择

type 设定为 dateTime,可以选择日期时间。
同时,如果希望去掉 TimePicker 的无限循环滚动交互,可以通过 timePickerOpts 传入特定配置关闭。

日期范围选择

type 设定为 dateRange,可以选择日期范围
注意事项
type=dateRange 或 dateTimeRange 时,只有开始日期和结束日期都被选择后才会触发 onChange。

日期范围时间选择

type 设定为 dateTimeRange, 可以选择日期时间范围
当未传入 defaultValue 或 value时,底部面板默认时间为当前时间。如果你有特殊需求(如指定默认时分秒),可以通过 defaultPickerValue 指定

内嵌输入框

使用 insetInput 可以控制日期面板是否展示内嵌输入框,默认为 false。v2.7.0 后支持。内嵌输入框适用于以下场景:
  • 日期时间选择,可以直接通过内嵌输入框单独修改时间,无须通过滚轮选择时间
  • 自定义触发器时 + 范围选择,使用内嵌输入框可以单独对开始和结束日期进行修改
insetInput 开启后包括以下功能:
  • 点击触发器后,面板默认在原有位置弹出。你可以通过 position 自定义弹出位置
  • 点击内嵌日期输入框,面板切换到日期选择;点击内嵌时间输入框,面板切换到时间选择
  • 和外部的输入框一致,如果输入了非法日期,面板关闭后日期会回到之前的合法日期
注意事项
注意,开启后会对组件做一些调整和限制:
1. 触发器样式:未打开面板时触发器只读,打开时触发器禁用
2. 面板样式:type 包括 time 时,隐藏底部的切换按钮
3. 开启 insetInput 后 format 只支持 `dateFormat[ timeFormat]` 格式,使用其他格式会影响内嵌输入框 placeholder 和触发器文本的展示

同步切换双面板月份

version: >= 1.28.0
在范围选择的场景中, 开启 syncSwitchMonth 则允许双面板同步切换。默认为 false。
Note:点击年份按钮也会同步切换两个面板,从滚轮里面切换年月不会同步切换面板,这保证了用户选择非固定间隔月份的能力。

切换面板日期的回调

版本:>=1.28.0
onPanelChange 回调函数会在面板的月份或年份切换改变时被调用。

周选择

dateRange 搭配 startDateOffset 和 endDateOffset 可以进行单击范围选择,如周选择、双周选择。v1.10.0 后支持。

年月选择

版本: >= 0.21.0
type 设定为 month,可以进行年月选择。

确认日期时间选择

版本: >= 0.18.0
对于“日期时间”(type="dateTime")或“日期时间范围”(type="dateTimeRange")的选择,可以进行确认后才将值写入输入框内,你可以通过传递 needConfirm=true 来开启这种行为。
同时支持 “确认”(onConfirm) 和 “取消”(onCancel) 两个按钮的点击回调。
下面这个例子绑定了 onChange、onConfirm、onCancel 三种回调,你可以打开控制台查看打印信息的区别。
注意:开启确认选择时,需要点击取消按钮关闭面板,点击空白区域不再关闭面板(v2.2.0)

带有快捷方式的日期时间选择

通过 presets 设定快捷日期选择

渲染顶部/底部额外区域

通过 topSlotbottomSlot 可以自定义渲染顶部和底部额外区域。

禁用日期选择

禁用部分日期或时间

传入 disabledDate 可以禁用指定日期,传入 disabledTime 可以禁用指定时间,配合 defaultPickerValue 可以指定面板打开时所处的年月。
disabledDatedisabledTime,接受的入参都为当前日期,前者返回一个 boolean 值,后者返回一个对象,将会透传给 TimePicker 组件。
注意事项
当你使用 timeZone 时,第一个参数为你选择的时区下时间(与onChange的第一个返回值类似)
在 type 包含 range 时,可以根据当前选择动态禁止日期。options 参数 1.9.0 后支持。

自定义显示格式

可以通过 format 自定义显示格式

自定义触发器

版本:>=0.34.0
默认情况下我们使用 Input 组件作为 DatePicker 组件的触发器,通过传递 triggerRender 方法你可以自定义这个触发器。
自定义触发器是对触发器的完全自定义,默认的清除按钮将不生效,如果你需要清除功能,请自定义一个清除按钮。
注意事项
范围选择时,面板打开后默认选择的日期为开始日期,选择后会切到结束日期选择。面板关闭后焦点会重置。
我们建议提供一个清除按钮,当你给 DatePicker 传入空值时,DatePicker 内部也会重置焦点。这样用户可以在清除后重新选择日期范围。(from v2.15)

自定义日期显示内容

版本:>=1.4.0
renderDate: (dayNumber: number, fullDate: string) => ReactNode,自定义日期内容。
  • dayNumber:当前日。如 13
  • fullDate:当前日的完整日期。如 2020-08-13

自定义日期格子渲染

版本:>=1.4.0
renderFullDate: (dayNumber: number, fullDate: string, dayStatus: object) => ReactNode, 自定义日期格子的渲染内容。
dayStatus 表示当前格子的状态,包括的 key 有:

API 参考

属性说明类型默认值版本
autoAdjustOverflow浮层被遮挡时是否自动调整方向booleantrue0.34.0
autoFocus自动获取焦点booleanfalse1.10.0
autoSwitchDate通过面板上方左右按钮、下拉菜单更改年月时,自动切换日期。仅对 date type 生效。booleantrue1.13.0
bottomSlot渲染底部额外区域ReactNode1.22.0
className类名string-
defaultOpen面板默认显示或隐藏booleanfalse
defaultPickerValue默认面板日期ValueType
defaultValue默认值ValueType
density面板的尺寸,可选值:default, compactstringdefault1.17.0
disabled是否禁用booleanfalse
disabledDate日期禁止判断方法,返回为 true 时禁止该日期,options 参数 1.9.0 后支持,rangeEnd 1.29 后支持(date: Date, options: { rangeStart: string, rangeEnd: string }) => boolean() => false
disabledTime时间禁止配置,返回值将会作为参数透传给 TimePicker(date: Date | Date[], panelType?: string) => ({
disabledHours:() => number[],
disabledMinutes: (hour: number) => number[],
disabledSeconds: (hour: number, minute: number) => number[] })
() => false0.36.0
disabledTimePicker是否禁止时间选择boolean0.32.0
dropdownClassName下拉列表的 CSS 类名string1.13.0
dropdownStyle下拉列表的内联样式object1.13.0
endDateOffsettype 为 dateRange 时,设置单击选择范围的结束日期(selectedDate?: Date) => Date;-1.10.0
format在输入框内展现的日期串格式string与 type 对应:详见日期时间格式
getPopupContainer指定父级 DOM,弹层将会渲染至该 DOM 中,自定义需要设置 position: relativefunction():HTMLElement() => document.body
hideDisabledOptions隐藏禁止选择的时间booleanfalse
insetInput面板中是否嵌入输入框booleanfalse
inputReadOnly文本框是否 readonlybooleanfalse
inputStyle输入框样式object
insetLabel前缀标签,优先级低于 prefixstring|ReactNode
maxmultiple 为 true 时,多选的数目,不传或者值为 null|undefined 的话无限制number-
motion是否开启面板展开的动画booleantrue
multiple是否可以选择多个,仅支持 type="date"booleanfalse
needConfirm是否需要“确认选择”,仅 type="dateTime"|"dateTimeRange" 时有效boolean0.18.0
open面板显示或隐藏的受控属性boolean
placeholder输入框提示文字string'Select date'
position浮层位置,可选值同Popover#API 参考·position 参数string'bottomLeft'
prefix前缀内容string|ReactNode
presets日期时间快捷方式Array<{start:BaseValueType, end:BaseValueType, text:string}| function():{start:BaseValueType, end:BaseValueType, text:string}>[]
preventScroll指示浏览器是否应滚动文档以显示新聚焦的元素,作用于组件内的 focus 方法boolean
presetPosition日期时间快捷方式面板位置, 可选值'left', 'right', 'top', 'bottom'string'bottom'2.18.0
rangeSeparator自定义范围类型输入框的日期分隔符string'~'1.31.0
renderDate自定义日期显示内容(dayNumber, fullDate) => ReactNode-1.4.0
renderFullDate自定义显示日期格子内容(dayNumber, fullDate, dayStatus) => ReactNode-1.4.0
showClear是否显示清除按钮booleantrue0.35.0
size尺寸,可选值:"small", "default", "large"string'default'
spacing浮层与 trigger 的距离number41.9.0
startDateOffsettype 为 dateRange 时,设置单击选择范围的开始日期(selectedDate?: Date) => Date;-1.10.0
stopPropagation是否阻止弹出层上的点击事件冒泡booleanfalse
style自定义样式CSSProperties
syncSwitchMonth在范围选择的场景中,支持同步切换双面板的月份booleanfalse1.28.0
timePickerOpts其他可以透传给时间选择器的参数,详见 TimePicker·API 参考object1.1.0
topSlot渲染顶部额外区域ReactNode1.22.0
triggerRender自定义触发器渲染方法,第一个参数是个 Object,详情看下方类型定义(props: TriggerRenderProps) => ReactNode-0.34.0
type类型,可选值:"date", "dateRange", "dateTime", "dateTimeRange", "month"string'date'type="month" 需要 0.21.0
validateStatus校验状态,可选值 default、error、warning,默认 default。仅影响展示样式string
value受控的值ValueType
weekStartsOn以周几作为每周第一天,0 代表周日,1 代表周一,以此类推number0
zIndex弹出面板的 zIndexnumber1030
onBlur失去焦点时的回调(e: domEvent) => void() => {}1.0.0
onCancel取消选择时的回调,入参为上次确认选择的值,仅 type="dateTime"|"dateTimeRange" 且 needConfirm=true 时有效。
1.0.0 版本之前为 (dateStr: StringType, date: DateType) => void
(date: DateType, dateStr: StringType) => void0.18.0
onChange值变化时的回调。
1.0.0 版本之前为 (dateStr: StringType, date: DateType) => void
(date: DateType, dateStr: StringType) => void
onChangeWithDateFirst0.x 中 onChange(string, Date), 1.0 后(Date, string)。此开关设为 false 时,入参顺序将与 0.x 版本保持一致booleantrue1.0.0
onClear点击 clear 按钮时触发(e: domEvent) => void() => {}1.16.0
onConfirm确认选择时的回调,入参为当前选择的值,仅 type="dateTime"|"dateTimeRange" 且 needConfirm=true 时有效。
1.0.0 版本之前为 (dateStr: StringType, date: DateType) => void
( date: DateType, dateStr: StringType) => void0.18.0
onFocus获得焦点时的回调(e: domEvent) => void() => {}1.0.0
onOpenChange面板显示或隐藏状态切换的回调(status: boolean) => void
onPanelChange切换面板的年份或者日期时的回调(date: DateType|DateType[], dateStr: StringType|StringType[])=>voidfunction1.28.0
onPresetClick点击快捷选择按钮的回调(item: Object, e: Event) => void() => {}1.24.0

Accessibility

ARIA

  • 未选中日期时,触发器的 aria-labelChoose date,选中日期时,触发器的 aria-labelChange date
  • 日期面板中月的 role 为 grid,周的 role 设置为 row,日期格子设置为 gridcell
  • 日期和时间禁用时对应选项的 aria-disabled 为 true
  • 多选时,月的 aria-multiselectable 为 true,选中时日期格子的 aria-selected 为 true
  • 面板中一些装饰作用的 icon,它们的 aria-hidden 为 true

类型定义

设计变量

日期时间格式

semi-ui 组件库中采用 date-fns(v2.9.0) 作为日期时间引擎,格式化 token 含义如下:
  • "y" :年
  • "M" :月
  • "d" :日
  • "H" :小时
  • "m" :分钟
  • "s" :秒
默认的日期时间会格式化为:
  • "date"(日期):"yyyy-MM-dd"
  • "dateTime"(日期时间):"yyyy-MM-dd HH:mm:ss"
  • "month"(年月):"yyyy-MM"
  • "dateRange"(日期范围):"yyyy-MM-dd ~ yyyy-MM-dd"
  • "dateTimeRange"(日期时间范围):"yyyy-MM-dd HH:mm:ss ~ yyyy-MM-dd HH:mm:ss"
多个日期或时间默认使用 "," (英文逗号)分隔。
更多 token 可以查阅 date-fns 官网

FAQ

  • 日期时间选择器,时分秒选择时不想要无限滚动效果如何实现?
    可以通过 timePickerOpts 中的特定开关控制该行为, timePickerOpts={{ scrollItemProps: { cycled: false } }} ,cycled 设为 false 即可
  • 如何设置面板打开时默认显示的时间?
    可通过 defaultPickerValue 属性。
  • 日期时间选择、范围日期选择,输入部分日期后,面板没有回显日期?
    输入框需要输入完整后才会回显到面板上。比如,日期时间选择,完整要求日期和时间都已输入。范围日期选择,完整要求开始日期和结束日期都已输入。

© 2021 Semi Design. All rights reserved.

京ICP备19058139号-13浙公网安备 33011002016131号

Designed & Developed with love by Douyin FE & MED