DatePicker 日期选择器
使用日期选择器来输入日期。
输入日期
以「日」为基本单位的日期选择器。
其他日期单位
通过扩展标准日期选择器组件,您可以选择周、月、年或多个日期。
日期范围
支持选择日期范围。
月份范围
支持选择月份范围。
年份范围 2.8.0
支持选择年份范围。
默认值
如果用户尚未选择日期,则默认显示今天的日历。您可以使用 default-value 来设置另一个日期。它的值应该可以被 new Date() 解析。
如果类型是 daterange,default-value 将设置左侧日历。
日期格式
使用 format 属性可以控制输入框中显示的文本格式。 使用 value-format 属性可以控制绑定值的格式。
默认情况下,该组件接受并返回一个 Date 对象。
点击这里查看 Day.js 中所有可用的格式。
警告
注意大小写
开始日期和结束日期的默认时间
选择日期范围时,您可以为开始日期和结束日期指定时间部分。
设置自定义前缀内容
前缀的内容可以自定义。
自定义内容
单元格的内容可以自定义,在作用域插槽中您可以获取单元格数据。请注意,自定义内容结构应与默认结构保持一致,否则可能会出现样式错位。
自定义图标 2.8.0
可以使用插槽来自定义图标。
有关数据详情,请参阅
ts
interface DateCell {
column: number
customClass: string | undefined
disabled: boolean
end: boolean
inRange: boolean
row: number
selected: Dayjs | undefined
isCurrent: boolean | undefined
isSelected: boolean
renderText: string | undefined
start: boolean
text: number
timestamp: number
date: Date
dayjs: Dayjs
type: 'normal' | 'today' | 'week' | 'next-month' | 'prev-month'
}本地化
默认的区域设置为英文,如果你需要使用其他语言,请参考 国际化
注意,日期时间区域设置 (月份名称、每周第一天等) 也在本地化配置中。
API
属性
| 名称 | 描述 | 类型 | 默认值 |
|---|---|---|---|
| model-value / v-model | 绑定值,如果它是一个 range 选择器,数组的长度应该是 2 | number / string / Date / array | '' |
| 只读 | 日期选择器是否只读 | boolean | false |
| disabled | DatePicker 是否被禁用 | boolean | false |
| size | 输入框尺寸 | 枚举 | — |
| 可编辑 | 输入框是否可编辑 | boolean | true |
| 可清空 | 是否显示清除按钮 | boolean | true |
| 占位符 | 非范围选择时的占位内容 | string | '' |
| start-placeholder | 范围模式下开始日期的占位符 | string | — |
| end-placeholder | 范围模式下结束日期的占位符 | string | — |
| type | 选择器类型 | 枚举 | 日 |
| format | 输入框中显示值的格式 | string 详见 日期格式 | YYYY-MM-DD |
| popper-class | DatePicker 下拉框的自定义类名 | string | — |
| popper-style | DatePicker 下拉框的自定义样式 | string / object | — |
| popper-options | 自定义 popper 选项,更多请看 popper.js | object | {} |
| range-separator | 选择范围时的分隔符 | string | '-' |
| default-value | 可选,选择器打开时默认显示的时间 | object | — |
| 默认时间 | 可选,选择日期范围时使用的时间值 | object | — |
| value-format | 可选,绑定值的格式。 如果未指定,则绑定值为 Date 对象 | string 详见 日期格式 | — |
| id | 与原生 input 的 `id` 属性相同 | string / object | — |
| 名称 | 与原生输入框的 `name` 相同 | string / object | '' |
| 取消面板链接 | 在范围选择器中取消两个日期面板的链接 | boolean | false |
| 前缀图标 | 自定义前缀图标组件。默认情况下,如果 type 的值是 TimeLikeType,则值为 Clock,否则为 Calendar | string / object | '' |
| clear-icon | 自定义清除图标组件 | string / object | CircleClose |
| validate-event | 是否触发表单验证 | boolean | true |
| 禁用日期 | 一个用来判断该日期是否被禁用的函数,接受一个日期作为参数。应该返回一个布尔值 | Function | — |
| 快捷选项 | 设置快捷选项的对象数组 | object | [] |
| 单元格类名 | 设置自定义的类名 | Function | — |
| teleported | 日期选择器下拉框是否传送到 body 元素 | boolean | true |
| empty-values 2.7.0 | 组件的空值,参见 config-provider | array | — |
| value-on-clear 2.7.0 | 清除返回值,参见 config-provider | string / number / boolean / Function | — |
| fallback-placements 2.8.4 | Tooltip 的可能位置列表 popper.js | array | ['bottom', 'top', 'right', 'left'] |
| placement 2.8.4 | 下拉框出现的位置 | 位置 | bottom |
| show-footer 2.10.5 | 是否显示页脚 | boolean | true |
| show-confirm 2.11.0 | 是否显示确认按钮 | boolean | true |
| show-week-number 2.10.3 | 在周旁边显示周数 | boolean | false |
| 自动下拉 2.11.4 | 此属性决定了当输入框获得焦点时日期选择器面板是否弹出。(在 3.0 版本中,默认值将设置为 false) | boolean | true |
事件
| 名称 | 描述 | 类型 |
|---|---|---|
| change | 当用户确认值或点击外部时触发 | Function |
| blur | 在 Input 失去焦点时触发 | Function |
| focus | 在 Input 获得焦点时触发 | Function |
| clear 2.7.7 | 在可清除的 DatePicker 中点击清除图标时触发 | Function |
| 日历更改 | 本日历所选日期发生更改时触发。 仅适用于 range | Function |
| 面板更改 | 在点击导航按钮时触发。 | Function |
| visible-change | 当 DatePicker 的下拉框出现/消失时触发 | Function |
插槽
| 名称 | 描述 |
|---|---|
| default | 自定义单元格内容 |
| range-separator | 自定义范围分隔符内容 |
| prev-month 2.8.0 | 上个月图标 |
| next-month 2.8.0 | 下个月图标 |
| prev-year 2.8.0 | 上一年图标 |
| next-year 2.8.0 | 下一年图标 |
暴露
| 名称 | 描述 | 类型 |
|---|---|---|
| focus | 聚焦日期选择器组件 | Function |
| blur 2.8.7 | 使日期选择器组件失焦 | Function |
| handleOpen 2.2.16 | 打开 DatePicker 弹出框 | Function |
| handleClose 2.2.16 | 关闭 DatePicker 弹出框 | Function |
类型声明
显示声明
ts
import type { Options as PopperOptions } from '@popperjs/core'
type TimeLikeType = 'datetime' | 'datetimerange'
type Placement =
| 'top'
| 'top-start'
| 'top-end'
| 'bottom'
| 'bottom-start'
| 'bottom-end'
| 'left'
| 'left-start'
| 'left-end'
| 'right'
| 'right-start'
| 'right-end'