1# 时间日期国际化 2 3## 使用场景 4 5在不同的国家和文化中，时间和日期格式的表示方法有所不同，使用惯例的不同点包括：日期中年月日的顺序、时间中时分秒的分隔符等。若应用中需展示时间日期，要确保界面以合适的方式显示，以便用户能够理解。 6 7时间日期国际化包括时间日期格式化、相对时间格式化、时间段格式化。时间日期格式化是指将时间和日期转换为指定格式的字符串。相对时间格式化是指将一个时间点与另一个时间点之间的时间差转换为指定格式，时间差如“30秒前”、“1天后”。时间段格式化是指将一段时间转换为指定格式，时间段如“星期三”、“8:00--11:30”。 8 9## 约束与限制 10 111. 日期格式和时间格式需同时设置。若设置了时间格式，未设置日期格式，只显示时间格式；若设置了日期格式，未设置时间格式，只显示日期格式。 12 132. 若设置了时间或日期格式，则不支持设置年、月、日、时、分、秒、工作日格式；不设置时间或日期格式时，支持独立设置年、月、日、时、分、秒、工作日格式。 14 15## 开发步骤 16 17### 时间日期和相对时间格式化 18 19时间日期格式化将表示时间日期的Date对象，通过[DateTimeFormat](../reference/apis-localization-kit/js-apis-intl.md#datetimeformat)类的[format](../reference/apis-localization-kit/js-apis-intl.md#format)接口实现格式化，具体开发步骤如下。 20 211. 导入模块。 22 ```ts 23 import { intl } from '@kit.LocalizationKit'; 24 ``` 25 262. 创建DateTimeFormat对象。 27 传入单独的locale参数或locale列表，若传入列表使用第一个有效的locale创建对象。不传入locale参数时，使用系统当前的locale创建对象。 28 构造函数支持通过DateTimeOptions设置不同的时间日期格式，具体请参考表1-表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(); //不传入locale参数 33 ``` 34 353. 时间日期和相对时间格式化。 36 ```ts 37 // 时间日期格式化 38 let formattedDate: string = dateFormat.format(date: Date); 39 40 // 相对时间格式化 41 let formattedDateRange: string = dateFormat.formatRange(startDate: Date, endDate: Date); 42 ``` 43 444. 获取格式化选项，查看对象的设置信息。 45 ```ts 46 let options: intl.DateTimeOptions = dateFormat.resolvedOptions(); 47 ``` 48 49**时间日期格式化选项** 50 51以时间：2021年9月17日 13:04:00，locale: zh-CN为例，说明[DateTimeOptions](../reference/apis-localization-kit/js-apis-intl.md#datetimeoptions)不同的取值和显示结果。 52 53**表1** 日期显示格式(dateStyle) 54 55| 取值 | 显示结果 | 56| -------- | -------- | 57| full | 2021年9月17日星期五 | 58| long | 2021年9月17日 | 59| short | 2021/9/17 | 60| medium | 2021年9月17日 | 61 62**表2** 时间显示格式(timeStyle) 63 64| 取值 | 显示效果 | 65| -------- | -------- | 66| full | 中国标准时间 13:04:00 | 67| long | GMT+8 13:4:00 | 68| short | 13:04 | 69| medium | 13:04:00 | 70 71**表3** 年份显示格式(year) 72 73| 取值 | 显示效果 | 74| -------- | -------- | 75| numeric | 2021 | 76| 2-digit | 21 | 77 78**表4** 工作日显示格式(weekday) 79 80| 取值 | 显示效果 | 81| -------- | -------- | 82| long | 星期五 | 83| short | 周五 | 84| narrow | 五 | 85 86 87**表5** 时制格式(hourCycle) 88 89| 取值 | 显示效果 | 90| -------- | -------- | 91| h11 | 下午13:04 | 92| h12 | 下午1:04 | 93| h23 | 1:04 | 94| h24 | 13:04 | 95 96**开发实例** 97```ts 98// 导入模块 99import { intl } from '@kit.LocalizationKit'; 100 101// 设置要格式化的日期 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// 在软件上展示完整的时间信息 107let dateFormat1 = new intl.DateTimeFormat('zh-CN', {dateStyle: 'full', timeStyle: 'full'}); 108let formattedDate1 = dateFormat1.format(date); // formattedDate1: 2021年9月17日星期五 中国标准时间 13:04:00 109 110// 在有限的空间展示简短的时间信息 111let dateFormat2 = new intl.DateTimeFormat('zh-CN', {dateStyle: 'short', timeStyle: 'short'}); 112let formattedDate2 = dateFormat2.format(date); // formattedDate2: 2021/9/17 13:04 113 114// 自定义年月日时分秒的显示效果 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// 仅显示一部分时间 119let dateFormat4 = new intl.DateTimeFormat('zh-CN', {month: 'long', day: 'numeric', weekday: 'long' }); 120let formattedDate4 = dateFormat4.format(date); // formattedDate4: 9月17日星期五 121 122// 自定义时制格式 123let dateFormat5 = new intl.DateTimeFormat('zh-CN', {dateStyle: 'short', timeStyle: 'short', hourCycle: 'h11'}); 124let formattedDate5 = dateFormat5.format(date); // formattedDate5: 2021/9/17 下午13:04 125 126// 面向习惯于其他数字系统的用户 127let dateFormat6 = new intl.DateTimeFormat('zh-CN', {dateStyle: 'short', timeStyle: 'short', numberingSystem: 'arab'}); 128let formattedDate6 = dateFormat6.format(date); // formattedDate6: ٢٠٢١/٩/١٧ ١٣:٠٤ 129 130// 格式化时间段 131let dataFormat7 = new intl.DateTimeFormat('en-GB'); 132let formattedDateRange = dataFormat7.formatRange(startDate, endDate); // formattedDateRange: 17/09/2021 - 18/09/2021 133 134// 获取格式化选项 135let dataFormat8 = new intl.DateTimeFormat('en-GB', {dateStyle: 'full'}); 136let options = dataFormat8.resolvedOptions(); 137let dateStyle = options.dateStyle; // dateStyle: full 138``` 139 140### 相对时间格式化 141 142格式化相对时间将表示时间日期的Date对象，通过[RelativeTimeFormat](../reference/apis-localization-kit/js-apis-intl.md#relativetimeformat8)类的[format](../reference/apis-localization-kit/js-apis-intl.md#format8)接口实现格式化，具体开发步骤如下。 143 1441. 导入模块。 145 ```ts 146 import { intl } from '@kit.LocalizationKit'; 147 ``` 148 1492. 创建RelativeTimeFormat对象。 150 构造函数支持通过RelativeTimeFormatInputOptions设置不同的输出消息格式和国际化消息长度，具体请参考表7-表8。 151 ```ts 152 let relativeTimeFormat: intl.RelativeTimeFormat = new intl.RelativeTimeFormat(locale: string | Array<string>, options?: RelativeTimeFormatInputOptions); 153 ``` 154 1553. 格式化相对时间。value为格式化的数值，unit为格式化的单位。 156 ```ts 157 let formattedRelativeTime: string = relativeTimeFormat.format(value: number, unit: string); 158 ``` 159 1604. 自定义相对时间的格式化。 161 ```ts 162 let parts: Array<object> = relativeTimeFormat.formatToParts(value: number, unit: string); 163 ``` 164 1655. 获取相对时间格式化选项，查看对象的设置信息。 166 ```ts 167 let options: intl.RelativeTimeFormatInputOptions = relativeTimeFormat.resolvedOptions(); 168 ``` 169 170**相对时间格式化选项** 171 172以相对时间：一天前，locale: fr-FR和en-GB为例，说明[RelativeTimeFormatInputOptions](../reference/apis-localization-kit/js-apis-intl.md#relativetimeformatinputoptions8)不同的取值和显示结果。 173 174**表6** 输出消息格式(numeric) 175 176| 取值 | 显示效果(fr-FR) | 显示效果(en-GB) | 177| -------- | -------- | -------- | 178| always | il y a 1 jour | 1 day ago | 179| auto | hier | yesterday | 180 181**表7** 国际化消息长度(style) 182 183| 取值 | 显示效果(fr-FR) | 显示效果(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**开发实例** 191```ts 192// 导入模块 193import { intl } from '@kit.LocalizationKit'; 194 195// 显示相对时间 196let relativeTimeFormat1 = new intl.RelativeTimeFormat('en-GB'); 197let formattedRelativeTime1 = relativeTimeFormat1.format(-1, 'day'); // formattedRelativeTime1: 1 day ago 198 199// 口语化 200let relativeTimeFormat2 = new intl.RelativeTimeFormat('en-GB', {numeric: "auto"}); 201let formattedRelativeTime2 = relativeTimeFormat2.format(-1, 'day'); // formattedRelativeTime2: yesterday 202 203// 部分语言支持更为简短的显示风格 204let relativeTimeFormat3 = new intl.RelativeTimeFormat('fr-FR'); // 默认style为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// 自定义区域设置格式的相对时间格式 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// 获取RelativeTimeFormat对象的格式化选项 215let relativeTimeFormat6 = new intl.RelativeTimeFormat('en-GB', {numeric: 'auto'}); 216let options = relativeTimeFormat6.resolvedOptions(); 217let numeric = options.numeric; // numeric: auto 218``` 219