FxDatePicker 日期选择器
日期选择器用于日期输入。
FxDatePicker 属于 @fx/components。
输入日期
按「日」选择的基础日期选择器。测量维度由 type 属性决定,可通过 shortcuts 启用快捷选项,通过 disabled-date 设置禁用日期。
其他测量维度
通过扩展标准日期选择器,可以选择周、月、年或多个日期。
日期范围
支持选择日期范围。范围模式下左右两面板默认联动,如需两面板独立切换月份,可使用 unlink-panels 属性。
月份范围
支持选择月份范围。范围模式下左右两面板默认联动,如需两面板独立切换年份,可使用 unlink-panels 属性。
年份范围
支持选择年份范围。范围模式下左右两面板默认联动,如需两面板独立切换年份,可使用 unlink-panels 属性。
单面板
默认情况下日期范围选择器有两个面板。如需单面板,设置 single-panel 属性。
默认值
若用户未选择日期,默认展示今天的日历。可通过 default-value 设置其他日期,其值应能被 new Date() 解析。type 为 daterange 时,default-value 设置左侧日历。
日期格式
用 format 控制输入框显示文本的格式;用 value-format 控制绑定值的格式。默认情况下,组件接受并发射 Date 对象。
WARNING
注意大小写
起止日期的默认时间
选择日期范围时,可为起止日期分别指定时间部分。默认起止日期的时间部分均为 00:00:00,设置 default-time 可分别改变,接受最多两个 Date 对象的数组。
自定义前缀内容
可自定义前缀内容。将 prefix-icon 设置为从其他 .vue 引入的组件,或由 render 函数生成。
自定义内容
可自定义单元格内容,作用域插槽中可获取单元格数据。注意自定义内容结构应与默认结构一致,否则可能出现样式错位。
自定义图标
通过插槽可使用自定义图标。
扩展能力
以下为 FxDatePicker 在基础日期选择之外额外提供的能力。
尺寸
size 支持 large / default / small。
快捷选项
shortcuts 数组每一项含 { text, value },value 可为 Date 或 () => Date(范围面板则为 [Date, Date] 或 () => [Date, Date])。
禁用日期
disabled-date 接收 (date: Date) => boolean,返回 true 表示禁用。下例禁用周末。
周选择
type="week" + show-week-number 可显示周数;可通过 format 自定义显示格式。
本地化
默认为中文,i18n 切换能力规划中。
API
Attributes
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| model-value / v-model | 绑定值,range 时数组长度为 2 | number | string | Date | array | — |
| readonly | 是否只读 | boolean | false |
| disabled | 是否禁用 | boolean | false |
| size | 输入框尺寸 | '' | 'large' | 'default' | 'small' | — |
| editable | 输入框是否可键入 | boolean | true |
| clearable | 是否显示清空按钮 | boolean | true |
| placeholder | 非范围模式的占位 | string | — |
| start-placeholder | 范围模式起始占位 | string | — |
| end-placeholder | 范围模式结束占位 | string | — |
| type | 选择器类型 | 'year' | 'years' | 'month' | 'months' | 'date' | 'dates' | 'datetime' | 'week' | 'datetimerange' | 'daterange' | 'monthrange' | 'yearrange' | date |
| format | 输入框显示格式 | string | YYYY-MM-DD |
| popper-class | 下拉自定义类名 | string | — |
| popper-style | 下拉自定义样式 | string | object | — |
| popper-options | 透传浮层选项 | object | {} |
| range-separator | 范围分隔符 | string | '-' |
| default-value | 默认聚焦日期 | Date | [Date, Date] | — |
| default-time | 选日期范围时使用的时间 | Date | [Date, Date] | — |
| value-format | 绑定值格式,未指定则绑定 Date 对象 | string | — |
| id | 原生 id | string | [string, string] | — |
| name | 原生 name | string | [string, string] | — |
| unlink-panels | 范围模式两面板独立翻月 | boolean | false |
| single-panel | 范围模式仅展示一面板 | boolean | false |
| prefix-icon | 自定义前缀图标 | string | Component | ep:calendar / ep:clock |
| clear-icon | 自定义清空图标 | string | Component | ep:circle-close |
| validate-event | 是否触发表单校验 | boolean | true |
| disabled-date | 禁用日期判定函数,返回 Boolean | (date: Date) => boolean | — |
| shortcuts | 快捷选项数组 | Array<{ text: string; value: Date | Function }> | [] |
| cell-class-name | 单元格自定义类 | (date: Date) => string | — |
| teleported | 是否将下拉挂载到 body | boolean | true |
| empty-values | 组件的空值列表 | array | — |
| value-on-clear | 清空时回填的值 | string | number | boolean | Function | — |
| fallback-placements | 浮层备选位置列表 | Placement[] | ['bottom','top','right','left'] |
| placement | 浮层位置 | Placement | bottom |
| show-footer | 是否显示底部按钮区 | boolean | true |
| show-confirm | 是否显示确认按钮 | boolean | true |
| show-week-number | 是否显示周数 | boolean | false |
| automatic-dropdown | 聚焦输入框时自动展开面板 | boolean | true |
| date-format | 面板内日期显示格式 | string | YYYY-MM-DD |
| time-format | 面板内时间显示格式 | string | HH:mm:ss |
| disabled-hours | 禁用小时(仅 datetime* 生效) | (role: string, comparingDate?: Dayjs) => number[] | — |
| disabled-minutes | 禁用分钟(仅 datetime* 生效) | (hour: number, role: string, comparingDate?: Dayjs) => number[] | — |
| disabled-seconds | 禁用秒(仅 datetime* 生效) | (hour: number, minute: number, role: string, comparingDate?: Dayjs) => number[] | — |
| show-now | 是否显示「此刻」按钮(仅 datetime*) | boolean | true |
| arrow-control | 时间面板是否用箭头选择 | boolean | false |
| save-on-blur | 失焦时是否保存当前时间值 | boolean | true |
| tabindex | 输入框 tabindex | string | number | 0 |
| aria-label | a11y 标签 | string | — |
Events
| 事件名 | 说明 | 类型 |
|---|---|---|
| change | 用户确认选值或点击外部时触发 | (val) => void |
| blur | 输入框失焦时触发 | (e: FocusEvent) => void |
| focus | 输入框聚焦时触发 | (e: FocusEvent) => void |
| clear | 点击清空按钮时触发 | () => void |
| calendar-change | 面板日期交互时触发,仅 range | (val: [Date, null | Date]) => void |
| panel-change | 点击导航按钮时触发 | (date: Date | [Date, Date], mode: 'month' | 'year', view?: string) => void |
| visible-change | 下拉显隐时触发 | (visible: boolean) => void |
Slots
| 插槽名 | 说明 |
|---|---|
| default | 自定义单元格内容 |
| range-separator | 自定义范围分隔内容 |
| prev-month | 上月导航图标 |
| next-month | 下月导航图标 |
| prev-year | 上年导航图标 |
| next-year | 下年导航图标 |
| prefix | 自定义前缀内容(替代 prefix-icon) |
Exposes
| 方法 | 说明 | 类型 |
|---|---|---|
| focus | 聚焦输入框 | () => void |
| blur | 失焦输入框 | () => void |
| handleOpen | 打开下拉 | () => void |
| handleClose | 关闭下拉 | () => void |
类型声明
展开查看
ts
type Placement =
| 'top'
| 'top-start'
| 'top-end'
| 'bottom'
| 'bottom-start'
| 'bottom-end'
| 'left'
| 'left-start'
| 'left-end'
| 'right'
| 'right-start'
| 'right-end'