# date-picker (w-date-picker)

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

## API

## API

### 属性

| 参数                  | 说明                                                                                                              | 类型                                                                                                                                                           | 默认值                            | Version |
| --------------------- | ----------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ------- |
| model-value / v-model | 绑定值，如果它是数组，长度应该是 2                                                                                | ^[number] / ^[string] / ^[Date] / ^[array]`number[] \| string[] \| 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]                                                                                                                                                      | —                                 |
| type                  | 显示类型                                                                                                          | ^[enum]`'year' \| 'years' \|'month' \| 'months' \| 'date' \| 'dates' \| 'datetime' \| 'week' \| 'datetimerange' \| 'daterange' \| 'monthrange' \| 'yearrange'` | date                              |
| format                | 显示在输入框中的格式                                                                                              | 参见 [date formats](/zh-CN/component/date-picker#date-formats)                                                                                                 | YYYY-MM-DD                        |
| popper-class          | DatePicker 下拉框的类名                                                                                           | ^[string]                                                                                                                                                      | —                                 |
| popper-options        | 自定义 popper 选项，更多请参考 [popper.js](https://popper.js.org/docs/v2/)                                        | ^[object]`Partial`                                                                                                                                             | {}                                |
| teleported            | 是否使用 teleport；为 `true` 时下拉层挂载到 `append-to` 指定位置                                                  | ^[boolean]                                                                                                                                                     | true                              |
| append-to             | 下拉层挂载到哪个 DOM 元素                                                                                         | ^[string]                                                                                                                                                      | —                                 |
| range-separator       | 选择范围时的分隔符                                                                                                | ^[string]                                                                                                                                                      | '-'                               |
| default-value         | 可选，选择器打开时默认显示的时间                                                                                  | ^[object]`Date \| [Date, Date]`                                                                                                                                | —                                 |
| default-time          | 范围选择时选中日期所使用的当日内具体时刻                                                                          | ^[object]`Date \| [Date, Date]`                                                                                                                                | —                                 |
| value-format          | 可选，绑定值的格式。 不指定则绑定值为 Date 对象                                                                   | 参见 [格式与绑定值](/zh-CN/component/date-picker#格式与绑定值)                                                                                                 | —                                 |
| id                    | 等价于原生 input `id` 属性                                                                                        | ^[string] / ^[object]`[string, string]`                                                                                                                        | —                                 |
| name                  | 等价于原生 input `name` 属性                                                                                      | ^[string] / ^[object]`[string, string]`                                                                                                                        | ''                                |
| unlink-panels         | 在范围选择器里取消两个日期面板之间的联动                                                                          | ^[boolean]                                                                                                                                                     | false                             |
| prefix-icon           | 自定义前缀图标；未设置时不显示                                                                                    | ^[string] / ^[object]`Component`                                                                                                                               | ''                                |
| suffix-icon           | 自定义后缀图标；未设置时默认为日历/时钟图标                                                                       | ^[string] / ^[object]`Component`                                                                                                                               | ''                                |
| clear-icon            | 自定义清除图标                                                                                                    | ^[string] / ^[object]`Component`                                                                                                                               | `CircleCloseFilled`               |
| validate-event        | 是否触发表单验证                                                                                                  | ^[boolean]                                                                                                                                                     | true                              |
| disabled-date         | 一个用来判断该日期是否被禁用的函数，接受一个 Date 对象作为参数。 应该返回一个 Boolean 值。                        | ^[Function]`(data: Date) => boolean`                                                                                                                           | —                                 |
| shortcuts             | 设置快捷选项，需要传入数组对象                                                                                    | ^[object]`Array`                                                                                                                                               | []                                |
| cell-class-name       | 设置自定义类名                                                                                                    | ^[Function]`(data: Date) => string`                                                                                                                            | —                                 |
| 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]                                                                                                               | —                                 |
| fallback-placements   | Tooltip 可用的 positions 请查看[popper.js 文档](https://popper.js.org/docs/v2/modifiers/flip/#fallbackplacements) | ^[array]`Placement[]`                                                                                                                                          | `['bottom','top','right','left']` |
| placement             | 下拉框出现的位置                                                                                                  | `Placement`                                                                                                                                                    | bottom-start                      |
| trigger-suffix        | 点击后缀图标触发下拉框                                                                                            | ^[boolean]                                                                                                                                                     | false                             | V0.0.8  |
| plain                 | 朴素的 DatePicker                                                                                                 | ^[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 的下拉列表出现/消失时触发 | ^[Function]`(visibility: boolean) => void`                                                |

### 插槽

| 名称            | 说明                 |
| --------------- | -------------------- |
| default         | 自定义单元格内容     |
| range-separator | 自定义范围分割符内容 |

### 暴露

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