1# @ohos.i18n (国际化-I18n)(系统接口) 2 3 本模块提供系统相关的或者增强的国际化能力，包括区域管理、电话号码处理、日历等，相关接口为ECMA 402标准中未定义的补充接口。[Intl模块](js-apis-intl.md)提供了ECMA 402标准定义的基础国际化接口，与本模块共同使用可提供完整地国际化支持能力。 4 5> **说明：** 6> - 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 7> 8> - 从API version 11开始，本模块部分接口支持在ArkTS卡片中使用。 9> 10> - 当前页面仅包含本模块的系统接口，其他公开接口参见[@ohos.i18n (国际化-I18n)](js-apis-intl.md)。 11 12 13## 导入模块 14 15```ts 16import { i18n } from '@kit.LocalizationKit'; 17``` 18 19## System<sup>9+</sup> 20 21### setSystemLanguage<sup>9+</sup> 22 23static setSystemLanguage(language: string): void 24 25设置系统语言。当前调用该接口不支持系统界面语言的实时刷新。 26 27若设置系统语言后，需要[监听事件](../apis-basic-services-kit/common_event/commonEventManager-definitions.md#common_event_locale_changed)OHOS::EventFwk::CommonEventSupport::COMMON_EVENT_LOCALE_CHANGED，可以[订阅](../apis-basic-services-kit/js-apis-commonEventManager.md#commoneventmanagercreatesubscriber-1)该事件。 28 29**系统接口**：此接口为系统接口。 30 31**需要权限**：ohos.permission.UPDATE_CONFIGURATION 32 33**系统能力**：SystemCapability.Global.I18n 34 35**参数：** 36 37| 参数名 | 类型 | 必填 | 说明 | 38| -------- | ------ | ---- | ----- | 39| language | string | 是 | 合法的语言ID。 | 40 41**错误码：** 42 43以下错误码的详细介绍请参见[ohos.i18n错误码](errorcode-i18n.md)和[通用错误码](../errorcode-universal.md)。 44 45| 错误码ID | 错误信息 | 46| ------ | ---------------------- | 47| 201 | Permission verification failed. The application does not have the permission required to call the API. | 48| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 49| 890001 | Invalid parameter. Possible causes: Parameter verification failed. | 50 51**示例：** 52 ```ts 53 import { BusinessError, commonEventManager } from '@kit.BasicServicesKit'; 54 55 // 设置系统语言 56 try { 57 i18n.System.setSystemLanguage('zh'); // 设置系统当前语言为 "zh" 58 } catch(error) { 59 let err: BusinessError = error as BusinessError; 60 console.error(`call System.setSystemLanguage failed, error code: ${err.code}, message: ${err.message}.`); 61 } 62 63 // 订阅公共事件 64 let subscriber: commonEventManager.CommonEventSubscriber; // 用于保存创建成功的订阅者对象，后续使用其完成订阅及退订的动作 65 let subscribeInfo: commonEventManager.CommonEventSubscribeInfo = { // 订阅者信息 66 events: [commonEventManager.Support.COMMON_EVENT_LOCALE_CHANGED] 67 }; 68 commonEventManager.createSubscriber(subscribeInfo).then((commonEventSubscriber:commonEventManager.CommonEventSubscriber) => { // 创建订阅者 69 console.info("createSubscriber"); 70 subscriber = commonEventSubscriber; 71 commonEventManager.subscribe(subscriber, (err, data) => { 72 if (err) { 73 console.error(`Failed to subscribe common event. error code: ${err.code}, message: ${err.message}.`); 74 return; 75 } 76 console.info("the subscribed event has occurred."); // 订阅的事件发生时执行 77 }) 78 }).catch((err: BusinessError) => { 79 console.error(`createSubscriber failed, code is ${err.code}, message is ${err.message}`); 80 }); 81 ``` 82 83### setSystemRegion<sup>9+</sup> 84 85static setSystemRegion(region: string): void 86 87设置系统区域。 88 89**系统接口**：此接口为系统接口。 90 91**需要权限**：ohos.permission.UPDATE_CONFIGURATION 92 93**系统能力**：SystemCapability.Global.I18n 94 95**参数：** 96 97| 参数名 | 类型 | 必填 | 说明 | 98| ------ | ------ | ---- | ----- | 99| region | string | 是 | 合法的地区ID。 | 100 101**错误码：** 102 103以下错误码的详细介绍请参见[ohos.i18n错误码](errorcode-i18n.md)和[通用错误码](../errorcode-universal.md)。 104 105| 错误码ID | 错误信息 | 106| ------ | ---------------------- | 107| 201 | Permission verification failed. The application does not have the permission required to call the API. | 108| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 109| 890001 | Invalid parameter. Possible causes: Parameter verification failed. | 110 111**示例：** 112 ```ts 113 import { BusinessError } from '@kit.BasicServicesKit'; 114 115 try { 116 i18n.System.setSystemRegion('CN'); // 设置系统当前地区为 "CN" 117 } catch(error) { 118 let err: BusinessError = error as BusinessError; 119 console.error(`call System.setSystemRegion failed, error code: ${err.code}, message: ${err.message}.`); 120 } 121 ``` 122 123 124 125### setSystemLocale<sup>9+</sup> 126 127static setSystemLocale(locale: string): void 128 129设置系统Locale。 130 131**系统接口**：此接口为系统接口。 132 133**需要权限**：ohos.permission.UPDATE_CONFIGURATION 134 135**系统能力**：SystemCapability.Global.I18n 136 137**参数：** 138 139| 参数名 | 类型 | 必填 | 说明 | 140| ------ | ------ | ---- | --------------- | 141| locale | string | 是 | 合法的区域ID，例如zh-CN。 | 142 143**错误码：** 144 145以下错误码的详细介绍请参见[ohos.i18n错误码](errorcode-i18n.md)和[通用错误码](../errorcode-universal.md)。 146 147| 错误码ID | 错误信息 | 148| ------ | ---------------------- | 149| 201 | Permission verification failed. The application does not have the permission required to call the API. | 150| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 151| 890001 | Invalid parameter. Possible causes: Parameter verification failed. | 152 153**示例：** 154 ```ts 155 import { BusinessError } from '@kit.BasicServicesKit'; 156 157 try { 158 i18n.System.setSystemLocale('zh-CN'); // 设置系统当前Locale为 "zh-CN" 159 } catch(error) { 160 let err: BusinessError = error as BusinessError; 161 console.error(`call System.setSystemLocale failed, error code: ${err.code}, message: ${err.message}.`); 162 } 163 ``` 164 165 166### set24HourClock<sup>9+</sup> 167 168static set24HourClock(option: boolean): void 169 170设置系统时间为24小时。 171 172**系统接口**：此接口为系统接口。 173 174**需要权限**：ohos.permission.UPDATE_CONFIGURATION 175 176**系统能力**：SystemCapability.Global.I18n 177 178**参数：** 179 180| 参数名 | 类型 | 必填 | 说明 | 181| ------ | ------- | ---- | ---------------------------------------- | 182| option | boolean | 是 | option为true，表示开启系统24小时制开关；返回false，表示关闭系统24小时开关。 | 183 184**错误码：** 185 186以下错误码的详细介绍请参见[ohos.i18n错误码](errorcode-i18n.md)和[通用错误码](../errorcode-universal.md)。 187 188| 错误码ID | 错误信息 | 189| ------ | ---------------------- | 190| 201 | Permission verification failed. The application does not have the permission required to call the API. | 191| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 192| 890001 | Invalid parameter. Possible causes: Parameter verification failed. | 193 194**示例：** 195 ```ts 196 import { BusinessError } from '@kit.BasicServicesKit'; 197 198 // 将系统时间设置为24小时制 199 try { 200 i18n.System.set24HourClock(true); 201 } catch(error) { 202 let err: BusinessError = error as BusinessError; 203 console.error(`call System.set24HourClock failed, error code: ${err.code}, message: ${err.message}.`); 204 } 205 ``` 206 207### addPreferredLanguage<sup>9+</sup> 208 209static addPreferredLanguage(language: string, index?: number): void 210 211在系统偏好语言列表中的指定位置添加偏好语言。 212 213**系统接口**：此接口为系统接口。 214 215**需要权限**：ohos.permission.UPDATE_CONFIGURATION 216 217**系统能力**：SystemCapability.Global.I18n 218 219**参数：** 220 221| 参数名 | 类型 | 必填 | 说明 | 222| -------- | ------ | ---- | ---------- | 223| language | string | 是 | 待添加的偏好语言，要求是合法的语言ID。 | 224| index | number | 否 | 偏好语言的添加位置。默认值：系统偏好语言列表长度。 | 225 226**错误码：** 227 228以下错误码的详细介绍请参见[ohos.i18n错误码](errorcode-i18n.md)和[通用错误码](../errorcode-universal.md)。 229 230| 错误码ID | 错误信息 | 231| ------ | ---------------------- | 232| 201 | Permission verification failed. The application does not have the permission required to call the API. | 233| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 234| 890001 | Invalid parameter. Possible causes: Parameter verification failed. | 235 236**示例：** 237 ```ts 238 import { BusinessError } from '@kit.BasicServicesKit'; 239 240 // 将语言zh-CN添加到系统偏好语言列表中 241 let language = 'zh-CN'; 242 let index = 0; 243 try { 244 i18n.System.addPreferredLanguage(language, index); // 将zh-CN添加到系统偏好语言列表的第1位 245 } catch(error) { 246 let err: BusinessError = error as BusinessError; 247 console.error(`call System.addPreferredLanguage failed, error code: ${err.code}, message: ${err.message}.`); 248 } 249 ``` 250 251### removePreferredLanguage<sup>9+</sup> 252 253static removePreferredLanguage(index: number): void 254 255删除系统偏好语言列表中指定位置的偏好语言。 256 257**系统接口**：此接口为系统接口。 258 259**需要权限**：ohos.permission.UPDATE_CONFIGURATION 260 261**系统能力**：SystemCapability.Global.I18n 262 263**参数：** 264 265| 参数名 | 类型 | 必填 | 说明 | 266| ----- | ------ | ---- | --------------------- | 267| index | number | 是 | 待删除偏好语言在系统偏好语言列表中的位置。 | 268 269**错误码：** 270 271以下错误码的详细介绍请参见[ohos.i18n错误码](errorcode-i18n.md)和[通用错误码](../errorcode-universal.md)。 272 273| 错误码ID | 错误信息 | 274| ------ | ---------------------- | 275| 201 | Permission verification failed. The application does not have the permission required to call the API. | 276| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 277| 890001 | Invalid parameter. Possible causes: Parameter verification failed. | 278 279**示例：** 280 ```ts 281 import { BusinessError } from '@kit.BasicServicesKit'; 282 283 // 删除系统偏好语言列表中的第一个偏好语言 284 let index: number = 0; 285 try { 286 i18n.System.removePreferredLanguage(index); 287 } catch(error) { 288 let err: BusinessError = error as BusinessError; 289 console.error(`call System.removePreferredLanguage failed, error code: ${err.code}, message: ${err.message}.`); 290 } 291 ``` 292 293### setUsingLocalDigit<sup>9+</sup> 294 295static setUsingLocalDigit(flag: boolean): void 296 297设置系统是否使用本地数字。 298 299**系统接口**：此接口为系统接口。 300 301**需要权限**：ohos.permission.UPDATE_CONFIGURATION 302 303**系统能力**：SystemCapability.Global.I18n 304 305**参数：** 306 307| 参数名 | 类型 | 必填 | 说明 | 308| ---- | ------- | ---- | ------------------------------- | 309| flag | boolean | 是 | true表示打开本地数字开关，false表示关闭本地数字开关。 | 310 311**错误码：** 312 313以下错误码的详细介绍请参见[ohos.i18n错误码](errorcode-i18n.md)和[通用错误码](../errorcode-universal.md)。 314 315| 错误码ID | 错误信息 | 316| ------ | ---------------------- | 317| 201 | Permission verification failed. The application does not have the permission required to call the API. | 318| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 319| 890001 | Invalid parameter. Possible causes: Parameter verification failed. | 320 321**示例：** 322 ```ts 323 import { BusinessError } from '@kit.BasicServicesKit'; 324 325 try { 326 i18n.System.setUsingLocalDigit(true); // 打开本地化数字开关 327 } catch(error) { 328 let err: BusinessError = error as BusinessError; 329 console.error(`call System.setUsingLocalDigit failed, error code: ${err.code}, message: ${err.message}.`); 330 } 331 ``` 332 333## SystemLocaleManager<sup>10+</sup> 334 335### constructor<sup>10+</sup> 336 337constructor() 338 339创建SystemLocaleManager对象。 340 341**系统接口**：此接口为系统接口。 342 343**系统能力**：SystemCapability.Global.I18n 344 345**示例：** 346 ```ts 347 let systemLocaleManager: i18n.SystemLocaleManager = new i18n.SystemLocaleManager(); 348 ``` 349 350 351### getLanguageInfoArray<sup>10+</sup> 352 353getLanguageInfoArray(languages: Array<string>, options?: SortOptions): Array<LocaleItem> 354 355获取语言排序数组。 356 357**系统接口**：此接口为系统接口。 358 359**系统能力**：SystemCapability.Global.I18n 360 361**参数：** 362 363| 参数名 | 类型 | 必填 | 说明 | 364| --------- | ------------- | ---- | ------------- | 365| languages | Array<string> | 是 | 待排序语言列表，要求是合法的语言ID。| 366| options | [SortOptions](#sortoptions10) | 否 | 语言排序选项。 | 367 368**返回值：** 369 370| 类型 | 说明 | 371| ----------------- | -------------------- | 372| Array<[LocaleItem](#localeitem10)> | 排序后的语言列表信息。 | 373 374**错误码：** 375 376以下错误码的详细介绍请参见[ohos.i18n错误码](errorcode-i18n.md)和[通用错误码](../errorcode-universal.md)。 377 378| 错误码ID | 错误信息 | 379| ------ | ---------------------- | 380| 202 | Permission verification failed. A non-system application calls a system API. | 381| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 382| 890001 | Invalid parameter. Possible causes: Parameter verification failed. | 383 384**示例：** 385 ```ts 386 import { BusinessError } from '@kit.BasicServicesKit'; 387 388 // 当系统语言为zh-Hans，系统地区为CN，系统Locale为zh-Hans-CN时 389 let systemLocaleManager: i18n.SystemLocaleManager = new i18n.SystemLocaleManager(); 390 let languages: string[] = ["zh-Hans", "en-US", "pt", "ar"]; 391 let sortOptions: i18n.SortOptions = {locale: "zh-Hans-CN", isUseLocalName: true, isSuggestedFirst: true}; 392 try { 393 // 排序后的语言顺序为: [zh-Hans, en-US, pt, ar] 394 let sortedLanguages: Array<i18n.LocaleItem> = systemLocaleManager.getLanguageInfoArray(languages, sortOptions); 395 } catch(error) { 396 let err: BusinessError = error as BusinessError; 397 console.error(`call systemLocaleManager.getLanguageInfoArray failed, error code: ${err.code}, message: ${err.message}.`); 398 } 399 ``` 400 401 402### getRegionInfoArray<sup>10+</sup> 403 404getRegionInfoArray(regions: Array<string>, options?: SortOptions): Array<LocaleItem> 405 406获取国家或地区排序数组。 407 408**系统接口**：此接口为系统接口。 409 410**系统能力**：SystemCapability.Global.I18n 411 412**参数：** 413 414| 参数名 | 类型 | 必填 | 说明 | 415| --------- | ------------- | ---- | ------------- | 416| regions | Array<string> | 是 | 待排序的国家或地区列表，要求是合法的国家或地区ID。| 417| options | [SortOptions](#sortoptions10) | 否 | 国家或地区排序选项。默认值：locale的默认值为系统Locale，isUseLocalName的默认值为false，isSuggestedFirst的默认值为true。 | 418 419**返回值：** 420 421| 类型 | 说明 | 422| ----------------- | -------------------- | 423| Array<[LocaleItem](#localeitem10)> | 排序后的国家或地区列表信息。 | 424 425**错误码：** 426 427以下错误码的详细介绍请参见[ohos.i18n错误码](errorcode-i18n.md)和[通用错误码](../errorcode-universal.md)。 428 429| 错误码ID | 错误信息 | 430| ------ | ---------------------- | 431| 202 | Permission verification failed. A non-system application calls a system API. | 432| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 433| 890001 | Invalid parameter. Possible causes: Parameter verification failed. | 434 435**示例：** 436 ```ts 437 import { BusinessError } from '@kit.BasicServicesKit'; 438 439 // 当系统语言为zh-Hans，系统地区为CN，系统Locale为zh-Hans-CN时 440 let systemLocaleManager: i18n.SystemLocaleManager = new i18n.SystemLocaleManager(); 441 let regions: string[] = ["CN", "US", "PT", "EG"]; 442 let sortOptions: i18n.SortOptions = {locale: "zh-Hans-CN", isUseLocalName: false, isSuggestedFirst: true}; 443 try { 444 // 排序后的地区顺序为: [CN, EG, US, PT] 445 let sortedRegions: Array<i18n.LocaleItem> = systemLocaleManager.getRegionInfoArray(regions, sortOptions); 446 } catch(error) { 447 let err: BusinessError = error as BusinessError; 448 console.error(`call systemLocaleManager.getRegionInfoArray failed, error code: ${err.code}, message: ${err.message}.`); 449 } 450 ``` 451 452### getTimeZoneCityItemArray<sup>10+</sup> 453 454static getTimeZoneCityItemArray(): Array<TimeZoneCityItem> 455 456获取时区城市组合信息的数组。 457 458**系统接口**：此接口为系统接口。 459 460**系统能力**：SystemCapability.Global.I18n 461 462**返回值：** 463 464| 类型 | 说明 | 465| ----------------- | -------------------- | 466| Array<[TimeZoneCityItem](#timezonecityitem10)> | 排序后的时区城市组合信息数组。 | 467 468**错误码：** 469 470以下错误码的详细介绍请参见[ohos.i18n错误码](errorcode-i18n.md)和[通用错误码](../errorcode-universal.md)。 471 472| 错误码ID | 错误信息 | 473| ------ | ---------------------- | 474| 202 | Permission verification failed. A non-system application calls a system API. | 475 476**示例：** 477 ```ts 478 import { BusinessError } from '@kit.BasicServicesKit'; 479 480 try { 481 let timeZoneCityItemArray: Array<i18n.TimeZoneCityItem> = i18n.SystemLocaleManager.getTimeZoneCityItemArray(); 482 for (let i = 0; i < timeZoneCityItemArray.length; i++) { 483 console.log(timeZoneCityItemArray[i].zoneId + ", " + timeZoneCityItemArray[i].cityId + ", " + timeZoneCityItemArray[i].cityDisplayName + 484 ", " + timeZoneCityItemArray[i].offset + "\r\n"); 485 } 486 } catch(error) { 487 let err: BusinessError = error as BusinessError; 488 console.error(`call SystemLocaleManager.getTimeZoneCityItemArray failed, error code: ${err.code}, message: ${err.message}.`); 489 } 490 ``` 491 492## LocaleItem<sup>10+</sup> 493 494SystemLocaleManager对语言或国家地区列表的排序结果信息项。 495 496**系统接口**：此接口为系统接口。 497 498**系统能力**：SystemCapability.Global.I18n 499 500| 名称 | 类型 | 必填 | 说明 | 501| --------------- | --------------- | ------ | --------------------------------------- | 502| id | string | 是 | 语言代码或国家地区代码，如"zh"、"CN"。 | 503| suggestionType | [SuggestionType](#suggestiontype10) | 是 | 语言或国家地区推荐类型。 | 504| displayName | string | 是 | id在SystemLocaleManager的Locale下的表示。| 505| localName | string | 否 | id的本地名称。 | 506 507## TimeZoneCityItem<sup>10+</sup> 508 509时区城市组合信息。 510 511**系统接口**：此接口为系统接口。 512 513**系统能力**：SystemCapability.Global.I18n 514 515| 名称 | 类型 | 必填 | 说明 | 516| --------------- | --------------- | ------ | --------------------------------------- | 517| zoneId | string | 是 | 时区Id，例如Asia/Shanghai。 | 518| cityId | string | 是 | 城市Id，例如Shanghai。 | 519| cityDisplayName | string | 是 | 城市Id在系统Locale下显示的名称。 | 520| offset | int | 是 | 时区Id的偏移量。 | 521| zoneDisplayName | string | 是 | 时区Id在系统Locale下显示的名称。 | 522| rawOffset | int | 否 | 时区Id的固定偏移量。 | 523 524 525## SuggestionType<sup>10+</sup> 526 527语言或国家地区的推荐类型。 528 529**系统接口**：此接口为系统接口。 530 531**系统能力**：SystemCapability.Global.I18n 532 533| 名称 | 值 | 说明 | 534| ---------------------- | ---- | ---- | 535| SUGGESTION_TYPE_NONE | 0x00 | 非推荐语言或国家地区。 | 536| SUGGESTION_TYPE_RELATED| 0x01 | 系统语言推荐的国家地区或系统国家地区推荐的语言。 | 537| SUGGESTION_TYPE_SIM | 0x02 | Sim卡国家地区推荐的语言。 | 538 539 540## SortOptions<sup>10+<sup> 541 542语言或国家地区排序选项。 543 544**系统接口**：此接口为系统接口。 545 546**系统能力**：SystemCapability.Global.I18n 547 548| 名称 | 类型 | 必填 | 说明 | 549| --------------- | --------------- | ---- | --------------------------------------- | 550| locale | string | 否 | 区域代码，如"zh-Hans-CN"。locale属性默认值为系统Locale。 | 551| isUseLocalName | boolean | 否 | 表示是否使用本地名称进行排序。若调用方法为getLanguageInfoArray，isUseLocalName属性默认值为true。若调用方法为getRegionInfoArray，isUseLocalName属性默认值为false。 | 552| isSuggestedFirst | boolean | 否 | 表示是否将推荐语言或国家地区在排序结果中置顶。isSuggestedFirst属性默认值为true。 | 553