1# 时间日期国际化 2 3## 使用场景 4 5在不同的国家和文化中，时间和日期格式的表示方法存在差异，具体表现在日期中年月日的顺序以及时间中时分秒的分隔符。若应用中需展示时间日期，要确保界面以合适的方式显示，以便用户能够理解。 6 7时间日期国际化包括时间日期格式化、相对时间格式化、时间段格式化。时间日期格式化是指将时间和日期转换为指定格式的字符串。相对时间格式化是指将一个时间点与另一个时间点之间的时间差转换为指定格式，例如“30秒前”、“1天后”。时间段格式化是指将一段时间转换为指定格式，例如“星期三”、“8:00 - 11:30”。 8 9## 约束与限制 10 111. dateStyle和timeStyle需同时设置。设置timeStyle但不设置dateStyle时，只显示时间；设置dateStyle但不设置timeStyle时，只显示日期。 12 132. 设置dateStyle或timeStyle时，不支持设置年、月、日、时、分、秒、工作日格式；不设置dateStyle和timeStyle时，支持独立设置年、月、日、时、分、秒、工作日格式。 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 传入单独的区域ID或区域ID列表。如果传入列表，使用第一个有效的区域ID创建对象。如果不传入区域参数，使用系统当前的区域ID创建对象。 28 构造函数支持通过DateTimeOptions设置不同的时间日期格式，具体请参考表1-表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(); // 不传入区域参数 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、2021年9月17日 00:25:00和区域ID: zh-CN、en为例，说明[DateTimeOptions](../reference/apis-localization-kit/js-apis-intl.md#datetimeoptions)的取值和显示结果。 52 53**表1** 日期显示格式(dateStyle) 54 55| 取值 | 描述 | 2021年9月17日 13:04:00，区域ID为zh-CN显示结果 | 2021年9月17日 13:04:00，区域ID为en显示结果 | 56| ------ | --------------------------------------- | ------------------------------------------ | ---------------------------------------- | 57| full | 完整的日期显示，包含年份、月份、天数和星期。| 2021年9月17日星期五 | Friday, September 17, 2021 | 58| long | 详细的日期显示，包含年份、月份和天数。 | 2021年9月17日 | September 17, 2021 | 59| short | 简短的日期显示，包含年份、月份和天数。 | 2021/9/17 | 9/17/21 | 60| medium | 中等长度日期显示，包含年份、月份和天数。 | 2021年9月17日 | Sep 17, 2021 | 61 62**表2** 时间显示格式(timeStyle) 63 64| 取值 | 描述 | 2021年9月17日 13:04:00，区域ID为zh-CN显示结果 | 2021年9月17日 13:04:00，区域ID为en显示结果 | 65| ------ | ------------- | -------- | -------- | 66| full | 完整的时间显示，包含时区和时间，时间精确到秒。 | 中国标准时间 13:04:00 | 13:04:00 China Standard Time | 67| long | 详细的时间显示，包含时区和时间，时区以GMT+时区偏移表示，时间精确到秒。 | GMT+8 13:04:00 | 13:04:00 GMT+8 | 68| short | 简短时间显示，包含小时和分钟。 | 13:04 | 13:04 | 69| medium | 中等长度时间显示，包含小时、分钟和秒。 | 13:04:00 | 13:04:00 | 70 71**表3** 年份显示格式(year) 72 73| 取值 | 描述 | 2021年9月17日 13:04:00，区域ID为zh-CN显示结果 | 2021年9月17日 13:04:00，区域ID为en显示结果 | 74| -------- | --------- | -------- | -------- | 75| numeric | 完整的年份显示。 | 2021年 | 2021 | 76| 2-digit | 用完整年份的后2位数字表示年份。 | 21年 | 21 | 77 78**表4** 星期显示格式(weekday) 79 80| 取值 | 描述 | 2021年9月17日 13:04:00，区域ID为zh-CN显示结果 | 2021年9月17日 13:04:00，区域ID为en显示结果 | 81| -------- | ------- | -------- | -------- | 82| long | 详细的星期显示。 | 星期五 | Friday | 83| short | 简短的星期显示。 | 周五 | Fri | 84| narrow | 最简短的星期显示。 | 五 | F | 85 86**表5** 时制格式(hourCycle) 87 88| 取值 | 描述 | 2021年9月17日 13:04:00，区域ID为zh-CN显示结果 | 2021年9月17日 00:25:00，区域ID为zh-CN显示结果 | 89| --- | --------------- | -------------------------------------------- | ------------------------------------------- | 90| h11 | 用0-11表示小时。 | 下午1:04 | 上午0:25 | 91| h12 | 用1-12表示小时。 | 下午1:04 | 上午12:25 | 92| h23 | 用0-23表示小时。 | 13:04 | 00:25 | 93| h24 | 用1-24表示小时。 | 13:04 | 24:25 | 94 95> **说明** 96> 97> 不设置dateStyle或timeStyle参数时，hourCycle不同取值的显示效果如上表格。 98 99 100**表6** 时制格式(hourCycle) 101 102| 取值 | 描述 | 2021年9月17日 13:04:00，区域ID为zh-CN显示结果 | 2021年9月17日 00:25:00，区域ID为zh-CN显示结果 | 103| --- | --------------- | -------------------------------------------- | ------------------------------------------- | 104| h11 | 用1-24表示小时。 | 下午13:04 | 上午24:25 | 105| h12 | 用1-12表示小时。 | 下午1:04 | 上午12:25 | 106| h23 | 用0-11表示小时。 | 1:04 | 0:25 | 107| h24 | 用0-23表示小时。 | 13:04 | 0:25 | 108 109> **说明** 110> 111> 设置dateStyle或timeStyle参数时，hourCycle不同取值的显示效果如上表格。 112 113**表7** 月份格式(month) 114 115| 取值 | 描述 | 2021年9月17日 13:04:00，区域ID为zh-CN显示结果 | 2021年9月17日 13:04:00，区域ID为en显示结果 | 116| -------- | --------- | -------- | -------- | 117| numeric | 以数字形式显示月份。 | 9月 | 9 | 118| 2-digit | 以两位数字形式显示月份。 | 09月 | 09 | 119| long | 详细的月份显示。 | 九月 | September | 120| short | 简短的月份显示。 | 9月 | Sep | 121| narrow | 最简短的月份显示。 | 9 | S | 122 123**表8** 时区名称的本地化表示(timeZoneName) 124 125| 取值 | 描述 | 2021年9月17日 13:04:00，区域ID为zh-CN显示结果 | 2021年9月17日 13:04:00，区域ID为en显示结果 | 126| ----- | ------------------ | -------------------------------------------- | ---------------------------------------- | 127| long | 详细的时区名称显示。 | 中国标准时间 | China Standard Time | 128| short | 简短的时区名称显示。 | GMT+8 | GMT+8 | 129 130**表9** 纪元的显示格式(era) 131 132| 取值 | 描述 | 2021年9月17日 13:04:00，区域ID为zh-CN显示效果 | 2021年9月17日 13:04:00，区域ID为en显示效果 | 133| -------- | ------ | -------- | -------- | 134| long | 详细的纪元显示。 | 公元 | Anno Domini | 135| short | 简短的纪元显示。 | 公元 | AD | 136| narrow | 最简短的纪元显示。 | 公元 | A | 137 138**表10** 时段的显示格式(dayPeriod) 139 140| 取值 | 描述 | 2021年9月17日 13:04:00，区域ID为zh-CN显示效果 | 2021年9月17日 13:04:00，区域ID为en显示效果 | 141| -------- | ------ | -------- | -------- | 142| long | 详细的时段表述。 | 下午 | in the afternoon | 143| short | 简短的时段表示。 | 下午 | in the afternoon | 144| narrow | 最简短的时段表示。 | 下午 | in the afternoon | 145 146**开发实例** 147```ts 148// 导入模块 149import { intl } from '@kit.LocalizationKit'; 150 151let date: Date = new Date(2021, 8, 17, 13, 4, 0); // 时间日期为2021.09.17 13:04:00 152let startDate: Date = new Date(2021, 8, 17, 13, 4, 0); 153let endDate: Date = new Date(2021, 8, 18, 13, 4, 0); 154 155// 在软件上展示完整的时间信息 156let fullFormat: intl.DateTimeFormat = new intl.DateTimeFormat('zh-CN', { dateStyle: 'full', timeStyle: 'full' }); 157let formattedDate: string = fullFormat.format(date); // formattedDate = '2021年9月17日星期五 中国标准时间 13:04:00' 158 159// 在有限的空间展示简短的时间信息 160let shortFormat: intl.DateTimeFormat = new intl.DateTimeFormat('zh-CN', { dateStyle: 'short', timeStyle: 'short' }); 161formattedDate = shortFormat.format(date); // formattedDate = '2021/9/17 13:04' 162 163// 自定义年月日时分秒的显示效果 164let customFormat: intl.DateTimeFormat = new intl.DateTimeFormat('zh-CN', 165 { 166 year: 'numeric', 167 month: '2-digit', 168 day: '2-digit', 169 hour: '2-digit', 170 minute: '2-digit', 171 second: '2-digit' 172 }); 173formattedDate = customFormat.format(date); // formattedDate = '2021/09/17 13:04:00' 174 175// 仅显示一部分时间 176let partialFormat: intl.DateTimeFormat = new intl.DateTimeFormat('zh-CN', 177 { 178 month: 'long', 179 day: 'numeric', 180 weekday: 'long' 181 }); 182formattedDate = partialFormat.format(date); // formattedDate = '9月17日星期五' 183 184// 自定义时制格式 185let hourCycleFormat: intl.DateTimeFormat = new intl.DateTimeFormat('zh-CN', 186 { 187 dateStyle: 'short', 188 timeStyle: 'short', 189 hourCycle: 'h11' 190 }); 191formattedDate = hourCycleFormat.format(date); // formattedDate = '2021/9/17 下午13:04' 192 193// 面向习惯于其他数字系统的用户 194let numberingSystemFormat: intl.DateTimeFormat = new intl.DateTimeFormat('zh-CN', 195 { 196 dateStyle: 'short', 197 timeStyle: 'short', 198 numberingSystem: 'arab' 199 }); 200formattedDate = numberingSystemFormat.format(date); // formattedDate = '٢٠٢١/٩/١٧ ١٣:٠٤' 201 202// 格式化时间段 203let dateRangeFormat: intl.DateTimeFormat = new intl.DateTimeFormat('en-GB'); 204let formattedDateRange: string = 205 dateRangeFormat.formatRange(startDate, endDate); // formattedDateRange = '17/09/2021 - 18/09/2021' 206 207// 获取格式化选项 208let dateFormat: intl.DateTimeFormat = new intl.DateTimeFormat('en-GB', { dateStyle: 'full' }); 209let options: intl.DateTimeOptions = dateFormat.resolvedOptions(); 210let dateStyle: string | undefined = options.dateStyle; // dateStyle = 'full' 211``` 212 213### 相对时间格式化 214 215格式化相对时间将表示时间日期的Date对象，通过[RelativeTimeFormat](../reference/apis-localization-kit/js-apis-intl.md#relativetimeformat8)类的[format](../reference/apis-localization-kit/js-apis-intl.md#format8)接口实现格式化，具体开发步骤如下： 216 2171. 导入模块。 218 ```ts 219 import { intl } from '@kit.LocalizationKit'; 220 ``` 221 2222. 创建RelativeTimeFormat对象。 223 构造函数支持通过RelativeTimeFormatInputOptions设置不同的输出消息格式和国际化消息长度，具体请参考表7和表8。 224 ```ts 225 let relativeTimeFormat: intl.RelativeTimeFormat = new intl.RelativeTimeFormat(locale: string | Array<string>, options?: RelativeTimeFormatInputOptions); 226 ``` 227 2283. 格式化相对时间。value为格式化的数值，unit为格式化的单位。 229 ```ts 230 let formattedRelativeTime: string = relativeTimeFormat.format(value: number, unit: string); 231 ``` 232 2334. 自定义相对时间的格式化。 234 ```ts 235 let parts: Array<object> = relativeTimeFormat.formatToParts(value: number, unit: string); 236 ``` 237 2385. 获取相对时间格式化选项，查看对象的设置信息。 239 ```ts 240 let options: intl.RelativeTimeFormatInputOptions = relativeTimeFormat.resolvedOptions(); 241 ``` 242 243**相对时间格式化选项** 244 245以相对时间：一天前，区域ID: fr-FR和en-GB为例，说明[RelativeTimeFormatInputOptions](../reference/apis-localization-kit/js-apis-intl.md#relativetimeformatinputoptions8)不同的取值和显示结果。 246 247**表11** 数值表示(numeric) 248 249| 取值 | 描述 | 显示效果(fr-FR) | 显示效果(en-GB) | 250| ------ | -------------------------------------------- | -------------- | --------------- | 251| always | 使用数值表示相对时间。 | il y a 1 jour | 1 day ago | 252| auto | 根据区域ID自适应选择短语或数值表示相对时间。 | hier | yesterday | 253 254**表12** 相对时间样式(style) 255 256| 取值 | 描述 | 显示效果(fr-FR) | 显示效果(en-GB) | 257| ------ | -------------------- | -------------- | -------------- | 258| long | 详细的相对时间显示。 | il y a 1 jour | 1 day ago | 259| short | 简短的相对时间显示。 | il y a 1 j | 1 day ago | 260| narrow | 最简短的相对时间显示。 | -1 j | 1 day ago | 261 262 263**开发实例** 264```ts 265// 导入模块 266import { intl } from '@kit.LocalizationKit'; 267 268// 显示相对时间 269let relativeTimeFormat: intl.RelativeTimeFormat = new intl.RelativeTimeFormat('en-GB'); 270let formattedRelativeTime: string = relativeTimeFormat.format(-1, 'day'); // formattedRelativeTime = '1 day ago' 271 272// 口语化 273let numericAutoFormat: intl.RelativeTimeFormat = new intl.RelativeTimeFormat('en-GB', { numeric: 'auto' }); 274formattedRelativeTime = numericAutoFormat.format(-1, 'day'); // formattedRelativeTime = 'yesterday' 275 276// 部分语言支持更为简短的显示风格 277let longFormat: intl.RelativeTimeFormat = new intl.RelativeTimeFormat('fr-FR'); // 默认style为long 278formattedRelativeTime = longFormat.format(-1, 'day'); // formattedRelativeTime = 'il y a 1 jour' 279let narrowFormat: intl.RelativeTimeFormat = new intl.RelativeTimeFormat('fr-FR', { style: 'narrow' }); 280formattedRelativeTime = narrowFormat.format(-1, 'day'); // formattedRelativeTime = '-1 j' 281 282// 自定义区域设置格式的相对时间格式 283let partFormat: intl.RelativeTimeFormat = new intl.RelativeTimeFormat('en-GB', { style: 'long' }); 284// parts = [{type: 'literal', value: 'in'}, {type: 'integer', value: 1, unit: 'day'}, {type: 'literal', value: 'day'}] 285let parts: object[] = partFormat.formatToParts(1, 'day'); 286 287// 获取RelativeTimeFormat对象的格式化选项 288let resolvedFormat: intl.RelativeTimeFormat = new intl.RelativeTimeFormat('en-GB', { numeric: 'auto' }); 289let options: intl.RelativeTimeFormatResolvedOptions = resolvedFormat.resolvedOptions(); 290let numeric: string = options.numeric; // numeric = 'auto' 291``` 292