Skip to content

Commit e5e20cc

Browse files
xmm228xiamingming1
xmm228
and
xiamingming1
authored
feat[data-picker]: improve format types and docs (#6371)
Co-authored-by: xiamingming1 <[email protected]>
1 parent 0a610d8 commit e5e20cc

File tree

3 files changed

+42
-20
lines changed

3 files changed

+42
-20
lines changed

‎components/date-picker/generatePicker/props.ts

Lines changed: 6 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,11 @@ function commonProps<DateType = any>() {
3434
defaultOpen: { type: Boolean, default: undefined },
3535
/** Make input readOnly to avoid popup keyboard in mobile */
3636
inputReadOnly: { type: Boolean, default: undefined },
37+
format: {
38+
type: [String, Function, Array] as PropType<
39+
string | CustomFormat<DateType> | (string | CustomFormat<DateType>)[]
40+
>,
41+
},
3742
// Value
3843
// format: string | CustomFormat<DateType> | (string | CustomFormat<DateType>)[];
3944
// Render
@@ -107,6 +112,7 @@ export interface CommonProps<DateType> {
107112
open?: boolean;
108113
defaultOpen?: boolean;
109114
inputReadOnly?: boolean;
115+
format?: string | CustomFormat<DateType> | (string | CustomFormat<DateType>)[];
110116
suffixIcon?: VueNode;
111117
clearIcon?: VueNode;
112118
prevIcon?: VueNode;
@@ -151,11 +157,6 @@ function datePickerProps<DateType = any>() {
151157
defaultValue: { type: [String, Object] as PropType<DateType | string> },
152158
value: { type: [String, Object] as PropType<DateType | string> },
153159
disabledTime: { type: Function as PropType<DisabledTime<DateType>> },
154-
format: {
155-
type: [String, Function, Array] as PropType<
156-
string | CustomFormat<DateType> | (string | CustomFormat<DateType>)[]
157-
>,
158-
},
159160
renderExtraFooter: { type: Function as PropType<(mode: PanelMode) => VueNode> },
160161
showNow: { type: Boolean, default: undefined },
161162
monthCellRender: { type: Function as PropType<MonthCellRender<DateType>> },
@@ -169,7 +170,6 @@ export interface DatePickerProps<DateType> {
169170
defaultValue?: DateType | string;
170171
value?: DateType | string;
171172
disabledTime?: DisabledTime<DateType>;
172-
format?: string | CustomFormat<DateType> | (string | CustomFormat<DateType>)[];
173173
renderExtraFooter?: (mode: PanelMode) => VueNode;
174174
showNow?: boolean;
175175
monthCellRender?: MonthCellRender<DateType>;
@@ -190,7 +190,6 @@ function rangePickerProps<DateType>() {
190190
type: Function as PropType<(date: EventValue<DateType>, type: RangeType) => DisabledTimes>,
191191
},
192192
disabled: { type: [Boolean, Array] as unknown as PropType<boolean | [boolean, boolean]> },
193-
format: String,
194193
renderExtraFooter: { type: Function as PropType<() => VueNode> },
195194
separator: { type: String },
196195
ranges: {
@@ -242,7 +241,6 @@ export interface RangePickerProps<DateType> {
242241
value?: RangeValue<DateType> | RangeValue<string>;
243242
disabledTime?: (date: EventValue<DateType>, type: RangeType) => DisabledTimes;
244243
disabled?: [boolean, boolean];
245-
format?: string;
246244
renderExtraFooter?: () => VueNode;
247245
separator?: string;
248246
ranges?: Record<

‎components/date-picker/index.en-US.md

Lines changed: 18 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -83,6 +83,7 @@ The following APIs are shared by DatePicker, RangePicker.
8383
| dateRender | Custom rendering function for date cells | v-slot:dateRender="{current, today}" | - | |
8484
| disabled | Determine whether the DatePicker is disabled | boolean | false | |
8585
| disabledDate | Specify the date that cannot be selected | (currentDate: dayjs) => boolean | - | |
86+
| 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` | |
8687
| dropdownClassName | To customize the className of the popup calendar | string | - | |
8788
| getPopupContainer | To set the container of the floating layer, while the default is to create a `div` element in `body` | function(trigger) | - | |
8889
| 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.
120121
| --- | --- | --- | --- | --- |
121122
| defaultPickerValue | To set default picker date | [dayjs](https://day.js.org/) | - | |
122123
| disabledTime | To specify the time that cannot be selected | function(date) | - | |
123-
| 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` | |
124+
| format | To set the date format, refer to [dayjs](https://day.js.org/) | [formatType](#formatType) | `YYYY-MM-DD` | |
124125
| renderExtraFooter | Render extra footer in panel | v-slot:renderExtraFooter="mode" | - | |
125126
| showNow | Whether to show 'Now' button on panel when `showTime` is set | boolean | - | |
126127
| 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.
139140

140141
| Property | Description | Type | Default | Version |
141142
| --- | --- | --- | --- | --- |
142-
| format | To set the date format, refer to [dayjs](https://day.js.org/) | string | `YYYY` | |
143+
| format | To set the date format, refer to [dayjs](https://day.js.org/) | [formatType](#formatType) | `YYYY` | |
143144

144145
### DatePicker\[picker=quarter]
145146

146147
| Property | Description | Type | Default | Version |
147148
| --- | --- | --- | --- | --- |
148-
| format | To set the date format, refer to [dayjs](https://day.js.org/) | string | `YYYY-\QQ` | |
149+
| format | To set the date format, refer to [dayjs](https://day.js.org/) | [formatType](#formatType) | `YYYY-\QQ` | |
149150

150151
### DatePicker\[picker=month]
151152

152153
| Property | Description | Type | Default | Version |
153154
| --- | --- | --- | --- | --- |
154-
| format | To set the date format, refer to [dayjs](https://day.js.org/) | string | `YYYY-MM` | |
155+
| format | To set the date format, refer to [dayjs](https://day.js.org/) | [formatType](#formatType) | `YYYY-MM` | |
155156
| monthCellRender | Custom month cell content render method | v-slot:monthCellRender="{current, locale}" | - | |
156157

157158
### DatePicker\[picker=week]
158159

159160
| Property | Description | Type | Default | Version |
160161
| --- | --- | --- | --- | --- |
161-
| format | To set the date format, refer to [dayjs](https://day.js.org/) | string | `YYYY-wo` | |
162+
| format | To set the date format, refer to [dayjs](https://day.js.org/) | [formatType](#formatType) | `YYYY-wo` | |
162163

163164
### RangePicker
164165

@@ -169,7 +170,7 @@ The following APIs are shared by DatePicker, RangePicker.
169170
| defaultPickerValue | To set default picker date | \[[dayjs](https://day.js.org/), [dayjs](https://day.js.org/)] | - | |
170171
| disabled | If disable start or end | \[boolean, boolean] | - | |
171172
| disabledTime | To specify the time that cannot be selected | function(date: dayjs, partial: `start` \| `end`) | - | |
172-
| 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` | |
173+
| format | To set the date format, refer to [dayjs](https://day.js.org/) | [formatType](#formatType) | `YYYY-MM-DD HH:mm:ss` | |
173174
| ranges | The preseted ranges for quick selection | { \[range: string]: [dayjs](https://day.js.org/)\[] } \| { \[range: string]: () => [dayjs](https://day.js.org/)\[] } | - | |
174175
| renderExtraFooter | Render extra footer in panel | v-slot:renderExtraFooter="mode" | - | |
175176
| separator | Set separator between inputs | string \| v-slot:separator | `<SwapRightOutlined />` | |
@@ -185,6 +186,17 @@ The following APIs are shared by DatePicker, RangePicker.
185186
| change | a callback function, can be executed when the selected time is changing | function(dates: \[dayjs, dayjs] \| \[string, string], dateStrings: \[string, string]) | | |
186187
| ok | callback when click ok button | function(dates: \[dayjs, dayjs] \| \[string, string]) | | |
187188

189+
#### formatType
190+
191+
```typescript
192+
import type { Dayjs } from 'dayjs';
193+
194+
type Generic = string;
195+
type GenericFn = (value: Dayjs) => string;
196+
197+
export type FormatType = Generic | GenericFn | Array<Generic | GenericFn>;
198+
```
199+
188200
## FAQ
189201

190202
### How to use DatePicker with customize date library（like moment.js \| dayjs \| date-fns）？

‎components/date-picker/index.zh-CN.md

Lines changed: 18 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -84,6 +84,7 @@ cover: https://gw.alipayobjects.com/zos/alicdn/RT_USzA48/DatePicker.svg
8484
| dateRender | 自定义日期单元格的内容 | v-slot:dateRender="{current, today}" | - | |
8585
| disabled | 禁用 | boolean | false | |
8686
| disabledDate | 不可选择的日期 | (currentDate: dayjs) => boolean | - | |
87+
| format | 设置日期格式，为数组时支持多格式匹配，展示以第一个为准。配置参考 [dayjs](https://day.js.org/docs/zh-CN/display/format)，支持[自定义格式](#components-date-picker-demo-format) | [formatType](#formatType) | `YYYY-MM-DD` | |
8788
| dropdownClassName | 额外的弹出日历 className | string | - | |
8889
| getPopupContainer | 定义浮层的容器，默认为 body 上新建 div | function(trigger) | - | |
8990
| inputReadOnly | 设置输入框为只读（避免在移动设备上打开虚拟键盘） | boolean | false | |
@@ -121,7 +122,7 @@ cover: https://gw.alipayobjects.com/zos/alicdn/RT_USzA48/DatePicker.svg
121122
| --- | --- | --- | --- | --- |
122123
| defaultPickerValue | 默认面板日期 | [dayjs](https://day.js.org/) | - | |
123124
| disabledTime | 不可选择的时间 | function(date) | - | |
124-
| 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` | |
125+
| format | 展示的日期格式，配置参考 [dayjs](https://day.js.org/docs/zh-CN/display/format) | [formatType](#formatType) | `YYYY-MM-DD` | |
125126
| renderExtraFooter | 在面板中添加额外的页脚 | v-slot:renderExtraFooter="mode" | - | |
126127
| showNow | 当设定了 `showTime` 的时候，面板是否显示“此刻”按钮 | boolean | - | |
127128
| showTime | 增加时间选择功能 | Object \| boolean | [TimePicker Options](/components/time-picker/#API) | |
@@ -140,26 +141,26 @@ cover: https://gw.alipayobjects.com/zos/alicdn/RT_USzA48/DatePicker.svg
140141

141142
| 参数 | 说明 | 类型 | 默认值 | 版本 |
142143
| --- | --- | --- | --- | --- |
143-
| format | 展示的日期格式，配置参考 [dayjs](https://day.js.org/docs/zh-CN/display/format) | string | `YYYY` | |
144+
| format | 展示的日期格式，配置参考 [dayjs](https://day.js.org/docs/zh-CN/display/format) | [formatType](#formatType) | `YYYY` | |
144145

145146
### DatePicker\[picker=quarter]
146147

147148
| 参数 | 说明 | 类型 | 默认值 | 版本 |
148149
| --- | --- | --- | --- | --- |
149-
| format | 展示的日期格式，配置参考 [dayjs](https://day.js.org/docs/zh-CN/display/format) | string | `YYYY-\QQ` | |
150+
| format | 展示的日期格式，配置参考 [dayjs](https://day.js.org/docs/zh-CN/display/format) | [formatType](#formatType) | `YYYY-\QQ` | |
150151

151152
### DatePicker\[picker=month]
152153

153154
| 参数 | 说明 | 类型 | 默认值 | 版本 |
154155
| --- | --- | --- | --- | --- |
155-
| format | 展示的日期格式，配置参考 [dayjs](https://day.js.org/docs/zh-CN/display/format) | string | `YYYY-MM` | |
156+
| format | 展示的日期格式，配置参考 [dayjs](https://day.js.org/docs/zh-CN/display/format) | [formatType](#formatType) | `YYYY-MM` | |
156157
| monthCellRender | 自定义的月份内容渲染方法 | v-slot:monthCellRender="{current, locale}" | - | |
157158

158159
### DatePicker\[picker=week]
159160

160161
| 参数 | 说明 | 类型 | 默认值 | 版本 |
161162
| --- | --- | --- | --- | --- |
162-
| format | 展示的日期格式，配置参考 [dayjs](https://day.js.org/docs/zh-CN/display/format) | string | `YYYY-wo` | |
163+
| format | 展示的日期格式，配置参考 [dayjs](https://day.js.org/docs/zh-CN/display/format) | [formatType](#formatType) | `YYYY-wo` | |
163164

164165
### RangePicker
165166

@@ -170,7 +171,7 @@ cover: https://gw.alipayobjects.com/zos/alicdn/RT_USzA48/DatePicker.svg
170171
| defaultPickerValue | 默认面板日期 | [dayjs](https://day.js.org/)\[] | - | |
171172
| disabled | 禁用起始项 | \[boolean, boolean] | - | |
172173
| disabledTime | 不可选择的时间 | function(date: dayjs, partial: `start` \| `end`) | - | |
173-
| format | 展示的日期格式 | string | `YYYY-MM-DD HH:mm:ss` | |
174+
| format | 展示的日期格式 | [formatType](#formatType) | `YYYY-MM-DD HH:mm:ss` | |
174175
| ranges | 预设时间范围快捷选择 | { \[range: string]: [dayjs](https://day.js.org/)\[] } \| { \[range: string]: () => [dayjs](https://day.js.org/)\[] } | - | |
175176
| renderExtraFooter | 在面板中添加额外的页脚 | v-slot:renderExtraFooter="mode" | - | |
176177
| separator | 设置分隔符 | string \| v-slot:separator | `<SwapRightOutlined />` | |
@@ -186,6 +187,17 @@ cover: https://gw.alipayobjects.com/zos/alicdn/RT_USzA48/DatePicker.svg
186187
| change | 日期范围发生变化的回调 | function(dates: \[dayjs, dayjs] \| \[string, string], dateStrings: \[string, string]) |
187188
| ok | 点击确定按钮的回调 | function(dates: \[dayjs, dayjs] \| \[string, string]) |
188189

190+
#### formatType
191+
192+
```typescript
193+
import type { Dayjs } from 'dayjs';
194+
195+
type Generic = string;
196+
type GenericFn = (value: Dayjs) => string;
197+
198+
export type FormatType = Generic | GenericFn | Array<Generic | GenericFn>;
199+
```
200+
189201
## FAQ
190202

191203
### 如何在 DatePicker 中使用自定义日期库（如 moment.js \| dayjs \| date-fns）？

0 commit comments

Comments
 (0)