# time-picker-pro (w-time-picker-pro)

- **Import**: `WTimePickerPro` from `win-design-next`
- **Tag**: `<w-time-picker-pro>`
- **说明**: Pro 时间选择器
- **分类**: date-time
- **Skill 版本**: V1.1.0
- **适配组件库**: win-design-next 1.2.2
- **API 来源**: `docs/zh-CN/component/time-picker-pro.md`

## API

## API

### Attributes

| 参数                        | 说明                                                                                                | 类型                                                                                            | 默认值            | Version |
| --------------------------- | --------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ----------------- | ------- |
| model-value / v-model       | 绑定值，如果它是数组，长度应该是 2                                                                  | ^[number] / ^[string] / ^[object]`Date \| [Date, Date] \| [number, number] \| [string, string]` | ''                |
| readonly                    | 完全只读                                                                                            | ^[boolean]                                                                                      | false             |
| disabled                    | 禁用                                                                                                | ^[boolean]                                                                                      | false             |
| editable                    | 文本框可输入                                                                                        | ^[boolean]                                                                                      | true              |
| clearable                   | 是否显示清除按钮                                                                                    | ^[boolean]                                                                                      | true              |
| size                        | 输入框尺寸                                                                                          | ^[enum]`'large' \| 'default' \| 'small' \| 'mini'`                                              | —                 |
| placeholder                 | 非范围选择时的占位内容                                                                              | ^[string]                                                                                       | ''                |
| start-placeholder           | 范围选择时开始日期的占位内容                                                                        | ^[string]                                                                                       | —                 |
| end-placeholder             | 范围选择时结束日期的占位内容                                                                        | ^[string]                                                                                       | —                 |
| is-range                    | 是否为时间范围选择                                                                                  | ^[boolean]                                                                                      | false             |
| arrow-control               | 是否使用箭头进行时间选择                                                                            | ^[boolean]                                                                                      | false             |
| popper-class                | TimePicker Pro 下拉框的类名                                                                         | ^[string]                                                                                       | ''                |
| teleported                  | 是否使用 teleport；为 `true` 时下拉层挂载到 `append-to` 指定位置                                    | ^[boolean]                                                                                      | true              |
| append-to                   | 下拉层挂载到哪个 DOM 元素                                                                           | ^[string]                                                                                       | —                 |
| range-separator             | 选择范围时的分隔符                                                                                  | ^[string]                                                                                       | '-'               |
| format                      | 显示在输入框中的格式                                                                                | ^[string] see [date formats](/zh-CN/component/date-picker-pro#格式与绑定值)                     | —                 |
| default-value               | 可选，选择器打开时默认显示的时间                                                                    | ^[Date] / ^[object]`[Date, Date]`                                                               | —                 |
| value-format                | 可选，绑定值的格式。 不指定则绑定值为 Date 对象                                                     | ^[string] 参考 [日期格式](/zh-CN/component/date-picker-pro#格式与绑定值)                        | —                 |
| id                          | 等价于原生 input `id` 属性                                                                          | ^[string] / ^[object]`[string, string]`                                                         | —                 |
| name                        | 等价于原生 input `name` 属性                                                                        | ^[string]                                                                                       | ''                |
| aria-label ^(a11y)          | 等价于原生 input `aria-label` 属性                                                                  | ^[string]                                                                                       | —                 |
| prefix-icon                 | 自定义前缀图标；未设置时不显示                                                                      | ^[string] / ^[Component]                                                                        | ''                |
| suffix-icon                 | 自定义后缀图标；未设置时默认为时钟图标                                                              | ^[string] / ^[Component]                                                                        | ''                |
| clear-icon                  | 自定义清除图标                                                                                      | ^[string] / ^[Component]                                                                        | CircleCloseFilled |
| disabled-hours              | 禁止选择部分小时选项                                                                                | ^[Function]`(role: string, comparingDate?: Dayjs) => number[]`                                  | —                 |
| disabled-minutes            | 禁止选择部分分钟选项                                                                                | ^[Function]`(hour: number, role: string, comparingDate?: Dayjs) => number[]`                    | —                 |
| disabled-seconds            | 禁止选择部分秒选项                                                                                  | ^[Function]`(hour: number, minute: number, role: string, comparingDate?: Dayjs) => number[]`    | —                 |
| automatic-dropdown          | 聚焦时是否自动展开面板                                                                              | ^[boolean]                                                                                      | true              |
| manual-input                | 是否启用智能分块手动录入                                                                            | ^[boolean]                                                                                      | true              |
| save-on-blur                | 无值时失焦是否写入当前时刻；`false` 时取消可恢复                                                    | ^[boolean]                                                                                      | true              |
| persistent                  | 关闭后是否保留下拉 DOM                                                                              | ^[boolean]                                                                                      | true              |
| popper-style                | 下拉层样式                                                                                          | ^[object]`CSSProperties`                                                                        | —                 |
| placement                   | 下拉层位置                                                                                          | `Placement`                                                                                     | `bottom-start`    |
| fallback-placements         | 下拉层备选位置                                                                                      | ^[array]`Placement[]`                                                                           | 见 popper 默认    |
| popper-options              | [popper.js](https://popper.js.org/docs/v2/) 配置                                                    | ^[object]`Partial`                                                                              | `{}`              |
| trigger-suffix              | 仅点击后缀图标打开面板                                                                              | ^[boolean]                                                                                      | false             |
| tabindex                    | 输入框的 tabindex                                                                                   | ^[string] / ^[number]                                                                           | 0                 |
| empty-values                | 组件的空值配置 [参考 config-provider](/zh-CN/component/config-provider#empty-values-configurations) | ^[array]                                                                                        | —                 |
| value-on-clear              | 清空选项的值 [参考 config-provider](/zh-CN/component/config-provider#empty-values-configurations)   | ^[string] / ^[number] / ^[boolean] / ^[Function]                                                | —                 |
| label ^(a11y) ^(deprecated) | 等价于原生 input `aria-label` 属性                                                                  | ^[string]                                                                                       | —                 |
| plain                       | 朴素的 TimePicker Pro                                                                               | ^[boolean]                                                                                      | false             | V0.0.8  |
| emit-formatted-value        | `change` 事件是否附带格式化字符串（第二参数）                                                       | ^[boolean]                                                                                      | false             | V0.0.8  |

### 事件

| 事件名         | 说明                                    | 类型                                                                                                         |
| -------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| change         | 用户确认选定的值时触发                  | ^[Function]`(val: number \| string \| Date \| [number, number] \| [string, string] \| [Date, Date]) => void` |
| blur           | 在组件 Input 失去焦点时触发             | ^[Function]`(e: FocusEvent) => void`                                                                         |
| focus          | 在组件 Input 获得焦点时触发             | ^[Function]`(e: FocusEvent) => void`                                                                         |
| clear          | 可清空的模式下用户点击清空按钮时触发    | ^[Function]`() => void`                                                                                      |
| visible-change | 当 TimePicker 的下拉列表出现/消失时触发 | ^[Function]`(visibility: boolean) => void`                                                                   |

### 暴露

| 名称        | 说明               | Type                    |
| ----------- | ------------------ | ----------------------- |
| focus       | 使组件获取焦点     | ^[Function]`() => void` |
| blur        | 使组件失去焦点     | ^[Function]`() => void` |
| handleOpen  | 打开时间选择器弹窗 | ^[Function]`() => void` |
| handleClose | 关闭时间选择器弹窗 | ^[Function]`() => void` |
