1# @ohos.intl (国际化-Intl) 2 3本模块提供基础的应用国际化能力，包括时间日期格式化、数字格式化、排序等，相关接口在ECMA 402标准中定义。 4[I18N模块](js-apis-i18n.md)提供其他非ECMA 402定义的国际化接口，与本模块共同使用可提供完整地国际化支持能力。 5 6> **说明：** 7> 8> - 本模块首批接口从API version 6开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 9> 10> - 本模块接口依据[CLDR](https://cldr.unicode.org) 国际化数据库进行处理，随着CLDR演进，本模块接口处理结果可能发生变化。其中，API version 12对应[CLDR 42](https://cldr.unicode.org/index/downloads/cldr-42)，详细数据变化请参考官方链接。 11> 12> - 从API version 11开始，本模块部分接口支持在ArkTS卡片中使用。 13> 14> - 从API version 12开始，本模块全接口支持在原子化服务中使用。 15 16 17## 导入模块 18 19```ts 20import { intl } from '@kit.LocalizationKit'; 21``` 22 23## Locale 24 25### 属性 26 27**卡片能力**：从API version 11开始，该接口支持在ArkTS卡片中使用。 28 29**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 30 31**系统能力**：SystemCapability.Global.I18n 32 33| 名称 | 类型 | 必填 | 说明 | 34| --------------- | ------- | -------- | ---------------------------------------- | 35| language | string | 是 | 与区域设置相关的语言，如：zh。 | 36| script | string | 是 | 区域语言的书写方式（脚本），如：Hans。 | 37| region | string | 是 | 与区域设置相关的国家或地区，如：CN。 | 38| baseName | string | 是 | Locale的基本信息，由语言、脚本、国家或地区组成，如：zh-Hans-CN。 | 39| caseFirst | string | 是 | 区域的排序规则是否考虑大小写，<br>取值包括："upper", "lower", "false"。 | 40| calendar | string | 是 | 区域的日历信息，<br>取值包括："buddhist", "chinese", "coptic","dangi", "ethioaa", "ethiopic", "gregory", "hebrew", "indian", "islamic", "islamic-umalqura", "islamic-tbla", "islamic-civil", "islamic-rgsa", "iso8601", "japanese", "persian", "roc", "islamicc"。 | 41| collation | string | 是 | 区域的排序规则，<br>取值包括："big5han", "compat", "dict", "direct", "ducet", "eor", "gb2312", "phonebk", "phonetic", "pinyin", "reformed", "searchjl", "stroke", "trad", "unihan", "zhuyin"。 | 42| hourCycle | string | 是 | 区域的时制信息，<br>取值包括："h12", "h23", "h11", "h24"。 | 43| numberingSystem | string | 是 | 区域使用的数字系统，<br>取值包括："adlm", "ahom", "arab", "arabext", "bali", "beng", "bhks", "brah", "cakm", "cham", "deva", "diak", "fullwide", "gong", "gonm", "gujr", "guru", "hanidec", "hmng", "hmnp", "java", "kali", "khmr", "knda", "lana", "lanatham", "laoo", "latn", "lepc", "limb", "mathbold", "mathdbl", "mathmono", "mathsanb", "mathsans", "mlym", "modi", "mong", "mroo", "mtei", "mymr", "mymrshan", "mymrtlng", "newa", "nkoo", "olck", "orya", "osma", "rohg", "saur", "segment", "shrd", "sind", "sinh", "sora", "sund", "takr", "talu", "tamldec", "telu", "thai", "tibt", "tirh", "vaii", "wara", "wcho"。 | 44| numeric | boolean | 是 | 是否对数字字符进行特殊的排序规则处理。<br>默认值：false。 | 45 46> **说明：** 47> 48> - caseFirst、collation：不同取值表示的含义请参考[本地习惯排序表1](../../internationalization/i18n-sorting-local.md)。 49> 50> - calendar：不同取值表示的含义请参考[设置日历和历法表1](../../internationalization/i18n-calendar.md)。 51> 52> - hourCycle：不同取值的显示效果可参考[时间日期国际化表5](../../internationalization/i18n-time-date.md)。 53 54### constructor<sup>8+</sup> 55 56constructor() 57 58创建区域对象。 59 60**卡片能力**：从API version 11开始，该接口支持在ArkTS卡片中使用。 61 62**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 63 64**系统能力**：SystemCapability.Global.I18n 65 66**示例：** 67 ```ts 68 // 默认构造函数使用系统当前locale创建 69 let locale = new intl.Locale(); 70 // 返回系统当前locale 71 let localeID = locale.toString(); 72 ``` 73 74### constructor 75 76constructor(locale: string, options?: LocaleOptions) 77 78创建区域对象。 79 80**卡片能力**：从API version 11开始，该接口支持在ArkTS卡片中使用。 81 82**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 83 84**系统能力**：SystemCapability.Global.I18n 85 86**参数：** 87 88| 参数名 | 类型 | 必填 | 说明 | 89| -------------------- | -------------------------------- | ---- | ---------------------------- | 90| locale | string | 是 | 表示区域信息的字符串，由语言、脚本、国家或地区组成。<br>locale可填写组成部分中的一个或多个。| 91| options | [LocaleOptions](#localeoptions) | 否 | 创建区域对象的选项。 | 92 93**示例：** 94 ```ts 95 // 创建 "zh-CN" Locale对象 96 let locale = new intl.Locale("zh-CN"); 97 let localeID = locale.toString(); // localeID = "zh-CN" 98 ``` 99 100 101### toString 102 103toString(): string 104 105获取区域对象的字符串。 106 107**卡片能力**：从API version 11开始，该接口支持在ArkTS卡片中使用。 108 109**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 110 111**系统能力**：SystemCapability.Global.I18n 112 113**返回值：** 114 115| 类型 | 说明 | 116| ------ | ----------- | 117| string | 区域对象的字符串。 | 118 119**示例：** 120 ```ts 121 // 创建 "en-GB" Locale对象 122 let locale = new intl.Locale("en-GB"); 123 let localeID = locale.toString(); // localeID = "en-GB" 124 ``` 125 126### maximize 127 128maximize(): Locale 129 130最大化区域信息，可补齐Locale中缺少脚本、国家或地区信息。 131 132**卡片能力**：从API version 11开始，该接口支持在ArkTS卡片中使用。 133 134**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 135 136**系统能力**：SystemCapability.Global.I18n 137 138**返回值：** 139 140| 类型 | 说明 | 141| ----------------- | ---------- | 142| [Locale](#locale) | 补充完脚本、国家或地区信息后的区域对象。 | 143 144**示例：** 145 ```ts 146 // 创建 "zh" Locale对象 147 let locale = new intl.Locale("zh"); 148 // 补齐Locale对象的脚本和地区 149 let maximizedLocale = locale.maximize(); 150 let localeID = maximizedLocale.toString(); // localeID = "zh-Hans-CN" 151 152 // 创建 "en-US" Locale对象 153 locale = new intl.Locale("en-US"); 154 // 补齐Locale对象的脚本 155 maximizedLocale = locale.maximize(); 156 localeID = maximizedLocale.toString(); // localeID = "en-Latn-US" 157 ``` 158 159 160### minimize 161 162minimize(): Locale 163 164最小化区域信息，可删除Locale中的脚本、国家或地区信息。 165 166**卡片能力**：从API version 11开始，该接口支持在ArkTS卡片中使用。 167 168**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 169 170**系统能力**：SystemCapability.Global.I18n 171 172**返回值：** 173 174| 类型 | 说明 | 175| ----------------- | ---------- | 176| [Locale](#locale) | 删除完脚本、国家或地区信息后的区域对象。 | 177 178**示例：** 179 ```ts 180 // 创建 "zh-Hans-CN" Locale对象 181 let locale = new intl.Locale("zh-Hans-CN"); 182 // 去除Locale对象的脚本和地区 183 let minimizedLocale = locale.minimize(); 184 let localeID = minimizedLocale.toString(); // localeID = "zh" 185 186 // 创建 "en-US" Locale对象 187 locale = new intl.Locale("en-US"); 188 // 去除Locale对象的地区 189 minimizedLocale = locale.minimize(); 190 localeID = minimizedLocale.toString(); // localeID = "en" 191 ``` 192 193## LocaleOptions 194 195区域初始化选项。从API9开始，LocaleOptions属性由必填改为可选。 196 197**卡片能力**：从API version 11开始，该类型支持在ArkTS卡片中使用。 198 199**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 200 201**系统能力**：SystemCapability.Global.I18n 202 203| 名称 | 类型 | 必填 | 说明 | 204| --------------- | ------- | ---- |---------------------------------------- | 205| calendar | string | 否 |日历参数，<br>取值包括："buddhist", "chinese", "coptic", "dangi", "ethioaa", "ethiopic", "gregory", "hebrew", "indian", "islamic", "islamic-umalqura", "islamic-tbla", "islamic-civil", "islamic-rgsa", "iso8601", "japanese", "persian", "roc", "islamicc"。 | 206| collation | string | 否 |排序参数，<br>取值包括："big5han", "compat", "dict", "direct", "ducet", "emoji", "eor", "gb2312", "phonebk", "phonetic", "pinyin", "reformed ", "search", "searchjl", "standard", "stroke", "trad", "unihan", "zhuyin"。 | 207| hourCycle | string | 否 |时制格式，<br>取值包括："h11", "h12", "h23", "h24"。 | 208| numberingSystem | string | 否 |数字系统，<br>取值包括："adlm", "ahom", "arab", "arabext", "bali", "beng", "bhks", "brah", "cakm", "cham", "deva", "diak", "fullwide", "gong", "gonm", "gujr", "guru", "hanidec", "hmng", "hmnp", "java", "kali", "khmr", "knda", "lana", "lanatham", "laoo", "latn", "lepc", "limb", "mathbold", "mathdbl", "mathmono", "mathsanb", "mathsans", "mlym", "modi", "mong", "mroo", "mtei", "mymr", "mymrshan", "mymrtlng", "newa", "nkoo", "olck", "orya", "osma", "rohg", "saur", "segment", "shrd", "sind", "sinh", "sora", "sund", "takr", "talu", "tamldec", "telu", "thai", "tibt", "tirh", "vaii", "wara", "wcho"。 | 209| numeric | boolean | 否 | 是否对数字字符进行特殊的排序规则处理。默认值：false。 | 210| caseFirst | string | 否 | 表示大写、小写的排序顺序，<br>取值范围："upper", "lower", "false"。 | 211 212> **说明：** 213> 214> - calendar：不同取值表示的含义请参考[设置日历和历法表1](../../internationalization/i18n-calendar.md)。 215> 216> - hourCycle：不同取值的显示效果可参考[时间日期国际化表5](../../internationalization/i18n-time-date.md)。 217> 218> - collation、caseFirst：不同取值表示的含义请参考[本地习惯排序表1](../../internationalization/i18n-sorting-local.md)。 219 220## DateTimeFormat 221 222### constructor<sup>8+</sup> 223 224constructor() 225 226创建时间、日期格式化对象。 227 228**卡片能力**：从API version 11开始，该接口支持在ArkTS卡片中使用。 229 230**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 231 232**系统能力**：SystemCapability.Global.I18n 233 234**示例：** 235 ```ts 236 // 使用系统当前locale创建DateTimeFormat对象 237 let datefmt= new intl.DateTimeFormat(); 238 ``` 239 240### constructor 241 242constructor(locale: string | Array<string>, options?: DateTimeOptions) 243 244创建时间、日期格式化对象。 245 246**卡片能力**：从API version 11开始，该接口支持在ArkTS卡片中使用。 247 248**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 249 250**系统能力**：SystemCapability.Global.I18n 251 252**参数：** 253 254| 参数名 | 类型 | 必填 | 说明 | 255| -------------------- | ------------------------------------ | ---- | ---------------------------- | 256| locale | string \| Array<string> | 是 | 表示区域信息的字符串，由语言、脚本、国家或地区组成。<br>locale可填写组成部分中的一个或多个。 | 257| options | [DateTimeOptions](#datetimeoptions) | 否 | 创建时间、日期格式化对象时可设置的配置项。<br>若所有选项均未设置时，year、month、day三个属性的默认值为numeric。 | 258 259**示例：** 260 ```ts 261 // 使用 "zh-CN" locale创建DateTimeFormat对象，日期风格为full，时间风格为medium 262 let datefmt= new intl.DateTimeFormat("zh-CN", { dateStyle: 'full', timeStyle: 'medium' }); 263 264 // 使用 ["ban", "zh"] locale列表创建DateTimeFormat对象，因为ban为非法LocaleID，因此使用zh Locale创建DateTimeFormat对象 265 let datefmt= new intl.DateTimeFormat(["ban", "zh"], { dateStyle: 'full', timeStyle: 'medium' }); 266 ``` 267 268### format 269 270format(date: Date): string 271 272对时间、日期进行格式化。 273 274**卡片能力**：从API version 11开始，该接口支持在ArkTS卡片中使用。 275 276**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 277 278**系统能力**：SystemCapability.Global.I18n 279 280**参数：** 281 282| 参数名 | 类型 | 必填 | 说明 | 283| ---- | ---- | ---- | ------- | 284| date | Date | 是 | 时间日期对象。 | 285 286**返回值：** 287 288| 类型 | 说明 | 289| ------ | ------------ | 290| string | 格式化后的时间、日期字符串。 | 291 292**示例：** 293 ```ts 294 let date = new Date(2021, 11, 17, 3, 24, 0); 295 // 使用 en-GB locale创建DateTimeFormat对象 296 let datefmt = new intl.DateTimeFormat("en-GB"); 297 let formattedDate = datefmt.format(date); // formattedDate "17/12/2021" 298 299 // 使用 en-GB locale创建DateTimeFormat对象，dateStyle设置为full，timeStyle设置为medium 300 datefmt = new intl.DateTimeFormat("en-GB", { dateStyle: 'full', timeStyle: 'medium' }); 301 formattedDate = datefmt.format(date); // formattedDate "Friday, 17 December 2021 at 03:24:00" 302 ``` 303 304### formatRange 305 306formatRange(startDate: Date, endDate: Date): string 307 308对时间段、日期段进行格式化。 309 310**卡片能力**：从API version 11开始，该接口支持在ArkTS卡片中使用。 311 312**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 313 314**系统能力**：SystemCapability.Global.I18n 315 316**参数：** 317 318| 参数名 | 类型 | 必填 | 说明 | 319| --------- | ---- | ---- | -------- | 320| startDate | Date | 是 | 时间、日期的开始。 | 321| endDate | Date | 是 | 时间、日期的结束。 | 322 323**返回值：** 324 325| 类型 | 说明 | 326| ------ | -------------- | 327| string | 格式化后的时间段、日期段字符串。 | 328 329**示例：** 330 ```ts 331 let startDate = new Date(2021, 11, 17, 3, 24, 0); 332 let endDate = new Date(2021, 11, 18, 3, 24, 0); 333 // 使用 en-GB locale创建DateTimeFormat对象 334 let datefmt = new intl.DateTimeFormat("en-GB"); 335 let formattedDateRange = datefmt.formatRange(startDate, endDate); // formattedDateRange = "17/12/2021 - 18/12/2021" 336 ``` 337 338### resolvedOptions 339 340resolvedOptions(): DateTimeOptions 341 342获取创建时间、日期格式化对象时设置的配置项。 343 344**卡片能力**：从API version 11开始，该接口支持在ArkTS卡片中使用。 345 346**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 347 348**系统能力**：SystemCapability.Global.I18n 349 350**返回值：** 351 352| 类型 | 说明 | 353| ------------------------------------ | ----------------------------- | 354| [DateTimeOptions](#datetimeoptions) | 时间、日期格式化对象设置的配置项。 | 355 356**示例：** 357 ```ts 358 let datefmt = new intl.DateTimeFormat("en-GB", { dateStyle: 'full', timeStyle: 'medium' }); 359 // 返回DateTimeFormat对象的配置项 360 let options = datefmt.resolvedOptions(); 361 let dateStyle = options.dateStyle; // dateStyle = "full" 362 let timeStyle = options.timeStyle; // timeStyle = "medium" 363 ``` 364 365 366## DateTimeOptions 367 368时间、日期格式化时可设置的配置项。从API9开始，DateTimeOptions的属性由必填改为可选。 369 370**卡片能力**：从API version 11开始，该类型支持在ArkTS卡片中使用。 371 372**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 373 374**系统能力**：SystemCapability.Global.I18n 375 376| 名称 | 类型 | 必填 | 说明 | 377| --------------- | ------- | ---- | ---------------------------------------- | 378| locale | string | 否 |区域参数， 如：zh-Hans-CN。 | 379| dateStyle | string | 否 |日期显示格式，<br>取值包括："long", "short", "medium", "full", "auto"。 | 380| timeStyle | string | 否 |时间显示格式，<br>取值包括："long", "short", "medium", "full", "auto"。 | 381| hourCycle | string | 否 |时制格式，<br>取值包括："h11", "h12", "h23", "h24"。 | 382| timeZone | string | 否 |使用的时区（合法的IANA时区ID）。 | 383| numberingSystem | string | 否 |数字系统，<br>取值包括："adlm", "ahom", "arab", "arabext", "bali", "beng", "bhks", "brah", "cakm", "cham", "deva", "diak", "fullwide", "gong", "gonm", "gujr", "guru", "hanidec", "hmng", "hmnp", "java", "kali", "khmr", "knda", "lana", "lanatham", "laoo", "latn", "lepc", "limb", "mathbold", "mathdbl", "mathmono", "mathsanb", "mathsans", "mlym", "modi", "mong", "mroo", "mtei", "mymr", "mymrshan", "mymrtlng", "newa", "nkoo", "olck", "orya", "osma", "rohg", "saur", "segment", "shrd", "sind", "sinh", "sora", "sund", "takr", "talu", "tamldec", "telu", "thai", "tibt", "tirh", "vaii", "wara", "wcho"。 | 384| hour12 | boolean | 否 | 是否使用12小时制，<br>若hour12和hourCycle未设置且系统24小时开关打开时，hour12属性的默认值为false。 | 385| weekday | string | 否 | 工作日的显示格式，<br>取值包括："long", "short", "narrow", "auto"。 | 386| era | string | 否 | 时代的显示格式，<br>取值包括："long", "short", "narrow", "auto"。 | 387| year | string | 否 | 年份的显示格式，<br>取值包括："numeric", "2-digit"。 | 388| month | string | 否 | 月份的显示格式，<br>取值包括："numeric", "2-digit", "long", "short", "narrow", "auto"。 | 389| day | string | 否 | 日期的显示格式，<br>取值包括："numeric", "2-digit"。 | 390| hour | string | 否 | 小时的显示格式，<br>取值包括："numeric", "2-digit"。 | 391| minute | string | 否 | 分钟的显示格式，<br>取值包括："numeric", "2-digit"。 | 392| second | string | 否 | 秒钟的显示格式，<br>取值包括："numeric", "2-digit"。 | 393| timeZoneName | string | 否 | 时区名称的本地化表示, <br>取值包括："long", "short", "auto"。 | 394| dayPeriod | string | 否 | 时段的显示格式，<br>取值包括："long", "short", "narrow", "auto"。 | 395| localeMatcher | string | 否 | 要使用的区域匹配算法，<br>取值包括："lookup", "best fit"。 | 396| formatMatcher | string | 否 | 要使用的格式匹配算法，<br>取值包括："basic", "best fit"。 | 397 398> **说明：** 399> 400> - dateStyle、timeStyle、weekday、year：不同取值的显示效果请参考[时间日期国际化表1](../../internationalization/i18n-time-date.md)。 401> 402> - 不同常用场景下各参数的取值请参考[时间日期国际化开发实例](../../internationalization/i18n-time-date.md)。 403 404## NumberFormat 405 406### constructor<sup>8+</sup> 407 408constructor() 409 410创建数字格式化对象。 411 412**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 413 414**系统能力**：SystemCapability.Global.I18n 415 416**示例：** 417 ```ts 418 // 使用系统当前locale创建NumberFormat对象 419 let numfmt = new intl.NumberFormat(); 420 ``` 421 422 423### constructor 424 425constructor(locale: string | Array<string>, options?: NumberOptions) 426 427创建数字格式化对象。 428 429**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 430 431**系统能力**：SystemCapability.Global.I18n 432 433**参数：** 434 435| 参数名 | 类型 | 必填 | 说明 | 436| -------------------- | -------------------------------- | ---- | ---------------------------- | 437| locale | string \| Array<string> | 是 | 表示区域信息的字符串，由语言、脚本、国家或地区组成。 | 438| options | [NumberOptions](#numberoptions) | 否 | 创建数字格式化对象时可设置的配置项。 | 439 440**示例：** 441 ```ts 442 // 使用 en-GB locale创建NumberFormat对象，style设置为decimal，notation设置为scientific 443 let numfmt = new intl.NumberFormat("en-GB", {style:'decimal', notation:"scientific"}); 444 ``` 445 446### format 447 448format(number: number): string 449 450格式化数字字符串。 451 452**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 453 454**系统能力**：SystemCapability.Global.I18n 455 456**参数：** 457 458| 参数名 | 类型 | 必填 | 说明 | 459| ------ | ------ | ---- | ---- | 460| number | number | 是 | 数字对象。 | 461 462**返回值：** 463 464| 类型 | 说明 | 465| ------ | ---------- | 466| string | 格式化后的数字字符串。 | 467 468 469**示例：** 470 ```ts 471 // 使用 ["en-GB", "zh"] locale列表创建NumberFormat对象，因为en-GB为合法LocaleID，因此使用en-GB创建NumberFormat对象 472 let numfmt = new intl.NumberFormat(["en-GB", "zh"], {style:'decimal', notation:"scientific"}); 473 let formattedNumber = numfmt.format(1223); // formattedNumber = 1.223E3 474 ``` 475 476 477### resolvedOptions 478 479resolvedOptions(): NumberOptions 480 481获取创建数字格式化对象时设置的配置项。 482 483**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 484 485**系统能力**：SystemCapability.Global.I18n 486 487**返回值：** 488 489| 类型 | 说明 | 490| -------------------------------- | --------------------------- | 491| [NumberOptions](#numberoptions) | 创建数字格式化对象时设置的配置项。 | 492 493 494**示例：** 495 ```ts 496 let numfmt = new intl.NumberFormat(["en-GB", "zh"], {style:'decimal', notation:"scientific"}); 497 // 获取NumberFormat对象配置项 498 let options = numfmt.resolvedOptions(); 499 let style = options.style; // style = decimal 500 let notation = options.notation; // notation = scientific 501 ``` 502 503## NumberOptions 504 505创建数字格式化对象时可设置的配置项。从API9开始，NumberOptions的属性由必填改为可选。 506 507**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 508 509**系统能力**：SystemCapability.Global.I18n 510 511| 名称 | 类型 | 必填 | 说明 | 512| ------------------------ | ------- | ---- | ---------------------------------------- | 513| locale | string | 否 | 区域参数， 如："zh-Hans-CN"。<br>locale属性默认值为系统当前Locale。 | 514| currency | string | 否 | 货币单位， 取值符合[ISO-4217标准](https://www.iso.org/iso-4217-currency-codes.html)，如："EUR"，"CNY"，"USD"等。<br>从API version 12开始支持三位数字代码，如："978"，"156"，"840"等。 | 515| currencySign | string | 否 | 货币单位的符号显示，取值包括： "standard"，"accounting"。<br>默认值为standard。 | 516| currencyDisplay | string | 否 | 货币的显示方式，取值包括："symbol", "narrowSymbol", "code", "name"。<br>默认值为symbol。 | 517| unit | string | 否 | 单位名称，如："meter"，"inch"，“hectare”等。 | 518| unitDisplay | string | 否 | 单位的显示格式，取值包括："long", "short", "narrow"。<br>默认值为short。 | 519| unitUsage<sup>8+</sup> | string | 否 | 单位的使用场景，取值包括："default", "area-land-agricult", "area-land-commercl", "area-land-residntl", "length-person", "length-person-small", "length-rainfall", "length-road", "length-road-small", "length-snowfall", "length-vehicle", "length-visiblty", "length-visiblty-small", "length-person-informal", "length-person-small-informal", "length-road-informal", "speed-road-travel", "speed-wind", "temperature-person", "temperature-weather", "volume-vehicle-fuel", "elapsed-time-second", "size-file-byte", "size-shortfile-byte"。<br>默认值为default。 | 520| signDisplay | string | 否 | 数字符号的显示格式，取值包括："auto", "never", "always", "expectZero"。<br>默认值为auto。 | 521| compactDisplay | string | 否 | 紧凑型的显示格式，取值包括："long", "short"。<br>默认值为short。 | 522| notation | string | 否 | 数字的格式化规格，取值包括："standard", "scientific", "engineering", "compact"。<br>默认值为standard。 | 523| localeMatcher | string | 否 | 要使用的区域匹配算法，取值包括："lookup", "best fit"。<br>默认值为best fit。 | 524| style | string | 否 | 数字的显示格式，取值包括："decimal", "currency", "percent", "unit"。<br>默认值为decimal。 | 525| numberingSystem | string | 否 | 数字系统，取值包括："adlm", "ahom", "arab", "arabext", "bali", "beng", "bhks", "brah", "cakm", "cham", "deva", "diak", "fullwide", "gong", "gonm", "gujr", "guru", "hanidec", "hmng", "hmnp", "java", "kali", "khmr", "knda", "lana", "lanatham", "laoo", "latn", "lepc", "limb", "mathbold", "mathdbl", "mathmono", "mathsanb", "mathsans", "mlym", "modi", "mong", "mroo", "mtei", "mymr", "mymrshan", "mymrtlng", "newa", "nkoo", "olck", "orya", "osma", "rohg", "saur", "segment", "shrd", "sind", "sinh", "sora", "sund", "takr", "talu", "tamldec", "telu", "thai", "tibt", "tirh", "vaii", "wara", "wcho"。numberingSystem属性默认值为locale的默认数字系统。 | 526| useGrouping | boolean | 否 | 是否分组显示。useGrouping属性默认值为auto。 | 527| minimumIntegerDigits | number | 否 | 表示要使用的最小整数位数，取值范围：1~21。<br>minimumIntegerDigits属性默认值为1。 | 528| minimumFractionDigits | number | 否 | 表示要使用的最小分数位数，取值范围：0~20。<br>minimumFractionDigits属性默认值为0。 | 529| maximumFractionDigits | number | 否 | 表示要使用的最大分数位数，取值范围：1~21。<br>maximumFractionDigits属性默认值为3。 | 530| minimumSignificantDigits | number | 否 | 表示要使用的最低有效位数，取值范围：1~21。<br>minimumSignificantDigits属性默认值为1。 | 531| maximumSignificantDigits | number | 否 | 表示要使用的最大有效位数，取值范围：1~21。<br>maximumSignificantDigits属性默认值为21。 | 532 533> **说明：** 534> 535> - 各属性不同取值代表的含义或呈现效果，请参考[数字与度量衡国际化](../../internationalization/i18n-numbers-weights-measures.md)。 536 537## Collator<sup>8+</sup> 538 539### constructor<sup>8+</sup> 540 541constructor() 542 543创建排序对象。 544 545**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 546 547**系统能力**：SystemCapability.Global.I18n 548 549**示例：** 550 ```ts 551 // 使用系统locale创建Collator对象 552 let collator = new intl.Collator(); 553 ``` 554 555 556### constructor<sup>8+</sup> 557 558constructor(locale: string | Array<string>, options?: CollatorOptions) 559 560创建排序对象。 561 562**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 563 564**系统能力**：SystemCapability.Global.I18n 565 566**参数：** 567 568| 参数名 | 类型 | 必填 | 说明 | 569| -------------------- | ------------------------------------ | ---- | ---------------------------- | 570| locale | string \| Array<string> | 是 | 表示区域信息的字符串，由语言、脚本、国家或地区组成。 | 571| options | [CollatorOptions](#collatoroptions8) | 否 | 创建排序对象时可设置的配置项。 | 572 573**示例：** 574 ```ts 575 // 使用 zh-CN locale创建Collator对象，localeMatcher设置为lookup，usage设置为sort 576 let collator = new intl.Collator("zh-CN", {localeMatcher: "lookup", usage: "sort"}); 577 ``` 578 579 580### compare<sup>8+</sup> 581 582compare(first: string, second: string): number 583 584依据配置项设置的排序规则，比较两个字符串。 585 586**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 587 588**系统能力**：SystemCapability.Global.I18n 589 590**参数：** 591 592| 参数名 | 类型 | 必填 | 说明 | 593| ------ | ------ | ---- | ------------ | 594| first | string | 是 | 进行比较第一个字符串。 | 595| second | string | 是 | 进行比较的第二个字符串。 | 596 597**返回值：** 598 599| 类型 | 说明 | 600| ------ | ---------------------------------------- | 601| number | 比较结果。<br>- number为负数时，表示first排序在second之前；<br>- number为0时，表示first与second排序相同；<br>- number为正数，表示first排序在second之后。 | 602 603**示例：** 604 ```ts 605 // 使用en-GB locale创建Collator对象 606 let collator = new intl.Collator("en-GB"); 607 // 比较 "first" 和 "second" 的先后顺序 608 let compareResult = collator.compare("first", "second"); // compareResult = -1 609 ``` 610 611 612### resolvedOptions<sup>8+</sup> 613 614resolvedOptions(): CollatorOptions 615 616获取创建排序对象时设置的配置项。 617 618**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 619 620**系统能力**：SystemCapability.Global.I18n 621 622**返回值：** 623 624| 类型 | 说明 | 625| ------------------------------------ | ----------------- | 626| [CollatorOptions](#collatoroptions8) | 返回排序对象的属性。 | 627 628**示例：** 629 ```ts 630 let collator = new intl.Collator("zh-Hans", { usage: 'sort', ignorePunctuation: true }); 631 // 获取Collator对象的配置项 632 let options = collator.resolvedOptions(); 633 let usage = options.usage; // usage = "sort" 634 let ignorePunctuation = options.ignorePunctuation; // ignorePunctuation = true 635 ``` 636 637 638## CollatorOptions<sup>8+</sup> 639 640创建排序对象时可设置的配置项。 641 642从API9中，CollatorOptions中的属性改为可选。 643 644**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 645 646**系统能力**：SystemCapability.Global.I18n 647 648| 名称 | 类型 | 必填 | 说明 | 649| ----------------- | ------- | ---- | ---------------------------------------- | 650| localeMatcher | string | 否 | locale匹配算法，取值范围："best fit", "lookup"。<br>默认值为best fit。 | 651| usage | string | 否 | 比较的用途，取值范围："sort", "search"。<br>默认值为sort。 | 652| sensitivity | string | 否 | 表示字符串中的哪些差异会导致非零结果值，取值范围："base", "accent", "case", "letiant"。<br>默认值为variant。 | 653| ignorePunctuation | boolean | 否 | 表示是否忽略标点符号，取值范围：true, false。<br>默认值为false。 | 654| collation | string | 否 | 排序规则，<br>取值范围："big5han", "compat", "dict", "direct", "ducet", "eor", "gb2312", "phonebk", "phonetic", "pinyin", "reformed", "searchjl", "stroke", "trad", "unihan", "zhuyin"。<br>默认值为default。 | 655| numeric | boolean | 否 | 是否使用数字排序，取值范围：true, false。<br>默认值为false。 | 656| caseFirst | string | 否 | 表示大写、小写的排序顺序，取值范围："upper", "lower", "false"。<br>默认值为false | 657 658 659> **说明：** 660> 661> - usage、sensitivity、collation、caseFirst不同取值代表的含义请参考[本地习惯排序](../../internationalization/i18n-sorting-local.md)。 662 663 664## PluralRules<sup>8+</sup> 665 666### constructor<sup>8+</sup> 667 668constructor() 669 670创建单复数对象来计算数字的单复数类别。 671 672**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 673 674**系统能力**：SystemCapability.Global.I18n 675 676**示例：** 677 ```ts 678 // 使用系统locale创建PluralRules对象 679 let pluralRules = new intl.PluralRules(); 680 ``` 681 682 683### constructor<sup>8+</sup> 684 685constructor(locale: string | Array<string>, options?: PluralRulesOptions) 686 687创建单复数对象来计算数字的单复数类别。 688 689**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 690 691**系统能力**：SystemCapability.Global.I18n 692 693**参数：** 694 695| 参数名 | 类型 | 必填 | 说明 | 696| -------------------- | ---------------------------------------- | ---- | ---------------------------- | 697| locale | string \| Array<string> | 是 | 表示区域信息的字符串，由语言、脚本、国家或地区组成。 | 698| options | [PluralRulesOptions](#pluralrulesoptions8) | 否 | 创建单复数对象时设置的配置项。 | 699 700**示例：** 701 ```ts 702 // 使用 zh-CN locale创建PluralRules对象，localeMatcher设置为lookup，type设置为cardinal 703 let pluralRules= new intl.PluralRules("zh-CN", {"localeMatcher": "lookup", "type": "cardinal"}); 704 ``` 705 706### select<sup>8+</sup> 707 708select(n: number): string 709 710返回一个字符串表示该数字的单复数类别。 711 712**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 713 714**系统能力**：SystemCapability.Global.I18n 715 716**参数：** 717 718| 参数名 | 类型 | 必填 | 说明 | 719| ---- | ------ | ---- | ------------ | 720| n | number | 是 | 待获取单复数类别的数字。 | 721 722**返回值：** 723 724| 类型 | 说明 | 725| ------ | ---------------------------------------- | 726| string | 单复数类别，取值包括："zero"，"one"，"two", "few", "many", "others"。 <br>不同取值代表的含义请参考[语言单复数规则](https://www.unicode.org/cldr/charts/45/supplemental/language_plural_rules.html)。| 727 728**示例：** 729 ```ts 730 // 使用 zh-Hans locale创建PluralRules对象 731 let zhPluralRules = new intl.PluralRules("zh-Hans"); 732 // 计算 zh-Hans locale中数字1对应的单复数类别 733 let plural = zhPluralRules.select(1); // plural = other 734 735 // 使用 en-US locale创建PluralRules对象 736 let enPluralRules = new intl.PluralRules("en-US"); 737 // 计算 en-US locale中数字1对应的单复数类别 738 plural = enPluralRules.select(1); // plural = one 739 ``` 740 741 742## PluralRulesOptions<sup>8+</sup> 743 744创建单复数对象时可设置的配置项。从API9开始，PluralRulesOptions的属性由必填改为可选。 745 746**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 747 748**系统能力**：SystemCapability.Global.I18n 749 750| 名称 | 类型 | 可读 | 可写 | 说明 | 751| ------------------------ | ------ | ---- | ---- | ---------------------------------------- | 752| localeMatcher | string | 是 | 是 | locale匹配算法，取值包括："best fit", "lookup"。<br>默认值为best fit。 | 753| type | string | 是 | 是 | 排序的类型，取值包括："cardinal", "ordinal",<br>默认值为cardinal。<br>- cardinal：基数词，ordinal：序数词。 | 754| minimumIntegerDigits | number | 是 | 是 | 表示要使用的最小整数位数，取值范围：1~21。<br>默认值为1。 | 755| minimumFractionDigits | number | 是 | 是 | 表示要使用的最小分数位数，取值范围：0~20。<br>默认值为0。 | 756| maximumFractionDigits | number | 是 | 是 | 表示要使用的最大分数位数，取值范围：1~21。<br>默认值为3。 | 757| minimumSignificantDigits | number | 是 | 是 | 表示要使用的最低有效位数，取值范围：1~21。<br>默认值为1。 | 758| maximumSignificantDigits | number | 是 | 是 | 表示要使用的最大有效位数，取值范围：1~21。<br>默认值为21。 | 759 760 761## RelativeTimeFormat<sup>8+</sup> 762 763### constructor<sup>8+</sup> 764 765constructor() 766 767创建相对时间格式化对象。 768 769**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 770 771**系统能力**：SystemCapability.Global.I18n 772 773**示例：** 774 ```ts 775 // 使用系统locale创建RelativeTimeFormat对象 776 let relativetimefmt = new intl.RelativeTimeFormat(); 777 ``` 778 779 780### constructor<sup>8+</sup> 781 782constructor(locale: string | Array<string>, options?: RelativeTimeFormatInputOptions) 783 784创建相对时间格式化对象。 785 786**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 787 788**系统能力**：SystemCapability.Global.I18n 789 790**参数：** 791 792| 参数名 | 类型 | 必填 | 说明 | 793| -------------------- | ---------------------------------------- | ---- | ---------------------------- | 794| locale | string \| Array<string> | 是 | 表示区域信息的字符串，由语言、脚本、国家或地区组成。 | 795| options | [RelativeTimeFormatInputOptions](#relativetimeformatinputoptions8) | 否 | 创建相对时间格式化对象时可配置的选项。 | 796 797**示例：** 798 ```ts 799 // 使用 zh-CN locale创建RelativeTimeFormat对象，localeMatcher设置为lookup，numeric设置为always，style设置为long 800 let relativeTimeFormat = new intl.RelativeTimeFormat("zh-CN", {"localeMatcher": "lookup", "numeric": "always", "style": "long"}); 801 ``` 802 803 804### format<sup>8+</sup> 805 806format(value: number, unit: string): string 807 808依据locale和格式化选项，对value和unit进行格式化。 809 810**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 811 812**系统能力**：SystemCapability.Global.I18n 813 814**参数：** 815 816| 参数名 | 类型 | 必填 | 说明 | 817| ----- | ------ | ---- | ---------------------------------------- | 818| value | number | 是 | 相对时间格式化的数值。 | 819| unit | string | 是 | 相对时间格式化的单位，<br>取值包括："year", "quarter", "month", "week", "day", "hour", "minute", "second"。 | 820 821**返回值：** 822 823| 类型 | 说明 | 824| ------ | ---------- | 825| string | 格式化后的相对时间。 | 826 827**示例：** 828 ```ts 829 // 使用 zh-CN locale创建RelativeTimeFormat对象 830 let relativetimefmt = new intl.RelativeTimeFormat("zh-CN"); 831 // 计算 zh-CN locale中数字3，单位quarter的本地化表示 832 let formatResult = relativetimefmt.format(3, "quarter"); // formatResult = "3个季度后" 833 ``` 834 835 836### formatToParts<sup>8+</sup> 837 838formatToParts(value: number, unit: string): Array<object> 839 840自定义区域的相对时间格式。 841 842**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 843 844**系统能力**：SystemCapability.Global.I18n 845 846**参数：** 847 848| 参数名 | 类型 | 必填 | 说明 | 849| ----- | ------ | ---- | ---------------------------------------- | 850| value | number | 是 | 相对时间格式化的数值。 | 851| unit | string | 是 | 相对时间格式化的单位，<br>取值包括："year", "quarter", "month", "week", "day", "hour", "minute", "second"。 | 852 853**返回值：** 854 855| 类型 | 说明 | 856| ------------------- | --------------------------- | 857| Array<object> | 相对时间格式的对象数组。 | 858 859**示例：** 860 ```ts 861 // 使用 en locale创建RelativeTimeFormat对象，numeric设置为auto 862 let relativetimefmt = new intl.RelativeTimeFormat("en", {"numeric": "auto"}); 863 let parts = relativetimefmt.formatToParts(10, "seconds"); // parts = [ {type: "literal", value: "in"}, {type: "integer", value: 10, unit: "second"}, {type: "literal", value: "seconds"} ] 864 ``` 865 866 867### resolvedOptions<sup>8+</sup> 868 869resolvedOptions(): RelativeTimeFormatResolvedOptions 870 871获取RelativeTimeFormat对象的格式化选项。 872 873**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 874 875**系统能力**：SystemCapability.Global.I18n 876 877**返回值：** 878 879| 类型 | 说明 | 880| ---------------------------------------- | --------------------------------- | 881| [RelativeTimeFormatResolvedOptions](#relativetimeformatresolvedoptions8) | RelativeTimeFormat 对象的格式化选项。 | 882 883**示例：** 884 ```ts 885 // 使用 en-GB locale创建RelativeTimeFormat对象 886 let relativetimefmt= new intl.RelativeTimeFormat("en-GB", { style: "short" }); 887 // 获取RelativeTimeFormat对象配置项 888 let options = relativetimefmt.resolvedOptions(); 889 let style = options.style; // style = "short" 890 ``` 891 892 893## RelativeTimeFormatInputOptions<sup>8+</sup> 894 895创建相对时间格式化对象时可设置的属性选项。 896 897从API9开始，RelativeTimeFormatInputOptions中的属性改为可选。 898 899**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 900 901**系统能力**：SystemCapability.Global.I18n 902 903| 名称 | 类型 | 必填 |说明 | 904| ------------- | ------ | ---- | ---------------------------------------- | 905| localeMatcher | string | 否 | locale匹配算法，取值包括："best fit", "lookup"。<br>默认值为best fit。 | 906| numeric | string | 否 | 输出消息的格式，取值包括："always", "auto"。<br>默认值为always。 | 907| style | string | 否 | 国际化消息的长度，取值包括："long", "short", "narrow"。<br>默认值为long。 | 908 909> **说明** 910> 911> numeric、style不同参数取值显示的效果，请参考[相对时间格式化选项](../../internationalization/i18n-time-date.md#相对时间格式化)。 912 913## RelativeTimeFormatResolvedOptions<sup>8+</sup> 914 915表示RelativeTimeFormat对象可设置的属性。 916 917**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 918 919**系统能力**：SystemCapability.Global.I18n 920 921| 名称 | 类型 | 必填 |说明 | 922| --------------- | ------ | ---- | ---------------------------------------- | 923| locale | string | 是 | 包含区域设置信息的字符串，包括语言以及可选的脚本和区域。 | 924| numeric | string | 是 | 输出消息的格式，取值包括："always", "auto"。 | 925| style | string | 是 | 国际化消息的长度，取值包括："long", "short", "narrow"。 | 926| numberingSystem | string | 是 | 使用的数字系统。 |