# datetime-picker (w-datetime-picker)

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

## API

## API

### Attributes

| 参数                  | 说明                                                                                                | 类型                                                                                           | 默认值            | Version |
| --------------------- | --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ----------------- | ------- |
| model-value / v-model | 绑定值，如果它是数组，长度应该是 2                                                                  | ^[number] / ^[string] / ^[Date] / ^[array]`number[] \| string[] \| Date[]`                     | —                 |
| readonly              | 只读                                                                                                | ^[boolean]                                                                                     | false             |
| disabled              | 禁用                                                                                                | ^[boolean]                                                                                     | false             |
| editable              | 文本框可输入                                                                                        | ^[boolean]                                                                                     | true              |
| clearable             | 是否显示清除按钮                                                                                    | ^[boolean]                                                                                     | true              |
| size                  | 输入框尺寸                                                                                          | ^[enum]`'large' \| 'default' \| 'mini' \| 'small'`                                             | default           |
| placeholder           | 非范围选择时的占位内容                                                                              | ^[string]                                                                                      | —                 |
| start-placeholder     | 范围选择时开始日期的占位内容                                                                        | ^[string]                                                                                      | —                 |
| end-placeholder       | 范围选择时结束日期的占位内容                                                                        | ^[string]                                                                                      | —                 |
| arrow-control         | 是否使用箭头进行时间选择                                                                            | ^[boolean]                                                                                     | false             |
| type                  | 显示类型                                                                                            | ^[enum]`'year' \| 'month' \| 'date' \| 'datetime' \| 'week' \| 'datetimerange' \| 'daterange'` | date              |
| format                | 显示在输入框中的格式                                                                                | ^[string] 参见 [格式与绑定值](/zh-CN/component/date-picker#格式与绑定值)                       | 按 `type` 默认    |
| popper-class          | DateTimePicker 下拉框的类名                                                                         | ^[string]                                                                                      | —                 |
| teleported            | 是否使用 teleport；为 `true` 时下拉层挂载到 `append-to` 指定位置                                    | ^[boolean]                                                                                     | true              |
| append-to             | 下拉层挂载到哪个 DOM 元素                                                                           | ^[string]                                                                                      | —                 |
| range-separator       | 选择范围时的分隔符                                                                                  | ^[string]                                                                                      | '-'               |
| default-value         | 可选，选择器打开时默认显示的时间                                                                    | ^[object]`Date \| [Date, Date]`                                                                | —                 |
| default-time          | 选择日期后的默认时间值。 如未指定则默认时间值为 `00:00:00`                                          | ^[object]`Date \| [Date, Date]`                                                                | —                 |
| value-format          | 可选，绑定值的格式。 不指定则绑定值为 Date 对象                                                     | ^[string] see [date formats](https://day.js.org/docs/en/display/format)                        | —                 |
| date-format           | 可选，时间选择器下拉列表中显示的日期格式                                                            | ^[string] see [date formats](https://day.js.org/docs/en/display/format)                        | —                 |
| time-format           | 可选，时间选择器下拉列表中显示的时间格式                                                            | ^[string] see [date formats](https://day.js.org/docs/en/display/format)                        | —                 |
| id                    | 等价于原生 input `id` 属性                                                                          | ^[string] / ^[object]`[string, string]`                                                        | —                 |
| name                  | 等价于原生 input `name` 属性                                                                        | ^[string]                                                                                      | —                 |
| unlink-panels         | 在范围选择器里取消两个日期面板之间的联动                                                            | ^[boolean]                                                                                     | false             |
| prefix-icon           | 自定义前缀图标组件                                                                                  | ^[string] / `Component`                                                                        |                   |
| clear-icon            | 自定义清除图标                                                                                      | ^[string] / `Component`                                                                        | CircleCloseFilled |
| shortcuts             | 设置快捷选项，需要传入数组对象                                                                      | ^[object]`Array`                                                                               | —                 |
| disabled-date         | 一个用来判断该日期是否被禁用的函数，接受一个 Date 对象作为参数。 应该返回一个 Boolean 值。          | ^[Function]`(data: Date) => boolean`                                                           | —                 |
| 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]                                               | —                 |
| show-now              | 是否显示 now 按钮                                                                                   | ^[boolean]                                                                                     | true              |
| plain                 | 朴素的 DatePicker                                                                                   | ^[boolean]                                                                                     | false             | V0.0.8  |
| emit-formatted-value  | `change` 事件是否附带格式化字符串（第二参数）                                                       | ^[boolean]                                                                                     | false             | V0.0.8  |

### 事件

| 事件名          | 说明                                                                                                     | 回调参数                      |
| --------------- | -------------------------------------------------------------------------------------------------------- | ----------------------------- |
| change          | 用户确认选定的值时触发                                                                                   | value                         |
| blur            | 在组件 Input 失去焦点时触发                                                                              | `(e: FocusEvent)`             |
| focus           | 在组件 Input 获得焦点时触发                                                                              | `(e: FocusEvent)`             |
| clear           | 可清空的模式下用户点击清空按钮时触发                                                                     | ^[Function]`() => void`       |
| calendar-change | 如果用户没有选择日期，那默认展示当前日的月份。 选中日历日期后会执行的回调，只有当 `datetimerange` 才生效 | [Date, Date]                  |
| visible-change  | 当 DateTimePicker 的下拉列表出现/消失时触发                                                              | 出现时为 true，隐藏时为 false |

### Slots

| 插槽名          | 说明                 |
| --------------- | -------------------- |
| default         | 自定义单元格内容     |
| range-separator | 自定义范围分割符内容 |
| prev-month      | 上个月的图标         |
| next-month      | 下个月的图标         |
| prev-year       | 上一年图标           |
| next-year       | 下一年图标           |

### Exposes

| 方法名 | 说明           | 类型                    |
| ------ | -------------- | ----------------------- |
| focus  | 使组件获取焦点 | ^[Function]`() => void` |
| blur   | 使组件失去焦点 | ^[Function]`() => void` |
