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