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