时间选择器 TimePicker

在弹出面板上选择时间，以便捷完成时间输入的控件。

安装

npm install @arco-design/web-react@2.66.18

在入口引入 @arco-design/web-react/dist/css/arco.css，用 ConfigProvider 设置语言。React 19 项目还需在入口最先引入 @arco-design/web-react/es/_util/react-19-adapter，否则 Message、Modal 等命令式 API 无法渲染。

示例

基础用法：时间输入器的基础用法。
不同状态：不同状态的时间输入器
受控组件：value 和 onChange 需要配合使用。
带有前缀：通过 prefix 属性设置前缀
尺寸：有四种尺寸可供选择。
禁用：禁用状态。
定制时分：通过设置 format，可以定制需要显示的时、分、秒。
定制步长：通过设置 step，可以定制需要显示的时、分、秒的步长。
默认值：时间输入器的有默认值的情况。
附加内容：选择框底部显示自定义的内容。
禁用部分时间选项：通过设置 disabledHours disabledMinutes disabledSeconds，可以禁用时 / 分 / 秒的部分选项。
十二小时制：通过设置 use12Hours，可以定制需要显示的时、分、秒。
范围选择器：时间输入器的范围选择器。
禁用确认：跳过确认步骤，直接点击选择时间。
UTC 时间：通过 utcOffset 字段设置 UTC 时间。 注意：使用 UTC 或者时区时间，传值的时候要用 timestamp 或者 Date 对象，使用字符串不能表示唯一时间，会造成困扰。
时区：通过 timezone 字段设置时区，如果设置了 utcOffset，以 utcOffset 为准。 注意：使用 UTC 或者时区时间，传值的时候要用 timestamp 或者 Date 对象，使用字符串不能表示唯一时间，会造成困扰。

示例来自 Arco Design 官方仓库（MIT），固定在 npm 2.66.18 对应的提交；部分示例使用在线图片或上传地址，预览中网络请求被禁用。

API

Picker

TimePicker 和 RangePicker 的通用属性

参数名	描述	类型	默认值	版本
allowClear	允许清除	boolean	`true`	-
disableConfirm	禁用确认步骤，开启后直接点选时间不需要点击确认按钮。	boolean	`-`	2.12.0
disabled	是否禁用	boolean	`-`	-
editable	是否可手动输入	boolean	`true`	-
error	是否是错误状态。(废弃，下个大版本移除，使用 status='error' 替代)	boolean	`-`	-
hideDisabledOptions	隐藏禁止选择的选项	boolean	`-`	-
popupVisible	控制弹出框打开或者关闭	boolean	`-`	-
scrollSticky	时间列在滚动的时候自动吸附和选中	boolean	`true`	2.23.0
unmountOnExit	是否在关闭后销毁 dom 结构	boolean	`-`	-
use12Hours	12 小时制	boolean	`-`	-
utcOffset	设置时区偏移，如果需要 utc 时间则设置为 0。	number	`-`	-
format	展示日期的格式，参考dayjs	string	`HH:mm:ss`	-
timezone	设置时区, 如果设置了 `utcOffset`，则以 `utcOffset` 为准。	string	`-`	-
position	弹出的框的位置	'top' \| 'tl' \| 'tr' \| 'bottom' \| 'bl' \| 'br'	`bl`	-
size	输入框尺寸	'mini' \| 'small' \| 'default' \| 'large'	`-`	-
status	状态	'error' \| 'warning'	`-`	2.45.0
extra	底部附加内容	ReactNode	`-`	-
prefix	前缀	ReactNode	`-`	2.43.0
triggerElement	触发元素。	ReactNode	`-`	2.38.0
className	节点类名	string \| string[]	`-`	-
icons	用于配置图标	{ inputSuffix?: ReactNode }	`-`	-
placeholder	提示文案	string \| string[]	`-`	-
step	设置时 / 分 / 秒的选择间隔	{ hour?: number; minute?: number; second?: number }	`-`	-
style	节点样式	CSSProperties	`-`	-
triggerProps	可以传入 `Trigger` 组件的参数	Partial<TriggerProps>	`-`	-
disabledHours	禁用的部分小时选项	() => number[]	`-`	-
disabledMinutes	禁用的部分分钟选项	(selectedHour) => number[]	`-`	-
disabledSeconds	禁用的部分秒数选项	(selectedHour, selectedMinute) => number[]	`-`	-
getPopupContainer	弹出框挂载的父节点	(node: HTMLElement) => Element	`-`	-
onClear	点击清除按钮的回调	() => void	`-`	-

TimePicker

参数名	描述	类型	默认值	版本
showNowBtn	是否显示选择当前时间的按钮	boolean	`true`	2.21.0
defaultValue	默认时间	CalendarValue	`-`	-
value	组件的值，受控模式	CalendarValue	`-`	-
onChange	选择时间时的回调	(valueString: string, value: Dayjs) => void	`-`	-
onSelect	组件值发生改变时的回调	(valueString: string, value: Dayjs) => void	`-`	-

TimePicker.RangePicker

参数名	描述	类型	默认值	版本
order	起止时间是否自动排序	boolean	`true`	2.21.0
defaultValue	默认时间	CalendarValue[]	`-`	-
placeholder	提示文案	string[]	`-`	-
value	日历组件的值	CalendarValue[]	`-`	-
onChange	日历组件值发生改变时的回调	(valueString: string[], value: Dayjs[]) => void	`-`	-
onSelect	选择日期时的回调	(valueString: string[], value: Dayjs[]) => void	`-`	-

CalendarValue

export type CalendarValue = Dayjs | Date | string | number;