1# 国际化-I18n 2 3 本模块提供系统相关的或者增强的国际化能力，包括区域管理、电话号码处理、日历等，相关接口为ECMA 402标准中未定义的补充接口。 4[Intl模块](js-apis-intl.md)提供了ECMA 402标准定义的基础国际化接口，与本模块共同使用可提供完整地国际化支持能力。 5 6> **说明：** 7> - 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8> 9> - I18N模块包含国际化能力增强接口（未在ECMA 402中定义），包括区域管理、电话号码处理、日历等，国际化基础能力请参考[Intl模块](js-apis-intl.md)。 10 11 12## 导入模块 13 14```js 15import i18n from '@ohos.i18n'; 16``` 17 18 19## i18n.getDisplayLanguage 20 21getDisplayLanguage(language: string, locale: string, sentenceCase?: boolean): string 22 23获取指定语言的本地化显示文本。 24 25**系统能力**：SystemCapability.Global.I18n 26 27**参数：** 28| 参数名 | 类型 | 必填 | 说明 | 29| ------------ | ------- | ---- | ---------------- | 30| language | string | 是 | 指定语言。 | 31| locale | string | 是 | 显示指定语言的区域ID。 | 32| sentenceCase | boolean | 否 | 本地化显示文本是否要首字母大写。 | 33 34**返回值：** 35| 类型 | 说明 | 36| ------ | ------------- | 37| string | 指定语言的本地化显示文本。 | 38 39**示例：** 40 ```js 41 i18n.getDisplayLanguage("zh", "en-GB", true); 42 i18n.getDisplayLanguage("zh", "en-GB"); 43 ``` 44 45 46## i18n.getDisplayCountry 47 48getDisplayCountry(country: string, locale: string, sentenceCase?: boolean): string 49 50获取指定国家的本地化显示文本。 51 52**系统能力**：SystemCapability.Global.I18n 53 54**参数：** 55| 参数名 | 类型 | 必填 | 说明 | 56| ------------ | ------- | ---- | ---------------- | 57| country | string | 是 | 指定国家。 | 58| locale | string | 是 | 显示指定国家的区域ID。 | 59| sentenceCase | boolean | 否 | 本地化显示文本是否要首字母大写。 | 60 61**返回值：** 62| 类型 | 说明 | 63| ------ | ------------- | 64| string | 指定国家的本地化显示文本。 | 65 66**示例：** 67 ```js 68 i18n.getDisplayCountry("zh-CN", "en-GB", true); 69 i18n.getDisplayCountry("zh-CN", "en-GB"); 70 ``` 71 72 73## i18n.isRTL<sup>7+</sup> 74 75isRTL(locale: string): boolean 76 77获取是否为从右至左显示语言。 78 79**系统能力**：SystemCapability.Global.I18n 80 81**参数：** 82| 参数名 | 类型 | 说明 | 83| ------ | ------ | ------- | 84| locale | string | 指定区域ID。 | 85 86**返回值：** 87| 类型 | 说明 | 88| ------- | ---------------------------------------- | 89| boolean | true表示该locale从右至左显示语言；false表示该locale从左至右显示语言。 | 90 91**示例：** 92 ```js 93 i18n.isRTL("zh-CN");// 中文不是RTL语言，返回false 94 i18n.isRTL("ar-EG");// 阿语是RTL语言，返回true 95 ``` 96 97 98## i18n.getSystemLanguage 99 100getSystemLanguage(): string 101 102获取系统语言。 103 104**系统能力**：SystemCapability.Global.I18n 105 106**返回值：** 107| 类型 | 说明 | 108| ------ | ------- | 109| string | 系统语言ID。 | 110 111**示例：** 112 ```js 113 i18n.getSystemLanguage(); 114 ``` 115 116 117## i18n.setSystemLanguage 118 119setSystemLanguage(language: string): boolean 120 121设置系统语言。当前调用该接口不支持系统界面语言的实时刷新。 122 123此接口为系统接口。 124 125**需要权限**：ohos.permission.UPDATE_CONFIGURATION 126 127**系统能力**：SystemCapability.Global.I18n 128 129**参数：** 130| 参数名 | 类型 | 说明 | 131| -------- | ------ | ----- | 132| language | string | 语言ID。 | 133 134**返回值：** 135| 类型 | 说明 | 136| ------- | ------------------------------------- | 137| boolean | 返回true，表示系统语言设置成功；返回false，表示系统语言设置失败。 | 138 139**示例：** 140 ```js 141 i18n.setSystemLanguage('zh'); 142 ``` 143 144 145## i18n.getSystemLanguages 146 147getSystemLanguages(): Array<string> 148 149获取系统支持的语言列表。 150 151此接口为系统接口。 152 153**系统能力**：SystemCapability.Global.I18n 154 155**返回值：** 156| 类型 | 说明 | 157| ------------------- | ------------ | 158| Array<string> | 系统支持的语言ID列表。 | 159 160**示例：** 161 ```js 162 i18n.getSystemLanguages(); 163 ``` 164 165 166## i18n.getSystemCountries 167 168getSystemCountries(language: string): Array<string> 169 170获取针对输入语言系统支持的区域列表。 171 172此接口为系统接口。 173 174**系统能力**：SystemCapability.Global.I18n 175 176**参数：** 177| 参数名 | 类型 | 说明 | 178| -------- | ------ | ----- | 179| language | string | 语言ID。 | 180 181**返回值：** 182| 类型 | 说明 | 183| ------------------- | ------------ | 184| Array<string> | 系统支持的区域ID列表。 | 185 186**示例：** 187 ```js 188 i18n.getSystemCountries('zh'); 189 ``` 190 191 192## i18n.getSystemRegion 193 194getSystemRegion(): string 195 196获取系统地区。 197 198**系统能力**：SystemCapability.Global.I18n 199 200**返回值：** 201| 类型 | 说明 | 202| ------ | ------- | 203| string | 系统地区ID。 | 204 205**示例：** 206 ```js 207 i18n.getSystemRegion(); 208 ``` 209 210 211## i18n.setSystemRegion 212 213setSystemRegion(region: string): boolean 214 215设置系统区域。 216 217此接口为系统接口。 218 219**需要权限**：ohos.permission.UPDATE_CONFIGURATION 220 221**系统能力**：SystemCapability.Global.I18n 222 223**参数：** 224| 参数名 | 类型 | 说明 | 225| ------ | ------ | ----- | 226| region | string | 地区ID。 | 227 228**返回值：** 229| 类型 | 说明 | 230| ------- | ------------------------------------- | 231| boolean | 返回true，表示系统区域设置成功；返回false，表示系统区域设置失败。 | 232 233**示例：** 234 ```js 235 i18n.setSystemRegion('CN'); 236 ``` 237 238 239## i18n.getSystemLocale 240 241getSystemLocale(): string 242 243获取系统区域。 244 245**系统能力**：SystemCapability.Global.I18n 246 247**返回值：** 248| 类型 | 说明 | 249| ------ | ------- | 250| string | 系统区域ID。 | 251 252**示例：** 253 ```js 254 i18n.getSystemLocale(); 255 ``` 256 257 258## i18n.setSystemLocale 259 260setSystemLocale(locale: string): boolean 261 262设置系统Locale。 263 264此接口为系统接口。 265 266**需要权限**：ohos.permission.UPDATE_CONFIGURATION 267 268**系统能力**：SystemCapability.Global.I18n 269 270**参数：** 271| 参数名 | 类型 | 说明 | 272| ------ | ------ | --------------- | 273| locale | string | 指定区域ID，例如zh-CN。 | 274 275**返回值：** 276| 类型 | 说明 | 277| ------- | ---------------------------------------- | 278| boolean | 返回true，表示系统Locale设置成功；返回false，表示系统Locale设置失败。 | 279 280**示例：** 281 ```js 282 i18n.setSystemLocale('zh-CN'); 283 ``` 284 285 286## i18n.isSuggested 287 288isSuggested(language: string, region?: string): boolean 289 290判断当前语言和区域是否匹配。 291 292此接口为系统接口。 293 294**系统能力**：SystemCapability.Global.I18n 295 296**参数：** 297| 参数名 | 类型 | 必填 | 说明 | 298| -------- | ------ | ---- | ------------- | 299| language | string | 是 | 合法的语言ID，例如zh。 | 300| region | string | 否 | 合法的地区ID，例如CN | 301 302**返回值：** 303| 类型 | 说明 | 304| ------- | ---------------------------------------- | 305| boolean | 返回true，表示当前语言和地区匹配；返回false，表示当前语言和地区不匹配。 | 306 307**示例：** 308 ```js 309 i18n.isSuggested('zh', 'CN'); 310 ``` 311 312 313## i18n.getCalendar<sup>8+</sup> 314 315getCalendar(locale: string, type? : string): Calendar 316 317获取日历对象。 318 319**系统能力**：SystemCapability.Global.I18n 320 321**参数：** 322| 参数名 | 类型 | 必填 | 说明 | 323| ------ | ------ | ---- | ---------------------------------------- | 324| locale | string | 是 | 合法的locale值，例如zh-Hans-CN。 | 325| type | string | 否 | 合法的日历类型，目前合法的类型有buddhist, chinese, coptic, ethiopic, hebrew, gregory, indian, islamic_civil, islamic_tbla, islamic_umalqura, japanese, persian。当type没有给出时，采用区域默认的日历类型。 | 326 327**返回值：** 328| 类型 | 说明 | 329| ---------------------- | ----- | 330| [Calendar](#calendar8) | 日历对象。 | 331 332**示例：** 333 ```js 334 i18n.getCalendar("zh-Hans", "gregory"); 335 ``` 336 337 338## Calendar<sup>8+</sup> 339 340 341### setTime<sup>8+</sup> 342 343setTime(date: Date): void 344 345设置日历对象内部的时间日期。 346 347**系统能力**：SystemCapability.Global.I18n 348 349**参数：** 350| 参数名 | 类型 | 必填 | 说明 | 351| ---- | ---- | ---- | ----------------- | 352| date | Date | 是 | 将要设置的日历对象的内部时间日期。 | 353 354**示例：** 355 ```js 356 var calendar = i18n.getCalendar("en-US", "gregory"); 357 var date = new Date(2021, 10, 7, 8, 0, 0, 0); 358 calendar.setTime(date); 359 ``` 360 361 362### setTime<sup>8+</sup> 363 364setTime(time: number): void 365 366设置日历对象内部的时间日期, time为从1970.1.1 00:00:00 GMT逝去的毫秒数。 367 368**系统能力**：SystemCapability.Global.I18n 369 370**参数：** 371| 参数名 | 类型 | 必填 | 说明 | 372| ---- | ------ | ---- | ---------------------------------------- | 373| time | number | 是 | time为从1970.1.1 00:00:00 GMT逝去的毫秒数。 | 374 375**示例：** 376 ```js 377 var calendar = i18n.getCalendar("en-US", "gregory"); 378 calendar.setTime(10540800000); 379 ``` 380 381 382### set<sup>8+</sup> 383 384set(year: number, month: number, date:number, hour?: number, minute?: number, second?: number): void 385 386设置日历对象的年、月、日、时、分、秒。 387 388**系统能力**：SystemCapability.Global.I18n 389 390**参数：** 391| 参数名 | 类型 | 必填 | 说明 | 392| ------ | ------ | ---- | ------ | 393| year | number | 是 | 设置的年。 | 394| month | number | 是 | 设置的月。 | 395| date | number | 是 | 设置的日。 | 396| hour | number | 否 | 设置的小时。 | 397| minute | number | 否 | 设置的分钟。 | 398| second | number | 否 | 设置的秒。 | 399 400**示例：** 401 ```js 402 var calendar = i18n.getCalendar("zh-Hans"); 403 calendar.set(2021, 10, 1, 8, 0, 0); // set time to 2021.10.1 08:00:00 404 ``` 405 406 407### setTimeZone<sup>8+</sup> 408 409setTimeZone(timezone: string): void 410 411设置日历对象的时区。 412 413**系统能力**：SystemCapability.Global.I18n 414 415**参数：** 416| 参数名 | 类型 | 必填 | 说明 | 417| -------- | ------ | ---- | ------------------------- | 418| timezone | string | 是 | 设置的时区id，如“Asia/Shanghai”。 | 419 420**示例：** 421 ```js 422 var calendar = i18n.getCalendar("zh-Hans"); 423 calendar.setTimeZone("Asia/Shanghai"); 424 ``` 425 426 427### getTimeZone<sup>8+</sup> 428 429getTimeZone(): string 430 431获取日历对象的时区。 432 433**系统能力**：SystemCapability.Global.I18n 434 435**返回值：** 436| 类型 | 说明 | 437| ------ | ---------- | 438| string | 日历对象的时区id。 | 439 440**示例：** 441 ```js 442 var calendar = i18n.getCalendar("zh-Hans"); 443 calendar.setTimeZone("Asia/Shanghai"); 444 calendar.getTimeZone(); // Asia/Shanghai" 445 ``` 446 447 448### getFirstDayOfWeek<sup>8+</sup> 449 450getFirstDayOfWeek(): number 451 452获取日历对象的一周起始日。 453 454**系统能力**：SystemCapability.Global.I18n 455 456**返回值：** 457| 类型 | 说明 | 458| ------ | --------------------- | 459| number | 获取一周的起始日，1代表周日，7代表周六。 | 460 461**示例：** 462 ```js 463 var calendar = i18n.getCalendar("en-US", "gregory"); 464 calendar.getFirstDayOfWeek(); 465 ``` 466 467 468### setFirstDayOfWeek<sup>8+</sup> 469 470setFirstDayOfWeek(value: number): void 471 472设置每一周的起始日。 473 474**系统能力**：SystemCapability.Global.I18n 475 476**参数：** 477| 参数名 | 类型 | 必填 | 说明 | 478| ----- | ------ | ---- | --------------------- | 479| value | number | 否 | 设置一周的起始日，1代表周日，7代表周六。 | 480 481**示例：** 482 ```js 483 var calendar = i18n.getCalendar("zh-Hans"); 484 calendar.setFirstDayOfWeek(0); 485 ``` 486 487 488### getMinimalDaysInFirstWeek<sup>8+</sup> 489 490getMinimalDaysInFirstWeek(): number 491 492获取一年中第一周的最小天数。 493 494**系统能力**：SystemCapability.Global.I18n 495 496**返回值：** 497| 类型 | 说明 | 498| ------ | ------------ | 499| number | 一年中第一周的最小天数。 | 500 501**示例：** 502 ```js 503 var calendar = i18n.getCalendar("zh-Hans"); 504 calendar.getMinimalDaysInFirstWeek(); 505 ``` 506 507 508### setMinimalDaysInFirstWeek<sup>8+</sup> 509 510setMinimalDaysInFirstWeek(value: number): void 511 512设置一年中第一周的最小天数。 513 514**系统能力**：SystemCapability.Global.I18n 515 516**参数：** 517| 参数名 | 类型 | 必填 | 说明 | 518| ----- | ------ | ---- | ------------ | 519| value | number | 否 | 一年中第一周的最小天数。 | 520 521**示例：** 522 ```js 523 var calendar = i18n.getCalendar("zh-Hans"); 524 calendar.setMinimalDaysInFirstWeek(3); 525 ``` 526 527 528### get<sup>8+</sup> 529 530get(field: string): number 531 532获取日历对象中与field相关联的值。 533 534**系统能力**：SystemCapability.Global.I18n 535 536**参数：** 537| 参数名 | 类型 | 必填 | 说明 | 538| ----- | ------ | ---- | ---------------------------------------- | 539| field | string | 是 | 通过field来获取日历对象相应的值。目前支持的field值有 era, year, month, week_of_year, week_of_month, date, day_of_year, day_of_week, day_of_week_in_month, hour, hour_of_day, minute, second, millisecond, zone_offset, dst_offset, year_woy, dow_local, extended_year, julian_day, milliseconds_in_day, is_leap_month。 | 540 541**返回值：** 542| 类型 | 说明 | 543| ------ | ---------------------------------------- | 544| number | 与field相关联的值，如当前Calendar对象的内部日期的年份为1990，get("year")返回1990。 | 545 546**示例：** 547 ```js 548 var calendar = i18n.getCalendar("zh-Hans"); 549 calendar.set(2021, 10, 1, 8, 0, 0); // set time to 2021.10.1 08:00:00 550 calendar.get("hour_of_day"); // 8 551 ``` 552 553 554### getDisplayName<sup>8+</sup> 555 556getDisplayName(locale: string): string 557 558获取日历对象在locale所指定的区域的名字。 559 560**系统能力**：SystemCapability.Global.I18n 561 562**参数：** 563| 参数名 | 类型 | 必填 | 说明 | 564| ------ | ------ | ---- | ---------------------------------------- | 565| locale | string | 是 | locale指定获取哪个区域下该calendar的名字，如buddhist在en-US上显示的名称为“Buddhist Calendar”。 | 566 567**返回值：** 568| 类型 | 说明 | 569| ------ | ------------------- | 570| string | 日历在locale所指示的区域的名字。 | 571 572**示例：** 573 ```js 574 var calendar = i18n.getCalendar("en-US", "buddhist"); 575 calendar.getDisplayName("zh"); // 佛历 576 ``` 577 578 579### isWeekend<sup>8+</sup> 580 581isWeekend(date?: Date): boolean 582 583判断给定的日期是否在日历中是周末。 584 585**系统能力**：SystemCapability.Global.I18n 586 587**参数：** 588| 参数名 | 类型 | 必填 | 说明 | 589| ---- | ---- | ---- | ---------------------------------------- | 590| date | Date | 否 | 判断日期在日历中是否是周末。如果date没有给出，判断calendar当前日期是否为周末。 | 591 592**返回值：** 593| 类型 | 说明 | 594| ------- | ----------------------------------- | 595| boolean | 当所判断的日期为周末时，返回 true，否则返回false。 | 596 597**示例：** 598 ```js 599 var calendar = i18n.getCalendar("zh-Hans"); 600 calendar.set(2021, 11, 11, 8, 0, 0); // set time to 2021.11.11 08:00:00 601 calendar.isWeekend(); // false 602 var date = new Date(2011, 11, 6, 9, 0, 0); 603 calendar.isWeekend(date); // true 604 ``` 605 606 607## PhoneNumberFormat<sup>8+</sup> 608 609 610### constructor<sup>8+</sup> 611 612constructor(country: string, options?: PhoneNumberFormatOptions) 613 614创建电话号码格式化对象。 615 616**系统能力**：SystemCapability.Global.I18n 617 618参数： 619| 参数名 | 类型 | 必填 | 说明 | 620| ------- | ---------------------------------------- | ---- | ---------------- | 621| country | string | 是 | 表示电话号码所属国家或地区代码。 | 622| options | [PhoneNumberFormatOptions](#phonenumberformatoptions8) | 否 | 电话号码格式化对象的相关选项。 | 623 624**示例：** 625 ```js 626 var phoneNumberFormat= new i18n.PhoneNumberFormat("CN", {"type": "E164"}); 627 ``` 628 629 630### isValidNumber<sup>8+</sup> 631 632isValidNumber(number: string): boolean 633 634判断传入的电话号码格式是否正确。 635 636**系统能力**：SystemCapability.Global.I18n 637 638**参数：** 639| 参数名 | 类型 | 必填 | 说明 | 640| ------ | ------ | ---- | --------- | 641| number | string | 是 | 待判断的电话号码。 | 642 643**返回值：** 644| 类型 | 说明 | 645| ------- | ------------------------------------- | 646| boolean | 返回true表示电话号码的格式正确，返回false表示电话号码的格式错误。 | 647 648**示例：** 649 ```js 650 var phonenumberfmt = new i18n.PhoneNumberFormat("CN"); 651 phonenumberfmt.isValidNumber("15812312312"); 652 ``` 653 654 655### format<sup>8+</sup> 656 657format(number: string): string 658 659对电话号码进行格式化。 660 661**系统能力**：SystemCapability.Global.I18n 662 663**参数：** 664| 参数名 | 类型 | 必填 | 说明 | 665| ------ | ------ | ---- | ---------- | 666| number | string | 是 | 待格式化的电话号码。 | 667 668**返回值：** 669| 类型 | 说明 | 670| ------ | ---------- | 671| string | 格式化后的电话号码。 | 672 673**示例：** 674 ```js 675 var phonenumberfmt = new i18n.PhoneNumberFormat("CN"); 676 phonenumberfmt.format("15812312312"); 677 ``` 678 679 680## PhoneNumberFormatOptions<sup>8+</sup> 681 682表示电话号码格式化对象可设置的属性。 683 684**系统能力**：SystemCapability.Global.I18n 685 686| 名称 | 参数类型 | 可读 | 可写 | 说明 | 687| ---- | ------ | ---- | ---- | ---------------------------------------- | 688| type | string | 是 | 是 | 表示对电话号码格式化的类型，取值范围："E164", "INTERNATIONAL", "NATIONAL", "RFC3966"。 | 689 690 691## UnitInfo<sup>8+</sup> 692 693度量衡单位信息。 694 695**系统能力**：SystemCapability.Global.I18n 696 697| 名称 | 参数类型 | 可读 | 可写 | 说明 | 698| ------------- | ------ | ---- | ---- | ---------------------------------------- | 699| unit | string | 是 | 是 | 单位的名称，如："meter", "inch", "cup"等。 | 700| measureSystem | string | 是 | 是 | 单位的度量体系，取值包括："SI", "US", "UK"。 | 701 702 703## Util<sup>8+</sup> 704 705 706### unitConvert<sup>8+</sup> 707 708static unitConvert(fromUnit: UnitInfo, toUnit: UnitInfo, value: number, locale: string, style?: string): string 709 710将fromUnit的单位转换为toUnit的单位，并根据区域与风格进行格式化。 711 712**系统能力**：SystemCapability.Global.I18n 713 714**参数：** 715| 参数名 | 类型 | 必填 | 说明 | 716| -------- | ---------------------- | ---- | ---------------------------------------- | 717| fromUnit | [UnitInfo](#unitinfo8) | 是 | 要被转换的单位。 | 718| toUnit | [UnitInfo](#unitinfo8) | 是 | 要转换为的单位。 | 719| value | number | 是 | 要被转换的单位的数量值。 | 720| locale | string | 是 | 格式化时使用的区域参数，如：zh-Hans-CN。 | 721| style | string | 否 | 格式化使用的风格，取值包括："long", "short", "narrow"。 | 722 723**返回值：** 724| 类型 | 说明 | 725| ------ | ----------------------- | 726| string | 按照toUnit的单位格式化后，得到的字符串。 | 727 728**示例：** 729 ```js 730 i18n.Util.unitConvert({unit: "cup", measureSystem: "US"}, {unit: "liter", measureSystem: "SI"}, 1000, "en-US", "long"); 731 ``` 732 733 734## getInstance<sup>8+</sup> 735 736getInstance(locale?:string): IndexUtil 737 738创建并返回IndexUtil对象。 739 740**系统能力**：SystemCapability.Global.I18n 741 742**参数：** 743| 参数名 | 类型 | 必填 | 说明 | 744| ------ | ------ | ---- | ---------------------------- | 745| locale | string | 否 | 包含区域设置信息的字符串，包括语言以及可选的脚本和区域。 | 746 747**返回值：** 748| 类型 | 说明 | 749| ------------------------ | --------------------- | 750| [IndexUtil](#indexutil8) | locale对应的IndexUtil对象。 | 751 752**示例：** 753 ```js 754 var indexUtil= i18n.getInstance("zh-CN"); 755 ``` 756 757 758## IndexUtil<sup>8+</sup> 759 760 761### getIndexList<sup>8+</sup> 762 763getIndexList(): Array<string> 764 765获取当前locale对应的索引列表。 766 767**系统能力**：SystemCapability.Global.I18n 768 769**返回值：** 770| 类型 | 说明 | 771| ------------------- | ------------------ | 772| Array<string> | 返回当前locale对应的索引列表。 | 773 774**示例：** 775 ```js 776 var indexUtil = i18n.getInstance("zh-CN"); 777 var indexList = indexUtil.getIndexList(); 778 ``` 779 780 781### addLocale<sup>8+</sup> 782 783addLocale(locale: string): void 784 785将新的locale对应的索引加入当前索引列表。 786 787**系统能力**：SystemCapability.Global.I18n 788 789**参数：** 790| 参数名 | 类型 | 必填 | 说明 | 791| ------ | ------ | ---- | ---------------------------- | 792| locale | string | 是 | 包含区域设置信息的字符串，包括语言以及可选的脚本和区域。 | 793 794**示例：** 795 ```js 796 var indexUtil = i18n.getInstance("zh-CN"); 797 indexUtil.addLocale("en-US"); 798 ``` 799 800 801### getIndex<sup>8+</sup> 802 803getIndex(text: string): string 804 805获取text对应的索引。 806 807**系统能力**：SystemCapability.Global.I18n 808 809**参数：** 810| 参数名 | 类型 | 必填 | 说明 | 811| ---- | ------ | ---- | ------------ | 812| text | string | 是 | 待计算索引值的输入文本。 | 813 814**返回值：** 815| 类型 | 说明 | 816| ------ | ----------- | 817| string | 输入文本对应的索引值。 | 818 819**示例：** 820 ```js 821 var indexUtil= i18n.getInstance("zh-CN"); 822 indexUtil.getIndex("hi"); // 返回hi 823 ``` 824 825 826## Character<sup>8+</sup> 827 828 829### isDigit<sup>8+</sup> 830 831static isDigit(char: string): boolean 832 833判断字符串char是否是数字。 834 835**系统能力**：SystemCapability.Global.I18n 836 837**参数：** 838| 参数名 | 类型 | 必填 | 说明 | 839| ---- | ------ | ---- | ----- | 840| char | string | 是 | 输入字符。 | 841 842**返回值：** 843| 类型 | 说明 | 844| ------- | ------------------------------------ | 845| boolean | 返回true表示输入的字符是数字，返回false表示输入的字符不是数字。 | 846 847**示例：** 848 ```js 849 var isdigit = i18n.Character.isDigit("1"); // 返回true 850 ``` 851 852 853### isSpaceChar<sup>8+</sup> 854 855static isSpaceChar(char: string): boolean 856 857判断字符串char是否是空格符。 858 859**系统能力**：SystemCapability.Global.I18n 860 861**参数：** 862| 参数名 | 类型 | 必填 | 说明 | 863| ---- | ------ | ---- | ----- | 864| char | string | 是 | 输入字符。 | 865 866**返回值：** 867| 类型 | 说明 | 868| ------- | -------------------------------------- | 869| boolean | 返回true表示输入的字符是空格符，返回false表示输入的字符不是空格符。 | 870 871**示例：** 872 ```js 873 var isspacechar = i18n.Character.isSpaceChar("a"); // 返回false 874 ``` 875 876 877### isWhitespace<sup>8+</sup> 878 879static isWhitespace(char: string): boolean 880 881判断字符串char是否是空白符。 882 883**系统能力**：SystemCapability.Global.I18n 884 885**参数：** 886| 参数名 | 类型 | 必填 | 说明 | 887| ---- | ------ | ---- | ----- | 888| char | string | 是 | 输入字符。 | 889 890**返回值：** 891| 类型 | 说明 | 892| ------- | -------------------------------------- | 893| boolean | 返回true表示输入的字符是空白符，返回false表示输入的字符不是空白符。 | 894 895**示例：** 896 ```js 897 var iswhitespace = i18n.Character.isWhitespace("a"); // 返回false 898 ``` 899 900 901### isRTL<sup>8+</sup> 902 903static isRTL(char: string): boolean 904 905判断字符串char是否是从右到左语言的字符。 906 907**系统能力**：SystemCapability.Global.I18n 908 909**参数：** 910| 参数名 | 类型 | 必填 | 说明 | 911| ---- | ------ | ---- | ----- | 912| char | string | 是 | 输入字符。 | 913 914**返回值：** 915| 类型 | 说明 | 916| ------- | ---------------------------------------- | 917| boolean | 返回true表示输入的字符是从右到左语言的字符，返回false表示输入的字符不是从右到左语言的字符。 | 918 919**示例：** 920 ```js 921 var isrtl = i18n.Character.isRTL("a"); // 返回false 922 ``` 923 924 925### isIdeograph<sup>8+</sup> 926 927static isIdeograph(char: string): boolean 928 929判断字符串char是否是表意文字。 930 931**系统能力**：SystemCapability.Global.I18n 932 933**参数：** 934| 参数名 | 类型 | 必填 | 说明 | 935| ---- | ------ | ---- | ----- | 936| char | string | 是 | 输入字符。 | 937 938**返回值：** 939| 类型 | 说明 | 940| ------- | ---------------------------------------- | 941| boolean | 返回true表示输入的字符是表意文字，返回false表示输入的字符不是表意文字。 | 942 943**示例：** 944 ```js 945 var isideograph = i18n.Character.isIdeograph("a"); // 返回false 946 ``` 947 948 949### isLetter<sup>8+</sup> 950 951static isLetter(char: string): boolean 952 953判断字符串char是否是字母。 954 955**系统能力**：SystemCapability.Global.I18n 956 957**参数：** 958| 参数名 | 类型 | 必填 | 说明 | 959| ---- | ------ | ---- | ----- | 960| char | string | 是 | 输入字符。 | 961 962**返回值：** 963| 类型 | 说明 | 964| ------- | ------------------------------------ | 965| boolean | 返回true表示输入的字符是字母，返回false表示输入的字符不是字母。 | 966 967**示例：** 968 ```js 969 var isletter = i18n.Character.isLetter("a"); // 返回true 970 ``` 971 972 973### isLowerCase<sup>8+</sup> 974 975static isLowerCase(char: string): boolean 976 977判断字符串char是否是小写字母。 978 979**系统能力**：SystemCapability.Global.I18n 980 981**参数：** 982| 参数名 | 类型 | 必填 | 说明 | 983| ---- | ------ | ---- | ----- | 984| char | string | 是 | 输入字符。 | 985 986**返回值：** 987| 类型 | 说明 | 988| ------- | ---------------------------------------- | 989| boolean | 返回true表示输入的字符是小写字母，返回false表示输入的字符不是小写字母。 | 990 991**示例：** 992 ```js 993 var islowercase = i18n.Character.isLowerCase("a"); // 返回true 994 ``` 995 996 997### isUpperCase<sup>8+</sup> 998 999static isUpperCase(char: string): boolean 1000 1001判断字符串char是否是大写字母。 1002 1003**系统能力**：SystemCapability.Global.I18n 1004 1005**参数：** 1006| 参数名 | 类型 | 必填 | 说明 | 1007| ---- | ------ | ---- | ----- | 1008| char | string | 是 | 输入字符。 | 1009 1010**返回值：** 1011| 类型 | 说明 | 1012| ------- | ---------------------------------------- | 1013| boolean | 返回true表示输入的字符是大写字母，返回false表示输入的字符不是大写字母。 | 1014 1015**示例：** 1016 ```js 1017 var isuppercase = i18n.Character.isUpperCase("a"); // 返回false 1018 ``` 1019 1020 1021### getType<sup>8+</sup> 1022 1023static getType(char: string): string 1024 1025获取输入字符串的一般类别值。 1026 1027**系统能力**：SystemCapability.Global.I18n 1028 1029**参数：** 1030| 参数名 | 类型 | 必填 | 说明 | 1031| ---- | ------ | ---- | ----- | 1032| char | string | 是 | 输入字符。 | 1033 1034**返回值：** 1035| 类型 | 说明 | 1036| ------ | ----------- | 1037| string | 输入字符的一般类别值。 | 1038 1039**示例：** 1040 ```js 1041 var type = i18n.Character.getType("a"); 1042 ``` 1043 1044 1045## i18n.getLineInstance<sup>8+</sup> 1046 1047getLineInstance(locale: string): BreakIterator 1048 1049获取一个用于断句的[BreakIterator](#breakiterator8)对象。 1050 1051**系统能力**：SystemCapability.Global.I18n 1052 1053**参数：** 1054| 参数名 | 类型 | 必填 | 说明 | 1055| ------ | ------ | ---- | ---------------------------------------- | 1056| locale | string | 是 | 合法的locale值，例如zh-Hans-CN。生成的[BreakIterator](#breakiterator8)将按照locale所指定的区域的规则来进行断句。 | 1057 1058**返回值：** 1059| 类型 | 说明 | 1060| -------------------------------- | ----------- | 1061| [BreakIterator](#breakiterator8) | 用于进行断句的处理器。 | 1062 1063**示例：** 1064 ```js 1065 var iterator = i18n.getLineInstance("en"); 1066 ``` 1067 1068 1069## BreakIterator<sup>8+</sup> 1070 1071 1072### setLineBreakText<sup>8+</sup> 1073 1074setLineBreakText(text: string): void 1075 1076设置[BreakIterator](#breakiterator8)要处理的文本。 1077 1078**系统能力**：SystemCapability.Global.I18n 1079 1080**参数：** 1081| 参数名 | 类型 | 必填 | 说明 | 1082| ---- | ------ | ---- | ----------------------- | 1083| text | string | 是 | 指定BreakIterator进行断句的文本。 | 1084 1085**示例：** 1086 ```js 1087 var iterator = i18n.getLineInstance("en"); 1088 iterator.setLineBreakText("Apple is my favorite fruit."); 1089 ``` 1090 1091 1092### getLineBreakText<sup>8+</sup> 1093 1094getLineBreakText(): string 1095 1096获取[BreakIterator](#breakiterator8)当前处理的文本。 1097 1098**系统能力**：SystemCapability.Global.I18n 1099 1100**返回值：** 1101| 类型 | 说明 | 1102| ------ | ---------------------- | 1103| string | BreakIterator对象正在处理的文本 | 1104 1105**示例：** 1106 ```js 1107 var iterator = i18n.getLineInstance("en"); 1108 iterator.setLineBreakText("Apple is my favorite fruit."); 1109 iterator.getLineBreakText(); // Apple is my favorite fruit. 1110 ``` 1111 1112 1113### current<sup>8+</sup> 1114 1115current(): number 1116 1117获取[BreakIterator](#breakiterator8)对象在当前处理的文本中的位置。 1118 1119**系统能力**：SystemCapability.Global.I18n 1120 1121**返回值：** 1122| 类型 | 说明 | 1123| ------ | --------------------------- | 1124| number | BreakIterator在当前所处理的文本中的位置。 | 1125 1126**示例：** 1127 ```js 1128 var iterator = i18n.getLineInstance("en"); 1129 iterator.setLineBreakText("Apple is my favorite fruit."); 1130 iterator.current(); // 0 1131 ``` 1132 1133 1134### first<sup>8+</sup> 1135 1136first(): number 1137 1138将[BreakIterator](#breakiterator8)对象设置到第一个可断句的分割点。第一个分割点总是被处理的文本的起始位置。 1139 1140**系统能力**：SystemCapability.Global.I18n 1141 1142**返回值：** 1143| 类型 | 说明 | 1144| ------ | ----------------- | 1145| number | 被处理文本的第一个分割点的偏移量。 | 1146 1147**示例：** 1148 ```js 1149 var iterator = i18n.getLineInstance("en"); 1150 iterator.setLineBreakText("Apple is my favorite fruit."); 1151 iterator.first(); // 0 1152 ``` 1153 1154 1155### last<sup>8+</sup> 1156 1157last(): number 1158 1159将[BreakIterator](#breakiterator8)对象的位置设置到最后一个可断句的分割点。最后一个分割点总是被处理文本末尾的下一个位置。 1160 1161**系统能力**：SystemCapability.Global.I18n 1162 1163**返回值：** 1164| 类型 | 说明 | 1165| ------ | ------------------ | 1166| number | 被处理的文本的最后一个分割点的偏移量 | 1167 1168**示例：** 1169 ```js 1170 var iterator = i18n.getLineInstance("en"); 1171 iterator.setLineBreakText("Apple is my favorite fruit."); 1172 iterator.last(); // 27 1173 ``` 1174 1175 1176### next<sup>8+</sup> 1177 1178next(index?: number): number 1179 1180如果index给出，并且index是一个正数将[BreakIterator](#breakiterator8)向后移动number个可断句的分割点，如果n是一个负数，向前移动相应个分割点。若index没有给出，则相当于index = 1。 1181 1182**系统能力**：SystemCapability.Global.I18n 1183 1184**参数：** 1185| 参数名 | 类型 | 必填 | 说明 | 1186| ----- | ------ | ---- | ---------------------------------------- | 1187| index | number | 否 | [BreakIterator](#breakiterator8)将要移动的分割点数，正数代表向后移动，负数代表向前移动。若index没有给出，则按照index=1处理。 | 1188 1189**返回值：** 1190| 类型 | 说明 | 1191| ------ | ---------------------------------------- | 1192| number | 返回移动了index个分割点后，当前[BreakIterator](#breakiterator8)在文本中的位置。若移动index个分割点后超出了所处理的文本的长度范围，返回-1。 | 1193 1194**示例：** 1195 ```js 1196 var iterator = i18n.getLineInstance("en"); 1197 iterator.setLineBreakText("Apple is my favorite fruit."); 1198 iterator.first(); // 0 1199 iterator.next(); // 6 1200 iterator.next(10); // -1 1201 ``` 1202 1203 1204### previous<sup>8+</sup> 1205 1206previous(): number 1207 1208将[BreakIterator](#breakiterator8)移动到前一个分割点处。 1209 1210**系统能力**：SystemCapability.Global.I18n 1211 1212**返回值：** 1213| 类型 | 说明 | 1214| ------ | ---------------------------------------- | 1215| number | 返回移动到前一个分割点后，当前[BreakIterator](#breakiterator8)在文本中的位置。若移动index个分割点后超出了所处理的文本的长度范围，返回-1。 | 1216 1217**示例：** 1218 ```js 1219 var iterator = i18n.getLineInstance("en"); 1220 iterator.setLineBreakText("Apple is my favorite fruit."); 1221 iterator.first(); // 0 1222 iterator.next(3); // 12 1223 iterator.previous(); // 9 1224 ``` 1225 1226 1227### following<sup>8+</sup> 1228 1229following(offset: number): number 1230 1231将[BreakIterator](#breakiterator8)设置到由offset指定的位置的后面一个分割点。返回移动后[BreakIterator](#breakiterator8)的位置。 1232 1233**系统能力**：SystemCapability.Global.I18n 1234 1235**参数：** 1236| 参数名 | 类型 | 必填 | 说明 | 1237| ------ | ------ | ---- | ---------------------------------------- | 1238| offset | number | 是 | 将[BreakIterator](#breakiterator8)对象的位置设置到由offset所指定的位置的下一个分割点。 | 1239 1240**返回值：** 1241| 类型 | 说明 | 1242| ------ | ---------------------------------------- | 1243| number | 返回[BreakIterator](#breakiterator8)移动后的位置，如果由offset所指定的位置的下一个分割点超出了文本的范围则返回-1。 | 1244 1245**示例：** 1246 ```js 1247 var iterator = i18n.getLineInstance("en"); 1248 iterator.setLineBreakText("Apple is my favorite fruit."); 1249 iterator.following(0); // 6 1250 iterator.following(100); // -1 1251 iterator.current(); // 27 1252 ``` 1253 1254 1255### isBoundary<sup>8+</sup> 1256 1257isBoundary(offset: number): boolean 1258 1259如果offset所指定的文本位置是一个分割点，那么返回true，否则返回false。如果返回true, 将[BreakIterator](#breakiterator8)对象设置到offset所指定的位置, 否则相当于调用[following](#following8)(offset)。 1260 1261**系统能力**：SystemCapability.Global.I18n 1262 1263**参数：** 1264| 参数名 | 类型 | 必填 | 说明 | 1265| ------ | ------ | ---- | ----------- | 1266| offset | number | 是 | 指定需要进行判断的位置 | 1267 1268**返回值：** 1269| 类型 | 说明 | 1270| ------- | ------------------------------- | 1271| boolean | 如果是一个分割点返回true, 否则返回false。 | 1272 1273**示例：** 1274 ```js 1275 var iterator = i18n.getLineInstance("en"); 1276 iterator.setLineBreakText("Apple is my favorite fruit."); 1277 iterator.isBoundary(0); // true; 1278 iterator.isBoundary(5); // false; 1279 ``` 1280 1281 1282## i18n.is24HourClock<sup>7+</sup> 1283 1284is24HourClock(): boolean 1285 1286判断系统时间是否为24小时制。 1287 1288**系统能力**：SystemCapability.Global.I18n 1289 1290**返回值：** 1291| 类型 | 说明 | 1292| ------- | ---------------------------------------- | 1293| boolean | 返回true，表示系统24小时开关开启；返回false，表示系统24小时开关关闭。 | 1294 1295**示例：** 1296 ```js 1297 var is24HourClock = i18n.is24HourClock(); 1298 ``` 1299 1300 1301## i18n.set24HourClock<sup>7+</sup> 1302 1303set24HourClock(option: boolean): boolean 1304 1305修改系统时间的24小时制设置。 1306 1307**需要权限**：ohos.permission.UPDATE_CONFIGURATION 1308 1309**系统能力**：SystemCapability.Global.I18n 1310 1311**参数：** 1312| 参数名 | 类型 | 必填 | 说明 | 1313| ------ | ------- | ---- | ---------------------------------------- | 1314| option | boolean | 是 | option为true，表示开启系统24小时制开关；返回false，表示关闭系统24小时开关。 | 1315 1316**返回值：** 1317| 类型 | 说明 | 1318| ------- | ----------------------------- | 1319| boolean | 返回true，表示修改成功；返回false，表示修改失败。 | 1320 1321**示例：** 1322 ```js 1323 // 将系统时间设置为24小时制 1324 var success = i18n.set24HourClock(true); 1325 ``` 1326 1327 1328## i18n.addPreferredLanguage<sup>8+</sup> 1329 1330addPreferredLanguage(language: string, index?: number): boolean 1331 1332在系统偏好语言列表中的指定位置添加偏好语言。 1333 1334**需要权限**：ohos.permission.UPDATE_CONFIGURATION 1335 1336**系统能力**：SystemCapability.Global.I18n 1337 1338**参数：** 1339| 参数名 | 类型 | 必填 | 说明 | 1340| -------- | ------ | ---- | ---------- | 1341| language | string | 是 | 待添加的偏好语言。 | 1342| index | number | 否 | 偏好语言的添加位置。 | 1343 1344**返回值：** 1345| 类型 | 说明 | 1346| ------- | ----------------------------- | 1347| boolean | 返回true，表示添加成功；返回false，表示添加失败。 | 1348 1349**示例：** 1350 ```js 1351 // 将语言zh-CN添加到系统偏好语言列表中 1352 var language = 'zh-CN'; 1353 var index = 0; 1354 var success = i18n.addPreferredLanguage(language, index); 1355 ``` 1356 1357 1358## i18n.removePreferredLanguage<sup>8+</sup> 1359 1360removePreferredLanguage(index: number): boolean 1361 1362删除系统偏好语言列表中指定位置的偏好语言。 1363 1364**需要权限**：ohos.permission.UPDATE_CONFIGURATION 1365 1366**系统能力**：SystemCapability.Global.I18n 1367 1368**参数：** 1369| 参数名 | 类型 | 必填 | 说明 | 1370| ----- | ------ | ---- | --------------------- | 1371| index | number | 是 | 待删除偏好语言在系统偏好语言列表中的位置。 | 1372 1373**返回值：** 1374| 类型 | 说明 | 1375| ------- | ----------------------------- | 1376| boolean | 返回true，表示删除成功；返回false，表示删除失败。 | 1377 1378**示例：** 1379 ```js 1380 // 删除系统偏好语言列表中的第一个偏好语言 1381 var index = 0; 1382 var success = i18n.removePreferredLanguage(index); 1383 ``` 1384 1385 1386## i18n.getPreferredLanguageList<sup>8+</sup> 1387 1388getPreferredLanguageList(): Array<string> 1389 1390获取系统偏好语言列表。 1391 1392**系统能力**：SystemCapability.Global.I18n 1393 1394**返回值：** 1395| 类型 | 说明 | 1396| ------------------- | --------- | 1397| Array<string> | 系统偏好语言列表。 | 1398 1399**示例：** 1400 ```js 1401 var preferredLanguageList = i18n.getPreferredLanguageList(); 1402 ``` 1403 1404 1405## i18n.getFirstPreferredLanguage<sup>8+</sup> 1406 1407getFirstPreferredLanguage(): string 1408 1409获取偏好语言列表中的第一个偏好语言。 1410 1411**系统能力**：SystemCapability.Global.I18n 1412 1413**返回值：** 1414| 类型 | 说明 | 1415| ------ | -------------- | 1416| string | 偏好语言列表中的第一个语言。 | 1417 1418**示例：** 1419 ```js 1420 var firstPreferredLanguage = i18n.getFirstPreferredLanguage(); 1421 ``` 1422 1423 1424## i18n.getTimeZone<sup>7+</sup> 1425 1426getTimeZone(zoneID?: string): TimeZone 1427 1428获取时区ID对应的时区对象。 1429 1430**系统能力**：SystemCapability.Global.I18n 1431 1432**参数：** 1433| 参数名 | 类型 | 必填 | 说明 | 1434| ------ | ------ | ---- | ----- | 1435| zondID | string | 否 | 时区ID。 | 1436 1437**返回值：** 1438| 类型 | 说明 | 1439| -------- | ------------ | 1440| TimeZone | 时区ID对应的时区对象。 | 1441 1442**示例：** 1443 ```js 1444 var timezone = i18n.getTimeZone(); 1445 ``` 1446 1447 1448## TimeZone 1449 1450 1451### getID 1452 1453getID(): string 1454 1455获取时区对象的ID。 1456 1457**系统能力**：SystemCapability.Global.I18n 1458 1459**返回值：** 1460| 类型 | 说明 | 1461| ------ | ------------ | 1462| string | 时区对象对应的时区ID。 | 1463 1464**示例：** 1465 ```js 1466 var timezone = i18n.getTimeZone(); 1467 timezone.getID(); 1468 ``` 1469 1470 1471### getDisplayName 1472 1473getDisplayName(locale?: string, isDST?: boolean): string 1474 1475获取时区对象在指定区域的表示。 1476 1477**系统能力**：SystemCapability.Global.I18n 1478 1479**参数：** 1480| 参数名 | 类型 | 必填 | 说明 | 1481| ------ | ------- | ---- | -------------------- | 1482| locale | string | 否 | 区域ID。 | 1483| isDST | boolean | 否 | 表示获取时区对象的表示时是否考虑夏令时。 | 1484 1485**返回值：** 1486| 类型 | 说明 | 1487| ------ | ------------- | 1488| string | 时区对象在指定区域的表示。 | 1489 1490**示例：** 1491 ```js 1492 var timezone = i18n.getTimeZone(); 1493 timezone.getDisplayName("zh-CN", false); 1494 ``` 1495 1496 1497### getRawOffset 1498 1499getRawOffset(): number 1500 1501获取时区对象表示的时区与UTC时区的偏差。 1502 1503**系统能力**：SystemCapability.Global.I18n 1504 1505**返回值：** 1506| 类型 | 说明 | 1507| ------ | ------------------- | 1508| number | 时区对象表示的时区与UTC时区的偏差。 | 1509 1510**示例：** 1511 ```js 1512 var timezone = i18n.getTimeZone(); 1513 timezone.getRawOffset(); 1514 ``` 1515 1516 1517### getOffset 1518 1519getOffset(date?: number): number 1520 1521获取某一时刻时区对象表示的时区与UTC时区的偏差。 1522 1523**系统能力**：SystemCapability.Global.I18n 1524 1525**返回值：** 1526| 类型 | 说明 | 1527| ------ | ----------------------- | 1528| number | 某一时刻时区对象表示的时区与UTC时区的偏差。 | 1529 1530**示例：** 1531 ```js 1532 var timezone = i18n.getTimeZone(); 1533 timezone.getOffset(1234567890); 1534 ``` 1535