HarmonyOS Developer I18n开发指导

丶龙八夷
发布于 2023-3-31 16:38
浏览
0收藏

本模块提供系统相关的或者增强的国际化能力,包括区域管理、电话号码处理、日历等,相关接口为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

获取国家的本地化表示。

开发步骤

  1. 导入Intl模块。
    未正确导入包可能会产生不明确的接口行为。

import I18n from '@ohos.i18n';
  1. 判断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}`);
}
  1. 获取语言的本地化表示。

调用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}`);
}
  1. 获取国家的本地化表示。

调用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+

判断给定的日期在日历中是否是周末。

开发步骤

  1. 导入Intl模块。
    未正确导入包可能会产生不明确的接口行为。

import I18n from '@ohos.i18n';
  1. 实例化日历对象。

调用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"); // 创建中文农历日历
  1. 设置日历对象的时间。

调用setTime方法设置日历对象的时间。setTime方法接收两种类型的参数。一种是传入一个Date对象,另一种是传入一个数值表示从1970.1.1 00:00:00 GMT逝去的毫秒数。

let date1 = new Date();
calendar.setTime(date1);
let date2 = 1000;
calendar.setTime(date2);
  1. 设置日历对象的年、月、日、时、分、秒。

调用set方法设置日历对象的年、月、日、时、分、秒。

calendar.set(2021, 12, 21, 6, 0, 0);
  1. 设置、获取日历对象的时区。

调用setTimeZone方法和getTimeZone方法来设置、获取日历对象的时区。其中,setTimeZone方法需要传入一个字符串表示需要设置的时区。

calendar.setTimeZone("Asia/Shanghai");
let timezone = calendar.getTimeZone();  // timezone = "China Standard Time"
  1. 设置、获取日历对象的一周起始日。

调用setFirstDayOfWeek方法和getFirstDayOfWeek方法设置、获取日历对象的一周起始日。其中,setFirstDayOfWeek需要传入一个数值表示一周的起始日,1代表周日,7代表周六。

calendar.setFirstDayOfWeek(1);
let firstDayOfWeek = calendar.getFirstDayOfWeek(); // firstDayOfWeek = 1
  1. 设置、获取日历对象第一周的最小天数

调用setMinimalDaysInFirstWeek方法和getMinimalDaysInFirstWeek方法来设置、获取日历对象第一周的最小天数。

calendar.setMinimalDaysInFirstWeek(3);
let minimalDaysInFirstWeek = calendar.getMinimalDaysInFirstWeek(); // minimalDaysInFirstWeek = 3
  1. 获取日历对象的本地化显示

调用getDisplayName来获取日历对象的本地化显示。

let localizedName = calendar.getDisplayName("zh-CN"); // localizedName = "农历"
  1. 判断某一个日期是否为周末。

调用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+

获取电话号码归属地。

开发步骤

  1. 导入Intl模块。
    未正确导入包可能会产生不明确的接口行为。

import I18n from '@ohos.i18n';
  1. 实例化电话号码格式化对象。

调用PhoneNumberFormat的构造函数来实例化电话号码格式化对象,需要传入电话号码的国家代码及格式化选项。其中,格式化选项是可选的,包括style选项,该选项的取值包括:"E164", "INTERNATIONAL", "NATIONAL", "RFC3966"。

let phoneNumberFormat = new I18n.PhoneNumberFormat("CN", {type: "E164"});
  1. 判断电话号码格式是否正确。

调用isValidNumber方法来判断输入的电话号码的格式是否正确。

let validNumber = phoneNumberFormat.isValidNumber("15812341234"); // validNumber = true
  1. 电话号码格式化。

调用电话号码格式化对象的format方法来对输入的电话号码进行格式化。

let formattedNumber = phoneNumberFormat.format("15812341234"); // formattedNumber = "+8615812341234"

度量衡转换

度量衡转换接口可以实现度量衡转换的相关功能。

接口说明

类名

接口名称

描述

I18NUtil

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

将fromUnit的单位转换为toUnit的单位,并根据区域与风格进行格式化。

开发步骤

  1. 导入Intl模块。
    未正确导入包可能会产生不明确的接口行为。

import I18n from '@ohos.i18n';
  1. 度量衡单位转换。

调用​​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对应的索引。

开发步骤

  1. 导入Intl模块。
    未正确导入包可能会产生不明确的接口行为。

import I18n from '@ohos.i18n';
  1. 实例化字母表索引对象。

调用getInstance方法来实例化特定locale对应的字母表索引对象。当locale参数为空时,实例化系统默认Locale的字母表索引对象。

let indexUtil = I18n.getInstance("zh-CN");
  1. 获取索引列表。

调用getIndexList方法来获取当前Locale对应的字母表索引列表。

let indexList = indexUtil.getIndexList(); // indexList = ["...", "A", "B", "C", ..., "X", "Y", "Z", "..."]
  1. 增加新的索引。

调用addLocale方法,将新的Locale对应的字母表索引添加到当前字母表索引列表中。

indexUtil.addLocale("ar");
  1. 获取字符串对应的索引。

调用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+

判断某个位置是否是分割点。

开发步骤

  1. 导入Intl模块。
    未正确导入包可能会产生不明确的接口行为。

import I18n from '@ohos.i18n';
  1. 实例化断行对象。

调用getLineInstance方法来实例化断行对象。

let locale = "en-US";
let breakIterator = I18n.getLineInstance(locale);
  1. 设置、访问要断行处理的文本。

调用setLineBreakText方法和getLineBreakText方法来设置、访问要断行处理的文本。

let text = "Apple is my favorite fruit";
breakIterator.setLineBreakText(text);
let breakText = breakIterator.getLineBreakText();  // breakText = "Apple is my favorite fruit"
  1. 获取断行对象当前的位置。

调用current方法来获取断行对象在当前处理文本中的位置。

let pos = breakIterator.current(); // pos = 0
  1. 设置断行对象的位置。

系统提供了很多接口可以用于调整断行对象在处理文本中的位置,包括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); 
  1. 判断某个位置是否为分割点。

调用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对应的时区对象。

开发步骤

  1. 导入I18n模块。

import I18n from '@ohos.i18n'
  1. 实例化时区对象,并获取相关时区信息。

调用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
  1. 获取系统支持的时区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 = "夏威夷-阿留申时间"
  1. 获取系统支持的时区城市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+

获取音译字符串。

开发步骤

  1. 导入I18n模块。

import I18n from '@ohos.i18n'
  1. 获取支持音译的ID列表。

调用getAvailableIDs接口来获取支持音译的ID列表。 每个ID的格式为 source-destination,例如 ASCII-Latin,表示将ASCII转换为Latin的音译ID。

let ids = I18n.Transliterator.getAvailableIDs(); // ids = ["ASCII-Latin", "Accents-Any", ... ],共支持671个语言
  1. 创建音译对象,获取音译字符串。

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+

获取字符的类型。

开发步骤

  1. 导入I18n模块。。

import I18n from '@ohos.i18n'
  1. 判断字符是否具有某种性质。

判断字符是否是数字。

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
  1. 获取字符的类型。

调用getType接口获取字符的类型

let type = I18n.Unicode.getType("a"); // type = U_LOWER_CASE_LETTER

获取日期中年月日的排列顺序

接口说明

模块

接口名称

描述

I18NUtil

getDateOrder(locale: string): string9+

判断日期中年月日的排列顺序。

开发步骤

  1. 导入I18n模块。

import I18n from '@ohos.i18n'
  1. 判断日期的年月日的排序顺序。

调用getDateOrder接口判断某一Locale的日期中,年月日的排列顺序。 接口返回一个字符串,由"y","L","d"三部分组成,分别表示年、月、日,使用中划线进行拼接。例如,"y-L-d"。

let order = I18n.I18NUtil.getDateOrder("zh-CN"); // order = "y-L-d",表示中文中年月日的顺序为年-月-日。



文章转载自:​​https://developer.harmonyos.com/cn/docs/documentation/doc-guides-V3/i18n-guidelines-0000001478181329-V3​

标签
已于2023-3-31 16:38:48修改
收藏
回复
举报
回复