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 10. 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 13:04:00 and 00:25:00 on September 17, 2021 and locales **zh-CN** and **en** as examples to illustrate the values and display results of [DateTimeOptions](../reference/apis-localization-kit/js-apis-intl.md#datetimeoptions). 52 53**Table 1** Date display format (dateStyle) 54 55| Value | Description | 2021-09-17 13:04:00 for Locale zh-CN| 2021-09-17 13:04:00 for Locale en| 56| ------ | --------------------------------------- | ------------------------------------------ | ---------------------------------------- | 57| full | Complete date display, including the year, month, day, and week.| Friday, September 17, 2021 | Friday, September 17, 2021 | 58| long | Long date display, including the year, month, and day. | September 17, 2021 | September 17, 2021 | 59| short | Short date display, including the year, month, and day. | 2021/9/17 | 9/17/21 | 60| medium | Medium date display, including the year, month, and day. | September 17, 2021 | Sep 17, 2021 | 61 62**Table 2** Time display format (timeStyle) 63 64| Value | Description| 2021-09-17 13:04:00 for Locale zh-CN|2021-09-17 13:04:00 for Locale en| 65| ------ | ------------- | -------- | -------- | 66| full | Complete time display, including the time zone and time accurate to seconds.| 13:04:00 China Standard Time| 13:04:00 China Standard Time | 67| long | Long time display, including the time zone expressed in the format of GMT + time zone offset and time accurate to seconds.| GMT+8 13:04:00 | 13:04:00 GMT+8 | 68| short | Short time display, including hour and minute.| 13:04 | 13:04 | 69| medium | Medium time display, including hour, minute, and second.| 13:04:00 | 13:04:00 | 70 71**Table 3** Year display format (year) 72 73| Value| Description| 2021-09-17 13:04:00 for Locale zh-CN| 2021-09-17 13:04:00 for Locale en| 74| -------- | --------- | -------- | -------- | 75| numeric | Complete year| 2021| 2021 | 76| 2-digit | 2-digit year display| 21| 21 | 77 78**Table 4** Weekday display format (weekday) 79 80| Value| Description| 2021-09-17 13:04:00 for Locale zh-CN| 2021-09-17 13:04:00 for Locale en| 81| -------- | ------- | -------- | -------- | 82| long | Long weekday display| 星期五| Friday | 83| short | Short weekday display.| 周五| Fri | 84| narrow | Narrow weekday display.| 五| F | 85 86**Table 5** Hour cycle format (hourCycle) 87 88| Value| Description | 2021-09-17 13:04:00 for Locale zh-CN| 2021-09-17 00:25:00 for Locale zh-CN| 89| --- | --------------- | -------------------------------------------- | ------------------------------------------- | 90| h11 | Use of 0-11 to indicate the hour| 下午1:04 | 上午0:25 | 91| h12 | Use of 1-12 to indicate the hour| 下午1:04 | 上午12:25 | 92| h23 | Use of 0-23 to indicate the hour| 13:04 | 00:25 | 93| h24 | Use of 1-24 to indicate the hour| 13:04 | 24:25 | 94 95> **NOTE** 96> 97> The preceding table shows the display effect for different values of **hourCycle** when **dateStyle** or **timeStyle** is not set. 98 99 100**Table 6** Hour cycle format (hourCycle) 101 102| Value| Description | 2021-09-17 13:04:00 for Locale zh-CN| 2021-09-17 00:25:00 for Locale zh-CN| 103| --- | --------------- | -------------------------------------------- | ------------------------------------------- | 104| h11 | Use of 1-24 to indicate the hour| 下午13:04 | 上午24:25 | 105| h12 | Use of 1-12 to indicate the hour| 下午1:04 | 上午12:25 | 106| h23 | Use of 0-11 to indicate the hour| 1:04 | 0:25 | 107| h24 | Use of 0-23 to indicate the hour| 13:04 | 0:25 | 108 109> **NOTE** 110> 111> The preceding table shows the display effect for different values of **hourCycle** when **dateStyle** or **timeStyle** is set. 112 113**Table 7** Month format (month) 114 115| Value| Description| 2021-09-17 13:04:00 for Locale zh-CN| 2021-09-17 13:04:00 for Locale en| 116| -------- | --------- | -------- | -------- | 117| numeric | Display of the month as a number| 9月| 9 | 118| 2-digit | Display of the month in two digits| 09月| 09 | 119| long | Long month display| 九月| September | 120| short | Short month display| 9| Sep | 121| narrow | Narrow month display| 9 | S | 122 123**Table 8** Localized representation of time zone names (timeZoneName) 124 125| Value | Description | 2021-09-17 13:04:00 for Locale zh-CN| 2021-09-17 13:04:00 for Locale en| 126| ----- | ------------------ | -------------------------------------------- | ---------------------------------------- | 127| long | Long time zone name| 中国标准时间 | China Standard Time | 128| short | Short time zone name| GMT+8 | GMT+8 | 129 130**Table 9** Era display format (era) 131 132| Value| Description| 2021-09-17 13:04:00 for Locale zh-CN| 2021-09-17 13:04:00 for Locale en| 133| -------- | ------ | -------- | -------- | 134| long | Long epoch display| 公元| Anno Domini | 135| short | Short epoch display| 公元| AD | 136| narrow | Narrow epoch display| 公元| A | 137 138**Table 10** Time period format (dayPeriod) 139 140| Value| Description| 2021-09-17 13:04:00 for Locale zh-CN| 2021-09-17 13:04:00 for Locale en| 141| -------- | ------ | -------- | -------- | 142| long | Long time period display| 下午| in the afternoon | 143| short | Short time period display| 下午| in the afternoon | 144| narrow | Narrow time period display| 下午| in the afternoon | 145 146**Development Example** 147```ts 148// Import the intl module. 149import { intl } from '@kit.LocalizationKit'; 150 151let date = new Date(2021, 8, 17, 13, 4, 0); // The date and time is 2021.09.17 13:04:00. 152let startDate = new Date(2021, 8, 17, 13, 4, 0); 153let endDate = new Date(2021, 8, 18, 13, 4, 0); 154 155// Display complete time information. 156let dateFormat1 = new intl.DateTimeFormat('zh-CN', {dateStyle: 'full', timeStyle: 'full'}); 157let formattedDate1 = dateFormat1.format(date); // formattedDate1: 2021年9月17日星期五 中国标准时间 13:04:00 158 159// Display short time information in limited space. 160let dateFormat2 = new intl.DateTimeFormat('zh-CN', {dateStyle: 'short', timeStyle: 'short'}); 161let formattedDate2 = dateFormat2.format(date); // formattedDate2: 2021/9/17 13:04 162 163// Customize the display effect of year, month, day, hour, minute, and second. 164let dateFormat3 = new intl.DateTimeFormat('zh-CN', {year: 'numeric', month: '2-digit', day: '2-digit', hour: '2-digit', minute: '2-digit', second: '2-digit'}); 165let formattedDate3 = dateFormat3.format(date); // formattedDate3: 2021/09/17 13:04:00 166 167// Display only part of the time. 168let dateFormat4 = new intl.DateTimeFormat('zh-CN', {month: 'long', day: 'numeric', weekday: 'long' }); 169let formattedDate4 = dateFormat4.format(date); // formattedDate4: 9月17日星期五 170 171// Customize the date and time format. 172let dateFormat5 = new intl.DateTimeFormat('zh-CN', {dateStyle: 'short', timeStyle: 'short', hourCycle: 'h11'}); 173let formattedDate5 = dateFormat5.format(date); // formattedDate5: 2021/9/17 下午13:04 174 175// Customize the date and time format for users accustomed to other numeral systems. 176let dateFormat6 = new intl.DateTimeFormat('zh-CN', {dateStyle: 'short', timeStyle: 'short', numberingSystem: 'arab'}); 177let formattedDate6 = dateFormat6.format(date); // formattedDate6: ٢٠٢١/٩/١٧ ١٣:٠٤ 178 179// Format a time segment. 180let dataFormat7 = new intl.DateTimeFormat('en-GB'); 181let formattedDateRange = dataFormat7.formatRange(startDate, endDate); // formattedDateRange: 17/09/2021 - 18/09/2021 182 183// Obtain formatting options. 184let dataFormat8 = new intl.DateTimeFormat('en-GB', {dateStyle: 'full'}); 185let options = dataFormat8.resolvedOptions(); 186let dateStyle = options.dateStyle; // dateStyle: full 187``` 188 189### Relative Time Formatting 190 191Relative 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: 192 1931. Import the **intl** module. 194 ```ts 195 import { intl } from '@kit.LocalizationKit'; 196 ``` 197 1982. Create a **RelativeTimeFormat** object. 199 You can use **RelativeTimeFormatInputOptions** to set different output message formats and message lengths. For details, see Table 7 and Table 8. 200 ```ts 201 let relativeTimeFormat: intl.RelativeTimeFormat = new intl.RelativeTimeFormat(locale: string | Array<string>, options?: RelativeTimeFormatInputOptions); 202 ``` 203 2043. Format the relative time. **value** indicates the formatted value, and **unit** indicates the formatted unit. 205 ```ts 206 let formattedRelativeTime: string = relativeTimeFormat.format(value: number, unit: string); 207 ``` 208 2094. Format the custom relative time. 210 ```ts 211 let parts: Array<object> = relativeTimeFormat.formatToParts(value: number, unit: string); 212 ``` 213 2145. Obtain **RelativeTimeFormatInputOptions** and view the configuration of formatting options. 215 ```ts 216 let options: intl.RelativeTimeFormatInputOptions = relativeTimeFormat.resolvedOptions(); 217 ``` 218 219**Relative Time Formatting Options** 220 221The 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. 222 223**Table 11** Numeric representation (numeric) 224 225| Value | Description | Display Effect (fr-FR)| Display Effect (en-GB)| 226| ------ | -------------------------------------------- | -------------- | --------------- | 227| always | Use of a number to indicate the relative time | il y a 1 jour | 1 day ago | 228| auto | Use of a phrase or value based on the locale to indicate the relative time| hier | yesterday | 229 230**Table 12** Relative time style (style) 231 232| Value | Description | Display Effect (fr-FR)| Display Effect (en-GB)| 233| ------ | -------------------- | -------------- | -------------- | 234| long | Long relative time display | il y a 1 jour | 1 day ago | 235| short | Short relative time display | il y a 1 j | 1 day ago | 236| narrow | Narrow relative time display| -1 j | 1 day ago | 237 238 239**Development Example** 240```ts 241// Import the intl module. 242import { intl } from '@kit.LocalizationKit'; 243 244// Display the relative time. 245let relativeTimeFormat1 = new intl.RelativeTimeFormat('en-GB'); 246let formattedRelativeTime1 = relativeTimeFormat1.format(-1, 'day'); // formattedRelativeTime1: 1 day ago 247 248// Display the relative time in a conversational style. 249let relativeTimeFormat2 = new intl.RelativeTimeFormat('en-GB', {numeric: "auto"}); 250let formattedRelativeTime2 = relativeTimeFormat2.format(-1, 'day'); // formattedRelativeTime2: yesterday 251 252// Use the narrow style for certain languages. 253let relativeTimeFormat3 = new intl.RelativeTimeFormat('fr-FR'); // The default style is long. 254let formattedRelativeTime3 = relativeTimeFormat3.format(-1, 'day'); // formattedRelativeTime3: il y a 1 jour 255let relativeTimeFormat4 = new intl.RelativeTimeFormat('fr-FR', {style: 'narrow'}); 256let formattedRelativeTime4 = relativeTimeFormat4.format(-1, 'day'); // formattedRelativeTime4: -1 j 257 258// Display the custom relative time for the specified locale. 259let relativeTimeFormat5 = new intl.RelativeTimeFormat('en-GB', {style: 'long'}); 260// parts: [{type: 'literal', value: 'in'}, {type: 'integer', value: 1, unit: 'day'}, {type: 'literal', value: 'day'}] 261let parts = relativeTimeFormat5.formatToParts(1, 'day'); 262 263// Obtain the formatting options of RelativeTimeFormat. 264let relativeTimeFormat6 = new intl.RelativeTimeFormat('en-GB', {numeric: 'auto'}); 265let options = relativeTimeFormat6.resolvedOptions(); 266let numeric = options.numeric; // numeric: auto 267``` 268<!--no_check-->