國際化-I18n

說明：
開發前請熟悉鴻蒙開發指導文檔 ：[gitee.com/li-shizhen-skin/harmony-os/blob/master/README.md]

• 本模塊首批接口從API version 7開始支持。后續版本的新增接口，采用上角標單獨標記接口的起始版本。
• I18N模塊包含國際化能力增強接口（未在ECMA 402中定義）。

導入模塊

import i18n from '@ohos.i18n';

i18n.getDisplayLanguage

getDisplayLanguage(language: string, locale: string, sentenceCase?: boolean): string

獲取指定語言的本地化顯示文本。

系統能力 ：SystemCapability.Global.I18n

參數：

返回值：

示例：

i18n.getDisplayLanguage("zh", "en-GB", true);
i18n.getDisplayLanguage("zh", "en-GB");

i18n.getDisplayCountry

getDisplayCountry(country: string, locale: string, sentenceCase?: boolean): string

獲取指定國家的本地化顯示文本。

系統能力 ：SystemCapability.Global.I18n

參數：

返回值：

示例：

i18n.getDisplayCountry("zh-CN", "en-GB", true);
i18n.getDisplayCountry("zh-CN", "en-GB");

i18n.isRTL7+

isRTL(locale: string): boolean

獲取是否為從右至左顯示語言。

系統能力 ：SystemCapability.Global.I18n

參數：

返回值：

示例：

i18n.isRTL("zh-CN");// 中文不是RTL語言，返回false
i18n.isRTL("ar-EG");// 阿語是RTL語言，返回true

i18n.getSystemLanguage

getSystemLanguage(): string

獲取系統語言。

系統能力 ：SystemCapability.Global.I18n

返回值：

示例：

i18n.getSystemLanguage();

i18n.setSystemLanguage

setSystemLanguage(language: string): boolean

設置系統語言。

需要權限 ：ohos.permission.UPDATE_CONFIGURATION

系統能力 ：SystemCapability.Global.I18n

系統API : 該接口為系統接口，三方應用不支持調用。

參數：

返回值：

示例：

i18n.setSystemLanguage('zh');

i18n.getSystemLanguages

getSystemLanguages(): Array

獲取系統支持的語言列表。

系統能力 ：SystemCapability.Global.I18n

系統API : 該接口為系統接口，三方應用不支持調用。

返回值：

示例：

i18n.getSystemLanguages();

i18n.getSystemCountries

getSystemCountries(language: string): Array

獲取針對輸入語言系統支持的區域列表。

系統能力 ：SystemCapability.Global.I18n

系統API : 該接口為系統接口，三方應用不支持調用。

參數：

返回值：

示例：

i18n.getSystemCountries('zh');

i18n.getSystemRegion

getSystemRegion(): string

獲取系統地區。

系統能力 ：SystemCapability.Global.I18n

返回值：

示例：

i18n.getSystemRegion();

i18n.setSystemRegion

setSystemRegion(region: string): boolean

設置系統區域。

需要權限 ：ohos.permission.UPDATE_CONFIGURATION

系統能力 ：SystemCapability.Global.I18n

系統API : 該接口為系統接口，三方應用不支持調用。

參數：

返回值：

示例：

i18n.setSystemRegion('CN');

i18n.getSystemLocale

getSystemLocale(): string

獲取系統區域。

系統能力 ：SystemCapability.Global.I18n

返回值：

示例：

i18n.getSystemLocale();

i18n.setSystemLocale

setSystemLocale(locale: string): boolean

設置系統Locale。

需要權限 ：ohos.permission.UPDATE_CONFIGURATION

系統能力 ：SystemCapability.Global.I18n

系統API : 該接口為系統接口，三方應用不支持調用。

參數：

返回值：

示例：

i18n.setSystemLocale('zh-CN');

i18n.isSuggested

isSuggested(language: string, region?: string): boolean

判斷當前語言和區域是否匹配。

系統能力 ：SystemCapability.Global.I18n

系統API : 該接口為系統接口，三方應用不支持調用。

參數：

返回值：

示例：

i18n.isSuggested('zh', 'CN');

i18n.getCalendar8+

getCalendar(locale: string, type? : string): Calendar

獲取日歷對象。

系統能力 ：SystemCapability.Global.I18n

參數：

返回值：

示例：

i18n.getCalendar("zh-Hans", "gregory");

Calendar8+

setTime8+

setTime(date: Date): void

設置日歷對象內部的時間日期。

系統能力 ：SystemCapability.Global.I18n

參數：

示例：

var calendar = i18n.getCalendar("en-US", "gregory");
var date = new Date(2021, 10, 7, 8, 0, 0, 0);
calendar.setTime(date);

setTime8+

setTime(time: number): void

設置日歷對象內部的時間日期, time為從1970.1.1 00:00:00 GMT逝去的毫秒數。

系統能力 ：SystemCapability.Global.I18n

參數：

示例：

var calendar = i18n.getCalendar("en-US", "gregory");
calendar.setTime(10540800000);

set8+

set(year: number, month: number, date:number, hour?: number, minute?: number, second?: number): void

設置日歷對象的年、月、日、時、分、秒。

系統能力 ：SystemCapability.Global.I18n

參數：

示例：

var calendar = i18n.getCalendar("zh-Hans");
calendar.set(2021, 10, 1, 8, 0, 0); // set time to 2021.10.1 08:00:00

setTimeZone8+

setTimeZone(timezone: string): void

設置日歷對象的時區。

系統能力 ：SystemCapability.Global.I18n

參數：

示例：

var calendar = i18n.getCalendar("zh-Hans");
calendar.setTimeZone("Asia/Shanghai");

getTimeZone8+

getTimeZone(): string

獲取日歷對象的時區。

系統能力 ：SystemCapability.Global.I18n

返回值：

示例：

var calendar = i18n.getCalendar("zh-Hans");
calendar.setTimeZone("Asia/Shanghai");
calendar.getTimeZone(); // Asia/Shanghai"

getFirstDayOfWeek8+

getFirstDayOfWeek(): number

獲取日歷對象的一周起始日。

系統能力 ：SystemCapability.Global.I18n

返回值：

示例：

var calendar = i18n.getCalendar("en-US", "gregory");
calendar.getFirstDayOfWeek();

setFirstDayOfWeek8+

setFirstDayOfWeek(value: number): void

設置每一周的起始日。

系統能力 ：SystemCapability.Global.I18n

參數：

示例：

var calendar = i18n.getCalendar("zh-Hans");
calendar.setFirstDayOfWeek(0);

getMinimalDaysInFirstWeek8+

getMinimalDaysInFirstWeek(): number

獲取一年中第一周的最小天數。

系統能力 ：SystemCapability.Global.I18n

返回值：

示例：

var calendar = i18n.getCalendar("zh-Hans");
calendar.getMinimalDaysInFirstWeek();

setMinimalDaysInFirstWeek8+

setMinimalDaysInFirstWeek(value: number): void

設置一年中第一周的最小天數。

系統能力 ：SystemCapability.Global.I18n

參數：

示例：

var calendar = i18n.getCalendar("zh-Hans");
calendar.setMinimalDaysInFirstWeek(3);

get8+

get(field: string): number

獲取日歷對象中與field相關聯的值。

系統能力 ：SystemCapability.Global.I18n

參數：

返回值：

示例：

var calendar = i18n.getCalendar("zh-Hans");
calendar.set(2021, 10, 1, 8, 0, 0); // set time to 2021.10.1 08:00:00
calendar.get("hour_of_day"); // 8

getDisplayName8+

getDisplayName(locale: string): string

獲取日歷對象在locale所指定的區域的名字。

系統能力 ：SystemCapability.Global.I18n

參數：

返回值：

示例：

var calendar = i18n.getCalendar("en-US", "buddhist");
calendar.getDisplayName("zh"); // 佛歷

isWeekend8+

isWeekend(date?: Date): boolean

判斷給定的日期是否在日歷中是周末。

系統能力 ：SystemCapability.Global.I18n

參數：

返回值：

示例：

var calendar = i18n.getCalendar("zh-Hans");
calendar.set(2021, 11, 11, 8, 0, 0); // set time to 2021.11.11 08:00:00
calendar.isWeekend(); // false
var date = new Date(2011, 11, 6, 9, 0, 0);
calendar.isWeekend(date); // true

PhoneNumberFormat8+

constructor8+

constructor(country: string, options?: PhoneNumberFormatOptions)

創建電話號碼格式化對象。

系統能力 ：SystemCapability.Global.I18n

參數：

示例：

var phoneNumberFormat= new i18n.PhoneNumberFormat("CN", {"type": "E164"});

isValidNumber8+

isValidNumber(number: string): boolean

判斷傳入的電話號碼格式是否正確。

系統能力 ：SystemCapability.Global.I18n

參數：

返回值：

示例：

var phonenumberfmt = new i18n.PhoneNumberFormat("CN");
phonenumberfmt.isValidNumber("15812312312");

format8+

format(number: string): string

對電話號碼進行格式化。

系統能力 ：SystemCapability.Global.I18n

參數：

返回值：

示例：

var phonenumberfmt = new i18n.PhoneNumberFormat("CN");
phonenumberfmt.format("15812312312");

PhoneNumberFormatOptions8+

表示電話號碼格式化對象可設置的屬性。

系統能力 ：以下各項對應的系統能力均為SystemCapability.Global.I18n

UnitInfo8+

度量衡單位信息。

系統能力 ：以下各項對應的系統能力均為SystemCapability.Global.I18n

Util8+

unitConvert8+

unitConvert(fromUnit: UnitInfo, toUnit: UnitInfo, value: number, locale: string, style?: string): string

將fromUnit的單位轉換為toUnit的單位，并根據區域與風格進行格式化。

系統能力 ：SystemCapability.Global.I18n

參數：

返回值：

示例：

i18n.Util.unitConvert({unit: "cup", measureSystem: "US"}, {unit: "liter", measureSystem: "SI"}, 1000, "en-US", "long");

getInstance8+

getInstance(locale?:string): IndexUtil

創建并返回IndexUtil對象。

系統能力 ：SystemCapability.Global.I18n

參數：

返回值：

示例：

var indexUtil= i18n.getInstance("zh-CN");

IndexUtil8+

getIndexList8+

getIndexList(): Array

獲取當前locale對應的索引列表。

系統能力 ：SystemCapability.Global.I18n

返回值：

示例：

var indexUtil = i18n.getInstance("zh-CN");
var indexList = indexUtil.getIndexList();

addLocale8+

addLocale(locale: string): void

將新的locale對應的索引加入當前索引列表。

系統能力 ：SystemCapability.Global.I18n

參數：

示例：

var indexUtil = i18n.getInstance("zh-CN");
indexUtil.addLocale("en-US");

getIndex8+

getIndex(text: string): string

獲取text對應的索引。

系統能力 ：SystemCapability.Global.I18n

參數：

返回值：

示例：

var indexUtil= i18n.getInstance("zh-CN");
indexUtil.getIndex("hi");  // 返回h

Character8+

isDigit8+

isDigit(char: string): boolean

判斷字符串char是否是數字。

系統能力 ：SystemCapability.Global.I18n

參數：

返回值：

示例：

var isdigit = i18n.Character.isDigit("1");  // 返回true

isSpaceChar8+

isSpaceChar(char: string): boolean

判斷字符串char是否是空格符。

系統能力 ：SystemCapability.Global.I18n

參數：

返回值：

示例：

var isspacechar = i18n.Character.isSpaceChar("a");  // 返回false

isWhitespace8+

isWhitespace(char: string): boolean

判斷字符串char是否是空白符。

系統能力 ：SystemCapability.Global.I18n

參數：

返回值：

示例：

var iswhitespace = i18n.Character.isWhitespace("a");  // 返回false

isRTL8+

isRTL(char: string): boolean

判斷字符串char是否是從右到左語言的字符。

系統能力 ：SystemCapability.Global.I18n

參數：

返回值：

示例：

var isrtl = i18n.Character.isRTL("a");  // 返回false

isIdeograph8+

isIdeograph(char: string): boolean

判斷字符串char是否是表意文字。

系統能力 ：SystemCapability.Global.I18n

參數：

返回值：

示例：

var isideograph = i18n.Character.isIdeograph("a");  // 返回false

isLetter8+

isLetter(char: string): boolean

判斷字符串char是否是字母。

系統能力 ：SystemCapability.Global.I18n

參數：

返回值：

示例：

var isletter = i18n.Character.isLetter("a");  // 返回true

isLowerCase8+

isLowerCase(char: string): boolean

判斷字符串char是否是小寫字母。

系統能力 ：SystemCapability.Global.I18n

參數：

返回值：

示例：

var islowercase = i18n.Character.isLowerCase("a");  // 返回true

isUpperCase8+

isUpperCase(char: string): boolean

判斷字符串char是否是大寫字母。

系統能力 ：SystemCapability.Global.I18n

參數：

返回值：

示例：

var isuppercase = i18n.Character.isUpperCase("a");  // 返回false

getType8+

getType(char: string): string

獲取輸入字符串的一般類別值。

系統能力 ：SystemCapability.Global.I18n

參數：

返回值：

示例：

var type = i18n.Character.getType("a");

i18n.getLineInstance8+

getLineInstance(locale: string): BreakIterator

獲取一個用于斷句的[BreakIterator]對象。

系統能力 ：SystemCapability.Global.I18n

參數：

返回值：

示例：

var iterator = i18n.getLineInstance("en");

BreakIterator8+

setLineBreakText8+

setLineBreakText(text: string): void

設置[BreakIterator]要處理的文本。

系統能力 ：SystemCapability.Global.I18n

參數：

示例：

var iterator = i18n.getLineInstance("en");
iterator.setLineBreakText("Apple is my favorite fruit.");

getLineBreakText8+

getLineBreakText(): string

獲取[BreakIterator]當前處理的文本。

系統能力 ：SystemCapability.Global.I18n

返回值：

示例：

var iterator = i18n.getLineInstance("en");
iterator.setLineBreakText("Apple is my favorite fruit.");
iterator.getLineBreakText(); // Apple is my favorite fruit.

current8+

current(): number

獲取[BreakIterator]對象在當前處理的文本中的位置。

系統能力 ：SystemCapability.Global.I18n

返回值：

示例：

var iterator = i18n.getLineInstance("en");
iterator.setLineBreakText("Apple is my favorite fruit.");
breakIter.current(); // 0

first8+

first(): number

將[BreakIterator]對象設置到第一個可斷句的分割點。第一個分割點總是被處理的文本的起始位置。

系統能力 ：SystemCapability.Global.I18n

返回值：

示例：

var iterator = i18n.getLineInstance("en");
iterator.setLineBreakText("Apple is my favorite fruit.");
breakIter.first(); // 0

last8+

last(): number

將[BreakIterator]對象的位置設置到最后一個可斷句的分割點。最后一個分割點總是被處理文本末尾的下一個位置。

系統能力 ：SystemCapability.Global.I18n

返回值：

示例：

var iterator = i18n.getLineInstance("en");
iterator.setLineBreakText("Apple is my favorite fruit.");
iterator.last(); // 27

next8+

next(index?: number): number

如果index給出，并且index是一個正數將[BreakIterator]向后移動number個可斷句的分割點，如果n是一個負數，向前移動相應個分割點。若index沒有給出，則相當于index = 1。

系統能力 ：SystemCapability.Global.I18n

參數：

返回值：

示例：

var iterator = i18n.getLineInstance("en");
iterator.setLineBreakText("Apple is my favorite fruit.");
iterator.first(); // 0
iterator.next(); // 6
iterator.next(10); // -1

previous8+

previous(): number

將[BreakIterator]移動到前一個分割點處。

系統能力 ：SystemCapability.Global.I18n

返回值：

示例：

var iterator = i18n.getLineInstance("en");
iterator.setLineBreakText("Apple is my favorite fruit.");
iterator.first(); // 0
iterator.next(3); // 12
iterator.previous(); // 9

following8+

following(offset: number): number

將[BreakIterator]設置到由offset指定的位置的后面一個分割點。返回移動后[BreakIterator]的位置。

系統能力 ：SystemCapability.Global.I18n

參數：

返回值：

示例：

var iterator = i18n.getLineInstance("en");
iterator.setLineBreakText("Apple is my favorite fruit.");
iterator.following(0); // 6
iterator.following(100); // -1
iterator.current(); // 27

isBoundary8+

isBoundary(offset: number): boolean

如果offset所指定的文本位置是一個分割點，那么返回true，否則返回false。如果返回true, 將[BreakIterator]對象設置到offset所指定的位置, 否則相當于調用[following]。

系統能力 ：SystemCapability.Global.I18n

參數：

返回值：

示例：

var iterator = i18n.getLineInstance("en");
iterator.setLineBreakText("Apple is my favorite fruit.");
iterator.isBoundary(0); // true;
iterator.isBoundary(5); // false;

i18n.is24HourClock7+

is24HourClock(): boolean

判斷系統時間是否為24小時制。

系統能力 ：SystemCapability.Global.I18n

返回值：

示例：

var is24HourClock = i18n.is24HourClock();

i18n.set24HourClock7+

set24HourClock(option: boolean): boolean

修改系統時間的24小時制設置。

需要權限 ：ohos.permission.UPDATE_CONFIGURATION

系統能力 ：SystemCapability.Global.I18n

參數：

返回值：

示例：

// 將系統時間設置為24小時制
var success = i18n.set24HourClock(true);

i18n.addPreferredLanguage8+

addPreferredLanguage(language: string, index?: number): boolean

在系統偏好語言列表中的指定位置添加偏好語言。

需要權限 ：ohos.permission.UPDATE_CONFIGURATION

系統能力 ：SystemCapability.Global.I18n

參數：

返回值：

示例：

// 將語言zh-CN添加到系統偏好語言列表中
var language = 'zh-CN';
var index = 0;
var success = i18n.addPreferredLanguage(language, index);

i18n.removePreferredLanguage8+

removePreferredLanguage(index: number): boolean

刪除系統偏好語言列表中指定位置的偏好語言。

需要權限 ：ohos.permission.UPDATE_CONFIGURATION

系統能力 ：SystemCapability.Global.I18n

參數：

返回值：

示例：

// 刪除系統偏好語言列表中的第一個偏好語言
var index = 0;
var success = i18n.removePreferredLanguage(index);

i18n.getPreferredLanguageList8+

getPreferredLanguageList(): Array

獲取系統偏好語言列表。

系統能力 ：SystemCapability.Global.I18n

返回值：

示例：

var preferredLanguageList = i18n.getPreferredLanguageList();

i18n.getFirstPreferredLanguage8+

getFirstPreferredLanguage(): string

獲取偏好語言列表中的第一個偏好語言。

系統能力 ：SystemCapability.Global.I18n

返回值：

示例：

var firstPreferredLanguage = i18n.getFirstPreferredLanguage();

i18n.getAppPreferredLanguage9+

getAppPreferredLanguage(): string

獲取應用的偏好語言。

系統能力 ：SystemCapability.Global.I18n

返回值：

示例：

var appPreferredLanguage = i18n.getAppPreferredLanguage();

i18n.getTimeZone7+

getTimeZone(zoneID?: string): TimeZone

獲取時區ID對應的時區對象。

系統能力 ：SystemCapability.Global.I18n

參數：

返回值：

示例：

var timezone = i18n.getTimeZone();

RelativeTimeFormat8+

getID8+

getID(): string

獲取時區對象的ID。

系統能力 ：SystemCapability.Global.I18n

返回值：

示例：

var timezone = i18n.getTimeZone();
timezone.getID();

getDisplayName8+

getDisplayName(locale?: string, isDST?: boolean): string

獲取時區對象在指定區域的表示。

系統能力 ：SystemCapability.Global.I18n

參數：

返回值：

示例：

var timezone = i18n.getTimeZone();
timezone.getDisplayName("zh-CN", false);

getRawOffset8+

getRawOffset(): number

獲取時區對象表示的時區與UTC時區的偏差。

系統能力 ：SystemCapability.Global.I18n

返回值：

示例：

var timezone = i18n.getTimeZone();
timezone.getRawOffset();

getOffset8+

getOffset(date?: number): number

獲取某一時刻時區對象表示的時區與UTC時區的偏差。

系統能力 ：SystemCapability.Global.I18n

返回值：

示例：

var timezone = i18n.getTimeZone();
timezone.getOffset(1234567890);

審核編輯 黃宇