1# Date and Time Formatting 2 3## Use Cases 4 5The date and time formats vary according to countries and cultures. The difference lies in such aspects as the sequence of year, month, and day in a date and the separator of hour, minute, and second in the time. If your application needs to display the date and time, ensure that the information is displayed in line with local user habits for easy understanding. 6 7Time and date formatting includes date and time formatting, relative time formatting, and time segment formatting. Date and time formatting means to convert the date and time into a string in the specified format. Relative time formatting means to convert the time difference between a time point and another time point to the specified format, for example, 30 seconds ago or 1 day later. Time segment formatting means to convert a time segment to the specified format, for example, Wednesday or 8:00-11:30. 8 9## Constraints 10 111. The date format and time format must be set at the same time. If the date format, but not the time format, is set, only the date format is displayed. If the time format, but not the date format, is set, only the time format is displayed. 12 132. If the date or time format is specified, setting of the year, month, day, hour, minute, second, and weekday formats is not supported. If the date or time format is not set, the year, month, day, hour, minute, second, and weekday formats can be set independently. 14 15## How to Develop 16 17### Date and Time Formatting 18 19Date and time formatting is implemented by the [format](../reference/apis-localization-kit/js-apis-intl.md#format) API of [DateTimeFormat](../reference/apis-localization-kit/js-apis-intl.md#datetimeformat). The development procedure is as follows: 20 211. Import the **intl** module. 22 ```ts 23 import { intl } from '@kit.LocalizationKit'; 24 ``` 25 262. Create a **DateTimeFormat** object. 27 Pass in a locale or locale list. If a locale list is passed, the first valid locale is used. If you do not pass in any locale, the current system locale will be used. 28 You can use **DateTimeOptions** to set different date and time formats. For details, see Table 1 to Table 6. 29 30 ```ts 31 let dateFormat: intl.DateTimeFormat = new intl.DateTimeFormat(locale: string | Array<string>, options?: DateTimeOptions); 32 let dateFormat: intl.DateTimeFormat = new intl.DateTimeFormat(); // Do not pass in the locale. 33 ``` 34 353. Format the date and time. 36 ```ts 37 // Format the date and time. 38 let formattedDate: string = dateFormat.format(date: Date); 39 40 // Format the time segment. 41 let formattedDateRange: string = dateFormat.formatRange(startDate: Date, endDate: Date); 42 ``` 43 444. Obtain **DateTimeOptions** and view the configuration of formatting options. 45 ```ts 46 let options: intl.DateTimeOptions = dateFormat.resolvedOptions(); 47 ``` 48 49**Date and Time Formatting Options** 50 51The following uses the time **2021-09-17 13:04:00** and locale **zh-CN** as an example to show the values of [DateTimeOptions](../reference/apis-localization-kit/js-apis-intl.md#datetimeoptions) and corresponding display effects. 52 53**Table 1** Date display format (dateStyle) 54 55| Value| Display Effect| 56| -------- | -------- | 57| full | Friday, September 17, 2021| 58| long | September 17, 2021| 59| short | 2021/9/17 | 60| medium | September 17, 2021| 61 62**Table 2** Time display format (timeStyle) 63 64| Value| Display Effect| 65| -------- | -------- | 66| full | 13:04:00 China Standard Time| 67| long | GMT+8 13:4:00 | 68| short | 13:04 | 69| medium | 13:04:00 | 70 71**Table 3** Year display format (year) 72 73| Value| Display Effect| 74| -------- | -------- | 75| numeric | 2021 | 76| 2-digit | 21 | 77 78**Table 4** Weekday display format (weekday) 79 80| Value| Display Effect| 81| -------- | -------- | 82| long | Friday| 83| short | Fri.| 84| narrow | 5| 85 86 87**Table 5** Hour cycle (hourCycle) 88 89| Value| Display Effect| 90| -------- | -------- | 91| h11 | 13:04| 92| h12 | 1:04| 93| h23 | 1:04 | 94| h24 | 13:04 | 95 96**Development Example** 97```ts 98// Import the intl module. 99import { intl } from '@kit.LocalizationKit'; 100 101// Set the date to be formatted. 102let date = new Date(2021, 8, 17, 13, 4, 0); 103let startDate = new Date(2021, 8, 17, 13, 4, 0); 104let endDate = new Date(2021, 8, 18, 13, 4, 0); 105 106// Display complete time information. 107let dateFormat1 = new intl.DateTimeFormat('zh-CN', {dateStyle: 'full', timeStyle: 'full'}); 108let formattedDate1 = dateFormat1.format(date); // formattedDate1: Friday, September 17, 2021 at 13:04:00 China Standard Time 109 110// Display short time information in limited space. 111let dateFormat2 = new intl.DateTimeFormat('zh-CN', {dateStyle: 'short', timeStyle: 'short'}); 112let formattedDate2 = dateFormat2.format(date); // formattedDate2: 2021/9/17 13:04 113 114// Customize the display effect of year, month, day, hour, minute, and second. 115let dateFormat3 = new intl.DateTimeFormat('zh-CN', {year: 'numeric', month: '2-digit', day: '2-digit', hour: '2-digit', minute: '2-digit', second: '2-digit'}); 116let formattedDate3 = dateFormat3.format(date); // formattedDate3: 2021/09/17 13:04:00 117 118// Display only part of the time. 119let dateFormat4 = new intl.DateTimeFormat('zh-CN', {month: 'long', day: 'numeric', weekday: 'long' }); 120let formattedDate4 = dateFormat4.format(date); // formattedDate4: Friday, September 17 121 122// Customize the date and time format. 123let dateFormat5 = new intl.DateTimeFormat('zh-CN', {dateStyle: 'short', timeStyle: 'short', hourCycle: 'h11'}); 124let formattedDate5 = dateFormat5.format(date); // formattedDate5: 2021/9/17 1:04 PM 125 126// Customize the date and time format for users accustomed to other numeral systems. 127let dateFormat6 = new intl.DateTimeFormat('zh-CN', {dateStyle: 'short', timeStyle: 'short', numberingSystem: 'arab'}); 128let formattedDate6 = dateFormat6.format(date); // formattedDate6: ٢٠٢١/٩/١٧ ١٣:٠٤ 129 130// Format a time segment. 131let dataFormat7 = new intl.DateTimeFormat('en-GB'); 132let formattedDateRange = dataFormat7.formatRange(startDate, endDate); // formattedDateRange: 17/09/2021 - 18/09/2021 133 134// Obtain formatting options. 135let dataFormat8 = new intl.DateTimeFormat('en-GB', {dateStyle: 'full'}); 136let options = dataFormat8.resolvedOptions(); 137let dateStyle = options.dateStyle; // dateStyle: full 138``` 139 140### Relative Time Formatting 141 142Relative time formatting is implemented by the [format](../reference/apis-localization-kit/js-apis-intl.md#format8) API of [RelativeTimeFormat](../reference/apis-localization-kit/js-apis-intl.md#relativetimeformat8). The development procedure is as follows: 143 1441. Import the **intl** module. 145 ```ts 146 import { intl } from '@kit.LocalizationKit'; 147 ``` 148 1492. Create a **RelativeTimeFormat** object. 150 You can use **RelativeTimeFormatInputOptions** to set different output message formats and message lengths. For details, see Table 7 and Table 8. 151 ```ts 152 let relativeTimeFormat: intl.RelativeTimeFormat = new intl.RelativeTimeFormat(locale: string | Array<string>, options?: RelativeTimeFormatInputOptions); 153 ``` 154 1553. Format the relative time. **value** indicates the formatted value, and **unit** indicates the formatted unit. 156 ```ts 157 let formattedRelativeTime: string = relativeTimeFormat.format(value: number, unit: string); 158 ``` 159 1604. Format the custom relative time. 161 ```ts 162 let parts: Array<object> = relativeTimeFormat.formatToParts(value: number, unit: string); 163 ``` 164 1655. Obtain **RelativeTimeFormatInputOptions** and view the configuration of formatting options. 166 ```ts 167 let options: intl.RelativeTimeFormatInputOptions = relativeTimeFormat.resolvedOptions(); 168 ``` 169 170**Relative Time Formatting Options** 171 172The following uses the relative time **one day ago** and locales **fr-FR** and **en-GB** as an example to show different values of [RelativeTimeFormatInputOptions](../reference/apis-localization-kit/js-apis-intl.md#relativetimeformatinputoptions8) and corresponding display effects. 173 174**Table 6** Output message format (numeric) 175 176| Value| Display Effect (fr-FR)| Display Effect (en-GB)| 177| -------- | -------- | -------- | 178| always | il y a 1 jour | 1 day ago | 179| auto | hier | yesterday | 180 181Table 7 Internationalization message length (style) 182 183| Value| Display Effect (fr-FR)| Display Effect (en-GB)| 184| -------- | -------- | -------- | 185| long | il y a 1 jour | 1 day ago | 186| short | il y a 1 j | 1 day ago | 187| narrow | -1 j | 1 day ago | 188 189 190**Development Example** 191```ts 192// Import the intl module. 193import { intl } from '@kit.LocalizationKit'; 194 195// Display the relative time. 196let relativeTimeFormat1 = new intl.RelativeTimeFormat('en-GB'); 197let formattedRelativeTime1 = relativeTimeFormat1.format(-1, 'day'); // formattedRelativeTime1: 1 day ago 198 199// Display the relative time in a conversational style. 200let relativeTimeFormat2 = new intl.RelativeTimeFormat('en-GB', {numeric: "auto"}); 201let formattedRelativeTime2 = relativeTimeFormat2.format(-1, 'day'); // formattedRelativeTime2: yesterday 202 203// Use the narrow style for certain languages. 204let relativeTimeFormat3 = new intl.RelativeTimeFormat('fr-FR'); // The default style is long. 205let formattedRelativeTime3 = relativeTimeFormat3.format(-1, 'day'); // formattedRelativeTime3: il y a 1 jour 206let relativeTimeFormat4 = new intl.RelativeTimeFormat('fr-FR', {style: 'narrow'}); 207let formattedRelativeTime4 = relativeTimeFormat4.format(-1, 'day'); // formattedRelativeTime4: -1 j 208 209// Display the custom relative time for the specified locale. 210let relativeTimeFormat5 = new intl.RelativeTimeFormat('en-GB', {style: 'long'}); 211// parts: [{type: 'literal', value: 'in'}, {type: 'integer', value: 1, unit: 'day'}, {type: 'literal', value: 'day'}] 212let parts = relativeTimeFormat5.formatToParts(1, 'day'); 213 214// Obtain the formatting options of RelativeTimeFormat. 215let relativeTimeFormat6 = new intl.RelativeTimeFormat('en-GB', {numeric: 'auto'}); 216let options = relativeTimeFormat6.resolvedOptions(); 217let numeric = options.numeric; // numeric: auto 218``` 219