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。 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若要监听系统区域变化,可以监听[事件](../apis-basic-services-kit/common_event/commonEventManager-definitions.md#common_event_locale_changed)OHOS::EventFwk::CommonEventSupport::COMMON_EVENT_LOCALE_CHANGED。 90 91**系统接口**:此接口为系统接口。 92 93**需要权限**:ohos.permission.UPDATE_CONFIGURATION 94 95**系统能力**:SystemCapability.Global.I18n 96 97**参数:** 98 99| 参数名 | 类型 | 必填 | 说明 | 100| ------ | ------ | ---- | ----- | 101| region | string | 是 | 合法的地区ID。 | 102 103**错误码:** 104 105以下错误码的详细介绍请参见[ohos.i18n错误码](errorcode-i18n.md)和[通用错误码](../errorcode-universal.md)。 106 107| 错误码ID | 错误信息 | 108| ------ | ---------------------- | 109| 201 | Permission verification failed. The application does not have the permission required to call the API. | 110| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 111| 890001 | Invalid parameter. Possible causes: Parameter verification failed. | 112 113**示例:** 114 ```ts 115 import { BusinessError } from '@kit.BasicServicesKit'; 116 117 try { 118 i18n.System.setSystemRegion('CN'); // 设置系统当前地区为 "CN" 119 } catch(error) { 120 let err: BusinessError = error as BusinessError; 121 console.error(`call System.setSystemRegion failed, error code: ${err.code}, message: ${err.message}.`); 122 } 123 ``` 124 125 126 127### setSystemLocale<sup>9+</sup> 128 129static setSystemLocale(locale: string): void 130 131设置系统Locale。 132 133若要监听系统Locale变化,可以监听[事件](../apis-basic-services-kit/common_event/commonEventManager-definitions.md#common_event_locale_changed)OHOS::EventFwk::CommonEventSupport::COMMON_EVENT_LOCALE_CHANGED。 134 135**系统接口**:此接口为系统接口。 136 137**需要权限**:ohos.permission.UPDATE_CONFIGURATION 138 139**系统能力**:SystemCapability.Global.I18n 140 141**参数:** 142 143| 参数名 | 类型 | 必填 | 说明 | 144| ------ | ------ | ---- | --------------- | 145| locale | string | 是 | [表示区域信息的字符串](../../internationalization/i18n-locale-culture.md#实现原理),由语言、脚本、国家或地区组成。 | 146 147**错误码:** 148 149以下错误码的详细介绍请参见[ohos.i18n错误码](errorcode-i18n.md)和[通用错误码](../errorcode-universal.md)。 150 151| 错误码ID | 错误信息 | 152| ------ | ---------------------- | 153| 201 | Permission verification failed. The application does not have the permission required to call the API. | 154| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 155| 890001 | Invalid parameter. Possible causes: Parameter verification failed. | 156 157**示例:** 158 ```ts 159 import { BusinessError } from '@kit.BasicServicesKit'; 160 161 try { 162 i18n.System.setSystemLocale('zh-CN'); // 设置系统当前Locale为 "zh-CN" 163 } catch(error) { 164 let err: BusinessError = error as BusinessError; 165 console.error(`call System.setSystemLocale failed, error code: ${err.code}, message: ${err.message}.`); 166 } 167 ``` 168 169 170### set24HourClock<sup>9+</sup> 171 172static set24HourClock(option: boolean): void 173 174设置系统时间为24小时。 175 176**系统接口**:此接口为系统接口。 177 178**需要权限**:ohos.permission.UPDATE_CONFIGURATION 179 180**系统能力**:SystemCapability.Global.I18n 181 182**参数:** 183 184| 参数名 | 类型 | 必填 | 说明 | 185| ------ | ------- | ---- | ---------------------------------------- | 186| option | boolean | 是 | option为true,表示开启系统24小时制开关;返回false,表示关闭系统24小时开关。 | 187 188**错误码:** 189 190以下错误码的详细介绍请参见[ohos.i18n错误码](errorcode-i18n.md)和[通用错误码](../errorcode-universal.md)。 191 192| 错误码ID | 错误信息 | 193| ------ | ---------------------- | 194| 201 | Permission verification failed. The application does not have the permission required to call the API. | 195| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 196| 890001 | Invalid parameter. Possible causes: Parameter verification failed. | 197 198**示例:** 199 ```ts 200 import { BusinessError } from '@kit.BasicServicesKit'; 201 202 // 将系统时间设置为24小时制 203 try { 204 i18n.System.set24HourClock(true); 205 } catch(error) { 206 let err: BusinessError = error as BusinessError; 207 console.error(`call System.set24HourClock failed, error code: ${err.code}, message: ${err.message}.`); 208 } 209 ``` 210 211### addPreferredLanguage<sup>9+</sup> 212 213static addPreferredLanguage(language: string, index?: number): void 214 215在系统偏好语言列表中的指定位置添加偏好语言。 216 217**系统接口**:此接口为系统接口。 218 219**需要权限**:ohos.permission.UPDATE_CONFIGURATION 220 221**系统能力**:SystemCapability.Global.I18n 222 223**参数:** 224 225| 参数名 | 类型 | 必填 | 说明 | 226| -------- | ------ | ---- | ---------- | 227| language | string | 是 | 待添加的偏好语言,要求是合法的语言ID。 | 228| index | number | 否 | 偏好语言的添加位置。默认值:系统偏好语言列表长度。 | 229 230**错误码:** 231 232以下错误码的详细介绍请参见[ohos.i18n错误码](errorcode-i18n.md)和[通用错误码](../errorcode-universal.md)。 233 234| 错误码ID | 错误信息 | 235| ------ | ---------------------- | 236| 201 | Permission verification failed. The application does not have the permission required to call the API. | 237| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 238| 890001 | Invalid parameter. Possible causes: Parameter verification failed. | 239 240**示例:** 241 ```ts 242 import { BusinessError } from '@kit.BasicServicesKit'; 243 244 // 将语言zh-CN添加到系统偏好语言列表中 245 let language = 'zh-CN'; 246 let index = 0; 247 try { 248 i18n.System.addPreferredLanguage(language, index); // 将zh-CN添加到系统偏好语言列表的第1位 249 } catch(error) { 250 let err: BusinessError = error as BusinessError; 251 console.error(`call System.addPreferredLanguage failed, error code: ${err.code}, message: ${err.message}.`); 252 } 253 ``` 254 255### removePreferredLanguage<sup>9+</sup> 256 257static removePreferredLanguage(index: number): void 258 259删除系统偏好语言列表中指定位置的偏好语言。 260 261**系统接口**:此接口为系统接口。 262 263**需要权限**:ohos.permission.UPDATE_CONFIGURATION 264 265**系统能力**:SystemCapability.Global.I18n 266 267**参数:** 268 269| 参数名 | 类型 | 必填 | 说明 | 270| ----- | ------ | ---- | --------------------- | 271| index | number | 是 | 待删除偏好语言在系统偏好语言列表中的位置。 | 272 273**错误码:** 274 275以下错误码的详细介绍请参见[ohos.i18n错误码](errorcode-i18n.md)和[通用错误码](../errorcode-universal.md)。 276 277| 错误码ID | 错误信息 | 278| ------ | ---------------------- | 279| 201 | Permission verification failed. The application does not have the permission required to call the API. | 280| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 281| 890001 | Invalid parameter. Possible causes: Parameter verification failed. | 282 283**示例:** 284 ```ts 285 import { BusinessError } from '@kit.BasicServicesKit'; 286 287 // 删除系统偏好语言列表中的第一个偏好语言 288 let index: number = 0; 289 try { 290 i18n.System.removePreferredLanguage(index); 291 } catch(error) { 292 let err: BusinessError = error as BusinessError; 293 console.error(`call System.removePreferredLanguage failed, error code: ${err.code}, message: ${err.message}.`); 294 } 295 ``` 296 297### setUsingLocalDigit<sup>9+</sup> 298 299static setUsingLocalDigit(flag: boolean): void 300 301设置系统是否使用本地数字。 302 303**系统接口**:此接口为系统接口。 304 305**需要权限**:ohos.permission.UPDATE_CONFIGURATION 306 307**系统能力**:SystemCapability.Global.I18n 308 309**参数:** 310 311| 参数名 | 类型 | 必填 | 说明 | 312| ---- | ------- | ---- | ------------------------------- | 313| flag | boolean | 是 | true表示打开本地数字开关,false表示关闭本地数字开关。 | 314 315**错误码:** 316 317以下错误码的详细介绍请参见[ohos.i18n错误码](errorcode-i18n.md)和[通用错误码](../errorcode-universal.md)。 318 319| 错误码ID | 错误信息 | 320| ------ | ---------------------- | 321| 201 | Permission verification failed. The application does not have the permission required to call the API. | 322| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 323| 890001 | Invalid parameter. Possible causes: Parameter verification failed. | 324 325**示例:** 326 ```ts 327 import { BusinessError } from '@kit.BasicServicesKit'; 328 329 try { 330 i18n.System.setUsingLocalDigit(true); // 打开本地化数字开关 331 } catch(error) { 332 let err: BusinessError = error as BusinessError; 333 console.error(`call System.setUsingLocalDigit failed, error code: ${err.code}, message: ${err.message}.`); 334 } 335 ``` 336 337## SystemLocaleManager<sup>10+</sup> 338 339### constructor<sup>10+</sup> 340 341constructor() 342 343创建SystemLocaleManager对象。 344 345**系统接口**:此接口为系统接口。 346 347**系统能力**:SystemCapability.Global.I18n 348 349**示例:** 350 ```ts 351 let systemLocaleManager: i18n.SystemLocaleManager = new i18n.SystemLocaleManager(); 352 ``` 353 354 355### getLanguageInfoArray<sup>10+</sup> 356 357getLanguageInfoArray(languages: Array<string>, options?: SortOptions): Array<LocaleItem> 358 359获取语言排序数组。 360 361**系统接口**:此接口为系统接口。 362 363**系统能力**:SystemCapability.Global.I18n 364 365**参数:** 366 367| 参数名 | 类型 | 必填 | 说明 | 368| --------- | ------------- | ---- | ------------- | 369| languages | Array<string> | 是 | 待排序语言列表,要求是合法的语言ID。| 370| options | [SortOptions](#sortoptions10) | 否 | 语言排序选项。 | 371 372**返回值:** 373 374| 类型 | 说明 | 375| ----------------- | -------------------- | 376| Array<[LocaleItem](#localeitem10)> | 排序后的语言列表信息。 | 377 378**错误码:** 379 380以下错误码的详细介绍请参见[ohos.i18n错误码](errorcode-i18n.md)和[通用错误码](../errorcode-universal.md)。 381 382| 错误码ID | 错误信息 | 383| ------ | ---------------------- | 384| 202 | Permission verification failed. A non-system application calls a system API. | 385| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 386| 890001 | Invalid parameter. Possible causes: Parameter verification failed. | 387 388**示例:** 389 ```ts 390 import { BusinessError } from '@kit.BasicServicesKit'; 391 392 // 当系统语言为zh-Hans,系统地区为CN,系统Locale为zh-Hans-CN时 393 let systemLocaleManager: i18n.SystemLocaleManager = new i18n.SystemLocaleManager(); 394 let languages: string[] = ["zh-Hans", "en-US", "pt", "ar"]; 395 let sortOptions: i18n.SortOptions = {locale: "zh-Hans-CN", isUseLocalName: true, isSuggestedFirst: true}; 396 try { 397 // 排序后的语言顺序为: [zh-Hans, en-US, pt, ar] 398 let sortedLanguages: Array<i18n.LocaleItem> = systemLocaleManager.getLanguageInfoArray(languages, sortOptions); 399 } catch(error) { 400 let err: BusinessError = error as BusinessError; 401 console.error(`call systemLocaleManager.getLanguageInfoArray failed, error code: ${err.code}, message: ${err.message}.`); 402 } 403 ``` 404 405 406### getRegionInfoArray<sup>10+</sup> 407 408getRegionInfoArray(regions: Array<string>, options?: SortOptions): Array<LocaleItem> 409 410获取国家或地区排序数组。 411 412**系统接口**:此接口为系统接口。 413 414**系统能力**:SystemCapability.Global.I18n 415 416**参数:** 417 418| 参数名 | 类型 | 必填 | 说明 | 419| --------- | ------------- | ---- | ------------- | 420| regions | Array<string> | 是 | 待排序的国家或地区列表,要求是合法的国家或地区ID。| 421| options | [SortOptions](#sortoptions10) | 否 | 国家或地区排序选项。<br>locale的默认值为系统Locale,isUseLocalName的默认值为false,isSuggestedFirst的默认值为true。 | 422 423**返回值:** 424 425| 类型 | 说明 | 426| ----------------- | -------------------- | 427| Array<[LocaleItem](#localeitem10)> | 排序后的国家或地区列表信息。 | 428 429**错误码:** 430 431以下错误码的详细介绍请参见[ohos.i18n错误码](errorcode-i18n.md)和[通用错误码](../errorcode-universal.md)。 432 433| 错误码ID | 错误信息 | 434| ------ | ---------------------- | 435| 202 | Permission verification failed. A non-system application calls a system API. | 436| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 437| 890001 | Invalid parameter. Possible causes: Parameter verification failed. | 438 439**示例:** 440 ```ts 441 import { BusinessError } from '@kit.BasicServicesKit'; 442 443 // 当系统语言为zh-Hans,系统地区为CN,系统Locale为zh-Hans-CN时 444 let systemLocaleManager: i18n.SystemLocaleManager = new i18n.SystemLocaleManager(); 445 let regions: string[] = ["CN", "US", "PT", "EG"]; 446 let sortOptions: i18n.SortOptions = {locale: "zh-Hans-CN", isUseLocalName: false, isSuggestedFirst: true}; 447 try { 448 // 排序后的地区顺序为: [CN, EG, US, PT] 449 let sortedRegions: Array<i18n.LocaleItem> = systemLocaleManager.getRegionInfoArray(regions, sortOptions); 450 } catch(error) { 451 let err: BusinessError = error as BusinessError; 452 console.error(`call systemLocaleManager.getRegionInfoArray failed, error code: ${err.code}, message: ${err.message}.`); 453 } 454 ``` 455 456### getTimeZoneCityItemArray<sup>10+</sup> 457 458static getTimeZoneCityItemArray(): Array<TimeZoneCityItem> 459 460获取时区城市组合信息的数组。 461 462**系统接口**:此接口为系统接口。 463 464**系统能力**:SystemCapability.Global.I18n 465 466**返回值:** 467 468| 类型 | 说明 | 469| ----------------- | -------------------- | 470| Array<[TimeZoneCityItem](#timezonecityitem10)> | 排序后的时区城市组合信息数组。 | 471 472**错误码:** 473 474以下错误码的详细介绍请参见[ohos.i18n错误码](errorcode-i18n.md)和[通用错误码](../errorcode-universal.md)。 475 476| 错误码ID | 错误信息 | 477| ------ | ---------------------- | 478| 202 | Permission verification failed. A non-system application calls a system API. | 479 480**示例:** 481 ```ts 482 import { BusinessError } from '@kit.BasicServicesKit'; 483 484 try { 485 let timeZoneCityItemArray: Array<i18n.TimeZoneCityItem> = i18n.SystemLocaleManager.getTimeZoneCityItemArray(); 486 for (let i = 0; i < timeZoneCityItemArray.length; i++) { 487 console.log(timeZoneCityItemArray[i].zoneId + ", " + timeZoneCityItemArray[i].cityId + ", " + timeZoneCityItemArray[i].cityDisplayName + 488 ", " + timeZoneCityItemArray[i].offset + "\r\n"); 489 } 490 } catch(error) { 491 let err: BusinessError = error as BusinessError; 492 console.error(`call SystemLocaleManager.getTimeZoneCityItemArray failed, error code: ${err.code}, message: ${err.message}.`); 493 } 494 ``` 495 496## LocaleItem<sup>10+</sup> 497 498SystemLocaleManager对语言或国家地区列表的排序结果信息项。 499 500**系统接口**:此接口为系统接口。 501 502**系统能力**:SystemCapability.Global.I18n 503 504| 名称 | 类型 | 必填 | 说明 | 505| --------------- | --------------- | ------ | --------------------------------------- | 506| id | string | 是 | 语言代码或国家地区代码,如"zh"、"CN"。 | 507| suggestionType | [SuggestionType](#suggestiontype10) | 是 | 语言或国家地区推荐类型。 | 508| displayName | string | 是 | id在SystemLocaleManager的Locale下的表示。| 509| localName | string | 否 | id的本地名称。 | 510 511## TimeZoneCityItem<sup>10+</sup> 512 513时区城市组合信息。 514 515**系统接口**:此接口为系统接口。 516 517**系统能力**:SystemCapability.Global.I18n 518 519| 名称 | 类型 | 必填 | 说明 | 520| --------------- | --------------- | ------ | --------------------------------------- | 521| zoneId | string | 是 | 时区Id,例如Asia/Shanghai。 | 522| cityId | string | 是 | 城市Id,例如Shanghai。 | 523| cityDisplayName | string | 是 | 城市Id在系统Locale下显示的名称。 | 524| offset | int | 是 | 时区Id的偏移量。 | 525| zoneDisplayName | string | 是 | 时区Id在系统Locale下显示的名称。 | 526| rawOffset | int | 否 | 时区Id的固定偏移量。 | 527 528 529## SuggestionType<sup>10+</sup> 530 531语言或国家地区的推荐类型。 532 533**系统接口**:此接口为系统接口。 534 535**系统能力**:SystemCapability.Global.I18n 536 537| 名称 | 值 | 说明 | 538| ---------------------- | ---- | ---- | 539| SUGGESTION_TYPE_NONE | 0x00 | 非推荐语言或国家地区。 | 540| SUGGESTION_TYPE_RELATED| 0x01 | 系统语言推荐的国家地区或系统国家地区推荐的语言。 | 541| SUGGESTION_TYPE_SIM | 0x02 | Sim卡国家地区推荐的语言。 | 542 543 544## SortOptions<sup>10+<sup> 545 546语言或国家地区排序选项。 547 548**系统接口**:此接口为系统接口。 549 550**系统能力**:SystemCapability.Global.I18n 551 552| 名称 | 类型 | 必填 | 说明 | 553| --------------- | --------------- | ---- | --------------------------------------- | 554| locale | string | 否 | [表示区域信息的字符串](../../internationalization/i18n-locale-culture.md#实现原理),由语言、脚本、国家或地区组成,如"zh-Hans-CN"。<br>默认值为系统Locale。 | 555| isUseLocalName | boolean | 否 | 表示是否使用本地名称进行排序。<br>若调用方法为getLanguageInfoArray,isUseLocalName属性默认值为true。<br>若调用方法为getRegionInfoArray,isUseLocalName属性默认值为false。 | 556| isSuggestedFirst | boolean | 否 | 表示是否将推荐语言或国家地区在排序结果中置顶。<br>isSuggestedFirst属性默认值为true。 | 557