输入类 · TimePicker
时间选择器
用户使用时间选择器可以方便地选择某一符合要求的、格式化的时间点

代码演示

如何引入

基础使用

点击 TimePicker,然后可以在浮层中选择或者输入某一时间。

无限滚动

版本V2.22.0开始,我们将 TimePicker 内的 ScrollItem 的默认模式从 wheel 变更为了 normal, 若想应用回无限滚动的效果,可参考以下示例。

受控组件

当使用 value 而不是 defaultValue 时,作为受控组件使用。value 和 onChange 需要配合使用。

不同的 Format 格式

TimePicker 浮层中的列会随着 format 变化,当略去 format 中的某部分时,浮层中对应的列也会消失。
NOTE: format 遵循 date-fns 的 format 格式。 https://date-fns.org/v2.0.0/docs/format

设置面板头部,底部

禁用时间选择

设置步长

可以使用 hourStep, minuteStep, secondStep 按步长展示可选的时分秒。

12 小时制

12 小时制的时间选择器,默认的 format 为 h:mm:ss a,传入的 format 格式必须在 dateFns 日期格式范围之内。
例如默认的 12 小时制格式串为:a h:mm:ss,如果传入 A h:mm:ss 则会导致无法正确格式化。

时间范围

传入 type="timeRange" 开启时间范围选择。

Range 模式下分别禁用左右面板(disabledTime)

当 type="timeRange" 时,你可以通过 disabledTime(value, panelType) 对左右面板分别应用不同的禁用规则。
  • value:单选模式为 Date;range 模式为 Date[](可能为空/长度为 1/2)
  • panelType:'left' | 'right',分别代表开始/结束面板
下面示例实现:选择开始时间后,右侧结束时间面板会禁用早于开始时间的选项。

自定义触发器

默认情况下我们使用 Input 组件作为 TimePicker 组件的触发器,通过传递 triggerRender 方法你可以自定义这个触发器。

时区设置

Semi 所有关于时区的配置都收敛在 ConfigProvider 中,详细使用可以参考 ConfigProvider

API 参考

参数说明类型默认值版本
autoAdjustOverflow浮层被遮挡时是否自动调整方向booleantrue
autoFocus自动获取焦点booleanfalse
borderless无边框模式 >=2.33.0boolean
className外层样式名string
clearIcon可用于自定义清除按钮, showClear为true时有效ReactNode2.25.0
defaultOpen面板是否默认打开boolean
defaultValue默认时间Date|timeStamp|String(type="timeRange"时为数组)
disabled禁用全部操作booleanfalse
disabledHours禁止选择部分小时选项Function(): number[]
disabledMinutes禁止选择部分分钟选项Function(selectedHour: number): number[]
disabledSeconds禁止选择部分秒选项Function(selectedHour: number, selectedMinute: number): number[]
disabledTime仅在 range 模式生效:根据当前已选 dates 与面板位置返回 disabled 配置,左右面板可分别给出不同规则。回调参数 value:当前已选时间数组(length 0/1/2);panelType:'left' 或 'right'。返回值中存在的字段会覆盖对应的顶层 disabledHours / disabledMinutes / disabledSeconds,未返回的字段则回退到顶层(如需关闭顶层规则,请显式返回空数组的函数)。单选模式下该 prop 被忽略,请直接使用顶层 disabledHours / disabledMinutes / disabledSecondsFunction(value: Date[], panelType: 'left' | 'right'): { disabledHours?: () => number[]; disabledMinutes?: (selectedHour: number) => number[]; disabledSeconds?: (selectedHour: number, selectedMinute: number) => number[] }2.97.0
dropdownMargin浮层算溢出时的增加的冗余值,详见issue#549,作用同 Tooltip marginobject|number2.25.0
focusOnOpen挂载时是否打开面板并focus输入框booleanfalse
format展示的时间格式string"HH:mm:ss"
getPopupContainer指定容器,浮层将会渲染至该元素内,自定义需要设置 position: relative 这会改变浮层 DOM 树位置,但不会改变视图渲染位置。Function(): HTMLElement() => document.body
hideDisabledOptions隐藏禁止选择的选项booleanfalse
hourStep小时选项间隔number1
inputReadOnly设置输入框为只读(避免在移动设备上打开虚拟键盘)booleanfalse
minuteStep分钟选项间隔number1
motion是否展示弹出层动画booleantrue
open面板是否打开的受控属性boolean
panelFooter面板底部 addonReactNode|ReactNode[]|string无
panelHeader面板头部 addonReactNode|ReactNode[]|string无
placeholder没有值的时候显示的内容string"请选择时间"
popupClassName弹出层类名string''
popupStyle弹出层样式对象object-
position浮层位置stringtype="timeRange"时默认为"bottom",type="time"时默认为"bottomLeft"
prefix前缀内容string|ReactNode
preventScroll指示浏览器是否应滚动文档以显示新聚焦的元素,作用于组件内的 focus 方法boolean
rangeSeparator时间范围分隔符string" ~ "
scrollItemProps透传给 scrollItem 的属性,可选值同ScrollList#APIobject
secondStep秒选项间隔number1
showClear是否展示清除按钮booleantrue
stopPropagation是否阻止弹出层上的点击事件冒泡booleantrue2.49.0
size输入框的大小,可选 'default','small','large'string'default'
triggerRender自定义触发器渲染方法({ placeholder: string }) => ReactNode-
type类型"time"|"timeRange""time"
use12Hours使用 12 小时制,为 true 时 format 默认为 h:mm:ss abooleanfalse
value当前时间Date|timeStamp|String(type="timeRange"时为数组)
onBlur失去焦点时的回调(e: domEvent) => void() => {}
onChange时间发生变化的回调Function(time: Date, timeString: string): void (type="timeRange"时入参皆为数组)无
onChangeWithDateFirst设置为 true 时 onChange 的入参顺序为 (Date, string), false 时为 (string, Date)booleantrue2.4.0
onFocus获得焦点时的回调(e: domEvent) => void() => {}
onOpenChange面板打开/关闭时的回调Function(isOpen: boolean): void无

Methods

绑定在组件实例上的方法,可以通过 ref 调用实现某些特殊交互
名称描述
blur()移除焦点
focus()获取焦点

文案规范

  • 时间选择器至少包括时和分,如:11:30,它在本地化过程中,可以适应为12小时制或者24小时制
  • 当选择12小时制,需要和AM/PM一起搭配使用

设计变量