# TimePicker <small>时间选择</small>

## 示例

### 三种模式

支持三种模式，分别是 `hour`、`minute` 和 `second`，可以通过 `mode` 属性来控制。

[[ demo src="/demo/time-picker/mode.vue" ]]

### 定制时间选项

支持定制时间选项，分别可以通过 `hours`、`minutes` 和 `seconds` 来定制对应的时间选项。

[[ demo src="/demo/time-picker/datasource.vue" ]]

### 范围限制

支持范围限制，可以通过 `min` 和 `max` 来分别设置最小值和最大值。

[[ demo src="/demo/time-picker/range.vue" ]]

## API

### 属性

| 名称 | 类型 | 默认值 | 描述 |
| -- | -- | -- | -- |
| `ui` | `string=` | - | [^ui] |
| `mode` | `string` | `'second'` | 指定选择的粒度，分别精确到时（`hour`）、分（`minute`）、秒（`second`）。 |
| `value` | `string` |  | [^prop-value] |
| `placeholder` | `string` | `timepicker.placeholder` | 未选择时的占位文本。 |
| `hours` | `Array<number>` | - | 小时选项，默认 0-23。 |
| `minutes` | `Array<number>` | - | 分钟选项，默认 0-59。 |
| `seconds` | `Array<number>` | - | 秒钟选项，默认 0-59。 |
| `min` | `string` | - | 最小值限制。 |
| `max` | `string` | - | 最大值限制。 |
| `autofocus` | `boolean` | `false` | 是否自动获得焦点。 |
| `clearable` | `boolean` | `false` | 已选值是否可以清除。 |
| `expanded` | `boolean=` | `false` | [^expanded] |
| `disabled` | `boolean=` | `false` | 是否为禁用状态。 |
| `readonly` | `boolean=` | `false` | 是否为只读状态。 |

^^^ui
预设样式。为空格分隔的一组枚举值的组合。

+++枚举值
| 值 | 描述 |
| -- | -- |
| `s` | 小尺寸样式。 |
| `m` | 中尺寸样式。 |
+++
^^^

^^^prop-value
:::badges
`v-model`
:::

当前选中的值。
^^^

^^^expanded
:::badges
`.sync`
:::

下拉浮层是否展开。
^^^

### 插槽

| 名称 | 描述 |
| -- | -- |
| `option` | [^scoped-slot-option] |

^^^scoped-slot-option

下拉面板中的时间选项插槽。

+++作用域参数
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `label` | `string` | 用来显示的文字描述。 |
| `value` | `string` | 实际对应的值。 |
| `disabled` | `boolean=` | 是否禁用。 |
| `part` | `string` | 该选项是哪个部分，分别是 `hour`/`minute`/`second`。 |
+++
^^^

### 事件

| 名称 | 描述 |
| -- | -- |
| `input` | [^event-input] |
| `change` | 若当前选中的值发生变化，在时间选择下拉面板关闭时会触发该事件，参数是当前选中值。 |
| `toggle` | 下拉浮层展开状态切换时触发，回调参数为 `(expanded: boolean)`。`expanded` 表示操作将触发下拉浮层展开还是收起。 |
| `clear` | 清除当前选中的值。 |

^^^event-input
:::badges
`v-model`
:::

当手动输入或下拉面板中选值会触发该事件，参数是当前输入值。
^^^

### 全局配置

| 配置项 | 类型 | 默认值 | 描述 |
| -- | -- | -- | -- |
| `timepicker.placeholder` | `string` | `@@timepickerpicker.placeholder` | 未选择时的占位文本。 |

:::tip
`@@` 开头的值表示引用多语言配置中的相应字段。
:::

### 图标

| 名称 | 描述 |
| -- | -- |
| `clock` | 时钟。 |
| `clear` | 清除内容。 |

