# date-picker-pro (w-date-picker-pro)

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

## API

## API

### 属性

| 参数                  | 说明                                                                                           | 类型                                                                                                                                                            | 默认值                  | Version |
| --------------------- | ---------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | ------- |
| model-value / v-model | 绑定值，如果它是数组，长度应该是 2                                                             | ^[number] / ^[string] / ^[Date] / ^[array]`number[] \| string[] \| Date[]`                                                                                      | ''                      |
| type                  | 显示类型                                                                                       | ^[enum]`'year' \| 'years' \| 'month' \| 'months' \| 'date' \| 'dates' \| 'week' \| 'datetime' \| 'datetimerange' \| 'daterange' \| 'monthrange' \| 'yearrange'` | date                    |
| readonly              | 只读                                                                                           | ^[boolean]                                                                                                                                                      | false                   |
| disabled              | 禁用                                                                                           | ^[boolean]                                                                                                                                                      | false                   |
| size                  | 输入框尺寸                                                                                     | ^[enum]`'' \| 'large' \| 'default' \| 'mini' \| 'small'`                                                                                                        | —                       |
| editable              | 文本框可输入                                                                                   | ^[boolean]                                                                                                                                                      | true                    |
| clearable             | 是否显示清除按钮                                                                               | ^[boolean]                                                                                                                                                      | true                    |
| placeholder           | 非范围选择时的占位内容                                                                         | ^[string]                                                                                                                                                       | ''                      |
| start-placeholder     | 范围选择时开始日期的占位内容                                                                   | ^[string]                                                                                                                                                       | —                       |
| end-placeholder       | 范围选择时结束日期的占位内容                                                                   | ^[string]                                                                                                                                                       | —                       |
| format                | 输入框显示格式                                                                                 | 参见 [格式与绑定值](#格式与绑定值)                                                                                                                              | `YYYY-MM-DD`（按 type） |
| value-format          | 绑定值格式；不指定则为 `Date`                                                                  | 参见 [格式与绑定值](#格式与绑定值)                                                                                                                              | —                       |
| date-format           | 面板内日期展示格式                                                                             | ^[string]                                                                                                                                                       | —                       |
| time-format           | 面板内时间展示格式（`datetime` / `datetimerange`）                                             | ^[string]                                                                                                                                                       | —                       |
| default-value         | 打开面板时默认展示的日期                                                                       | ^[object]`Date \| [Date, Date]`                                                                                                                                 | —                       |
| default-time          | 范围选中日期使用的当日内时刻（`datetimerange` 等）                                             | ^[object]`Date \| [Date, Date]`                                                                                                                                 | —                       |
| range-separator       | 范围分隔符                                                                                     | ^[string]                                                                                                                                                       | `-`                     |
| calendar-range        | **Pro** 面板年份窗口 `[startYear, endYear]`                                                    | ^[array]`[number, number]`                                                                                                                                      | 当前年 ±10              |
| persistent            | **Pro** 关闭后是否保留下拉 DOM；默认销毁以优化性能                                             | ^[boolean]                                                                                                                                                      | false                   |
| manual-input          | **Pro** 是否启用智能分块手动录入                                                               | ^[boolean]                                                                                                                                                      | true                    |
| automatic-dropdown    | 聚焦输入框时是否自动展开面板                                                                   | ^[boolean]                                                                                                                                                      | true                    |
| prefix-icon           | 自定义前缀图标；未设置时不显示                                                                 | ^[string] / ^[object]`Component`                                                                                                                                | —                       |
| suffix-icon           | 自定义后缀图标；未设置时默认为日历/时钟图标                                                    | ^[string] / ^[object]`Component`                                                                                                                                | —                       |
| clear-icon            | 自定义清除图标                                                                                 | ^[string] / ^[object]`Component`                                                                                                                                | `CircleCloseFilled`     |
| disabled-date         | 判断日期是否禁用                                                                               | ^[Function]`(date: Date) => boolean`                                                                                                                            | —                       |
| disabled-hours        | 禁用小时（`datetime` / `datetimerange`）                                                       | ^[Function]`(role, comparingDate?) => number[]`                                                                                                                 | —                       |
| disabled-minutes      | 禁用分钟（`datetime` / `datetimerange`）                                                       | ^[Function]`(hour, role, comparingDate?) => number[]`                                                                                                           | —                       |
| disabled-seconds      | 禁用秒（`datetime` / `datetimerange`）                                                         | ^[Function]`(hour, minute, role, comparingDate?) => number[]`                                                                                                   | —                       |
| shortcuts             | 快捷选项                                                                                       | ^[array]`Array`                                                                                                                                                 | `[]`                    |
| cell-class-name       | 单元格自定义类名                                                                               | ^[Function]`(data: Date) => string`                                                                                                                             | —                       |
| arrow-control         | 时间列是否使用箭头切换（含时刻的类型）                                                         | ^[boolean]                                                                                                                                                      | false                   |
| show-week-number      | 是否显示周数                                                                                   | ^[boolean]                                                                                                                                                      | false                   |
| show-footer           | 是否显示面板页脚                                                                               | ^[boolean]                                                                                                                                                      | true                    |
| show-confirm          | 是否显示确定按钮                                                                               | ^[boolean]                                                                                                                                                      | true                    |
| show-now              | 是否显示「此刻」按钮（含时刻的类型）                                                           | ^[boolean]                                                                                                                                                      | true                    |
| popper-class          | 下拉层类名                                                                                     | ^[string]                                                                                                                                                       | —                       |
| popper-style          | 下拉层样式                                                                                     | ^[object]`CSSProperties`                                                                                                                                        | —                       |
| popper-options        | [popper.js](https://popper.js.org/docs/v2/) 配置                                               | ^[object]`Partial`                                                                                                                                              | `{}`                    |
| teleported            | 是否使用 teleport；为 `true` 时下拉层挂载到 `append-to` 指定位置                               | ^[boolean]                                                                                                                                                      | true                    |
| append-to             | 下拉层挂载到哪个 DOM 元素                                                                      | ^[string]                                                                                                                                                       | —                       |
| placement             | 下拉层位置                                                                                     | `Placement`                                                                                                                                                     | `bottom-start`          |
| fallback-placements   | 下拉层备选位置                                                                                 | ^[array]`Placement[]`                                                                                                                                           | 见 popper 默认          |
| id                    | 原生 `id`                                                                                      | ^[string] / ^[array]`[string, string]`                                                                                                                          | —                       |
| name                  | 原生 `name`                                                                                    | ^[string] / ^[array]`[string, string]`                                                                                                                          | —                       |
| tabindex              | 输入框 `tabindex`                                                                              | ^[string] / ^[number]                                                                                                                                           | `0`                     |
| aria-label            | 无障碍标签                                                                                     | ^[string]                                                                                                                                                       | —                       |
| validate-event        | 是否触发表单校验                                                                               | ^[boolean]                                                                                                                                                      | true                    |
| 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]                                                                                                                | —                       |
| trigger-suffix        | 仅点击后缀图标时打开面板                                                                       | ^[boolean]                                                                                                                                                      | false                   | V0.0.8  |
| plain                 | 朴素样式                                                                                       | ^[boolean]                                                                                                                                                      | false                   | V0.0.8  |
| emit-formatted-value  | `change` 是否返回格式化字符串                                                                  | ^[boolean]                                                                                                                                                      | false                   | V0.0.8  |

### 事件

| 事件名          | 说明                                        | 类型                                                                                      |
| --------------- | ------------------------------------------- | ----------------------------------------------------------------------------------------- |
| change          | 用户确认选定的值时触发                      | ^[Function]`(val: typeof v-model) => void`                                                |
| blur            | 在组件 Input 失去焦点时触发                 | ^[Function]`(e: FocusEvent) => void`                                                      |
| focus           | 在组件 Input 获得焦点时触发                 | ^[Function]`(e: FocusEvent) => void`                                                      |
| clear           | 可清空的模式下用户点击清空按钮时触发        | ^[Function]`() => void`                                                                   |
| calendar-change | 在日历所选日期更改时触发                    | ^[Function]`(val: [Date, null \| Date]) => void`                                          |
| panel-change    | 当日期面板改变时触发。                      | ^[Function]`(date: Date \| [Date, Date], mode: 'month' \| 'year', view?: string) => void` |
| visible-change  | 当 DatePicker Pro 的下拉列表出现/消失时触发 | ^[Function]`(visibility: boolean) => void`                                                |

### 插槽

Pro 版**不支持**经典版 `prev-month` / `next-month` / `prev-year` / `next-year` 面板导航插槽；面板导航使用内置图标。输入框图标请用 `prefix-icon`、`suffix-icon`。

| 名称            | 说明                 |
| --------------- | -------------------- |
| default         | 自定义单元格内容     |
| range-separator | 自定义范围分割符内容 |
| sidebar         | 侧边栏快捷选项区域   |

### 暴露

| 方法名      | 说明               | 类型                    |
| ----------- | ------------------ | ----------------------- |
| focus       | 使组件获取焦点     | ^[Function]`() => void` |
| blur        | 使组件失去焦点     | ^[Function]`() => void` |
| handleOpen  | 打开日期选择器弹窗 | ^[Function]`() => void` |
| handleClose | 关闭日期选择器弹窗 | ^[Function]`() => void` |
