@ohos.intl (国际化-Intl)

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

说明：

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

• Intl模块包含国际化能力基础接口（在ECMA 402中定义），包括时间日期格式化、数字格式化、排序等，国际化增强能力请参考I18N模块。

导入模块

import Intl from '@ohos.intl';

未正确导入包可能产生不明确的接口行为。

Locale

属性

系统能力：SystemCapability.Global.I18n

constructor⁸⁺

constructor()

创建区域对象

系统能力：SystemCapability.Global.I18n

示例：

// 默认构造函数使用系统当前locale创建Locale对象
let locale = new Intl.Locale();
// 返回系统当前localel
let localeID = locale.toString();

constructor

constructor(locale: string, options?: LocaleOptions)

创建区域对象

系统能力：SystemCapability.Global.I18n

参数：

示例：

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

toString

toString(): string

获取区域对象的字符串表示

系统能力：SystemCapability.Global.I18n

返回值：

示例：

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

maximize

maximize(): Locale

最大化区域信息，若缺少脚本与地区信息，则补齐。

系统能力：SystemCapability.Global.I18n

返回值：

示例：

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

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

minimize

minimize(): Locale

最小化区域信息，若包含脚本与地区信息，则去除。

系统能力：SystemCapability.Global.I18n

返回值：

示例：

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

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

LocaleOptions⁹⁺

表示区域初始化选项。

系统能力：SystemCapability.Global.I18n

DateTimeFormat

constructor⁸⁺

constructor()

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

系统能力：SystemCapability.Global.I18n

示例：

// 使用系统当前locale创建DateTimeFormat对象
let datefmt= new Intl.DateTimeFormat();

constructor

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

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

系统能力：SystemCapability.Global.I18n

参数：

示例：

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

示例：

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

format

format(date: Date): string

格式化时间日期字符串。

系统能力：SystemCapability.Global.I18n

参数：

返回值：

示例：

let date = new Date(2021, 11, 17, 3, 24, 0);
// 使用 en-GB locale创建DateTimeFormat对象
let datefmt = new Intl.DateTimeFormat("en-GB");
let formattedDate = datefmt.format(date); // formattedDate "17/12/2021"

// 使用 en-GB locale创建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

格式化时间日期段字符串。

系统能力：SystemCapability.Global.I18n

参数：

返回值：

示例：

let startDate = new Date(2021, 11, 17, 3, 24, 0);
let endDate = new Date(2021, 11, 18, 3, 24, 0);
// 使用 en-GB locale创建DateTimeFormat对象
let datefmt = new Intl.DateTimeFormat("en-GB");
let formattedDateRange = datefmt.formatRange(startDate, endDate); // formattedDateRange = "17/12/2021-18/12/2021"

resolvedOptions

resolvedOptions(): DateTimeOptions

获取DateTimeFormat对象的格式化选项。

系统能力：SystemCapability.Global.I18n

返回值：

示例：

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⁹⁺

表示时间日期格式化选项。

系统能力：SystemCapability.Global.I18n

NumberFormat

constructor⁸⁺

constructor()

创建数字格式化对象。

系统能力：SystemCapability.Global.I18n

示例：

// 使用系统当前locale创建NumberFormat对象
let numfmt = new Intl.NumberFormat();

constructor

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

创建数字格式化对象。

系统能力：SystemCapability.Global.I18n

参数：

示例：

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

format

format(number: number): string;

格式化数字字符串。

系统能力：SystemCapability.Global.I18n

参数：

返回值：

示例：

// 使用 ["en-GB", "zh"] locale列表创建NumberFormat对象，因为en-GB为合法LocaleID，因此使用en-GB创建NumberFormat对象
let numfmt = new Intl.NumberFormat(["en-GB", "zh"], {style:'decimal', notation:"scientific"});
let formattedNumber = numfmt.format(1223); // formattedNumber = 1.223E3

resolvedOptions

resolvedOptions(): NumberOptions

获取NumberFormat 对象的格式化选项。

系统能力：SystemCapability.Global.I18n

返回值：

示例：

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⁹⁺

表示设备支持的能力。

系统能力：SystemCapability.Global.I18n

Collator⁸⁺

constructor⁸⁺

constructor()

创建排序对象。

系统能力：SystemCapability.Global.I18n

示例：

// 使用系统locale创建Collator对象
let collator = new Intl.Collator();

constructor⁸⁺

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

创建排序对象。

系统能力：SystemCapability.Global.I18n

参数：

示例：

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

compare⁸⁺

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

依据Collator的排序策略对两个字符串进行比较。

系统能力：SystemCapability.Global.I18n

参数：

返回值：

示例：

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

resolvedOptions⁸⁺

resolvedOptions(): CollatorOptions

返回Collator对象的属性。

系统能力：SystemCapability.Global.I18n

返回值：

示例：

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⁹⁺

表示Collator可设置的属性。

系统能力：SystemCapability.Global.I18n

PluralRules⁸⁺

constructor⁸⁺

constructor()

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

系统能力：SystemCapability.Global.I18n

示例：

// 使用系统locale创建PluralRules对象
let pluralRules = new Intl.PluralRules();

constructor⁸⁺

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

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

系统能力：SystemCapability.Global.I18n

参数：

示例：

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

select⁸⁺

select(n: number): string

返回一个字符串表示该数字的单复数类别。

系统能力：SystemCapability.Global.I18n

参数：

返回值：

示例：

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

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

PluralRulesOptions⁹⁺

表示PluralRules对象可设置的属性。

系统能力：SystemCapability.Global.I18n

RelativeTimeFormat⁸⁺

constructor⁸⁺

constructor()

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

系统能力：SystemCapability.Global.I18n

示例：

// 使用系统locale创建RelativeTimeFormat对象
let relativetimefmt = new Intl.RelativeTimeFormat();

constructor⁸⁺

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

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

系统能力：SystemCapability.Global.I18n

参数：

示例：

// 使用 zh-CN locale创建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

依据locale和格式化选项，对value和unit进行格式化。

系统能力：SystemCapability.Global.I18n

参数：

返回值：

示例：

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

formatToParts⁸⁺

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

返回一个对象数组，表示可用于自定义区域设置格式的相对时间格式。

系统能力：SystemCapability.Global.I18n

参数：

返回值：

示例：

// 使用 en locale创建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

获取RelativeTimeFormat对象的格式化选项。

系统能力：SystemCapability.Global.I18n

返回值：

示例：

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

RelativeTimeFormatInputOptions⁹⁺

表示RelativeTimeFormat对象可设置的属性。

系统能力：SystemCapability.Global.I18n

RelativeTimeFormatResolvedOptions⁸⁺

表示RelativeTimeFormat对象可设置的属性。

系统能力：SystemCapability.Global.I18n