HarmonyOS Developer I18n开发指导
本模块提供系统相关的或者增强的国际化能力,包括区域管理、电话号码处理、日历等,相关接口为ECMA 402标准中未定义的补充接口。更多接口和使用方式请见I18N。
Intl模块提供了ECMA 402标准定义的基础国际化接口,与本模块共同使用可提供完整地国际化支持能力。
获取和设置系统国际化相关信息
调用接口访问和设置系统语言、偏好语言、地区、本地数字等国际化信息。
接口说明
类名 | 接口名称 | 描述 |
System | isRTL(locale:string):boolean7+ | locale对应的语言是否为从右到左语言。 |
System | getDisplayLanguage(language:string,locale:string,sentenceCase?:boolean):string | 获取语言的本地化表示。 |
System | getDisplayCountry(country:string,locale:string,sentenceCase?:boolean):string | 获取国家的本地化表示。 |
开发步骤
- 导入Intl模块。
未正确导入包可能会产生不明确的接口行为。
import I18n from '@ohos.i18n';
- 判断Locale的语言是否为RTL语言。
调用isRTL方法获取Locale的语言是否为从右到左语言。
try {
let rtl = I18n.isRTL("zh-CN"); // rtl = false
rtl = I18n.isRTL("ar"); // rtl = true
} catch(error) {
console.error(`call i18n.System interface failed, error code: ${error.code}, message: ${error.message}`);
}
- 获取语言的本地化表示。
调用getDisplayLanguage方法获取某一语言的本地化表示。其中,language表示待本地化显示的语言,locale表示本地化的Locale,sentenceCase结果是否需要首字母大写。
try {
let language = "en";
let locale = "zh-CN";
let sentenceCase = false;
let localizedLanguage = I18n.System.getDisplayLanguage(language, locale, sentenceCase); // localizedLanguage = "英语"
} catch(error) {
console.error(`call i18n.System interface failed, error code: ${error.code}, message: ${error.message}`);
}
- 获取国家的本地化表示。
调用getDisplayCountry方法获取某一国家的本地化表示。其中,country表示待本地化显示的国家,locale表示本地化的Locale,sentenceCase结果是否需要首字母大写。
try {
let country = "US"; let locale = "zh-CN";
let sentenceCase = false;
let localizedCountry = I18n.System.getDisplayCountry(country, locale, sentenceCase); // localizedCountry = "美国"
} catch(error) {
console.error(`call i18n.System interface failed, error code: ${error.code}, message: ${error.message}`);
}
获取日历信息
调用日历Calendar相关接口来获取日历的相关信息,例如获取日历的本地化显示、一周起始日、一年中第一周的最小天数等。
接口说明
类名 | 接口名称 | 描述 |
Calendar | getCalendar(locale:string,type?:string):Calendar8+ | 获取指定locale和type的日历对象。 |
Calendar | setTime(date:Date): void8+ | 设置日历对象内部的时间日期。 |
Calendar | setTime(time:number): void8+ | 设置日历对象内部的时间日期。 |
Calendar | set(year:number,month:number,date:number,hour?:number,minute?:number,second?:number): void8+ | 设置日历对象的年、月、日、时、分、秒。 |
Calendar | setTimeZone(timezone:string): void8+ | 设置日历对象的时区。 |
Calendar | getTimeZone():string8+ | 获取日历对象的时区。 |
Calendar | getFirstDayOfWeek():number8+ | 获取日历对象的一周起始日。 |
Calendar | setFirstDayOfWeek(value:number): void8+ | 设置日历对象的一周起始日。 |
Calendar | getMinimalDaysInFirstWeek():number8+ | 获取一年中第一周的最小天数。 |
Calendar | setMinimalDaysInFirstWeek(value:number): void8+ | 设置一年中第一周的最小天数。 |
Calendar | getDisplayName(locale:string):string8+ | 获取日历对象的本地化表示。 |
Calendar | isWeekend(date?:Date):boolean8+ | 判断给定的日期在日历中是否是周末。 |
开发步骤
- 导入Intl模块。
未正确导入包可能会产生不明确的接口行为。
import I18n from '@ohos.i18n';
- 实例化日历对象。
调用getCalendar方法获取指定locale和type的时区对象(i18n为导入的模块)。其中,type表示合法的日历类型,目前合法的日历类型包括:"buddhist", "chinese", "coptic", "ethiopic", "hebrew", "gregory", "indian", "islamic_civil", "islamic_tbla", "islamic_umalqura", "japanese", "persian"。当type没有给出时,采用区域默认的日历类型。
let calendar = I18n.getCalendar("zh-CN", "chinese"); // 创建中文农历日历
- 设置日历对象的时间。
调用setTime方法设置日历对象的时间。setTime方法接收两种类型的参数。一种是传入一个Date对象,另一种是传入一个数值表示从1970.1.1 00:00:00 GMT逝去的毫秒数。
let date1 = new Date();
calendar.setTime(date1);
let date2 = 1000;
calendar.setTime(date2);
- 设置日历对象的年、月、日、时、分、秒。
调用set方法设置日历对象的年、月、日、时、分、秒。
calendar.set(2021, 12, 21, 6, 0, 0);
- 设置、获取日历对象的时区。
调用setTimeZone方法和getTimeZone方法来设置、获取日历对象的时区。其中,setTimeZone方法需要传入一个字符串表示需要设置的时区。
calendar.setTimeZone("Asia/Shanghai");
let timezone = calendar.getTimeZone(); // timezone = "China Standard Time"
- 设置、获取日历对象的一周起始日。
调用setFirstDayOfWeek方法和getFirstDayOfWeek方法设置、获取日历对象的一周起始日。其中,setFirstDayOfWeek需要传入一个数值表示一周的起始日,1代表周日,7代表周六。
calendar.setFirstDayOfWeek(1);
let firstDayOfWeek = calendar.getFirstDayOfWeek(); // firstDayOfWeek = 1
- 设置、获取日历对象第一周的最小天数
调用setMinimalDaysInFirstWeek方法和getMinimalDaysInFirstWeek方法来设置、获取日历对象第一周的最小天数。
calendar.setMinimalDaysInFirstWeek(3);
let minimalDaysInFirstWeek = calendar.getMinimalDaysInFirstWeek(); // minimalDaysInFirstWeek = 3
- 获取日历对象的本地化显示
调用getDisplayName来获取日历对象的本地化显示。
let localizedName = calendar.getDisplayName("zh-CN"); // localizedName = "农历"
- 判断某一个日期是否为周末。
调用isWeekend方法来判断输入的Date是否为周末。
let date = new Date(2022, 12, 12, 12, 12, 12);
let weekend = calendar.isWeekend(date); // weekend = false
电话号码格式化
调用电话号码格式化PhoneNumberFormat的接口,实现对针对不同国家电话号码的格式化以及判断电话号码格式是否正确的功能。
接口说明
类名 | 接口名称 | 描述 |
PhoneNumberFormat | constructor(country:string,options?:PhoneNumberFormatOptions)8+ | 实例化PhoneNumberFormat对象。 |
PhoneNumberFormat | isValidNumber(number:string):boolean8+ | 判断number是否是一个格式正确的电话号码。 |
PhoneNumberFormat | format(number:string):string8+ | 对number按照指定国家及风格进行格式化。 |
PhoneNumberFormat | getLocationName(number: string, locale: string): string9+ | 获取电话号码归属地。 |
开发步骤
- 导入Intl模块。
未正确导入包可能会产生不明确的接口行为。
import I18n from '@ohos.i18n';
- 实例化电话号码格式化对象。
调用PhoneNumberFormat的构造函数来实例化电话号码格式化对象,需要传入电话号码的国家代码及格式化选项。其中,格式化选项是可选的,包括style选项,该选项的取值包括:"E164", "INTERNATIONAL", "NATIONAL", "RFC3966"。
let phoneNumberFormat = new I18n.PhoneNumberFormat("CN", {type: "E164"});
- 判断电话号码格式是否正确。
调用isValidNumber方法来判断输入的电话号码的格式是否正确。
let validNumber = phoneNumberFormat.isValidNumber("15812341234"); // validNumber = true
- 电话号码格式化。
调用电话号码格式化对象的format方法来对输入的电话号码进行格式化。
let formattedNumber = phoneNumberFormat.format("15812341234"); // formattedNumber = "+8615812341234"
度量衡转换
度量衡转换接口可以实现度量衡转换的相关功能。
接口说明
类名 | 接口名称 | 描述 |
I18NUtil | unitConvert(fromUnit:UnitInfo,toUnit:UnitInfo,value:number,locale:string,style?:string):string9+ | 将fromUnit的单位转换为toUnit的单位,并根据区域与风格进行格式化。 |
开发步骤
- 导入Intl模块。
未正确导入包可能会产生不明确的接口行为。
import I18n from '@ohos.i18n';
- 度量衡单位转换。
调用unitConvert方法实现度量衡单位转换,并进行格式化显示的功能。
let fromUnit = {unit: "cup", measureSystem: "US"};
let toUnit = {unit: "liter", measureSystem: "SI"};
let number = 1000;let locale = "en-US";
let style = "long";
let converttedUnit = I18n.I18NUtil.unitConvert(fromUnit, toUnit, number, locale, style); // converttedUnit = "236.588 liters"
字母表索引
调用字母表索引IndexUtil的接口可以获取不同Locale的字母表索引,以及实现计算字符串所属索引的功能。
接口说明
类名 | 接口名称 | 描述 |
IndexUtil | getInstance(locale?:string):IndexUtil8+ | 实例化字母表索引对象。 |
IndexUtil | getIndexList():Array<string>8+ | 获取当前Locale的索引列表。 |
IndexUtil | addLocale(locale:string): void8+ | 将新的Locale对应的索引加入当前索引列表。 |
IndexUtil | getIndex(text:string):string8+ | 获取text对应的索引。 |
开发步骤
- 导入Intl模块。
未正确导入包可能会产生不明确的接口行为。
import I18n from '@ohos.i18n';
- 实例化字母表索引对象。
调用getInstance方法来实例化特定locale对应的字母表索引对象。当locale参数为空时,实例化系统默认Locale的字母表索引对象。
let indexUtil = I18n.getInstance("zh-CN");
- 获取索引列表。
调用getIndexList方法来获取当前Locale对应的字母表索引列表。
let indexList = indexUtil.getIndexList(); // indexList = ["...", "A", "B", "C", ..., "X", "Y", "Z", "..."]
- 增加新的索引。
调用addLocale方法,将新的Locale对应的字母表索引添加到当前字母表索引列表中。
indexUtil.addLocale("ar");
- 获取字符串对应的索引。
调用getIndex方法来获取某一字符串对应的字母表索引。
let text = "access index";
let index = indexUtil.getIndex(text); // index = "A"
获取文本断点位置
当文本比较长无法在一行进行显示时,调用文本断点BreakIterator8的接口,来获取文本可以断行的位置。
接口说明
类名 | 接口名称 | 描述 |
BreakIterator | getLineInstance(locale:string):BreakIterator8+ | 实例化断行对象。 |
BreakIterator | setLineBreakText(text:string): void8+ | 设置要处理的文本。 |
BreakIterator | getLineBreakText():string8+ | 获取要处理的文本。 |
BreakIterator | current():number8+ | 获取当前断行对象在处理文本的位置。 |
BreakIterator | first():number8+ | 将断行对象设置到第一个可断句的分割点。 |
BreakIterator | last():number8+ | 将断行对象设置到最后一个可断句的分割点。 |
BreakIterator | next(index?:number):number8+ | 将断行对象移动index个分割点的位置。 |
BreakIterator | previous():number8+ | 将断行对象移动到前一个分割点的位置。 |
BreakIterator | following(offset:number):number8+ | 将断行对象移动到offset指定位置的后面一个分割点的位置。 |
BreakIterator | isBoundary(offset:number):boolean8+ | 判断某个位置是否是分割点。 |
开发步骤
- 导入Intl模块。
未正确导入包可能会产生不明确的接口行为。
import I18n from '@ohos.i18n';
- 实例化断行对象。
调用getLineInstance方法来实例化断行对象。
let locale = "en-US";
let breakIterator = I18n.getLineInstance(locale);
- 设置、访问要断行处理的文本。
调用setLineBreakText方法和getLineBreakText方法来设置、访问要断行处理的文本。
let text = "Apple is my favorite fruit";
breakIterator.setLineBreakText(text);
let breakText = breakIterator.getLineBreakText(); // breakText = "Apple is my favorite fruit"
- 获取断行对象当前的位置。
调用current方法来获取断行对象在当前处理文本中的位置。
let pos = breakIterator.current(); // pos = 0
- 设置断行对象的位置。
系统提供了很多接口可以用于调整断行对象在处理文本中的位置,包括first, last, next, previous, following。
let firstPos = breakIterator.first(); // 将断行对象设置到第一个分割点的位置,即文本的起始位置;
let lastPos = breakIterator.last(); // 将断行对象设置到最后一个分割点的位置,即文本末尾的下一个位置;
// 将断行对象向前或向后移动一定数量的分割点。
// 当传入正数时,向后移动;当传入负数时,向前移动;当未传入数值时,则向后移动一个位置;
// 当移动超出了文本的长度范围,则返回-1;
let nextPos = breakIterator.next(-2); // nextPos = 12
let previousPos = breakIterator.previous(); // 将断行对象向前移动向前移动一个分割点,当超出文本长度范围时返回-1;
// 将断行对象移动到offset指定位置的后面一个分割点。如果offset所指定的位置的下一个分割点超出了文本的长度范围,则返回-1;
let followingPos = breakIterator.following(10);
- 判断某个位置是否为分割点。
调用isBoundary方法来判断一个方法是否为分割点;如果该位置是分割点,则返回true,并且将断行对象移动到该位置;如果该位置不是分割点,则返回false,并且将断行对象移动到该位置后的一个分割点。
let isboundary = breakIterator.isBoundary(5);
获取时区
调用时区TimeZone相关接口来获取时区的相关信息,例如获取时区的ID、本地化显示、时区偏移量等。
接口说明
模块 | 接口名称 | 描述 |
TimeZone | getTimeZone(zoneID?: string): TimeZone7+ | 获取时区对象。 |
TimeZone | getID(): string7+ | 获取时区ID。 |
TimeZone | getDisplayName(locale?: string, isDST?: boolean): string7+ | 获取时区的本地化显示。 |
TimeZone | getRawOffset(): number7+ | 获取时区对象与UTC时区的偏移量。 |
TimeZone | getOffset(date?: number): number7+ | 获取某一时间点时区对象与UTC时区的偏移量。 |
TimeZone | getAvailableIDs(): Array9+ | 获取系统支持的时区ID列表。 |
TimeZone | getAvailableZoneCityIDs(): Array9+ | 获取系统支持的时区城市ID列表。 |
TimeZone | getCityDisplayName(cityID: string, locale: string): string9+ | 获取时区城市ID的本地化显示。 |
TimeZone | getTimezoneFromCity(cityID: string): TimeZone9+ | 获取时区城市ID对应的时区对象。 |
开发步骤
- 导入I18n模块。
import I18n from '@ohos.i18n'
- 实例化时区对象,并获取相关时区信息。
调用getTimeZone接口来获取时区对象。
let timezone = I18n.getTimeZone(); // 使用默认参数可以获取系统时区对象。
获取时区ID、本地化显示、时区偏移量、某一时刻的时区偏移量信息。
let timezoneID = timezone.getID(); // timezoneID = "Asia/Shanghai"
let timezoneDisplayName = timezone.getDisplayName(); // timezoneDisplayName = "中国标准时间"
let rawOffset = timezone.getRawOffset(); // rawOffset = 28800000
let offset = timezone.getOffset(new Date().getTime()); // offset = 28800000
- 获取系统支持的时区ID。
调用getAvailableIDs接口获取系统支持的时区ID列表。 时区ID列表中的时区ID可以作为getTimeZone接口的参数,来创建TimeZone对象。
let timezoneIDs = I18n.TimeZone.getAvailableIDs(); // timezoneIDs = ["America/Adak", ...],共包含24个时区ID
let timezone = I18n.getTimeZone(timezoneIDs[0]);
let timezoneDisplayName = timezone.getDisplayName(); // timezoneDisplayName = "夏威夷-阿留申时间"
- 获取系统支持的时区城市ID。
调用getAvailableZoneCityIDs接口获取系统支持的时区城市ID列表。 调用getCityDisplayName接口获取时区城市ID的本地化显示。 调用getTimezoneFromCity接口基于时区城市ID创建时区对象。
let zoneCityIDs = I18n.TimeZone.getAvailableZoneCityIDs(); // ["Auckland", "Magadan", ...]
let cityDisplayName = I18n.TimeZone.getCityDisplayName(zoneCityIDs[0], "zh-Hans"); // cityDisplayName = "奥克兰(新西兰)"
let timezone = I18n.TimeZone.getTimezoneFromCity(zoneCityIDs[0]);
let timezoneDisplayName = timezone.getDisplayName(); // timezoneDisplayName = "新西兰时间"
获取音译对象
调用音译Transliterator相关接口来创建音译对象,获取音译字符串。
接口说明
模块 | 接口名称 | 描述 |
Transliterator | getAvailableIDs():Array9+ | 获取音译支持的ID列表。 |
Transliterator | getInstance(): Transliterator9+ | 创建音译对象。 |
Transliterator | transform(text: string): string9+ | 获取音译字符串。 |
开发步骤
- 导入I18n模块。
import I18n from '@ohos.i18n'
- 获取支持音译的ID列表。
调用getAvailableIDs接口来获取支持音译的ID列表。 每个ID的格式为 source-destination,例如 ASCII-Latin,表示将ASCII转换为Latin的音译ID。
let ids = I18n.Transliterator.getAvailableIDs(); // ids = ["ASCII-Latin", "Accents-Any", ... ],共支持671个语言
- 创建音译对象,获取音译字符串。
let transliterator = I18n.Transliterator.getInstance("Any-Latn"); // Any-Latn表示将任意文本转换为Latn文本
let transformText = transliterator.transform("你好"); // transformText = "nǐ hǎo "
字符类型判断
调用字符Unicode相关接口来获取字符的相关信息,例如字符是否是数字、字符是否是空格符等。
接口说明
模块 | 接口名称 | 描述 |
Unicode | isDigit(char: string): boolean9+ | 判断字符是否是数字。 |
Unicode | isSpaceChar(char: string): boolean9+ | 判断字符是否是空格符。 |
Unicode | isWhitespace(char: string): boolean9+ | 判断字符是否是空白符。 |
Unicode | isRTL(char: string): boolean9+ | 判断字符是否是从左到右显示的字符。 |
Unicode | isIdeograph(char: string): boolean9+ | 判断字符是否是表意文字。 |
Unicode | isLetter(char: string): boolean9+ | 判断字符是否是字母。 |
Unicode | isLowerCase(char: string): boolean9+ | 判断字符是否是小写字母。 |
Unicode | isUpperCase(char: string): boolean9+ | 判断字符是否是大写字母。 |
Unicode | getType(char: string): string9+ | 获取字符的类型。 |
开发步骤
- 导入I18n模块。。
import I18n from '@ohos.i18n'
- 判断字符是否具有某种性质。
判断字符是否是数字。
let isDigit = I18n.Unicode.isDigit("1"); // isDigit = true
isDigit = I18n.Unicode.isDigit("a"); // isDigit = false
判断字符是否是空格符。
let isSpaceChar = I18n.Unicode.isSpaceChar(" "); // isSpaceChar = true
isSpaceChar = I18n.Unicode.isSpaceChar("\n"); // isSpaceChar = false
判断字符是否是空白符。
let isWhitespace = I18n.Unicode.isWhitespace(" "); // isWhitespace = true
isWhitespace = I18n.Unicode.isWhitespace("\n"); // isWhitespace = true
判断字符是否是从左到右书写的文字。
let isRTL = I18n.Unicode.isRTL("مرحبًا"); // isRTL = true,阿拉伯语的文字是从左到右书写的文字
isRTL = I18n.Unicode.isRTL("a"); // isRTL = false
判断字符是否是表意文字。
let isIdeograph = I18n.Unicode.isIdeograph("你好"); // isIdeograph = true
isIdeograph = I18n.Unicode.isIdeograph("a"); // isIdeograph = false
判断字符是否是字母。
let isLetter = I18n.Unicode.isLetter("a"); // isLetter = true
isLetter = I18n.Unicode.isLetter("."); // isLetter = false
判断字符是否是小写字母。
let isLowerCase = I18n.Unicode.isLowerCase("a"); // isLetter = true
isLowerCase = I18n.Unicode.isLowerCase("A"); // isLetter = false
判断字符是否是大写字母。
let isUpperCase = I18n.Unicode.isUpperCase("a"); // isUpperCase = false
isUpperCase = I18n.Unicode.isUpperCase("A"); // isUpperCase = true
- 获取字符的类型。
调用getType接口获取字符的类型
let type = I18n.Unicode.getType("a"); // type = U_LOWER_CASE_LETTER
获取日期中年月日的排列顺序
接口说明
模块 | 接口名称 | 描述 |
I18NUtil | getDateOrder(locale: string): string9+ | 判断日期中年月日的排列顺序。 |
开发步骤
- 导入I18n模块。
import I18n from '@ohos.i18n'
- 判断日期的年月日的排序顺序。
调用getDateOrder接口判断某一Locale的日期中,年月日的排列顺序。 接口返回一个字符串,由"y","L","d"三部分组成,分别表示年、月、日,使用中划线进行拼接。例如,"y-L-d"。
let order = I18n.I18NUtil.getDateOrder("zh-CN"); // order = "y-L-d",表示中文中年月日的顺序为年-月-日。