1# Intl开发指导 2 3本模块提供基础的应用国际化能力，包括时间日期格式化、数字格式化、排序等，相关接口在ECMA 402标准中定义。更多接口和使用方式请见[Intl](../reference/apis/js-apis-intl.md)。 4 5[I18N](i18n-guidelines.md)模块提供其他非ECMA 402定义的国际化接口，与本模块共同使用可提供完整地国际化支持能力。 6 7## 设置区域信息 8 9调用[Locale](../reference/apis/js-apis-intl.md#locale)的相关接口实现最大化区域信息或最小化区域信息。 10 11### 接口说明 12 13| 类名 | 接口名称 | 描述 | 14| -------- | -------- | -------- | 15| Locale | constructor()<sup>8+</sup> | 实例化Locale对象。 | 16| Locale | constructor(locale:string,options?:LocaleOptions) | 基于locale参数及其选项实例化Locale对象。 | 17| Locale | toString():string | 将Locale信息转换为字符串。 | 18| Locale | maximize():Locale | 最大化区域信息。 | 19| Locale | minimize():Locale | 最小化区域信息。 | 20 21### 开发步骤 22 231. 导入Intl模块。 24 25 未正确导入包可能会产生不明确的接口行为。 26 27 ```js 28 import Intl from '@ohos.intl'; 29 ``` 30 312. 实例化Locale对象。 32 33 使用Locale的构造函数创建Locale对象，该方法接收一个表示Locale的字符串及可选的[属性](../reference/apis/js-apis-intl.md#localeoptions)列表（intl为导入的模块名）。 34 35 表示Locale的字符串参数可以分为以下四部分：语言、脚本、地区、扩展参数。各个部分按照顺序使用中划线“-”进行连接。 36 - 语言：必选，使用2个或3个小写英文字母表示（可参考ISO-639标准），例如英文使用“en”表示，中文使用“zh”表示。 37 - 脚本：可选，使用4个英文字母表示，其中首字母需要大写，后面3个使用小写字母（可参考ISO-15924）。例如，中文繁体使用脚本“Hant”表示，中文简体使用脚本“Hans”表示。 38 - 国家或地区：可选，使用两个大写字母表示（可参考ISO-3166），例如中国使用“CN”表示，美国使用“US”表示； 39 - 扩展参数：可选，由key和value两部分组成，目前支持以下扩展参数（可参考BCP 47扩展）。各个扩展参数之间没有严格的顺序，使用“-key-value”的格式书写。扩展参数整体使用“-u”连接到语言、脚本、地区后面。例如“zh-u-nu-latn-ca-chinese”表示使用“latn”数字系统，“chinese”日历系统。扩展参数也可以通过第二个参数传入。 40 | 扩展参数ID | 扩展参数说明 | 41 | -------- | -------- | 42 | ca | 表示日历系统 | 43 | co | 表示排序规则 | 44 | hc | 表示守时惯例 | 45 | nu | 表示数字系统 | 46 | kn | 表示字符串排序、比较时是否考虑数字的实际值 | 47 | kf | 表示字符串排序、比较时是否考虑大小写 | 48 49 50 ```js 51 let locale = "zh-CN"; 52 let options = {caseFirst: "false", calendar: "chinese", collation: "pinyin"}; 53 let localeObj = new Intl.Locale(locale, options); 54 ``` 55 563. 获取Locale的字符串表示。 57 58 调用toString方法来获取Locale对象的字符串表示，其中包括了语言、区域及其他选项信息。 59 60 ```js 61 let localeStr = localeObj.toString(); // localeStr = "zh-CN-u-ca-chinese-co-pinyin-kf-false 62 ``` 63 644. 最大化区域信息。 65 66 调用maximize方法来最大化区域信息，即当缺少脚本与地区信息时，对其进行补全。 67 68 ```js 69 let maximizedLocale = localeObj.maximize(); 70 let maximizedLocaleStr = maximizedLocale.toString(); // localeStr = "zh-Hans-CN-u-ca-chinese-co-pinyin-kf-false 71 ``` 72 735. 最小化区域信息。 74 75 调用minimize方法来最小化区域信息，即当存在脚本与地区信息时，对其进行删除。 76 77 ```js 78 let minimizedLocale = localeObj.minimize(); 79 let minimizedLocaleStr = minimizedLocale.toString(); // zh-u-ca-chinese-co-pinyin-kf-false 80 ``` 81 82## 格式化日期时间 83 84调用日期时间格式化[DateTimeFormat](../reference/apis/js-apis-intl.md#datetimeformat)的接口，实现针对特定Locale的日期格式化以及时间段格式化功能。 85 86### 接口说明 87 88| 类名 | 接口名称 | 描述 | 89| -------- | -------- | -------- | 90| DateTimeFormat | constructor()<sup>8+</sup> | 创建日期时间格式化对象。 | 91| DateTimeFormat | constructor(locale:string\|Array<string>,options?:DateTimeOptions) | 创建日期时间格式化对象，并设置提供的Locale和格式化相关属性。 | 92| DateTimeFormat | format(date:Date):string | 依据DateTimeFormat对象的Locale及其他格式化属性，计算日期时间的格式化表示。 | 93| DateTimeFormat | formatRange(startDate:Date,endDate:Date):string | 依据DateTimeFormat对象的Locale及其他格式化属性，计算时间段的格式化表示。 | 94| DateTimeFormat | resolvedOptions():DateTimeOptions | 获取DateTimeFormat对象的相关属性。 | 95 96### 开发步骤 97 981. 导入Intl模块。 99 100 未正确导入包可能会产生不明确的接口行为。 101 102 ```js 103 import Intl from '@ohos.intl'; 104 ``` 105 1062. 实例化日期时间格式化对象。 107 108 一种方法是使用DateTimeFormat提供的默认构造函数，通过访问系统语言和地区设置，获取系统默认Locale，并将其作为DateTimeFormat对象内部的Locale。 109 110 ```js 111 let dateTimeFormat = new Intl.DateTimeFormat(); 112 ``` 113 114 另一种方法是使用开发者提供的Locale和格式化参数来创建日期时间格式化对象。其中，格式化参数是可选的，完整的格式化参数列表见[DateTimeOptions](../reference/apis/js-apis-intl.md#datetimeoptions9)。 115 116 ```js 117 let options = {dateStyle: "full", timeStyle: "full"}; 118 let dateTimeFormat = new Intl.DateTimeFormat("zh-CN", options); 119 ``` 120 1213. 格式化日期时间。 122 123 使用DateTimeFormat的format方法对一个Date对象进行格式化，该方法会返回一个字符串作为格式化的结果。 124 125 ```js 126 let options = {dateStyle: "full", timeStyle: "full"}; 127 let dateTimeFormat = new Intl.DateTimeFormat("zh-CN", options); 128 let date = new Date(2022, 12, 12, 12, 12, 12); 129 let formatResult = dateTimeFormat.format(date); // formatResult = "2023年1月12日星期四 中国标准时间 下午12:12:12" 130 ``` 131 1324. 格式化时间段。 133 134 使用DateTimeFormat的formatRange方法对一个时间段进行格式化。该方法需要传入两个Date对象，分别表示时间段的起止日期，返回一个字符串作为格式化的结果。 135 136 ```js 137 let startDate = new Date(2021, 11, 17, 3, 24, 0); 138 let endDate = new Date(2021, 11, 18, 3, 24, 0); 139 let datefmt = new Intl.DateTimeFormat("en-GB"); 140 let formatRangeResult = datefmt.formatRange(startDate, endDate); // formatRangeResult = "17/12/2021-18/12/2021" 141 ``` 142 1435. 访问日期时间格式化对象的相关属性。 144 145 DateTimeFormat的resolvedOptions方法会返回一个对象，该对象包含了DateTimeFormat对象的所有相关属性及其值。 146 147 ```js 148 let options = {dateStyle: "full", timeStyle: "full"}; 149 let dateTimeFormat = new Intl.DateTimeFormat("zh-CN", options); 150 let resolvedOptions = dateTimeFormat.resolvedOptions(); // resolvedOptions = {"locale": "zh-CN", "calendar": "gregorian", "dateStyle":"full", "timeStyle":"full", "timeZone": "CST"} 151 ``` 152 153## 数字格式化 154 155调用数字格式化[NumberFormat](../reference/apis/js-apis-intl.md#numberformat)的接口，实现针对特定Locale的数字格式化功能。 156 157### 接口说明 158 159| 类名 | 接口名称 | 描述 | 160| -------- | -------- | -------- | 161| NumberFormat | constructor()<SUP>8+</SUP> | 创建数字格式化对象。 | 162| NumberFormat | constructor(locale:string\|Array<string>,options?:NumberOptions) | 创建数字格式化对象，并设置提供的locale和格式化相关属性。 | 163| NumberFormat | format(number:number):string | 依据NumberFormat对象的Locale及其他格式化属性，计算数字的格式化表示。 | 164| NumberFormat | resolvedOptions():NumberOptions | 获取NumberFormat对象的相关属性。 | 165 166### 开发步骤 167 1681. 导入Intl模块。 169 170 未正确导入包可能会产生不明确的接口行为。 171 172 ```js 173 import Intl from '@ohos.intl'; 174 ``` 175 1762. 实例化数字格式化对象。 177 178 一种方法是使用NumberFormat提供的默认构造函数，通过访问系统的语言和地区以获取系统默认Locale并进行设置（intl为导入的模块名）。 179 180 ```js 181 let numberFormat = new Intl.NumberFormat(); 182 ``` 183 184 另一种方法是使用开发者提供的Locale和格式化参数来创建数字格式化对象。其中，格式化参数是可选的，完整的格式化参数列表参见[NumberOptions](../reference/apis/js-apis-intl.md#numberoptions9)。 185 186 ```js 187 let options = {compactDisplay: "short", notation: "compact"}; 188 let numberFormat = new Intl.NumberFormat("zh-CN", options); 189 ``` 190 1913. 数字格式化。 192 193 使用NumberFormat的format方法对传入的数字进行格式化。该方法返回一个字符串作为格式化的结果。 194 195 ```js 196 let options = {compactDisplay: "short", notation: "compact"}; 197 let numberFormat = new Intl.NumberFormat("zh-CN", options); 198 let number = 1234.5678; 199 let formatResult = numberFormat.format(number); // formatResult = "1235" 200 ``` 201 2024. 访问数字格式化对象的相关属性。 203 204 NumberFormat的resolvedOptions方法会返回一个对象，该对象包含了NumberFormat对象的所有相关属性及其值。 205 206 ```js 207 let options = {compactDisplay: "short", notation: "compact"}; 208 let numberFormat = new Intl.NumberFormat("zh-CN", options); 209 let resolvedOptions = numberFormat.resolvedOptions(); // resolvedOptions = {"locale": "zh-CN", "compactDisplay": "short", "notation": "compact", "numberingSystem": "Latn"} 210 ``` 211 212## 字符串排序 213 214不同区域的用户对于字符串排序具有不同的需求。调用字符串排序[Collator](../reference/apis/js-apis-intl.md#collator8)的接口，实现针对特定Locale的字符串排序功能。 215 216### 接口说明 217 218| 类名 | 接口名称 | 描述 | 219| -------- | -------- | -------- | 220| Collator | constructor()<sup>8+</sup> | 创建排序对象。 | 221| Collator | constructor(locale:string\|Array<string>,options?:CollatorOptions)<sup>8+</sup> | 创建排序对象，并设置提供的locale和其他相关属性。 | 222| Collator | compare(first:string,second:string):number<sup>8+</sup> | 依据排序对象的Locale及其属性，计算两个字符串的比较结果。 | 223| Collator | resolvedOptions():CollatorOptions<sup>8+</sup> | 获取排序对象的相关属性。 | 224 225### 开发步骤 226 2271. 导入Intl模块。 228 229 未正确导入包可能会产生不明确的接口行为。 230 231 ```js 232 import Intl from '@ohos.intl'; 233 ``` 234 2352. 实例化排序对象。 236 237 一种方法是使用Collator提供的默认构造函数，通过访问系统的语言和地区以获取系统默认Locale并进行设置（intl为导入的模块名）。 238 239 ```js 240 let collator = new Intl.Collator(); 241 ``` 242 243 另一种方法是使用开发者提供的Locale和其他相关参数来创建Collator对象，完整的参数列表参见[CollatorOptions](../reference/apis/js-apis-intl.md#collatoroptions9)。 244 其中，sensitivity参数用于控制哪些级别的差异会被用于比较两个字符串。取值"base"表示，仅比较字符本身，不考虑重音符号、大小写差异。例如，'a' != 'b'，'a' == 'á'，'a' == 'A'。取值"accent"表示考虑重音符号，不考虑大小写的差异。例如，'a' != 'b'，'a' != 'á'，'a' == 'A'。取值"case"表示考虑大小写的差异，不考虑重音符号的差异。例如，'a' != 'b'，'a' == 'á'，'a' != 'A'。取值"variant"表示考虑重音符号、大小写等方面差异。例如'a' != 'b'，'a' != 'á'，'a' != 'A'。 245 246 ```js 247 let collator= new Intl.Collator("zh-CN", {localeMatcher: "best fit", usage: "sort", sensitivity: "case"}); 248 ``` 249 2503. 比较字符串。 251 252 使用Collator的compare方法对传入的两个字符串进行比较。该方法返回一个数值作为比较的结果，返回-1表示第一个字符串小于第二个字符串，返回1表示第一个字符大于第二个字符串，返回0表示两个字符串相同。基于两个字符串的比较结果，开发者可以字符串集合进行排序。 253 254 ```js 255 let collator= new Intl.Collator("zh-CN", {localeMatcher: "best fit", usage: "sort", sensitivity: "case"}); 256 let str1 = "first string"; 257 let str2 = "second string"; 258 let compareResult = collator.compare(str1, str2); // compareResult = -1 259 str1 = "first"; 260 str2 = "First"; 261 compareResult = collator.compare(str1, str2); // compareResult = -1 262 ``` 263 2644. 访问排序对象的相关属性。 265 266 Collator的resolvedOptions方法会返回一个对象，该对象包含了Collator对象的所有相关属性及其值。 267 268 ```js 269 let collator= new Intl.Collator("zh-CN", {localeMatcher: "best fit", usage: "sort"}); 270 let options = collator.resolvedOptions(); // options = {"localeMatcher": "best fit", "locale": "zh-CN", "usage": "sort", "sensitivity": "variant", "ignorePunctuation": "false", "numeric": false, "caseFirst": "false", "collation": "default"} 271 ``` 272 273## 判定单复数类别 274 275在一些语言的语法中，当数字后面存在名词时，名词需要根据数字的值采用不同的形式。调用单复数[PluralRules](../reference/apis/js-apis-intl.md#pluralrules8)的接口，可以实现针对特定Locale计算数字单复数类别的功能，从而选择合适的名词单复数表示。 276 277### 接口说明 278 279| 类名 | 接口名称 | 描述 | 280| -------- | -------- | -------- | 281| PluralRules | constructor()<sup>8+</sup> | 创建单复数对象。 | 282| PluralRules | constructor(locale:string\|Array<string>,options?:PluralRulesOptions)<sup>8+</sup> | 创建单复数对象，并设置提供的locale和其他相关属性。 | 283| PluralRules | select(n:number):string<sup>8+</sup> | 依据单复数对象的Locale及其他格式化属性，计算数字的单复数类别。 | 284 285 286### 开发步骤 287 2881. 导入Intl模块。 289 290 未正确导入包可能会产生不明确的接口行为。 291 292 ```js 293 import Intl from '@ohos.intl'; 294 ``` 295 2962. 实例化单复数对象。 297 298 一种方法是使用PluralRules提供的默认构造函数，通过访问系统的语言和地区以获取系统默认Locale并进行设置（intl为导入的模块名）。 299 300 ```js 301 let pluralRules = new Intl.PluralRules(); 302 ``` 303 304 另一种方法是使用开发者提供的Locale和其他相关参数来创建单复数对象。完整的参数列表参见[PluralRulesOptions](../reference/apis/js-apis-intl.md#pluralrulesoptions9)。 305 306 ```js 307 let pluralRules = new Intl.PluralRules("zh-CN", {localeMatcher: "best fit", type: "cardinal"}); 308 ``` 309 3103. 计算数字单复数类别。 311 312 使用PluralRules的select方法计算传入数字的单复数类别。该方法返回一个字符串作为传入数字的类别，包括："zero", "one", "two", "few", "many", "other"六个类别。 313 314 ```js 315 let pluralRules = new Intl.PluralRules("zh-CN", {localeMatcher: "best fit", type: "cardinal"}); 316 let number = 1234.5678; 317 let categoryResult = pluralRules.select(number); // categoryResult = "other" 318 ``` 319 320## 相对时间格式化 321 322调用相对时间格式化[RelativeTimeFormat](../reference/apis/js-apis-intl.md#relativetimeformat8)的接口，实现针对特定Locale的相对时间格式化功能。 323 324### 接口说明 325 326| 类名 | 接口名称 | 描述 | 327| -------- | -------- | -------- | 328| RelativeTimeFormat | constructor()<sup>8+</sup> | 创建相对时间格式化对象。 | 329| RelativeTimeFormat | constructor(locale:string\|Array<string>,options?:RelativeTimeFormatInputOptions)<sup>8+</sup> | 创建相对时间格式化对象，并设置提供的locale和格式化相关属性。 | 330| RelativeTimeFormat | format(value:number,unit:string):string<sup>8+</sup> | 依据相对时间格式化对象的Locale及其他格式化属性，计算相对时间的格式化表示。 | 331| RelativeTimeFormat | formatToParts(value:number,unit:string):Array<object><sup>8+</sup> | 依据相对时间格式化对象的Locale及其他格式化属性，返回相对时间格式化表示的各个部分。 | 332| RelativeTimeFormat | resolvedOptions():RelativeTimeFormatResolvedOptions<sup>8+</sup> | 获取相对时间格式化对象的相关属性。 | 333 334### 开发步骤 335 3361. 导入Intl模块。 337 338 未正确导入包可能会产生不明确的接口行为。 339 340 ```js 341 import Intl from '@ohos.intl'; 342 ``` 343 3442. 实例化相对时间格式化对象。 345 346 一种方法是使用RelativeTimeFormat提供的默认构造函数，通过访问系统的语言和地区以获取系统默认Locale并进行设置（intl为导入的模块名）。 347 348 ```js 349 let relativeTimeFormat = new Intl.RelativeTimeFormat(); 350 ``` 351 352 另一种方法是使用开发者提供的Locale和格式化参数来创建相对时间格式化对象。其中，格式化参数是可选的，完整的参数列表参见[ RelativeTimeFormatInputOptions](../reference/apis/js-apis-intl.md#relativetimeformatinputoptions9)。 353 354 ```js 355 let relativeTimeFormat = new Intl.RelativeTimeFormat("zh-CN", {numeric: "always", style: "long"}); 356 ``` 357 3583. 相对时间格式化。 359 360 使用RelativeTimeFormat的format方法对相对时间进行格式化。方法接收一个表示相对时间长度的数值和表示单位的字符串，其中单位包括："year", "quarter", "month", "week", "day", "hour", "minute", "second"。方法返回一个字符串作为格式化的结果。 361 362 ```js 363 let relativeTimeFormat = new Intl.RelativeTimeFormat("zh-CN", {numeric: "always", style: "long"}); 364 let number = 2; 365 let unit = "year"; 366 let formatResult = relativeTimeFormat.format(number, unit); // 2年后 367 ``` 368 3694. 获取相对时间格式化结果的各个部分。 370 371 获取相对时间格式化结果的各个部分，从而自定义格式化结果。 372 373 ```js 374 let relativeTimeFormat = new Intl.RelativeTimeFormat("zh-CN", {numeric: "always", style: "long"}); 375 let number = 2; 376 let unit = "year"; 377 let formatPartsResult = relativeTimeFormat.formatToParts(number, unit); // formatPartsResult = [{"type": "integer", "value": "2", "unit": "year"}, {"type":"literal", "value": "年后"}] 378 ``` 379 3805. 访问相对时间格式化对象的相关属性。 381 382 RelativeTimeFormat的resolvedOptions方法会返回一个对象，该对象包含了RelativeTimeFormat对象的所有相关属性及其值，完整的属性列表参见[ RelativeTimeFormatResolvedOptions](../reference/apis/js-apis-intl.md#relativetimeformatresolvedoptions8)。 383 384 ```js 385 let relativeTimeFormat = new Intl.RelativeTimeFormat("zh-CN", {numeric: "always", style: "long"}); 386 let options = relativeTimeFormat.resolvedOptions(); // options = {"locale": "zh-CN", "style": "long", "numeric": "always", "numberingSystem": "latn"} 387 ``` 388 389## 相关实例 390 391针对Intl开发，有以下相关实例可供参考： 392 393-[`International`：国际化（ArkTS）（API9）（Full SDK）](https://gitee.com/openharmony/applications_app_samples/tree/OpenHarmony-3.2-Release/code/SystemFeature/Internationalnation/International) 394