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

代码演示

如何引入

基础使用

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

无限滚动

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

带内嵌标签

受控组件

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

不同的 Format 格式

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

设置面板头部,底部

禁用时间选择

设置步长

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

12 小时制

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

时间范围

版本: >=0.23.0
传入 type="timeRange" 开启时间范围选择。

自定义触发器

默认情况下我们使用 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[]
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
insetLabel前缀标签,优先级低于 prefixstring|ReactNode
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一起搭配使用

设计变量