59850932创建于 2025年6月4日历史提交

@ohos.intl (国际化-Intl)

本模块提供基础的应用国际化能力，包括时间日期格式化、数字格式化、排序等，相关接口在ECMA 402标准中定义。 I18N模块提供其他非ECMA 402定义的国际化接口，与本模块共同使用可提供完整地国际化支持能力。

说明：

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

本模块接口依据CLDR 国际化数据库进行处理。随着CLDR演进，本模块接口处理结果可能发生变化。其中，API version 12对应CLDR 42，详细数据变化请参考官方链接。

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

从API version 12开始，本模块全接口支持在原子化服务中使用。

导入模块

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

Locale

属性

卡片能力：从API version 11开始，该接口支持在ArkTS卡片中使用。

原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.Global.I18n

名称	类型	必填	说明
language	string	是	与区域设置相关的语言，如：zh。取值遵循ISO 639标准。
script	string	是	区域语言的书写方式（脚本），如：Hans。取值遵循Unicode ISO 15924标准。
region	string	是	与区域设置相关的国家地区，如：CN。取值遵循ISO 3166标准。
baseName	string	是	区域对象的基本信息，由语言、脚本、国家地区组成，如：zh-Hans-CN。
caseFirst	string	是	区域的排序规则是否考虑大小写，取值包括： "upper", "lower", "false"。不同取值表示的含义请参考本地习惯排序表1。
calendar	string	是	区域的日历信息，取值包括： "buddhist", "chinese", "coptic","dangi", "ethioaa", "ethiopic", "gregory", "hebrew", "indian", "islamic", "islamic-umalqura", "islamic-tbla", "islamic-civil", "islamic-rgsa", "iso8601", "japanese", "persian", "roc", "islamicc"。不同取值表示的含义请参考设置日历和历法表1。
collation	string	是	区域的排序规则，取值包括： "big5han", "compat", "dict", "direct", "ducet", "eor", "gb2312", "phonebk", "phonetic", "pinyin", "reformed", "searchjl", "stroke", "trad", "unihan", "zhuyin"。不同取值表示的含义请参考本地习惯排序表1。
hourCycle	string	是	区域的时制信息，取值包括： "h11"、"h12"、"h23"、"h24"。不同取值的显示效果可参考时间日期国际化表5。
numberingSystem	string	是	区域使用的数字系统，取值包括： "adlm", "ahom", "arab", "arabext", "bali", "beng", "bhks", "brah", "cakm", "cham", "deva", "diak", "fullwide", "gong", "gonm", "gujr", "guru", "hanidec", "hmng", "hmnp", "java", "kali", "khmr", "knda", "lana", "lanatham", "laoo", "latn", "lepc", "limb", "mathbold", "mathdbl", "mathmono", "mathsanb", "mathsans", "mlym", "modi", "mong", "mroo", "mtei", "mymr", "mymrshan", "mymrtlng", "newa", "nkoo", "olck", "orya", "osma", "rohg", "saur", "segment", "shrd", "sind", "sinh", "sora", "sund", "takr", "talu", "tamldec", "telu", "thai", "tibt", "tirh", "vaii", "wara", "wcho"。
numeric	boolean	是	true表示对数字字符进行特殊的排序规则处理，false表示不对数字字符进行特殊的排序规则处理。默认值：false。

constructor⁸⁺

constructor()

创建区域对象。

卡片能力：从API version 11开始，该接口支持在ArkTS卡片中使用。

原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.Global.I18n

示例：

// 默认构造函数使用系统当前区域ID创建
let locale = new intl.Locale();
// 返回系统当前区域ID
let localeID = locale.toString();

constructor

constructor(locale: string, options?: LocaleOptions)

创建区域对象。

卡片能力：从API version 11开始，该接口支持在ArkTS卡片中使用。

原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.Global.I18n

参数：

参数名	类型	必填	说明
locale	string	是	表示区域ID的字符串，由语言、脚本、国家地区组成。
options	LocaleOptions	否	创建区域对象的选项。

示例：

// 创建zh-CN区域对象
let locale = new intl.Locale("zh-CN");
let localeID = locale.toString(); // localeID = "zh-CN"

toString

toString(): string

获取区域对象的字符串。

卡片能力：从API version 11开始，该接口支持在ArkTS卡片中使用。

原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.Global.I18n

返回值：

类型	说明
string	区域对象的字符串。

示例：

// 创建en-GB区域对象
let locale = new intl.Locale("en-GB");
let localeID = locale.toString(); // localeID = "en-GB"

maximize

maximize(): Locale

最大化区域信息，补齐区域对象中缺少的脚本、国家地区信息。

卡片能力：从API version 11开始，该接口支持在ArkTS卡片中使用。

原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.Global.I18n

返回值：

类型	说明
Locale	补齐完脚本、国家地区信息后的区域对象。

示例：

// 创建zh区域对象
let locale = new intl.Locale("zh");
// 补齐区域对象的脚本和地区
let maximizedLocale = locale.maximize();
let localeID = maximizedLocale.toString(); // localeID = "zh-Hans-CN"

// 创建en-US区域对象
locale = new intl.Locale("en-US");
// 补齐区域对象的脚本
maximizedLocale = locale.maximize();
localeID = maximizedLocale.toString(); // localeID = "en-Latn-US"

minimize

minimize(): Locale

最小化区域信息，移除区域对象中的脚本、国家地区信息。

卡片能力：从API version 11开始，该接口支持在ArkTS卡片中使用。

原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.Global.I18n

返回值：

类型	说明
Locale	移除完脚本、国家地区信息后的区域对象。

示例：

// 创建zh-Hans-CN区域对象
let locale = new intl.Locale("zh-Hans-CN");
// 移除区域对象的脚本和地区
let minimizedLocale = locale.minimize();
let localeID = minimizedLocale.toString(); // localeID = "zh"

// 创建en-US区域对象
locale = new intl.Locale("en-US");
// 移除区域对象的地区
minimizedLocale = locale.minimize();
localeID = minimizedLocale.toString(); // localeID = "en"

LocaleOptions

区域初始化选项。从API version 9开始，LocaleOptions属性由必填改为可选。

卡片能力：从API version 11开始，该类型支持在ArkTS卡片中使用。

原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.Global.I18n

名称	类型	必填	说明
calendar	string	否	日历参数，取值包括： "buddhist", "chinese", "coptic", "dangi", "ethioaa", "ethiopic", "gregory", "hebrew", "indian", "islamic", "islamic-umalqura", "islamic-tbla", "islamic-civil", "islamic-rgsa", "iso8601", "japanese", "persian", "roc", "islamicc"。
collation	string	否	排序参数，取值包括： "big5han", "compat", "dict", "direct", "ducet", "emoji", "eor", "gb2312", "phonebk", "phonetic", "pinyin", "reformed ", "search", "searchjl", "standard", "stroke", "trad", "unihan", "zhuyin"。
hourCycle	string	否	时制格式，取值包括： "h11", "h12", "h23", "h24"。
numberingSystem	string	否	数字系统，取值包括： "adlm", "ahom", "arab", "arabext", "bali", "beng", "bhks", "brah", "cakm", "cham", "deva", "diak", "fullwide", "gong", "gonm", "gujr", "guru", "hanidec", "hmng", "hmnp", "java", "kali", "khmr", "knda", "lana", "lanatham", "laoo", "latn", "lepc", "limb", "mathbold", "mathdbl", "mathmono", "mathsanb", "mathsans", "mlym", "modi", "mong", "mroo", "mtei", "mymr", "mymrshan", "mymrtlng", "newa", "nkoo", "olck", "orya", "osma", "rohg", "saur", "segment", "shrd", "sind", "sinh", "sora", "sund", "takr", "talu", "tamldec", "telu", "thai", "tibt", "tirh", "vaii", "wara", "wcho"。
numeric	boolean	否	true表示对数字字符进行特殊的排序规则处理，false表示不对数字字符进行特殊的排序规则处理。默认值：false。
caseFirst	string	否	表示大写、小写的排序顺序，取值范围："upper", "lower", "false"。

说明：

calendar：不同取值的含义请参考设置日历和历法表1。

hourCycle：不同取值的显示效果请参考时间日期国际化表5。

collation、caseFirst：不同取值的含义请参考本地习惯排序表1。

DateTimeFormat

constructor⁸⁺

constructor()

创建时间、日期格式化对象。

卡片能力：从API version 11开始，该接口支持在ArkTS卡片中使用。

原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.Global.I18n

示例：

// 使用系统当前区域ID创建DateTimeFormat对象
let datefmt= new intl.DateTimeFormat();

constructor

constructor(locale: string | Array<string>, options?: DateTimeOptions)

创建时间、日期格式化对象。

卡片能力：从API version 11开始，该接口支持在ArkTS卡片中使用。

原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.Global.I18n

参数：

参数名	类型	必填	说明
locale	string \| Array<string>	是	区域ID或区域ID数组。输入是区域ID数组时，使用第一个有效的区域ID。
options	DateTimeOptions	否	创建时间、日期格式化对象时可设置的配置项。若所有选项均未设置时，year、month、day三个属性的默认值为numeric。

示例：

// 使用zh-CN区域ID创建DateTimeFormat对象，日期风格为full，时间风格为medium
let datefmt= new intl.DateTimeFormat("zh-CN", { dateStyle: 'full', timeStyle: 'medium' });

// 使用区域ID列表创建DateTimeFormat对象，因为ban为非法区域ID，因此使用zh区域ID创建DateTimeFormat对象
let datefmt= new intl.DateTimeFormat(["ban", "zh"], { dateStyle: 'full', timeStyle: 'medium' });

format

format(date: Date): string

对时间、日期进行格式化。

卡片能力：从API version 11开始，该接口支持在ArkTS卡片中使用。

原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.Global.I18n

参数：

参数名	类型	必填	说明
date	Date	是	时间、日期。说明：月份从0开始计数，例如0表示一月。

返回值：

类型	说明
string	格式化后的时间、日期字符串。

示例：

let date = new Date(2021, 11, 17, 3, 24, 0); // 时间日期为2021.12.17 03:24:00
// 使用en-GB区域ID创建DateTimeFormat对象
let datefmt = new intl.DateTimeFormat("en-GB");
let formattedDate = datefmt.format(date); // formattedDate "17/12/2021"

// 使用en-GB区域ID创建DateTimeFormat对象，dateStyle设置为full，timeStyle设置为medium
datefmt = new intl.DateTimeFormat("en-GB", { dateStyle: 'full', timeStyle: 'medium' });
formattedDate = datefmt.format(date); // formattedDate "Friday, 17 December 2021 at 03:24:00"

formatRange

formatRange(startDate: Date, endDate: Date): string

对时间段、日期段进行格式化。

卡片能力：从API version 11开始，该接口支持在ArkTS卡片中使用。

原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.Global.I18n

参数：

参数名	类型	必填	说明
startDate	Date	是	时间、日期的开始。说明：月份从0开始计数，例如0表示一月。
endDate	Date	是	时间、日期的结束。说明：月份从0开始计数，例如0表示一月。

返回值：

类型	说明
string	格式化后的时间段、日期段字符串。

示例：

let startDate = new Date(2021, 11, 17, 3, 24, 0); // 时间日期为2021.12.17 03:24:00
let endDate = new Date(2021, 11, 18, 3, 24, 0);
// 使用en-GB区域ID创建DateTimeFormat对象
let datefmt = new intl.DateTimeFormat("en-GB");
let formattedDateRange = datefmt.formatRange(startDate, endDate); // formattedDateRange = "17/12/2021 - 18/12/2021"

resolvedOptions

resolvedOptions(): DateTimeOptions

获取创建时间、日期格式化对象时设置的配置项。

卡片能力：从API version 11开始，该接口支持在ArkTS卡片中使用。

原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.Global.I18n

返回值：

类型	说明
DateTimeOptions	时间、日期格式化对象设置的配置项。

示例：

let datefmt = new intl.DateTimeFormat("en-GB", { dateStyle: 'full', timeStyle: 'medium' });
// 返回DateTimeFormat对象的配置项
let options = datefmt.resolvedOptions();
let dateStyle = options.dateStyle; // dateStyle = "full"
let timeStyle = options.timeStyle; // timeStyle = "medium"

DateTimeOptions

时间、日期格式化时可设置的配置项。从API version 9开始，DateTimeOptions的属性由必填改为可选。

卡片能力：从API version 11开始，该类型支持在ArkTS卡片中使用。

原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.Global.I18n

名称	类型	必填	说明
locale	string	否	合法的区域ID，如：zh-Hans-CN。默认值：系统当前区域ID。
dateStyle	string	否	日期显示格式，取值包括： "long", "short", "medium", "full", "auto"。不同取值的显示效果请参考时间日期国际化表1。
timeStyle	string	否	时间显示格式，取值包括： "long", "short", "medium", "full", "auto"。不同取值的显示效果请参考时间日期国际化表2。
hourCycle	string	否	时制格式，取值包括： "h11", "h12", "h23", "h24"。不设置dateStyle或timeStyle参数时的显示效果请参考时间日期国际化表5。设置dateStyle或timeStyle参数时的显示效果请参考时间日期国际化表6。
timeZone	string	否	使用的时区，取值为合法的IANA时区ID。
numberingSystem	string	否	数字系统，取值包括： "adlm", "ahom", "arab", "arabext", "bali", "beng", "bhks", "brah", "cakm", "cham", "deva", "diak", "fullwide", "gong", "gonm", "gujr", "guru", "hanidec", "hmng", "hmnp", "java", "kali", "khmr", "knda", "lana", "lanatham", "laoo", "latn", "lepc", "limb", "mathbold", "mathdbl", "mathmono", "mathsanb", "mathsans", "mlym", "modi", "mong", "mroo", "mtei", "mymr", "mymrshan", "mymrtlng", "newa", "nkoo", "olck", "orya", "osma", "rohg", "saur", "segment", "shrd", "sind", "sinh", "sora", "sund", "takr", "talu", "tamldec", "telu", "thai", "tibt", "tirh", "vaii", "wara", "wcho"。
hour12	boolean	否	true表示使用12小时制，false表示使用24小时制。同时设置hour12和hourCycle时，hourCycle不生效。若hour12和hourCycle未设置且系统24小时开关打开时，hour12属性的默认值为false。
weekday	string	否	星期的显示格式，取值包括： "long", "short", "narrow", "auto"。不同取值的显示效果请参考时间日期国际化表4。
era	string	否	纪元的显示格式，取值包括： "long", "short", "narrow", "auto"。不同取值的显示效果请参考时间日期国际化表9。
year	string	否	年份的显示格式，取值包括： "numeric", "2-digit"。不同取值的显示效果请参考时间日期国际化表3。
month	string	否	月份的显示格式，取值包括： "numeric", "2-digit", "long", "short", "narrow", "auto"。不同取值的显示效果请参考时间日期国际化表6。
day	string	否	日期的显示格式，取值包括： "numeric", "2-digit"。
hour	string	否	小时的显示格式，取值包括： "numeric", "2-digit"。
minute	string	否	分钟的显示格式，取值包括： "numeric", "2-digit"。
second	string	否	秒钟的显示格式，取值包括： "numeric", "2-digit"。
timeZoneName	string	否	时区名称的本地化表示，取值包括： "long", "short", "auto"。不同取值的显示效果请参考时间日期国际化表8。
dayPeriod	string	否	时段的显示格式，取值包括： "long", "short", "narrow", "auto"。不同取值的显示效果请参考时间日期国际化表10。
localeMatcher	string	否	要使用的区域匹配算法，取值包括： "lookup"：精确匹配。 "best fit"：最佳匹配。
formatMatcher	string	否	要使用的格式匹配算法，取值包括： "basic"：精确匹配。 "best fit"：最佳匹配。

NumberFormat

constructor⁸⁺

constructor()

创建数字格式化对象。

原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.Global.I18n

示例：

// 使用系统当前区域ID创建NumberFormat对象
let numfmt = new intl.NumberFormat();

constructor

constructor(locale: string | Array<string>, options?: NumberOptions)

创建数字格式化对象。

原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.Global.I18n

参数：

参数名	类型	必填	说明
locale	string \| Array<string>	是	区域ID或区域ID数组。输入是区域ID数组时，使用第一个有效的区域ID。
options	NumberOptions	否	创建数字格式化对象时可设置的配置项。

示例：

// 使用en-GB区域ID创建NumberFormat对象，style设置为decimal，notation设置为scientific
let numfmt = new intl.NumberFormat("en-GB", {style:'decimal', notation:"scientific"});

format

format(number: number): string

对数字进行格式化。

原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.Global.I18n

参数：

参数名	类型	必填	说明
number	number	是	数字对象。

返回值：

类型	说明
string	格式化后的数字字符串。

示例：

// 使用区域ID列表创建NumberFormat对象，因为en-GB为合法的区域ID，因此使用en-GB创建NumberFormat对象
let numfmt : intl.NumberFormat = new intl.NumberFormat(["en-GB", "zh"], {style:'decimal', notation:"scientific"});
let formattedNumber : string = numfmt.format(1223); // formattedNumber = 1.223E3
let options : intl.NumberOptions = {
  roundingPriority: "lessPrecision",
  maximumFractionDigits: 3,
  maximumSignificantDigits: 3
}
let numberFmt : intl.NumberFormat = new intl.NumberFormat("en", options);
let result : string = numberFmt.format(1.23456); // result = 1.23

formatRange¹⁸⁺

formatRange(startRange: number, endRange: number): string

对数字范围进行格式化。

原子化服务API：从API version 18开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.Global.I18n

参数：

参数名	类型	必填	说明
startRange	number	是	开始数字。
endRange	number	是	结束数字。

返回值：

类型	说明
string	格式化后的数字范围字符串。

示例：

let numfmt : intl.NumberFormat = new intl.NumberFormat("en-US", {style:'unit', unit:"meter"});
let formattedRange : string = numfmt.formatRange(0, 3); // formattedRange: 0–3 m

resolvedOptions

resolvedOptions(): NumberOptions

获取创建数字格式化对象时设置的配置项。

原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.Global.I18n

返回值：

类型	说明
NumberOptions	创建数字格式化对象时设置的配置项。

示例：

let numfmt = new intl.NumberFormat(["en-GB", "zh"], {style:'decimal', notation:"scientific"});
// 获取NumberFormat对象配置项
let options = numfmt.resolvedOptions();
let style = options.style; // style = decimal
let notation = options.notation; // notation = scientific

NumberOptions

创建数字格式化对象时可设置的配置项。从API version 9开始，NumberOptions的属性由必填改为可选。

系统能力：SystemCapability.Global.I18n

名称	类型	必填	说明
locale	string	否	合法的区域ID，如："zh-Hans-CN"。默认值：系统当前区域ID。原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。
currency	string	否	货币单位，取值符合ISO-4217标准，如："EUR"，"CNY"，"USD"等。从API version 12开始支持三位数字代码，如："978"，"156"，"840"等。原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。
currencySign	string	否	货币单位的符号显示，取值包括： "standard"，"accounting"。默认值：standard。原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。
currencyDisplay	string	否	货币的显示方式，取值包括："symbol", "narrowSymbol", "code", "name"。默认值：symbol。原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。
unit	string	否	单位名称，如："meter"，"inch"，“hectare”等。从API version 18开始新增支持的组合单位有： "beat-per-minute", "body-weight-per-second", "breath-per-minute", "foot-per-hour", "jump-rope-per-minute", "meter-per-hour", "milliliter-per-minute-per-kilogram", "rotation-per-minute", "step-per-minute", "stroke-per-minute"。原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。
unitDisplay	string	否	单位的显示格式，取值包括："long", "short", "narrow"。默认值：short。原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。
unitUsage⁸⁺	string	否	单位的使用场景，取值包括："default", "area-land-agricult", "area-land-commercl", "area-land-residntl", "length-person", "length-person-small", "length-rainfall", "length-road", "length-road-small", "length-snowfall", "length-vehicle", "length-visiblty", "length-visiblty-small", "length-person-informal", "length-person-small-informal", "length-road-informal", "speed-road-travel", "speed-wind", "temperature-person", "temperature-weather", "volume-vehicle-fuel", "elapsed-time-second", "size-file-byte", "size-shortfile-byte"。默认值：default。原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。
signDisplay	string	否	数字符号的显示格式，取值包括： "auto"：自动判断是否显示正负符号。 "never"：不显示正负号。 "always"：总是显示正负号。 "exceptZero"：除了0都显示正负号。默认值："auto"。原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。
compactDisplay	string	否	紧凑显示格式，取值包括："long", "short"。默认值：short。原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。
notation	string	否	数字的表示方法，取值包括："standard", "scientific", "engineering", "compact"。默认值：standard。原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。
localeMatcher	string	否	要使用的区域匹配算法，取值包括："lookup", "best fit"。默认值：best fit。原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。
style	string	否	数字的显示格式，取值包括："decimal", "currency", "percent", "unit"。默认值：decimal。原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。
numberingSystem	string	否	数字系统，取值包括： "adlm", "ahom", "arab", "arabext", "bali", "beng", "bhks", "brah", "cakm", "cham", "deva", "diak", "fullwide", "gong", "gonm", "gujr", "guru", "hanidec", "hmng", "hmnp", "java", "kali", "khmr", "knda", "lana", "lanatham", "laoo", "latn", "lepc", "limb", "mathbold", "mathdbl", "mathmono", "mathsanb", "mathsans", "mlym", "modi", "mong", "mroo", "mtei", "mymr", "mymrshan", "mymrtlng", "newa", "nkoo", "olck", "orya", "osma", "rohg", "saur", "segment", "shrd", "sind", "sinh", "sora", "sund", "takr", "talu", "tamldec", "telu", "thai", "tibt", "tirh", "vaii", "wara", "wcho"。默认值：区域的默认数字系统。原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。
useGrouping	boolean	否	true表示分组显示，false表示不分组显示。默认值：true。原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。
minimumIntegerDigits	number	否	表示要使用的最小整数位数，取值范围：1~21。默认值：1。原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。
minimumFractionDigits	number	否	表示要使用的最小分数位数，取值范围：0~20。默认值：0。原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。
maximumFractionDigits	number	否	表示要使用的最大分数位数，取值范围：1~21。默认值：3。原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。
minimumSignificantDigits	number	否	表示要使用的最小有效位数，取值范围：1~21。默认值：1。原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。
maximumSignificantDigits	number	否	表示要使用的最大有效位数，取值范围：1~21。默认值：21。原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。
roundingPriority¹⁸⁺	string	否	最大分数位数和最大有效位数同时设置时的舍入优先级，取值包括："auto"，"morePrecision" 取最大分数位数，"lessPrecision" 取最大有效位数。默认值：auto。原子化服务API：从API version 18开始，该接口支持在原子化服务中使用。
roundingIncrement¹⁸⁺	number	否	表示舍入增量，取值范围：1，2，5，10，20，25，50，100，200，250，500，1000，2000，2500，5000。默认值：1。原子化服务API：从API version 18开始，该接口支持在原子化服务中使用。
roundingMode¹⁸⁺	string	否	表示舍入模式，取值包括： "ceil"：向上取整。 "floor"：向下取整。 "expand"：远离零取整。 "trunc"：向零取整。 "halfCeil"：半向上取整，大于等于增量的一半时向上取整，小于增量的一半时向下取整。 "halfFloor"：半向下取整，大于增量的一半时向上取整，小于等于增量的一半时向下取整。 "halfExpand"：半远离零取整，大于等于增量的一半时远离零取整，小于增量的一半时向零取整。 "halfTrunc"：半向零取整，大于增量的一半时远离零取整，小于等于增量的一半时向零取整。 "halfEven"：半向偶数取整，大于增量的一半时远离零取整，小于增量的一半时向零取整，等于增量的一半时向最近的偶数位舍入。默认值：halfExpand。原子化服务API：从API version 18开始，该接口支持在原子化服务中使用。

说明：

各属性不同取值代表的含义或呈现效果，请参考数字与度量衡国际化。

Collator⁸⁺

constructor⁸⁺

constructor()

创建排序对象。

原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.Global.I18n

示例：

// 使用系统区域创建Collator对象
let collator = new intl.Collator();

constructor⁸⁺

constructor(locale: string | Array<string>, options?: CollatorOptions)

创建排序对象。

原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.Global.I18n

参数：

参数名	类型	必填	说明
locale	string \| Array<string>	是	区域ID或区域ID数组。输入是区域ID数组时，使用第一个有效的区域ID。
options	CollatorOptions	否	创建排序对象时可设置的配置项。

示例：

// 使用zh-CN区域ID创建Collator对象，localeMatcher设置为lookup，usage设置为sort
let collator = new intl.Collator("zh-CN", {localeMatcher: "lookup", usage: "sort"});

compare⁸⁺

compare(first: string, second: string): number

根据配置项的排序规则，比较两个字符串。

原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.Global.I18n

参数：

参数名	类型	必填	说明
first	string	是	进行比较的第一个字符串。
second	string	是	进行比较的第二个字符串。

返回值：

类型	说明
number	比较结果。 - number为负数时，表示first排序在second之前。 - number为0时，表示first与second排序相同。 - number为正数，表示first排序在second之后。

示例：

// 使用en-GB区域ID创建Collator对象
let collator = new intl.Collator("en-GB");
// 比较first和second的先后顺序
let compareResult = collator.compare("first", "second"); // compareResult = -1

resolvedOptions⁸⁺

resolvedOptions(): CollatorOptions

获取创建排序对象时设置的配置项。

原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.Global.I18n

返回值：

类型	说明
CollatorOptions	返回排序对象的属性。

示例：

let collator = new intl.Collator("zh-Hans", { usage: 'sort', ignorePunctuation: true });
// 获取Collator对象的配置项
let options = collator.resolvedOptions();
let usage = options.usage; // usage = "sort"
let ignorePunctuation = options.ignorePunctuation; // ignorePunctuation = true

CollatorOptions⁸⁺

创建排序对象时可设置的配置项。

从API version 9中，CollatorOptions中的属性改为可选。

原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.Global.I18n

名称	类型	必填	说明
localeMatcher	string	否	区域匹配算法，取值范围："best fit", "lookup"。默认值：best fit。
usage	string	否	比较的用途，取值范围："sort", "search"。默认值：sort。
sensitivity	string	否	表示字符串中的哪些差异会导致非零结果值，取值范围："base", "accent", "case", "letiant"。默认值：variant。
ignorePunctuation	boolean	否	true表示忽略标点符号，false表示考虑标点符号。默认值：false。
collation	string	否	排序规则，取值范围："big5han", "compat", "dict", "direct", "ducet", "eor", "gb2312", "phonebk", "phonetic", "pinyin", "reformed", "searchjl", "stroke", "trad", "unihan", "zhuyin"。默认值：default。
numeric	boolean	否	true表示使用数字排序，false表示不使用数字排序。默认值：false。
caseFirst	string	否	表示大写、小写的排序顺序，取值范围："upper", "lower", "false"。默认值：false。

说明：

CollatorOptions中属性的不同取值代表的含义请参考本地习惯排序。

PluralRules⁸⁺

constructor⁸⁺

constructor()

创建单复数对象来计算数字的单复数类别。

原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.Global.I18n

示例：

// 使用系统区域创建PluralRules对象
let pluralRules = new intl.PluralRules();

constructor⁸⁺

constructor(locale: string | Array<string>, options?: PluralRulesOptions)

创建单复数对象来计算数字的单复数类别。

原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.Global.I18n

参数：

参数名	类型	必填	说明
locale	string \| Array<string>	是	区域ID或区域ID数组。输入是区域ID数组时，使用第一个有效的区域ID。
options	PluralRulesOptions	否	创建单复数对象时设置的配置项。

示例：

// 使用zh-CN区域ID创建PluralRules对象，localeMatcher设置为lookup，type设置为cardinal
let pluralRules= new intl.PluralRules("zh-CN", {"localeMatcher": "lookup", "type": "cardinal"});

select⁸⁺

select(n: number): string

获取数字的单复数类别。

原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.Global.I18n

参数：

参数名	类型	必填	说明
n	number	是	待获取单复数类别的数字。

返回值：

类型	说明
string	单复数类别，取值包括："zero"，"one"，"two", "few", "many", "others"。不同取值的含义请参考语言单复数规则。

示例：

// 使用zh-Hans区域ID创建PluralRules对象
let zhPluralRules = new intl.PluralRules("zh-Hans");
// 计算zh-Hans区域中数字1对应的单复数类别
let plural = zhPluralRules.select(1); // plural = other

// 使用en-US区域ID创建PluralRules对象
let enPluralRules = new intl.PluralRules("en-US");
// 计算en-US区域中数字1对应的单复数类别
plural = enPluralRules.select(1); // plural = one

PluralRulesOptions⁸⁺

创建单复数对象时可设置的配置项。从API version 9开始，PluralRulesOptions的属性由必填改为可选。

原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.Global.I18n

名称	类型	可读	可写	说明
localeMatcher	string	是	是	区域匹配算法，取值包括："best fit", "lookup"。默认值：best fit。
type	string	是	是	排序的类型，取值包括："cardinal", "ordinal", 默认值：cardinal。 - cardinal：基数词，ordinal：序数词。
minimumIntegerDigits	number	是	是	表示要使用的最小整数位数，取值范围：1~21。默认值：1。
minimumFractionDigits	number	是	是	表示要使用的最小分数位数，取值范围：0~20。默认值：0。
maximumFractionDigits	number	是	是	表示要使用的最大分数位数，取值范围：1~21。默认值：3。
minimumSignificantDigits	number	是	是	表示要使用的最小有效位数，取值范围：1~21。默认值：1。
maximumSignificantDigits	number	是	是	表示要使用的最大有效位数，取值范围：1~21。默认值：21。

RelativeTimeFormat⁸⁺

constructor⁸⁺

constructor()

创建相对时间格式化对象。

原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.Global.I18n

示例：

// 使用系统区域创建RelativeTimeFormat对象
let relativetimefmt = new intl.RelativeTimeFormat();

constructor⁸⁺

constructor(locale: string | Array<string>, options?: RelativeTimeFormatInputOptions)

创建相对时间格式化对象。

原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.Global.I18n

参数：

参数名	类型	必填	说明
locale	string \| Array<string>	是	区域ID或区域ID数组。输入是区域ID数组时，使用第一个有效的区域ID。
options	RelativeTimeFormatInputOptions	否	创建相对时间格式化对象时可配置的选项。

示例：

// 使用zh-CN区域ID创建RelativeTimeFormat对象，localeMatcher设置为lookup，numeric设置为always，style设置为long
let relativeTimeFormat = new intl.RelativeTimeFormat("zh-CN", {"localeMatcher": "lookup", "numeric": "always", "style": "long"});

format⁸⁺

format(value: number, unit: string): string

对相对时间进行格式化。

原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.Global.I18n

参数：

参数名	类型	必填	说明
value	number	是	相对时间格式化的数值。
unit	string	是	相对时间格式化的单位，取值包括："year", "quarter", "month", "week", "day", "hour", "minute", "second"。

返回值：

类型	说明
string	格式化后的相对时间。

示例：

// 使用zh-CN区域ID创建RelativeTimeFormat对象
let relativetimefmt = new intl.RelativeTimeFormat("zh-CN");
// 计算zh-CN区域中数字3，单位quarter的本地化表示
let formatResult = relativetimefmt.format(3, "quarter"); // formatResult = "3个季度后"

formatToParts⁸⁺

formatToParts(value: number, unit: string): Array<object>

对相对时间进行格式化，获取格式化结果中各个部分的对象数组。

原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.Global.I18n

参数：

参数名	类型	必填	说明
value	number	是	相对时间格式化的数值。
unit	string	是	相对时间格式化的单位，取值包括："year", "quarter", "month", "week", "day", "hour", "minute", "second"。

返回值：

类型	说明
Array<object>	格式化结果中各个部分的对象数组。

示例：

// 使用en区域ID创建RelativeTimeFormat对象，numeric设置为auto
let relativetimefmt = new intl.RelativeTimeFormat("en", {"numeric": "auto"});
let parts = relativetimefmt.formatToParts(10, "seconds"); // parts = [ {type: "literal", value: "in"}, {type: "integer", value: 10, unit: "second"}, {type: "literal", value: "seconds"} ]

resolvedOptions⁸⁺

resolvedOptions(): RelativeTimeFormatResolvedOptions

获取相对时间格式化对象的格式化配置项。

原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.Global.I18n

返回值：

类型	说明
RelativeTimeFormatResolvedOptions	相对时间格式化对象的格式化配置项。

示例：

// 使用en-GB区域ID创建RelativeTimeFormat对象
let relativetimefmt= new intl.RelativeTimeFormat("en-GB", { style: "short" });
// 获取RelativeTimeFormat对象配置项
let options = relativetimefmt.resolvedOptions();
let style = options.style; // style = "short"

RelativeTimeFormatInputOptions⁸⁺

创建相对时间格式化对象时可设置的配置项。

从API version 9开始，RelativeTimeFormatInputOptions中的属性改为可选。

原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.Global.I18n

名称	类型	必填	说明
localeMatcher	string	否	区域匹配算法，取值包括："best fit", "lookup"。默认值：best fit。
numeric	string	否	输出消息的格式，取值包括："always", "auto"。默认值：always。
style	string	否	国际化消息的长度，取值包括："long", "short", "narrow"。默认值：long。

说明

numeric、style不同取值的显示效果，请参考相对时间格式化选项。

RelativeTimeFormatResolvedOptions⁸⁺

相对时间格式化对象的格式化配置项。

原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.Global.I18n

名称	类型	必填	说明
locale	string	是	表示区域ID的字符串，包括语言以及可选的脚本和区域。
numeric	string	是	输出消息的格式，取值包括："always", "auto"。
style	string	是	国际化消息的长度，取值包括："long", "short", "narrow"。
numberingSystem	string	是	使用的数字系统，取值包括： "adlm", "ahom", "arab", "arabext", "bali", "beng", "bhks", "brah", "cakm", "cham", "deva", "diak", "fullwide", "gong", "gonm", "gujr", "guru", "hanidec", "hmng", "hmnp", "java", "kali", "khmr", "knda", "lana", "lanatham", "laoo", "latn", "lepc", "limb", "mathbold", "mathdbl", "mathmono", "mathsanb", "mathsans", "mlym", "modi", "mong", "mroo", "mtei", "mymr", "mymrshan", "mymrtlng", "newa", "nkoo", "olck", "orya", "osma", "rohg", "saur", "segment", "shrd", "sind", "sinh", "sora", "sund", "takr", "talu", "tamldec", "telu", "thai", "tibt", "tirh", "vaii", "wara", "wcho"。

说明

numeric、style不同参数取值显示的效果，请参考相对时间格式化选项。

@ohos.intl (国际化-Intl)

导入模块

Locale

属性

constructor8+

constructor

toString

maximize

minimize

LocaleOptions

DateTimeFormat

constructor8+

constructor

format

formatRange

resolvedOptions

DateTimeOptions

NumberFormat

constructor8+

constructor

format

formatRange18+

resolvedOptions

NumberOptions

Collator8+

constructor8+

constructor8+

compare8+

resolvedOptions8+

CollatorOptions8+

PluralRules8+

constructor8+

constructor8+

select8+

PluralRulesOptions8+

RelativeTimeFormat8+

constructor8+

constructor8+

format8+

formatToParts8+

resolvedOptions8+

RelativeTimeFormatInputOptions8+

RelativeTimeFormatResolvedOptions8+

constructor⁸⁺

constructor⁸⁺

constructor⁸⁺

formatRange¹⁸⁺

Collator⁸⁺

constructor⁸⁺

constructor⁸⁺

compare⁸⁺

resolvedOptions⁸⁺

CollatorOptions⁸⁺

PluralRules⁸⁺

constructor⁸⁺

constructor⁸⁺

select⁸⁺

PluralRulesOptions⁸⁺

RelativeTimeFormat⁸⁺

constructor⁸⁺

constructor⁸⁺

format⁸⁺

formatToParts⁸⁺

resolvedOptions⁸⁺

RelativeTimeFormatInputOptions⁸⁺

RelativeTimeFormatResolvedOptions⁸⁺