國(guó)際化-I18n

說(shuō)明：
開(kāi)發(fā)前請(qǐng)熟悉鴻蒙開(kāi)發(fā)指導(dǎo)文檔 ：[gitee.com/li-shizhen-skin/harmony-os/blob/master/README.md]

• 本模塊首批接口從API version 7開(kāi)始支持。后續(xù)版本的新增接口，采用上角標(biāo)單獨(dú)標(biāo)記接口的起始版本。
• I18N模塊包含國(guó)際化能力增強(qiáng)接口（未在ECMA 402中定義）。

導(dǎo)入模塊

import i18n from '@ohos.i18n';

i18n.getDisplayLanguage

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

獲取指定語(yǔ)言的本地化顯示文本。

系統(tǒng)能力 ：SystemCapability.Global.I18n

參數(shù)：

返回值：

示例：

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

i18n.getDisplayCountry

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

獲取指定國(guó)家的本地化顯示文本。

系統(tǒng)能力 ：SystemCapability.Global.I18n

參數(shù)：

返回值：

示例：

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

i18n.isRTL7+

isRTL(locale: string): boolean

獲取是否為從右至左顯示語(yǔ)言。

系統(tǒng)能力 ：SystemCapability.Global.I18n

參數(shù)：

返回值：

示例：

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

i18n.getSystemLanguage

getSystemLanguage(): string

獲取系統(tǒng)語(yǔ)言。

系統(tǒng)能力 ：SystemCapability.Global.I18n

返回值：

示例：

i18n.getSystemLanguage();

i18n.setSystemLanguage

setSystemLanguage(language: string): boolean

設(shè)置系統(tǒng)語(yǔ)言。

需要權(quán)限 ：ohos.permission.UPDATE_CONFIGURATION

系統(tǒng)能力 ：SystemCapability.Global.I18n

系統(tǒng)API : 該接口為系統(tǒng)接口，三方應(yīng)用不支持調(diào)用。

參數(shù)：

返回值：

示例：

i18n.setSystemLanguage('zh');

i18n.getSystemLanguages

getSystemLanguages(): Array

獲取系統(tǒng)支持的語(yǔ)言列表。

系統(tǒng)能力 ：SystemCapability.Global.I18n

系統(tǒng)API : 該接口為系統(tǒng)接口，三方應(yīng)用不支持調(diào)用。

返回值：

示例：

i18n.getSystemLanguages();

i18n.getSystemCountries

getSystemCountries(language: string): Array

獲取針對(duì)輸入語(yǔ)言系統(tǒng)支持的區(qū)域列表。

系統(tǒng)能力 ：SystemCapability.Global.I18n

系統(tǒng)API : 該接口為系統(tǒng)接口，三方應(yīng)用不支持調(diào)用。

參數(shù)：

返回值：

示例：

i18n.getSystemCountries('zh');

i18n.getSystemRegion

getSystemRegion(): string

獲取系統(tǒng)地區(qū)。

系統(tǒng)能力 ：SystemCapability.Global.I18n

返回值：

示例：

i18n.getSystemRegion();

i18n.setSystemRegion

setSystemRegion(region: string): boolean

設(shè)置系統(tǒng)區(qū)域。

需要權(quán)限 ：ohos.permission.UPDATE_CONFIGURATION

系統(tǒng)能力 ：SystemCapability.Global.I18n

系統(tǒng)API : 該接口為系統(tǒng)接口，三方應(yīng)用不支持調(diào)用。

參數(shù)：

返回值：

示例：

i18n.setSystemRegion('CN');

i18n.getSystemLocale

getSystemLocale(): string

獲取系統(tǒng)區(qū)域。

系統(tǒng)能力 ：SystemCapability.Global.I18n

返回值：

示例：

i18n.getSystemLocale();

i18n.setSystemLocale

setSystemLocale(locale: string): boolean

設(shè)置系統(tǒng)Locale。

需要權(quán)限 ：ohos.permission.UPDATE_CONFIGURATION

系統(tǒng)能力 ：SystemCapability.Global.I18n

系統(tǒng)API : 該接口為系統(tǒng)接口，三方應(yīng)用不支持調(diào)用。

參數(shù)：

返回值：

示例：

i18n.setSystemLocale('zh-CN');

i18n.isSuggested

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

判斷當(dāng)前語(yǔ)言和區(qū)域是否匹配。

系統(tǒng)能力 ：SystemCapability.Global.I18n

系統(tǒng)API : 該接口為系統(tǒng)接口，三方應(yīng)用不支持調(diào)用。

參數(shù)：

返回值：

示例：

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

i18n.getCalendar8+

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

獲取日歷對(duì)象。

系統(tǒng)能力 ：SystemCapability.Global.I18n

參數(shù)：

返回值：

示例：

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

Calendar8+

setTime8+

setTime(date: Date): void

設(shè)置日歷對(duì)象內(nèi)部的時(shí)間日期。

系統(tǒng)能力 ：SystemCapability.Global.I18n

參數(shù)：

示例：

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

設(shè)置日歷對(duì)象內(nèi)部的時(shí)間日期, time為從1970.1.1 00:00:00 GMT逝去的毫秒數(shù)。

系統(tǒng)能力 ：SystemCapability.Global.I18n

參數(shù)：

示例：

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

設(shè)置日歷對(duì)象的年、月、日、時(shí)、分、秒。

系統(tǒng)能力 ：SystemCapability.Global.I18n

參數(shù)：

示例：

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

設(shè)置日歷對(duì)象的時(shí)區(qū)。

系統(tǒng)能力 ：SystemCapability.Global.I18n

參數(shù)：

示例：

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

getTimeZone8+

getTimeZone(): string

獲取日歷對(duì)象的時(shí)區(qū)。

系統(tǒng)能力 ：SystemCapability.Global.I18n

返回值：

示例：

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

getFirstDayOfWeek8+

getFirstDayOfWeek(): number

獲取日歷對(duì)象的一周起始日。

系統(tǒng)能力 ：SystemCapability.Global.I18n

返回值：

示例：

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

setFirstDayOfWeek8+

setFirstDayOfWeek(value: number): void

設(shè)置每一周的起始日。

系統(tǒng)能力 ：SystemCapability.Global.I18n

參數(shù)：

示例：

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

getMinimalDaysInFirstWeek8+

getMinimalDaysInFirstWeek(): number

獲取一年中第一周的最小天數(shù)。

系統(tǒng)能力 ：SystemCapability.Global.I18n

返回值：

示例：

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

setMinimalDaysInFirstWeek8+

setMinimalDaysInFirstWeek(value: number): void

設(shè)置一年中第一周的最小天數(shù)。

系統(tǒng)能力 ：SystemCapability.Global.I18n

參數(shù)：

示例：

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

get8+

get(field: string): number

獲取日歷對(duì)象中與field相關(guān)聯(lián)的值。

系統(tǒng)能力 ：SystemCapability.Global.I18n

參數(shù)：

返回值：

示例：

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

獲取日歷對(duì)象在locale所指定的區(qū)域的名字。

系統(tǒng)能力 ：SystemCapability.Global.I18n

參數(shù)：

返回值：

示例：

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

isWeekend8+

isWeekend(date?: Date): boolean

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

系統(tǒng)能力 ：SystemCapability.Global.I18n

參數(shù)：

返回值：

示例：

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)

創(chuàng)建電話號(hào)碼格式化對(duì)象。

系統(tǒng)能力 ：SystemCapability.Global.I18n

參數(shù)：

示例：

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

isValidNumber8+

isValidNumber(number: string): boolean

判斷傳入的電話號(hào)碼格式是否正確。

系統(tǒng)能力 ：SystemCapability.Global.I18n

參數(shù)：

返回值：

示例：

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

format8+

format(number: string): string

對(duì)電話號(hào)碼進(jìn)行格式化。

系統(tǒng)能力 ：SystemCapability.Global.I18n

參數(shù)：

返回值：

示例：

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

PhoneNumberFormatOptions8+

表示電話號(hào)碼格式化對(duì)象可設(shè)置的屬性。

系統(tǒng)能力 ：以下各項(xiàng)對(duì)應(yīng)的系統(tǒng)能力均為SystemCapability.Global.I18n

UnitInfo8+

度量衡單位信息。

系統(tǒng)能力 ：以下各項(xiàng)對(duì)應(yīng)的系統(tǒng)能力均為SystemCapability.Global.I18n

Util8+

unitConvert8+

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

將fromUnit的單位轉(zhuǎn)換為toUnit的單位，并根據(jù)區(qū)域與風(fēng)格進(jìn)行格式化。

系統(tǒng)能力 ：SystemCapability.Global.I18n

參數(shù)：

返回值：

示例：

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

getInstance8+

getInstance(locale?:string): IndexUtil

創(chuàng)建并返回IndexUtil對(duì)象。

系統(tǒng)能力 ：SystemCapability.Global.I18n

參數(shù)：

返回值：

示例：

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

IndexUtil8+

getIndexList8+

getIndexList(): Array

獲取當(dāng)前l(fā)ocale對(duì)應(yīng)的索引列表。

系統(tǒng)能力 ：SystemCapability.Global.I18n

返回值：

示例：

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

addLocale8+

addLocale(locale: string): void

將新的locale對(duì)應(yīng)的索引加入當(dāng)前索引列表。

系統(tǒng)能力 ：SystemCapability.Global.I18n

參數(shù)：

示例：

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

getIndex8+

getIndex(text: string): string

獲取text對(duì)應(yīng)的索引。

系統(tǒng)能力 ：SystemCapability.Global.I18n

參數(shù)：

返回值：

示例：

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

Character8+

isDigit8+

isDigit(char: string): boolean

判斷字符串char是否是數(shù)字。

系統(tǒng)能力 ：SystemCapability.Global.I18n

參數(shù)：

返回值：

示例：

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

isSpaceChar8+

isSpaceChar(char: string): boolean

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

系統(tǒng)能力 ：SystemCapability.Global.I18n

參數(shù)：

返回值：

示例：

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

isWhitespace8+

isWhitespace(char: string): boolean

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

系統(tǒng)能力 ：SystemCapability.Global.I18n

參數(shù)：

返回值：

示例：

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

isRTL8+

isRTL(char: string): boolean

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

系統(tǒng)能力 ：SystemCapability.Global.I18n

參數(shù)：

返回值：

示例：

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

isIdeograph8+

isIdeograph(char: string): boolean

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

系統(tǒng)能力 ：SystemCapability.Global.I18n

參數(shù)：

返回值：

示例：

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

isLetter8+

isLetter(char: string): boolean

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

系統(tǒng)能力 ：SystemCapability.Global.I18n

參數(shù)：

返回值：

示例：

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

isLowerCase8+

isLowerCase(char: string): boolean

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

系統(tǒng)能力 ：SystemCapability.Global.I18n

參數(shù)：

返回值：

示例：

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

isUpperCase8+

isUpperCase(char: string): boolean

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

系統(tǒng)能力 ：SystemCapability.Global.I18n

參數(shù)：

返回值：

示例：

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

getType8+

getType(char: string): string

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

系統(tǒng)能力 ：SystemCapability.Global.I18n

參數(shù)：

返回值：

示例：

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

i18n.getLineInstance8+

getLineInstance(locale: string): BreakIterator

獲取一個(gè)用于斷句的[BreakIterator]對(duì)象。

系統(tǒng)能力 ：SystemCapability.Global.I18n

參數(shù)：

返回值：

示例：

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

BreakIterator8+

setLineBreakText8+

setLineBreakText(text: string): void

設(shè)置[BreakIterator]要處理的文本。

系統(tǒng)能力 ：SystemCapability.Global.I18n

參數(shù)：

示例：

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

getLineBreakText8+

getLineBreakText(): string

獲取[BreakIterator]當(dāng)前處理的文本。

系統(tǒng)能力 ：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]對(duì)象在當(dāng)前處理的文本中的位置。

系統(tǒng)能力 ：SystemCapability.Global.I18n

返回值：

示例：

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

first8+

first(): number

將[BreakIterator]對(duì)象設(shè)置到第一個(gè)可斷句的分割點(diǎn)。第一個(gè)分割點(diǎn)總是被處理的文本的起始位置。

系統(tǒng)能力 ：SystemCapability.Global.I18n

返回值：

示例：

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

last8+

last(): number

將[BreakIterator]對(duì)象的位置設(shè)置到最后一個(gè)可斷句的分割點(diǎn)。最后一個(gè)分割點(diǎn)總是被處理文本末尾的下一個(gè)位置。

系統(tǒng)能力 ：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是一個(gè)正數(shù)將[BreakIterator]向后移動(dòng)number個(gè)可斷句的分割點(diǎn)，如果n是一個(gè)負(fù)數(shù)，向前移動(dòng)相應(yīng)個(gè)分割點(diǎn)。若index沒(méi)有給出，則相當(dāng)于index = 1。

系統(tǒng)能力 ：SystemCapability.Global.I18n

參數(shù)：

返回值：

示例：

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]移動(dòng)到前一個(gè)分割點(diǎn)處。

系統(tǒng)能力 ：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]設(shè)置到由offset指定的位置的后面一個(gè)分割點(diǎn)。返回移動(dòng)后[BreakIterator]的位置。

系統(tǒng)能力 ：SystemCapability.Global.I18n

參數(shù)：

返回值：

示例：

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所指定的文本位置是一個(gè)分割點(diǎn)，那么返回true，否則返回false。如果返回true, 將[BreakIterator]對(duì)象設(shè)置到offset所指定的位置, 否則相當(dāng)于調(diào)用[following]。

系統(tǒng)能力 ：SystemCapability.Global.I18n

參數(shù)：

返回值：

示例：

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

i18n.is24HourClock7+

is24HourClock(): boolean

判斷系統(tǒng)時(shí)間是否為24小時(shí)制。

系統(tǒng)能力 ：SystemCapability.Global.I18n

返回值：

示例：

var is24HourClock = i18n.is24HourClock();

i18n.set24HourClock7+

set24HourClock(option: boolean): boolean

修改系統(tǒng)時(shí)間的24小時(shí)制設(shè)置。

需要權(quán)限 ：ohos.permission.UPDATE_CONFIGURATION

系統(tǒng)能力 ：SystemCapability.Global.I18n

參數(shù)：

返回值：

示例：

// 將系統(tǒng)時(shí)間設(shè)置為24小時(shí)制
var success = i18n.set24HourClock(true);

i18n.addPreferredLanguage8+

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

在系統(tǒng)偏好語(yǔ)言列表中的指定位置添加偏好語(yǔ)言。

需要權(quán)限 ：ohos.permission.UPDATE_CONFIGURATION

系統(tǒng)能力 ：SystemCapability.Global.I18n

參數(shù)：

返回值：

示例：

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

i18n.removePreferredLanguage8+

removePreferredLanguage(index: number): boolean

刪除系統(tǒng)偏好語(yǔ)言列表中指定位置的偏好語(yǔ)言。

需要權(quán)限 ：ohos.permission.UPDATE_CONFIGURATION

系統(tǒng)能力 ：SystemCapability.Global.I18n

參數(shù)：

返回值：

示例：

// 刪除系統(tǒng)偏好語(yǔ)言列表中的第一個(gè)偏好語(yǔ)言
var index = 0;
var success = i18n.removePreferredLanguage(index);

i18n.getPreferredLanguageList8+

getPreferredLanguageList(): Array

獲取系統(tǒng)偏好語(yǔ)言列表。

系統(tǒng)能力 ：SystemCapability.Global.I18n

返回值：

示例：

var preferredLanguageList = i18n.getPreferredLanguageList();

i18n.getFirstPreferredLanguage8+

getFirstPreferredLanguage(): string

獲取偏好語(yǔ)言列表中的第一個(gè)偏好語(yǔ)言。

系統(tǒng)能力 ：SystemCapability.Global.I18n

返回值：

示例：

var firstPreferredLanguage = i18n.getFirstPreferredLanguage();

i18n.getAppPreferredLanguage9+

getAppPreferredLanguage(): string

獲取應(yīng)用的偏好語(yǔ)言。

系統(tǒng)能力 ：SystemCapability.Global.I18n

返回值：

示例：

var appPreferredLanguage = i18n.getAppPreferredLanguage();

i18n.getTimeZone7+

getTimeZone(zoneID?: string): TimeZone

獲取時(shí)區(qū)ID對(duì)應(yīng)的時(shí)區(qū)對(duì)象。

系統(tǒng)能力 ：SystemCapability.Global.I18n

參數(shù)：

返回值：

示例：

var timezone = i18n.getTimeZone();

RelativeTimeFormat8+

getID8+

getID(): string

獲取時(shí)區(qū)對(duì)象的ID。

系統(tǒng)能力 ：SystemCapability.Global.I18n

返回值：

示例：

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

getDisplayName8+

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

獲取時(shí)區(qū)對(duì)象在指定區(qū)域的表示。

系統(tǒng)能力 ：SystemCapability.Global.I18n

參數(shù)：

返回值：

示例：

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

getRawOffset8+

getRawOffset(): number

獲取時(shí)區(qū)對(duì)象表示的時(shí)區(qū)與UTC時(shí)區(qū)的偏差。

系統(tǒng)能力 ：SystemCapability.Global.I18n

返回值：

示例：

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

getOffset8+

getOffset(date?: number): number

獲取某一時(shí)刻時(shí)區(qū)對(duì)象表示的時(shí)區(qū)與UTC時(shí)區(qū)的偏差。

系統(tǒng)能力 ：SystemCapability.Global.I18n

返回值：

示例：

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

審核編輯 黃宇