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 101let date = new Date(2021, 8, 17, 13, 4, 0); // The date and time is 2021.09.17 13:04:00. 102let startDate = new Date(2021, 8, 17, 13, 4, 0); 103let endDate = new Date(2021, 8, 18, 13, 4, 0); 104 105// Display complete time information. 106let dateFormat1 = new intl.DateTimeFormat('zh-CN', {dateStyle: 'full', timeStyle: 'full'}); 107let formattedDate1 = dateFormat1.format(date); // formattedDate1: Friday, September 17, 2021 at 13:04:00 China Standard Time 108 109// Display short time information in limited space. 110let dateFormat2 = new intl.DateTimeFormat('zh-CN', {dateStyle: 'short', timeStyle: 'short'}); 111let formattedDate2 = dateFormat2.format(date); // formattedDate2: 2021/9/17 13:04 112 113// Customize the display effect of year, month, day, hour, minute, and second. 114let dateFormat3 = new intl.DateTimeFormat('zh-CN', {year: 'numeric', month: '2-digit', day: '2-digit', hour: '2-digit', minute: '2-digit', second: '2-digit'}); 115let formattedDate3 = dateFormat3.format(date); // formattedDate3: 2021/09/17 13:04:00 116 117// Display only part of the time. 118let dateFormat4 = new intl.DateTimeFormat('zh-CN', {month: 'long', day: 'numeric', weekday: 'long' }); 119let formattedDate4 = dateFormat4.format(date); // formattedDate4: Friday, September 17 120 121// Customize the date and time format. 122let dateFormat5 = new intl.DateTimeFormat('zh-CN', {dateStyle: 'short', timeStyle: 'short', hourCycle: 'h11'}); 123let formattedDate5 = dateFormat5.format(date); // formattedDate5: 2021/9/17 1:04 PM 124 125// Customize the date and time format for users accustomed to other numeral systems. 126let dateFormat6 = new intl.DateTimeFormat('zh-CN', {dateStyle: 'short', timeStyle: 'short', numberingSystem: 'arab'}); 127let formattedDate6 = dateFormat6.format(date); // formattedDate6: ٢٠٢١/٩/١٧ ١٣:٠٤ 128 129// Format a time segment. 130let dataFormat7 = new intl.DateTimeFormat('en-GB'); 131let formattedDateRange = dataFormat7.formatRange(startDate, endDate); // formattedDateRange: 17/09/2021 - 18/09/2021 132 133// Obtain formatting options. 134let dataFormat8 = new intl.DateTimeFormat('en-GB', {dateStyle: 'full'}); 135let options = dataFormat8.resolvedOptions(); 136let dateStyle = options.dateStyle; // dateStyle: full 137``` 138 139### Relative Time Formatting 140 141Relative 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: 142 1431. Import the **intl** module. 144 ```ts 145 import { intl } from '@kit.LocalizationKit'; 146 ``` 147 1482. Create a **RelativeTimeFormat** object. 149 You can use **RelativeTimeFormatInputOptions** to set different output message formats and message lengths. For details, see Table 7 and Table 8. 150 ```ts 151 let relativeTimeFormat: intl.RelativeTimeFormat = new intl.RelativeTimeFormat(locale: string | Array<string>, options?: RelativeTimeFormatInputOptions); 152 ``` 153 1543. Format the relative time. **value** indicates the formatted value, and **unit** indicates the formatted unit. 155 ```ts 156 let formattedRelativeTime: string = relativeTimeFormat.format(value: number, unit: string); 157 ``` 158 1594. Format the custom relative time. 160 ```ts 161 let parts: Array<object> = relativeTimeFormat.formatToParts(value: number, unit: string); 162 ``` 163 1645. Obtain **RelativeTimeFormatInputOptions** and view the configuration of formatting options. 165 ```ts 166 let options: intl.RelativeTimeFormatInputOptions = relativeTimeFormat.resolvedOptions(); 167 ``` 168 169**Relative Time Formatting Options** 170 171The 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. 172 173**Table 6** Output message format (numeric) 174 175| Value| Display Effect (fr-FR)| Display Effect (en-GB)| 176| -------- | -------- | -------- | 177| always | il y a 1 jour | 1 day ago | 178| auto | hier | yesterday | 179 180Table 7 Internationalization message length (style) 181 182| Value| Display Effect (fr-FR)| Display Effect (en-GB)| 183| -------- | -------- | -------- | 184| long | il y a 1 jour | 1 day ago | 185| short | il y a 1 j | 1 day ago | 186| narrow | -1 j | 1 day ago | 187 188 189**Development Example** 190```ts 191// Import the intl module. 192import { intl } from '@kit.LocalizationKit'; 193 194// Display the relative time. 195let relativeTimeFormat1 = new intl.RelativeTimeFormat('en-GB'); 196let formattedRelativeTime1 = relativeTimeFormat1.format(-1, 'day'); // formattedRelativeTime1: 1 day ago 197 198// Display the relative time in a conversational style. 199let relativeTimeFormat2 = new intl.RelativeTimeFormat('en-GB', {numeric: "auto"}); 200let formattedRelativeTime2 = relativeTimeFormat2.format(-1, 'day'); // formattedRelativeTime2: yesterday 201 202// Use the narrow style for certain languages. 203let relativeTimeFormat3 = new intl.RelativeTimeFormat('fr-FR'); // The default style is long. 204let formattedRelativeTime3 = relativeTimeFormat3.format(-1, 'day'); // formattedRelativeTime3: il y a 1 jour 205let relativeTimeFormat4 = new intl.RelativeTimeFormat('fr-FR', {style: 'narrow'}); 206let formattedRelativeTime4 = relativeTimeFormat4.format(-1, 'day'); // formattedRelativeTime4: -1 j 207 208// Display the custom relative time for the specified locale. 209let relativeTimeFormat5 = new intl.RelativeTimeFormat('en-GB', {style: 'long'}); 210// parts: [{type: 'literal', value: 'in'}, {type: 'integer', value: 1, unit: 'day'}, {type: 'literal', value: 'day'}] 211let parts = relativeTimeFormat5.formatToParts(1, 'day'); 212 213// Obtain the formatting options of RelativeTimeFormat. 214let relativeTimeFormat6 = new intl.RelativeTimeFormat('en-GB', {numeric: 'auto'}); 215let options = relativeTimeFormat6.resolvedOptions(); 216let numeric = options.numeric; // numeric: auto 217``` 218