# 时间选择器 TimePicker

- 页面: https://jiguang132.com/zh/resources/arco-design/docs/time-picker
- 资源: Arco Design (https://jiguang132.com/zh/resources/arco-design.md)
- 全部指南: https://jiguang132.com/zh/resources/arco-design/docs.md

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

## 安装

```bash
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](https://github.com/iamkun/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](trigger#trigger)> |`-`|-|
|disabledHours|禁用的部分小时选项|() => number[] |`-`|-|
|disabledMinutes|禁用的部分分钟选项|(selectedHour) => number[] |`-`|-|
|disabledSeconds|禁用的部分秒数选项|(selectedHour, selectedMinute) => number[] |`-`|-|
|getPopupContainer|弹出框挂载的父节点|(node: HTMLElement) => Element |`-`|-|
|onClear|点击清除按钮的回调|() => void |`-`|-|

### TimePicker

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

### TimePicker.RangePicker

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

### CalendarValue

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

---

JGuang 全部资源索引: https://jiguang132.com/llms.txt