mirror of
https://github.com/ant-design/ant-design.git
synced 2024-11-29 05:29:37 +08:00
feat: Picker luxon support (#41580)
* chore: add luxon english documentation * chore: add draft chinese documentation This documentation was auto-generated based on the english version so it is only a rough draft and will most likely need to be refined. * fix: improve documentation phrasing
This commit is contained in:
Sylvain Boulade
GitHub
parent
512374734a
commit
e3e71dfeda
@ -3,9 +3,9 @@ order: 7.5
|
||||
title: Use custom date library
|
||||
---
|
||||
|
||||
By default, Ant Design use [Day.js](https://day.js.org) to handle time and date. Day.js is an immutable date-time library alternative to Moment.js with the same API.
|
||||
By default, Ant Design uses [Day.js](https://day.js.org) to handle time and date. Day.js is an immutable date-time library alternative to Moment.js with the same API.
|
||||
|
||||
You might want to use another date library (**Ant design currently supports [moment](http://momentjs.com/) and [date-fns](https://date-fns.org)**). We provide two ways to customize:
|
||||
You might want to use another date library (**Ant design currently supports [moment](http://momentjs.com/), [date-fns](https://date-fns.org), and [luxon](https://moment.github.io/luxon/)**). We provide two ways to customize:
|
||||
|
||||
## Custom component
|
||||
|
||||
@ -20,9 +20,9 @@ Create `src/components/DatePicker.tsx`.
|
||||
For example:
|
||||
|
||||
```tsx
|
||||
import generatePicker from 'antd/es/date-picker/generatePicker';
|
||||
import type { Moment } from 'moment';
|
||||
import momentGenerateConfig from 'rc-picker/lib/generate/moment';
|
||||
import generatePicker from 'antd/es/date-picker/generatePicker';
|
||||
|
||||
const DatePicker = generatePicker<Moment>(momentGenerateConfig);
|
||||
|
||||
@ -36,9 +36,9 @@ Create `src/components/TimePicker.tsx`.
|
||||
For example:
|
||||
|
||||
```tsx
|
||||
import type { PickerTimeProps } from 'antd/es/date-picker/generatePicker';
|
||||
import type { Moment } from 'moment';
|
||||
import * as React from 'react';
|
||||
import type { PickerTimeProps } from 'antd/es/date-picker/generatePicker';
|
||||
import DatePicker from './DatePicker';
|
||||
|
||||
export interface TimePickerProps extends Omit<PickerTimeProps<Moment>, 'picker'> {}
|
||||
@ -59,9 +59,9 @@ Create `src/components/Calendar.tsx`.
|
||||
For example:
|
||||
|
||||
```tsx
|
||||
import generateCalendar from 'antd/es/calendar/generateCalendar';
|
||||
import type { Moment } from 'moment';
|
||||
import momentGenerateConfig from 'rc-picker/lib/generate/moment';
|
||||
import generateCalendar from 'antd/es/calendar/generateCalendar';
|
||||
|
||||
const Calendar = generateCalendar<Moment>(momentGenerateConfig);
|
||||
|
||||
@ -75,8 +75,8 @@ Create `src/components/index.tsx`.
|
||||
For example:
|
||||
|
||||
```tsx
|
||||
export { default as DatePicker } from './DatePicker';
|
||||
export { default as Calendar } from './Calendar';
|
||||
export { default as DatePicker } from './DatePicker';
|
||||
export { default as TimePicker } from './TimePicker';
|
||||
```
|
||||
|
||||
@ -119,11 +119,63 @@ Create `src/components/DatePicker.tsx`.
|
||||
Code as follows:
|
||||
|
||||
```tsx
|
||||
import dateFnsGenerateConfig from 'rc-picker/lib/generate/dateFns';
|
||||
import generatePicker from 'antd/es/date-picker/generatePicker';
|
||||
import 'antd/es/date-picker/style/index';
|
||||
import dateFnsGenerateConfig from 'rc-picker/lib/generate/dateFns';
|
||||
|
||||
const DatePicker = generatePicker<Date>(dateFnsGenerateConfig);
|
||||
|
||||
export default DatePicker;
|
||||
```
|
||||
|
||||
## Use luxon
|
||||
|
||||
Since `antd 5.4.0`, [luxon](https://moment.github.io/luxon/) can be used instead of `dayjs` and supports the same functionality, but it does introduce some differences in behavior that we will explain below.
|
||||
|
||||
### Implementation
|
||||
|
||||
Create a `src/components/DatePicker.tsx` file, and implement the luxon based picker as follows:
|
||||
|
||||
```tsx
|
||||
import generatePicker from 'antd/es/date-picker/generatePicker';
|
||||
import 'antd/es/date-picker/style/index';
|
||||
import type { DateTime } from 'luxon';
|
||||
import luxonGenerateConfig from 'rc-picker/lib/generate/luxon';
|
||||
|
||||
const DatePicker = generatePicker<DateTime>(luxonGenerateConfig);
|
||||
|
||||
export default DatePicker;
|
||||
```
|
||||
|
||||
### Notable differences with day-js
|
||||
|
||||
luxon users should be familiar with the fact that it does not come with a custom implementation for localization. Instead, it relies on the browser's native [Intl API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl).
|
||||
|
||||
This introduces some formatting differences with the other date libraries. As of today, the main differences are:
|
||||
|
||||
- First day of the week is always Monday regardless of locale.
|
||||
- Week of year number is sometimes different (ISO week rules are used to determine it).
|
||||
- Short week days format will sometimes be different for custom locales (it might have 3 characters instead of 2).
|
||||
- Selected week label format will be slightly different (e.g. "2021-01" instead of "2021-1st").
|
||||
|
||||
It is possible to customize these default luxon behaviors by adjusting the luxon config:
|
||||
|
||||
```tsx
|
||||
import generatePicker from 'antd/es/date-picker/generatePicker';
|
||||
import 'antd/es/date-picker/style/index';
|
||||
import type { DateTime } from 'luxon';
|
||||
import luxonGenerateConfig from 'rc-picker/lib/generate/luxon';
|
||||
|
||||
const customLuxonConfig = {
|
||||
...luxonGenerateConfig,
|
||||
getWeekFirstDay: (locale) => {
|
||||
// Your custom implementation goes here
|
||||
},
|
||||
};
|
||||
|
||||
const DatePicker = generatePicker<DateTime>(customLuxonConfig);
|
||||
|
||||
export default DatePicker;
|
||||
```
|
||||
|
||||
Note that by doing such customization, the resulting DatePicker behavior might be altered in unexpected ways, so make sure you are testing for edge cases.
|
||||
|
||||
@ -3,7 +3,7 @@ order: 7.5
|
||||
title: 使用自定义日期库
|
||||
---
|
||||
|
||||
Ant Design 默认使用 [Day.js](https://day.js.org) 来处理时间日期问题。Day.js 相比于 moment 使用了不可变数据结构，性能更快，体积仅 2KB，API 设计完全一致。你可以很方便的改用其他自定义日期库如（[moment](http://momentjs.com/)、[date-fns](https://date-fns.org)）。在这里我们提供了两种方式来实现替换:
|
||||
Ant Design 默认使用 [Day.js](https://day.js.org) 来处理时间日期问题。Day.js 相比于 moment 使用了不可变数据结构，性能更快，体积仅 2KB，API 设计完全一致。你可以很方便的改用其他自定义日期库如（[moment](http://momentjs.com/)、[date-fns](https://date-fns.org)、[luxon](https://moment.github.io/luxon/)）。在这里我们提供了两种方式来实现替换:
|
||||
|
||||
## 自定义组件
|
||||
|
||||
@ -18,9 +18,9 @@ Ant Design 默认使用 [Day.js](https://day.js.org) 来处理时间日期问题
|
||||
编写如下代码:
|
||||
|
||||
```tsx
|
||||
import generatePicker from 'antd/es/date-picker/generatePicker';
|
||||
import type { Moment } from 'moment';
|
||||
import momentGenerateConfig from 'rc-picker/es/generate/moment';
|
||||
import generatePicker from 'antd/es/date-picker/generatePicker';
|
||||
|
||||
const DatePicker = generatePicker<Moment>(momentGenerateConfig);
|
||||
|
||||
@ -34,9 +34,9 @@ export default DatePicker;
|
||||
编写如下代码:
|
||||
|
||||
```tsx
|
||||
import type { PickerTimeProps } from 'antd/es/date-picker/generatePicker';
|
||||
import type { Moment } from 'moment';
|
||||
import * as React from 'react';
|
||||
import type { PickerTimeProps } from 'antd/es/date-picker/generatePicker';
|
||||
import DatePicker from './DatePicker';
|
||||
|
||||
export interface TimePickerProps extends Omit<PickerTimeProps<Moment>, 'picker'> {}
|
||||
@ -57,9 +57,9 @@ export default TimePicker;
|
||||
编写如下代码:
|
||||
|
||||
```tsx
|
||||
import generateCalendar from 'antd/es/calendar/generateCalendar';
|
||||
import type { Moment } from 'moment';
|
||||
import momentGenerateConfig from 'rc-picker/es/generate/moment';
|
||||
import generateCalendar from 'antd/es/calendar/generateCalendar';
|
||||
|
||||
const Calendar = generateCalendar<Moment>(momentGenerateConfig);
|
||||
|
||||
@ -73,8 +73,8 @@ export default Calendar;
|
||||
编写如下代码:
|
||||
|
||||
```tsx
|
||||
export { default as DatePicker } from './DatePicker';
|
||||
export { default as Calendar } from './Calendar';
|
||||
export { default as DatePicker } from './DatePicker';
|
||||
export { default as TimePicker } from './TimePicker';
|
||||
```
|
||||
|
||||
@ -117,11 +117,63 @@ module.exports = {
|
||||
编写如下代码:
|
||||
|
||||
```tsx
|
||||
import dateFnsGenerateConfig from 'rc-picker/es/generate/dateFns';
|
||||
import generatePicker from 'antd/es/date-picker/generatePicker';
|
||||
import 'antd/es/date-picker/style/index';
|
||||
import dateFnsGenerateConfig from 'rc-picker/es/generate/dateFns';
|
||||
|
||||
const DatePicker = generatePicker<Date>(dateFnsGenerateConfig);
|
||||
|
||||
export default DatePicker;
|
||||
```
|
||||
|
||||
## 使用 luxon
|
||||
|
||||
可以使用 [luxon](https://moment.github.io/luxon/) 代替 dayjs 并支持同样的功能，但它与 dayjs 有一些差异，我们将在下面解释：
|
||||
|
||||
### 执行
|
||||
|
||||
创建一个 `DatePicker.tsx` 文件，并定义一个基于 luxon 的 DatePicker 组件：
|
||||
|
||||
```tsx
|
||||
import generatePicker from 'antd/es/date-picker/generatePicker';
|
||||
import 'antd/es/date-picker/style/index';
|
||||
import type { DateTime } from 'luxon';
|
||||
import luxonGenerateConfig from 'rc-picker/lib/generate/luxon';
|
||||
|
||||
const DatePicker = generatePicker<DateTime>(luxonGenerateConfig);
|
||||
|
||||
export default DatePicker;
|
||||
```
|
||||
|
||||
### 与 day.js 的差异
|
||||
|
||||
luxon 用户应该悉知，它不附带用于本地化的自定义实现。 相反，它依赖于浏览器的本机 [Intl API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl)。
|
||||
|
||||
这导致了与其他日期库的一些差异， 主要区别是：
|
||||
|
||||
- 无论语言环境如何，一周的第一天总是星期一。
|
||||
- 一年中的周数有时不同（ISO 周规则用于确定它）。
|
||||
- 短工作日格式有时会因自定义区域而异（可能有 3 个字符而不是 2 个）。
|
||||
- 选定的周标签格式会略有不同（例如“2021-01”而不是“2021-1st”）。
|
||||
|
||||
可以通过调整 luxon 配置来自定义这些默认的 luxon 行为：
|
||||
|
||||
```tsx
|
||||
import generatePicker from 'antd/es/date-picker/generatePicker';
|
||||
import 'antd/es/date-picker/style/index';
|
||||
import type { DateTime } from 'luxon';
|
||||
import luxonGenerateConfig from 'rc-picker/lib/generate/luxon';
|
||||
|
||||
const customLuxonConfig = {
|
||||
...luxonGenerateConfig,
|
||||
getWeekFirstDay: (locale) => {
|
||||
// Your custom implementation goes here
|
||||
},
|
||||
};
|
||||
|
||||
const DatePicker = generatePicker<DateTime>(customLuxonConfig);
|
||||
|
||||
export default DatePicker;
|
||||
```
|
||||
|
||||
请注意，通过进行此类自定义，生成的 DatePicker 行为可能会以意想不到的方式发生变化，因此请确保你测试过一些边界情况。
|
||||
|
||||
Loading…
Reference in New Issue
Block a user