@ohos.i18n (国际化-I18n)(系统接口)

本模块提供系统相关的或者增强的国际化能力，包括区域管理、电话号码处理、日历等，相关接口为ECMA 402标准中未定义的补充接口。Intl模块提供了ECMA 402标准定义的基础国际化接口，与本模块共同使用可提供完整地国际化支持能力。

说明： - 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。

• 从API version 11开始，本模块部分接口支持在ArkTS卡片中使用。

• 当前页面仅包含本模块的系统接口，其他公开接口参见@ohos.i18n (国际化-I18n)。

导入模块

import { i18n } from '@kit.LocalizationKit';

System⁹⁺

setSystemLanguage⁹⁺

static setSystemLanguage(language: string): void

设置系统语言。

若要监听系统语言变化，可以监听事件OHOS::EventFwk::CommonEventSupport::COMMON_EVENT_LOCALE_CHANGED。

系统接口：此接口为系统接口。

需要权限：ohos.permission.UPDATE_CONFIGURATION

系统能力：SystemCapability.Global.I18n

参数：

错误码：

以下错误码的详细介绍请参见ohos.i18n错误码和通用错误码。

示例：

  import { BusinessError, commonEventManager } from '@kit.BasicServicesKit';

  // 设置系统语言
  try {
    i18n.System.setSystemLanguage('zh'); // 设置系统当前语言为 "zh"
  } catch(error) {
    let err: BusinessError = error as BusinessError;
    console.error(`call System.setSystemLanguage failed, error code: ${err.code}, message: ${err.message}.`);
  }
 
  // 订阅公共事件
  let subscriber: commonEventManager.CommonEventSubscriber; // 用于保存创建成功的订阅者对象，后续使用其完成订阅及退订的动作
  let subscribeInfo: commonEventManager.CommonEventSubscribeInfo = { // 订阅者信息
    events: [commonEventManager.Support.COMMON_EVENT_LOCALE_CHANGED]
  };
  commonEventManager.createSubscriber(subscribeInfo).then((commonEventSubscriber:commonEventManager.CommonEventSubscriber) => { // 创建订阅者
      console.info("createSubscriber");
      subscriber = commonEventSubscriber;
      commonEventManager.subscribe(subscriber, (err, data) => {
        if (err) {
          console.error(`Failed to subscribe common event. error code: ${err.code}, message: ${err.message}.`);
          return;
        }
        console.info("the subscribed event has occurred."); // 订阅的事件发生时执行
      })
  }).catch((err: BusinessError) => {
      console.error(`createSubscriber failed, code is ${err.code}, message is ${err.message}`);
  });  

setSystemRegion⁹⁺

static setSystemRegion(region: string): void

设置系统地区。

若要监听系统地区变化，可以监听事件OHOS::EventFwk::CommonEventSupport::COMMON_EVENT_LOCALE_CHANGED。

系统接口：此接口为系统接口。

需要权限：ohos.permission.UPDATE_CONFIGURATION

系统能力：SystemCapability.Global.I18n

参数：

错误码：

以下错误码的详细介绍请参见ohos.i18n错误码和通用错误码。

示例：

  import { BusinessError } from '@kit.BasicServicesKit';

  try {
    i18n.System.setSystemRegion('CN');  // 设置系统当前地区为 "CN"
  } catch(error) {
    let err: BusinessError = error as BusinessError;
    console.error(`call System.setSystemRegion failed, error code: ${err.code}, message: ${err.message}.`);
  }

setSystemLocale⁹⁺

static setSystemLocale(locale: string): void

设置系统区域。

若要监听系统区域变化，可以监听事件OHOS::EventFwk::CommonEventSupport::COMMON_EVENT_LOCALE_CHANGED。

系统接口：此接口为系统接口。

需要权限：ohos.permission.UPDATE_CONFIGURATION

系统能力：SystemCapability.Global.I18n

参数：

错误码：

以下错误码的详细介绍请参见ohos.i18n错误码和通用错误码。

示例：

  import { BusinessError } from '@kit.BasicServicesKit';

  try {
    i18n.System.setSystemLocale('zh-CN');  // 设置系统当前区域ID为 "zh-CN"
  } catch(error) {
    let err: BusinessError = error as BusinessError;
    console.error(`call System.setSystemLocale failed, error code: ${err.code}, message: ${err.message}.`);
  }

set24HourClock⁹⁺

static set24HourClock(option: boolean): void

设置系统时制是否为24小时制。

系统接口：此接口为系统接口。

需要权限：ohos.permission.UPDATE_CONFIGURATION

系统能力：SystemCapability.Global.I18n

参数：

错误码：

以下错误码的详细介绍请参见ohos.i18n错误码和通用错误码。

示例：

  import { BusinessError } from '@kit.BasicServicesKit';

  // 将系统时制设置为24小时制
  try {
    i18n.System.set24HourClock(true);
  } catch(error) {
    let err: BusinessError = error as BusinessError;
    console.error(`call System.set24HourClock failed, error code: ${err.code}, message: ${err.message}.`);
  }

addPreferredLanguage⁹⁺

static addPreferredLanguage(language: string, index?: number): void

在系统偏好语言列表的指定位置添加偏好语言。

系统接口：此接口为系统接口。

需要权限：ohos.permission.UPDATE_CONFIGURATION

系统能力：SystemCapability.Global.I18n

参数：

错误码：

以下错误码的详细介绍请参见ohos.i18n错误码和通用错误码。

示例：

  import { BusinessError } from '@kit.BasicServicesKit';

  // 将语言zh-CN添加到系统偏好语言列表中
  let language = 'zh-CN';
  let index = 0;
  try {
    i18n.System.addPreferredLanguage(language, index); // 将zh-CN添加到系统偏好语言列表的第1位
  } catch(error) {
    let err: BusinessError = error as BusinessError;
    console.error(`call System.addPreferredLanguage failed, error code: ${err.code}, message: ${err.message}.`);
  }

removePreferredLanguage⁹⁺

static removePreferredLanguage(index: number): void

从系统偏好语言列表中移除指定位置的偏好语言。

系统接口：此接口为系统接口。

需要权限：ohos.permission.UPDATE_CONFIGURATION

系统能力：SystemCapability.Global.I18n

参数：

错误码：

以下错误码的详细介绍请参见ohos.i18n错误码和通用错误码。

示例：

  import { BusinessError } from '@kit.BasicServicesKit';

  // 删除系统偏好语言列表中的第一个偏好语言
  let index: number = 0;
  try {
    i18n.System.removePreferredLanguage(index);
  } catch(error) {
    let err: BusinessError = error as BusinessError;
    console.error(`call System.removePreferredLanguage failed, error code: ${err.code}, message: ${err.message}.`);
  }

setUsingLocalDigit⁹⁺

static setUsingLocalDigit(flag: boolean): void

设置系统是否使用本地数字。

系统接口：此接口为系统接口。

需要权限：ohos.permission.UPDATE_CONFIGURATION

系统能力：SystemCapability.Global.I18n

参数：

错误码：

以下错误码的详细介绍请参见ohos.i18n错误码和通用错误码。

示例：

  import { BusinessError } from '@kit.BasicServicesKit';

  try {
    i18n.System.setUsingLocalDigit(true); // 打开本地化数字开关
  } catch(error) {
    let err: BusinessError = error as BusinessError;
    console.error(`call System.setUsingLocalDigit failed, error code: ${err.code}, message: ${err.message}.`);
  }

setTemperatureType¹⁸⁺

static setTemperatureType(type: TemperatureType): void

设置系统的温度单位。

系统接口：此接口为系统接口。

需要权限：ohos.permission.UPDATE_CONFIGURATION

系统能力：SystemCapability.Global.I18n

参数：

错误码：

以下错误码的详细介绍请参见ohos.i18n错误码和通用错误码。

说明

890001的报错信息请以接口的实际报错为准。

示例：

  import { BusinessError } from '@kit.BasicServicesKit';

  try {
    i18n.System.setTemperatureType(i18n.TemperatureType.CELSIUS); // 设置温度单位为摄氏度
  } catch(error) {
    let err: BusinessError = error as BusinessError;
    console.error(`call System.setTemperatureType failed, error code: ${err.code}, message: ${err.message}.`);
  }

setFirstDayOfWeek¹⁸⁺

static setFirstDayOfWeek(type: WeekDay): void

设置系统的周起始日。

系统接口：此接口为系统接口。

需要权限：ohos.permission.UPDATE_CONFIGURATION

系统能力：SystemCapability.Global.I18n

参数：

错误码：

以下错误码的详细介绍请参见ohos.i18n错误码和通用错误码。

说明

890001的报错信息请以接口的实际报错为准。

示例：

  import { BusinessError } from '@kit.BasicServicesKit';

  try {
    i18n.System.setFirstDayOfWeek(i18n.WeekDay.MON); // 设置用户偏好的周起始日为周一
  } catch(error) {
    let err: BusinessError = error as BusinessError;
    console.error(`call System.setFirstDayOfWeek failed, error code: ${err.code}, message: ${err.message}.`);
  }

SystemLocaleManager¹⁰⁺

constructor¹⁰⁺

constructor()

创建SystemLocaleManager对象。

系统接口：此接口为系统接口。

系统能力：SystemCapability.Global.I18n

示例：

  let systemLocaleManager: i18n.SystemLocaleManager = new i18n.SystemLocaleManager();

getLanguageInfoArray¹⁰⁺

getLanguageInfoArray(languages: Array<string>, options?: SortOptions): Array<LocaleItem>

获取排序后的语言信息列表。

系统接口：此接口为系统接口。

系统能力：SystemCapability.Global.I18n

参数：

返回值：

错误码：

以下错误码的详细介绍请参见ohos.i18n错误码和通用错误码。

示例：

  import { BusinessError } from '@kit.BasicServicesKit';

  // 当系统语言为zh-Hans，系统地区为CN，系统区域为zh-Hans-CN时
  let systemLocaleManager: i18n.SystemLocaleManager = new i18n.SystemLocaleManager();
  let languages: string[] = ["zh-Hans", "en-US", "pt", "ar"];
  let sortOptions: i18n.SortOptions = {locale: "zh-Hans-CN", isUseLocalName: true, isSuggestedFirst: true};
  try {
      // 排序后的语言顺序为: [zh-Hans, en-US, pt, ar]
      let sortedLanguages: Array<i18n.LocaleItem> = systemLocaleManager.getLanguageInfoArray(languages, sortOptions);
  } catch(error) {
      let err: BusinessError = error as BusinessError;
      console.error(`call systemLocaleManager.getLanguageInfoArray failed, error code: ${err.code}, message: ${err.message}.`);
  }

getRegionInfoArray¹⁰⁺

getRegionInfoArray(regions: Array<string>, options?: SortOptions): Array<LocaleItem>

获取排序后的国家或地区信息列表。

系统接口：此接口为系统接口。

系统能力：SystemCapability.Global.I18n

参数：

返回值：

错误码：

以下错误码的详细介绍请参见ohos.i18n错误码和通用错误码。

示例：

  import { BusinessError } from '@kit.BasicServicesKit';

  // 当系统语言为zh-Hans，系统地区为CN，系统区域为zh-Hans-CN时
  let systemLocaleManager: i18n.SystemLocaleManager = new i18n.SystemLocaleManager();
  let regions: string[] = ["CN", "US", "PT", "EG"];
  let sortOptions: i18n.SortOptions = {locale: "zh-Hans-CN", isUseLocalName: false, isSuggestedFirst: true};
  try {
      // 排序后的地区顺序为: [CN, EG, US, PT]
      let sortedRegions: Array<i18n.LocaleItem> = systemLocaleManager.getRegionInfoArray(regions, sortOptions);
  } catch(error) {
      let err: BusinessError = error as BusinessError;
      console.error(`call systemLocaleManager.getRegionInfoArray failed, error code: ${err.code}, message: ${err.message}.`);
  }

getTimeZoneCityItemArray¹⁰⁺

static getTimeZoneCityItemArray(): Array<TimeZoneCityItem>

获取排序后的时区城市组合信息列表。

系统接口：此接口为系统接口。

系统能力：SystemCapability.Global.I18n

返回值：

错误码：

以下错误码的详细介绍请参见ohos.i18n错误码和通用错误码。

示例：

  import { BusinessError } from '@kit.BasicServicesKit';

  try {
    let timeZoneCityItemArray: Array<i18n.TimeZoneCityItem> = i18n.SystemLocaleManager.getTimeZoneCityItemArray();
    for (let i = 0; i < timeZoneCityItemArray.length; i++) {
        console.log(timeZoneCityItemArray[i].zoneId + ", " + timeZoneCityItemArray[i].cityId + ", " + timeZoneCityItemArray[i].cityDisplayName +
            ", " + timeZoneCityItemArray[i].offset + "\r\n");
    }
  } catch(error) {
    let err: BusinessError = error as BusinessError;
    console.error(`call SystemLocaleManager.getTimeZoneCityItemArray failed, error code: ${err.code}, message: ${err.message}.`);
  }

LocaleItem¹⁰⁺

语言或国家地区的组合信息。

系统接口：此接口为系统接口。

系统能力：SystemCapability.Global.I18n

TimeZoneCityItem¹⁰⁺

时区城市的组合信息。

系统接口：此接口为系统接口。

系统能力：SystemCapability.Global.I18n

SuggestionType¹⁰⁺

语言或国家地区的推荐类型。

系统接口：此接口为系统接口。

系统能力：SystemCapability.Global.I18n

SortOptions¹⁰⁺

语言或国家地区排序选项。

系统接口：此接口为系统接口。

系统能力：SystemCapability.Global.I18n

你可能感兴趣的鸿蒙文章

harmony 鸿蒙Localization Kit（本地化开发服务）

harmony 鸿蒙RawFileDescriptor

harmony 鸿蒙RawFileDescriptor64

harmony 鸿蒙ResourceManager_Configuration

harmony 鸿蒙字体管理错误码

harmony 鸿蒙I18n错误码

harmony 鸿蒙资源管理错误码

harmony 鸿蒙@ohos.fontManager (字体管理)

harmony 鸿蒙@ohos.i18n (国际化-I18n)

harmony 鸿蒙@ohos.intl (国际化-Intl)