From e5e20cca5b6ebdb19ce7d5c2cb0d22cb5ecfe99c Mon Sep 17 00:00:00 2001 From: ming <819601702@qq.com> Date: Tue, 21 Mar 2023 14:05:57 +0800 Subject: [PATCH] feat[data-picker]: improve format types and docs (#6371) Co-authored-by: xiamingming1 --- .../date-picker/generatePicker/props.ts | 14 +++++------ components/date-picker/index.en-US.md | 24 ++++++++++++++----- components/date-picker/index.zh-CN.md | 24 ++++++++++++++----- 3 files changed, 42 insertions(+), 20 deletions(-) diff --git a/components/date-picker/generatePicker/props.ts b/components/date-picker/generatePicker/props.ts index f64febfb0..27fd3caa3 100644 --- a/components/date-picker/generatePicker/props.ts +++ b/components/date-picker/generatePicker/props.ts @@ -34,6 +34,11 @@ function commonProps() { defaultOpen: { type: Boolean, default: undefined }, /** Make input readOnly to avoid popup keyboard in mobile */ inputReadOnly: { type: Boolean, default: undefined }, + format: { + type: [String, Function, Array] as PropType< + string | CustomFormat | (string | CustomFormat)[] + >, + }, // Value // format: string | CustomFormat | (string | CustomFormat)[]; // Render @@ -107,6 +112,7 @@ export interface CommonProps { open?: boolean; defaultOpen?: boolean; inputReadOnly?: boolean; + format?: string | CustomFormat | (string | CustomFormat)[]; suffixIcon?: VueNode; clearIcon?: VueNode; prevIcon?: VueNode; @@ -151,11 +157,6 @@ function datePickerProps() { defaultValue: { type: [String, Object] as PropType }, value: { type: [String, Object] as PropType }, disabledTime: { type: Function as PropType> }, - format: { - type: [String, Function, Array] as PropType< - string | CustomFormat | (string | CustomFormat)[] - >, - }, renderExtraFooter: { type: Function as PropType<(mode: PanelMode) => VueNode> }, showNow: { type: Boolean, default: undefined }, monthCellRender: { type: Function as PropType> }, @@ -169,7 +170,6 @@ export interface DatePickerProps { defaultValue?: DateType | string; value?: DateType | string; disabledTime?: DisabledTime; - format?: string | CustomFormat | (string | CustomFormat)[]; renderExtraFooter?: (mode: PanelMode) => VueNode; showNow?: boolean; monthCellRender?: MonthCellRender; @@ -190,7 +190,6 @@ function rangePickerProps() { type: Function as PropType<(date: EventValue, type: RangeType) => DisabledTimes>, }, disabled: { type: [Boolean, Array] as unknown as PropType }, - format: String, renderExtraFooter: { type: Function as PropType<() => VueNode> }, separator: { type: String }, ranges: { @@ -242,7 +241,6 @@ export interface RangePickerProps { value?: RangeValue | RangeValue; disabledTime?: (date: EventValue, type: RangeType) => DisabledTimes; disabled?: [boolean, boolean]; - format?: string; renderExtraFooter?: () => VueNode; separator?: string; ranges?: Record< diff --git a/components/date-picker/index.en-US.md b/components/date-picker/index.en-US.md index e1887c776..59421cb5f 100644 --- a/components/date-picker/index.en-US.md +++ b/components/date-picker/index.en-US.md @@ -83,6 +83,7 @@ The following APIs are shared by DatePicker, RangePicker. | dateRender | Custom rendering function for date cells | v-slot:dateRender="{current, today}" | - | | | disabled | Determine whether the DatePicker is disabled | boolean | false | | | disabledDate | Specify the date that cannot be selected | (currentDate: dayjs) => boolean | - | | +| format | To set the date format, refer to [dayjs](https://day.js.org/). When an array is provided, all values are used for parsing and first value is used for formatting, support [Custom Format](#components-date-picker-demo-format) | [formatType](#formatType) | `YYYY-MM-DD` | | | dropdownClassName | To customize the className of the popup calendar | string | - | | | getPopupContainer | To set the container of the floating layer, while the default is to create a `div` element in `body` | function(trigger) | - | | | inputReadOnly | Set the `readonly` attribute of the input tag (avoids virtual keyboard on touch devices) | boolean | false | | @@ -120,7 +121,7 @@ The following APIs are shared by DatePicker, RangePicker. | --- | --- | --- | --- | --- | | defaultPickerValue | To set default picker date | [dayjs](https://day.js.org/) | - | | | disabledTime | To specify the time that cannot be selected | function(date) | - | | -| format | To set the date format, refer to [dayjs](https://day.js.org/). When an array is provided, all values are used for parsing and first value is used for formatting, support [Custom Format](#components-date-picker-demo-format) | string \| (value: dayjs) => string \| (string \| (value: dayjs) => string)\[] | `YYYY-MM-DD` | | +| format | To set the date format, refer to [dayjs](https://day.js.org/) | [formatType](#formatType) | `YYYY-MM-DD` | | | renderExtraFooter | Render extra footer in panel | v-slot:renderExtraFooter="mode" | - | | | showNow | Whether to show 'Now' button on panel when `showTime` is set | boolean | - | | | showTime | To provide an additional time selection | object \| boolean | [TimePicker Options](/components/time-picker/#API) | | @@ -139,26 +140,26 @@ The following APIs are shared by DatePicker, RangePicker. | Property | Description | Type | Default | Version | | --- | --- | --- | --- | --- | -| format | To set the date format, refer to [dayjs](https://day.js.org/) | string | `YYYY` | | +| format | To set the date format, refer to [dayjs](https://day.js.org/) | [formatType](#formatType) | `YYYY` | | ### DatePicker\[picker=quarter] | Property | Description | Type | Default | Version | | --- | --- | --- | --- | --- | -| format | To set the date format, refer to [dayjs](https://day.js.org/) | string | `YYYY-\QQ` | | +| format | To set the date format, refer to [dayjs](https://day.js.org/) | [formatType](#formatType) | `YYYY-\QQ` | | ### DatePicker\[picker=month] | Property | Description | Type | Default | Version | | --- | --- | --- | --- | --- | -| format | To set the date format, refer to [dayjs](https://day.js.org/) | string | `YYYY-MM` | | +| format | To set the date format, refer to [dayjs](https://day.js.org/) | [formatType](#formatType) | `YYYY-MM` | | | monthCellRender | Custom month cell content render method | v-slot:monthCellRender="{current, locale}" | - | | ### DatePicker\[picker=week] | Property | Description | Type | Default | Version | | --- | --- | --- | --- | --- | -| format | To set the date format, refer to [dayjs](https://day.js.org/) | string | `YYYY-wo` | | +| format | To set the date format, refer to [dayjs](https://day.js.org/) | [formatType](#formatType) | `YYYY-wo` | | ### RangePicker @@ -169,7 +170,7 @@ The following APIs are shared by DatePicker, RangePicker. | defaultPickerValue | To set default picker date | \[[dayjs](https://day.js.org/), [dayjs](https://day.js.org/)] | - | | | disabled | If disable start or end | \[boolean, boolean] | - | | | disabledTime | To specify the time that cannot be selected | function(date: dayjs, partial: `start` \| `end`) | - | | -| format | To set the date format, refer to [dayjs](https://day.js.org/). When an array is provided, all values are used for parsing and first value is used for formatting | string \| string\[] | `YYYY-MM-DD HH:mm:ss` | | +| format | To set the date format, refer to [dayjs](https://day.js.org/) | [formatType](#formatType) | `YYYY-MM-DD HH:mm:ss` | | | ranges | The preseted ranges for quick selection | { \[range: string]: [dayjs](https://day.js.org/)\[] } \| { \[range: string]: () => [dayjs](https://day.js.org/)\[] } | - | | | renderExtraFooter | Render extra footer in panel | v-slot:renderExtraFooter="mode" | - | | | separator | Set separator between inputs | string \| v-slot:separator | `` | | @@ -185,6 +186,17 @@ The following APIs are shared by DatePicker, RangePicker. | change | a callback function, can be executed when the selected time is changing | function(dates: \[dayjs, dayjs] \| \[string, string], dateStrings: \[string, string]) | | | | ok | callback when click ok button | function(dates: \[dayjs, dayjs] \| \[string, string]) | | | +#### formatType + +```typescript +import type { Dayjs } from 'dayjs'; + +type Generic = string; +type GenericFn = (value: Dayjs) => string; + +export type FormatType = Generic | GenericFn | Array; +``` + ## FAQ ### How to use DatePicker with customize date library（like moment.js \| dayjs \| date-fns）？ diff --git a/components/date-picker/index.zh-CN.md b/components/date-picker/index.zh-CN.md index 3cf3cdfc8..0b861a498 100644 --- a/components/date-picker/index.zh-CN.md +++ b/components/date-picker/index.zh-CN.md @@ -84,6 +84,7 @@ cover: https://gw.alipayobjects.com/zos/alicdn/RT_USzA48/DatePicker.svg | dateRender | 自定义日期单元格的内容 | v-slot:dateRender="{current, today}" | - | | | disabled | 禁用 | boolean | false | | | disabledDate | 不可选择的日期 | (currentDate: dayjs) => boolean | - | | +| format | 设置日期格式，为数组时支持多格式匹配，展示以第一个为准。配置参考 [dayjs](https://day.js.org/docs/zh-CN/display/format)，支持[自定义格式](#components-date-picker-demo-format) | [formatType](#formatType) | `YYYY-MM-DD` | | | dropdownClassName | 额外的弹出日历 className | string | - | | | getPopupContainer | 定义浮层的容器，默认为 body 上新建 div | function(trigger) | - | | | inputReadOnly | 设置输入框为只读（避免在移动设备上打开虚拟键盘） | boolean | false | | @@ -121,7 +122,7 @@ cover: https://gw.alipayobjects.com/zos/alicdn/RT_USzA48/DatePicker.svg | --- | --- | --- | --- | --- | | defaultPickerValue | 默认面板日期 | [dayjs](https://day.js.org/) | - | | | disabledTime | 不可选择的时间 | function(date) | - | | -| format | 设置日期格式，为数组时支持多格式匹配，展示以第一个为准。配置参考 [dayjs](https://day.js.org/docs/zh-CN/display/format)，支持[自定义格式](#components-date-picker-demo-format) | string \| (value: dayjs) => string \| (string \| (value: dayjs) => string)\[] | `YYYY-MM-DD` | | +| format | 展示的日期格式，配置参考 [dayjs](https://day.js.org/docs/zh-CN/display/format) | [formatType](#formatType) | `YYYY-MM-DD` | | | renderExtraFooter | 在面板中添加额外的页脚 | v-slot:renderExtraFooter="mode" | - | | | showNow | 当设定了 `showTime` 的时候，面板是否显示“此刻”按钮 | boolean | - | | | showTime | 增加时间选择功能 | Object \| boolean | [TimePicker Options](/components/time-picker/#API) | | @@ -140,26 +141,26 @@ cover: https://gw.alipayobjects.com/zos/alicdn/RT_USzA48/DatePicker.svg | 参数 | 说明 | 类型 | 默认值 | 版本 | | --- | --- | --- | --- | --- | -| format | 展示的日期格式，配置参考 [dayjs](https://day.js.org/docs/zh-CN/display/format) | string | `YYYY` | | +| format | 展示的日期格式，配置参考 [dayjs](https://day.js.org/docs/zh-CN/display/format) | [formatType](#formatType) | `YYYY` | | ### DatePicker\[picker=quarter] | 参数 | 说明 | 类型 | 默认值 | 版本 | | --- | --- | --- | --- | --- | -| format | 展示的日期格式，配置参考 [dayjs](https://day.js.org/docs/zh-CN/display/format) | string | `YYYY-\QQ` | | +| format | 展示的日期格式，配置参考 [dayjs](https://day.js.org/docs/zh-CN/display/format) | [formatType](#formatType) | `YYYY-\QQ` | | ### DatePicker\[picker=month] | 参数 | 说明 | 类型 | 默认值 | 版本 | | --- | --- | --- | --- | --- | -| format | 展示的日期格式，配置参考 [dayjs](https://day.js.org/docs/zh-CN/display/format) | string | `YYYY-MM` | | +| format | 展示的日期格式，配置参考 [dayjs](https://day.js.org/docs/zh-CN/display/format) | [formatType](#formatType) | `YYYY-MM` | | | monthCellRender | 自定义的月份内容渲染方法 | v-slot:monthCellRender="{current, locale}" | - | | ### DatePicker\[picker=week] | 参数 | 说明 | 类型 | 默认值 | 版本 | | --- | --- | --- | --- | --- | -| format | 展示的日期格式，配置参考 [dayjs](https://day.js.org/docs/zh-CN/display/format) | string | `YYYY-wo` | | +| format | 展示的日期格式，配置参考 [dayjs](https://day.js.org/docs/zh-CN/display/format) | [formatType](#formatType) | `YYYY-wo` | | ### RangePicker @@ -170,7 +171,7 @@ cover: https://gw.alipayobjects.com/zos/alicdn/RT_USzA48/DatePicker.svg | defaultPickerValue | 默认面板日期 | [dayjs](https://day.js.org/)\[] | - | | | disabled | 禁用起始项 | \[boolean, boolean] | - | | | disabledTime | 不可选择的时间 | function(date: dayjs, partial: `start` \| `end`) | - | | -| format | 展示的日期格式 | string | `YYYY-MM-DD HH:mm:ss` | | +| format | 展示的日期格式 | [formatType](#formatType) | `YYYY-MM-DD HH:mm:ss` | | | ranges | 预设时间范围快捷选择 | { \[range: string]: [dayjs](https://day.js.org/)\[] } \| { \[range: string]: () => [dayjs](https://day.js.org/)\[] } | - | | | renderExtraFooter | 在面板中添加额外的页脚 | v-slot:renderExtraFooter="mode" | - | | | separator | 设置分隔符 | string \| v-slot:separator | `` | | @@ -186,6 +187,17 @@ cover: https://gw.alipayobjects.com/zos/alicdn/RT_USzA48/DatePicker.svg | change | 日期范围发生变化的回调 | function(dates: \[dayjs, dayjs] \| \[string, string], dateStrings: \[string, string]) | | ok | 点击确定按钮的回调 | function(dates: \[dayjs, dayjs] \| \[string, string]) | +#### formatType + +```typescript +import type { Dayjs } from 'dayjs'; + +type Generic = string; +type GenericFn = (value: Dayjs) => string; + +export type FormatType = Generic | GenericFn | Array; +``` + ## FAQ ### 如何在 DatePicker 中使用自定义日期库（如 moment.js \| dayjs \| date-fns）？