# 国际化-Intl
> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明:**
> - 本模块首批接口从API version 6开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。
>
> - Intl模块包含国际化能力基础接口(在ECMA 402中定义)。
## 导入模块
```
import Intl from '@ohos.intl';
```
## Locale
### 属性
**系统能力**:以下各项对应的系统能力均为SystemCapability.Global.I18n
| 名称 | 参数类型 | 可读 | 可写 | 说明 |
| --------------- | ------- | ---- | ---- | ---------------------------------------- |
| language | string | 是 | 否 | 与区域设置关联的语, 如:zh。 |
| script | string | 是 | 否 | 语言的书写方式,如:Hans。 |
| region | string | 是 | 否 | 与区域设置相关的地区,如:CN。 |
| baseName | string | 是 | 否 | Locale的基本核心信息(由语言脚本与地区组成),如:zh-Hans-CN。 |
| caseFirst | string | 是 | 否 | 区域的整理规则是否考虑大小写,取值包括:"upper", "lower", "false"。 |
| 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", "eor", "gb2312", "phonebk", "phonetic", "pinyin", "reformed", "searchjl", "stroke", "trad", "unihan", "zhuyin"。 |
| hourCycle | string | 是 | 否 | 区域的时制信息,取值包括:"h12", "h23", "h11", "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 | 是 | 否 | 是否对数字字符具有特殊的排序规则处理。 |
### constructor8+
constructor()
创建区域对象
**系统能力**:SystemCapability.Global.I18n
**示例:**
```
var locale = new Intl.Locale();
```
### constructor
constructor(locale: string, options?: LocaleOptions)
创建区域对象
**系统能力**:SystemCapability.Global.I18n
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| ------- | ------------- | ---- | ---------------------------- |
| locale | string | 是 | 包含区域设置信息的字符串,包括语言以及可选的脚本和区域。 |
| options | LocaleOptions | 否 | 用于创建区域对象的选项。 |
**示例:**
```
var locale = new Intl.Locale("zh-CN");
```
### toString
toString(): string
将区域信息转换为字符串
**系统能力**:SystemCapability.Global.I18n
**返回值:**
| 类型 | 说明 |
| ------ | ----------- |
| string | 字符串形式的区域信息。 |
**示例:**
```
var locale = new Intl.Locale("zh-CN");
locale.toString();
```
### maximize
maximize(): Locale
最大化区域信息,若缺少脚本与地区信息,则补齐。
**系统能力**:SystemCapability.Global.I18n
**返回值:**
| 类型 | 说明 |
| ----------------- | ---------- |
| [Locale](#locale) | 最大化后的区域对象。 |
**示例:**
```
var locale = new Intl.Locale("zh-CN");
locale.maximize();
```
### minimize
minimize(): Locale
最小化区域信息,若包含脚本与地区信息,则去除。
**系统能力**:SystemCapability.Global.I18n
**返回值:**
| 类型 | 说明 |
| ----------------- | ---------- |
| [Locale](#locale) | 最小化后的区域对象。 |
**示例:**
```
var locale = new Intl.Locale("zh-CN");
locale.minimize();
```
## LocaleOptions
表示区域初始化选项。
**系统能力**:以下各项对应的系统能力均为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 | 是 | 是 | 是否使用12小时制。 |
| caseFirst | string | 是 | 是 | 表示大写、小写的排序顺序,取值范围:"upper", "lower", "false"。 |
## DateTimeFormat
### constructor8+
constructor()
创建时间日期格式化对象。
**系统能力**:SystemCapability.Global.I18n
**示例:**
```
var datefmt= new Intl.DateTimeFormat();
```
### constructor
constructor(locale: string | Array<string>, options?: DateTimeOptions)
创建时间日期格式化对象。
**系统能力**:SystemCapability.Global.I18n
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| ------- | ----------------------------------- | ---- | ---------------------------- |
| locale | string \| Array<string> | 是 | 包含区域设置信息的字符串,包括语言以及可选的脚本和区域。 |
| options | [DateTimeOptions](#datetimeoptions) | 否 | 用于创建时间日期格式化的选项。 |
**示例:**
```
var datefmt= new Intl.DateTimeFormat("zh-CN", { dateStyle: 'full', timeStyle: 'medium' });
```
**示例:**
```
var datefmt= new Intl.DateTimeFormat(["ban", "zh"], { dateStyle: 'full', timeStyle: 'medium' });
```
### format
format(date: Date): string
格式化时间日期字符串。
**系统能力**:SystemCapability.Global.I18n
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| ---- | ---- | ---- | ------- |
| date | Date | 是 | 时间日期对象。 |
**返回值:**
| 类型 | 说明 |
| ------ | ------------ |
| string | 格式化后的时间日期字符串 |
**示例:**
```
var date = new Date(2021, 11, 17, 3, 24, 0);
var datefmt = new Intl.DateTimeFormat("en-GB");
datefmt.format(date);
```
### formatRange
formatRange(startDate: Date, endDate: Date): string
格式化时间日期段字符串。
**系统能力**:SystemCapability.Global.I18n
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| --------- | ---- | ---- | -------- |
| startDate | Date | 是 | 起始的时间日期。 |
| endDate | Date | 是 | 结束的时间日期。 |
**返回值:**
| 类型 | 说明 |
| ------ | -------------- |
| string | 格式化后的时间日期段字符串。 |
**示例:**
```
var startDate = new Date(2021, 11, 17, 3, 24, 0);
var endDate = new Date(2021, 11, 18, 3, 24, 0);
var datefmt = new Intl.DateTimeFormat("en-GB");
datefmt.formatRange(startDate, endDate);
```
### resolvedOptions
resolvedOptions(): DateTimeOptions
获取DateTimeFormat对象的格式化选项。
**系统能力**:SystemCapability.Global.I18n
**返回值:**
| 类型 | 说明 |
| ----------------------------------- | ----------------------------- |
| [DateTimeOptions](#datetimeoptions) | DateTimeFormat 对象的格式化选项。 |
**示例:**
```
var datefmt = new Intl.DateTimeFormat("en-GB");
datefmt.resolvedOptions();
```
## DateTimeOptions
表示时间日期格式化选项。
**系统能力**:以下各项对应的系统能力均为SystemCapability.Global.I18n
| 名称 | 参数类型 | 可读 | 可写 | 说明 |
| --------------- | ------- | ---- | ---- | ---------------------------------------- |
| locale | string | 是 | 否 | 区域参数, 如:zh-Hans-CN。 |
| dateStyle | string | 是 | 是 | 日期显示格式,取值包括:"long", "short", "medium", "full"。 |
| timeStyle | string | 是 | 是 | 时间显示格式,取值包括:"long", "short", "medium", "full"。 |
| hourCycle | string | 是 | 是 | 时制格式,取值包括:"h11", "h12", "h23", "h24"。 |
| 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 | 是 | 是 | 是否使用12小时制。 |
| weekday | string | 是 | 是 | 工作日的显示格式,取值包括:"long", "short", "narrow"。 |
| era | string | 是 | 是 | 时代的显示格式,取值包括:"long", "short", "narrow"。 |
| year | string | 是 | 是 | 年份的显示格式,取值包括:"numeric", "2-digit"。 |
| month | string | 是 | 是 | 月份的显示格式,取值包括:"numeric", "2-digit", "long", "short", "narrow"。 |
| day | string | 是 | 是 | 日期的显示格式,取值包括:"numeric", "2-digit"。 |
| hour | string | 是 | 是 | 小时的显示格式,取值包括:"numeric", "2-digit"。 |
| minute | string | 是 | 是 | 分钟的显示格式,取值包括:"numeric", "2-digit"。 |
| second | string | 是 | 是 | 秒钟的显示格式,取值包括:"numeric", "2-digit"。 |
| timeZoneName | string | 是 | 是 | 时区名称的本地化表示。 |
| dayPeriod | string | 是 | 是 | 时段的显示格式,取值包括:"long", "short", "narrow"。 |
| localeMatcher | string | 是 | 是 | 要使用的区域匹配算法,取值包括:"lookup", "best fit"。 |
| formatMatcher | string | 是 | 是 | 要使用的格式匹配算法,取值包括:"basic", "best fit"。 |
## NumberFormat
### constructor8+
constructor()
创建数字格式化对象。
**系统能力**:SystemCapability.Global.I18n
**示例:**
```
var numfmt = new Intl.NumberFormat();
```
### constructor
constructor(locale: string | Array<string>, options?: NumberOptions)
创建数字格式化对象。
**系统能力**:SystemCapability.Global.I18n
参数:
| 参数名 | 类型 | 必填 | 说明 |
| ------- | ------------------------------- | ---- | ---------------------------- |
| locale | string \| Array<string> | 是 | 包含区域设置信息的字符串,包括语言以及可选的脚本和区域。 |
| options | [NumberOptions](#numberoptions) | 否 | 用于创建数字格式化的选项。 |
**示例:**
```
var numfmt = new Intl.NumberFormat("en-GB", {style:'decimal', notation:"scientific"});
```
### format
format(number: number): string;
格式化数字字符串。
**系统能力**:SystemCapability.Global.I18n
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | ---- |
| number | number | 是 | 数字对象 |
**返回值:**
| 类型 | 说明 |
| ------ | ---------- |
| string | 格式化后的数字字符串 |
**示例:**
```
var numfmt = new Intl.NumberFormat(["en-GB", "zh"], {style:'decimal', notation:"scientific"});
numfmt.format(1223);
```
### resolvedOptions
resolvedOptions(): NumberOptions
获取NumberFormat 对象的格式化选项。
**系统能力**:SystemCapability.Global.I18n
**返回值:**
| 类型 | 说明 |
| ------------------------------- | --------------------------- |
| [NumberOptions](#numberoptions) | NumberFormat 对象的格式化选项。 |
**示例:**
```
var numfmt = new Intl.NumberFormat(["en-GB", "zh"], {style:'decimal', notation:"scientific"});
numfmt.resolvedOptions();
```
## NumberOptions
表示设备支持的能力。
**系统能力**:以下各项对应的系统能力均为SystemCapability.Global.I18n
| 名称 | 参数类型 | 可读 | 可写 | 说明 |
| ------------------------ | ------- | ---- | ---- | ---------------------------------------- |
| locale | string | 是 | 否 | 区域参数, 如:"zh-Hans-CN"。 |
| currency | string | 是 | 是 | 货币单位, 如:"EUR","CNY","USD"等。 |
| currencySign | string | 是 | 是 | 货币单位的符号显示,取值包括: "symbol","narrowSymbol","code","name" 。 |
| currencyDisplay | string | 是 | 是 | 货币的显示方式,取值包括:"symbol", "narrowSymbol", "code", "name"。 |
| unit | string | 是 | 是 | 单位名称,如:"meter","inch",“hectare”等。 |
| unitDisplay | string | 是 | 是 | 单位的显示格式,取值包括:"long", "short", "medium"。 |
| 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"。 |
| signDisplay | string | 是 | 是 | 数字符号的显示格式,取值包括:"auto", "never", "always", "expectZero"。 |
| compactDisplay | string | 是 | 是 | 紧凑型的显示格式,取值包括:"long", "short"。 |
| notation | string | 是 | 是 | 数字的格式化规格,取值包括:"standard", "scientific", "engineering", "compact"。 |
| localeMatcher | string | 是 | 是 | 要使用的区域匹配算法,取值包括:"lookup", "best fit"。 |
| style | string | 是 | 是 | 数字的显示格式,取值包括:"decimal", "currency", "percent", "unit"。 |
| 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"。 |
| useGrouping | boolean | 是 | 是 | 是否分组显示。 |
| minimumIntegerDigits | number | 是 | 是 | 表示要使用的最小整数位数,取值范围:1~21。 |
| minimumFractionDigits | number | 是 | 是 | 表示要使用的最小分数位数,取值范围:0~20。 |
| maximumFractionDigits | number | 是 | 是 | 表示要使用的最大分数位数,取值范围:1~21。 |
| minimumSignificantDigits | number | 是 | 是 | 表示要使用的最低有效位数,取值范围:1~21。 |
| maximumSignificantDigits | number | 是 | 是 | 表示要使用的最大有效位数,取值范围:1~21。 |
## Collator8+
### constructor8+
constructor()
创建排序对象。
**系统能力**:SystemCapability.Global.I18n
**示例:**
```
var collator = new Intl.Collator();
```
### constructor8+
constructor(locale: string | Array<string>, options?: CollatorOptions)
创建排序对象。
**系统能力**:SystemCapability.Global.I18n
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| ------- | ----------------------------------- | ---- | ---------------------------- |
| locale | string \| Array<string> | 是 | 包含区域设置信息的字符串,包括语言以及可选的脚本和区域。 |
| options | [CollatorOptions](#collatoroptions) | 否 | 用于创建排序对象的选项。 |
**示例:**
```
var collator = new Intl.Collator("zh-CN", {localeMatcher: "lookup", usage: "sort"});
```
### compare8+
compare(first: string, second: string): number
依据Collator的排序策略对两个字符串进行比较。
**系统能力**:SystemCapability.Global.I18n
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | ------------ |
| first | string | 是 | 进行比较第一个字符串。 |
| second | string | 是 | 进行比较的第二个字符串。 |
**返回值:**
| 类型 | 说明 |
| ------ | ---------------------------------------- |
| number | 比较结果。当number为负数,表示first排序在second之前;当number为0,表示first与second排序相同;当number为正数,表示first排序在second之后。 |
**示例:**
```
var collator = new Intl.Collator("zh-Hans");
collator.compare("first", "second");
```
### resolvedOptions8+
resolvedOptions(): CollatorOptions
返回Collator对象的属性。
**系统能力**:SystemCapability.Global.I18n
**返回值:**
| 类型 | 说明 |
| ----------------------------------- | ----------------- |
| [CollatorOptions](#collatoroptions) | 返回的Collator对象的属性。 |
**示例:**
```
var collator = new Intl.Collator("zh-Hans");
var options = collator.resolvedOptions();
```
## CollatorOptions8+
表示Collator可设置的属性。
**系统能力**:以下各项对应的系统能力均为SystemCapability.Global.I18n
| 名称 | 参数类型 | 可读 | 可写 | 说明 |
| ----------------- | ------- | ---- | ---- | ---------------------------------------- |
| localeMatcher | string | 是 | 是 | locale匹配算法,取值范围:"best fit", "lookup"。 |
| usage | string | 是 | 是 | 比较的用途,取值范围:"sort", "search"。 |
| sensitivity | string | 是 | 是 | 表示字符串中的哪些差异会导致非零结果值,取值范围:"base", "accent", "case", "variant"。 |
| ignorePunctuation | boolean | 是 | 是 | 表示是否忽略标点符号,取值范围:true, false。 |
| collation | string | 是 | 是 | 排序规则,取值范围:"big5han", "compat", "dict", "direct", "ducet", "eor", "gb2312", "phonebk", "phonetic", "pinyin", "reformed", "searchjl", "stroke", "trad", "unihan", "zhuyin"。 |
| numeric | boolean | 是 | 是 | 是否使用数字排序,取值范围:true, false。 |
| caseFirst | string | 是 | 是 | 表示大写、小写的排序顺序,取值范围:"upper", "lower", "false"。 |
## PluralRules8+
### constructor8+
constructor()
创建PluralRules对象。
**系统能力**:SystemCapability.Global.I18n
**示例:**
```
var pluralRules = new Intl.PluralRules();
```
### constructor8+
constructor(locale: string | Array<string>, options?: PluralRulesOptions)
创建PluralRules对象。
**系统能力**:SystemCapability.Global.I18n
参数:
| 参数名 | 类型 | 必填 | 说明 |
| ------- | ---------------------------------------- | ---- | ---------------------------- |
| locale | string \| Array<string> | 是 | 包含区域设置信息的字符串,包括语言以及可选的脚本和区域。 |
| options | [PluralRulesOptions](#pluralrulesoptions) | 否 | 用于创建单复数对象的选项。 |
**示例:**
```
var pluralRules= new Intl.PluraRules("zh-CN", {"localeMatcher": "lookup", "type": "cardinal"});
```
### select8+
select(n: number): string
返回一个字符串表示该数字的单复数类别。
**系统能力**:SystemCapability.Global.I18n
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| ---- | ------ | ---- | ------------ |
| n | number | 是 | 待获取单复数类别的数字。 |
**返回值:**
| 类型 | 说明 |
| ------ | ---------------------------------------- |
| string | 单复数类别,取值包括:"zero","one","two", "few", "many", "others"。 |
**示例:**
```
var pluralRules = new Intl.PluralRules("zh-Hans");
pluralRules.select(1);
```
## PluralRulesOptions8+
表示PluralRules对象可设置的属性。
**系统能力**:以下各项对应的系统能力均为SystemCapability.Global.I18n
| 名称 | 参数类型 | 可读 | 可写 | 说明 |
| ------------------------ | ------ | ---- | ---- | ---------------------------------------- |
| localeMatcher | string | 是 | 是 | locale匹配算法,取值包括:"best fit", "lookup"。 |
| type | string | 是 | 是 | 排序的类型,取值包括:"cardinal", "ordinal"。 |
| minimumIntegerDigits | number | 是 | 是 | 表示要使用的最小整数位数,取值范围:1~21。 |
| minimumFractionDigits | number | 是 | 是 | 表示要使用的最小分数位数,取值范围:0~20。 |
| maximumFractionDigits | number | 是 | 是 | 表示要使用的最大分数位数,取值范围:1~21。 |
| minimumSignificantDigits | number | 是 | 是 | 表示要使用的最低有效位数,取值范围:1~21。 |
| maximumSignificantDigits | number | 是 | 是 | 表示要使用的最大有效位数,取值范围:1~21。 |
## RelativeTimeFormat8+
### constructor8+
constructor()
创建相对时间格式化对象。
**系统能力**:SystemCapability.Global.I18n
**示例:**
```
var relativetimefmt = new Intl.RelativeTimeFormat();
```
### constructor8+
constructor(locale: string | Array<string>, options?: RelativeTimeFormatInputOptions)
创建相对时间格式化对象。
**系统能力**:SystemCapability.Global.I18n
参数:
| 参数名 | 类型 | 必填 | 说明 |
| ------- | ---------------------------------------- | ---- | ---------------------------- |
| locale | string \| Array<string> | 是 | 包含区域设置信息的字符串,包括语言以及可选的脚本和区域。 |
| options | [RelativeTimeFormatInputOptions](#relativetimeformatinputoptions) | 否 | 用于创建相对时间格式化对象的选项。 |
**示例:**
```
var relativeTimeFormat = new Intl.RelativeTimeFormat("zh-CN", {"localeMatcher": "lookup", "numeric": "always", "style": "long"});
```
### format8+
format(value: number, unit: string): string
依据locale和格式化选项,对value和unit进行格式化。
**系统能力**:SystemCapability.Global.I18n
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| ----- | ------ | ---- | ---------------------------------------- |
| value | number | 是 | 相对时间格式化的数值。 |
| unit | string | 是 | 相对时间格式化的单位,取值包括:"year", "quarter", "month", "week", "day", "hour", "minute", "second"。 |
**返回值:**
| 类型 | 说明 |
| ------ | ---------- |
| string | 格式化后的相对时间。 |
**示例:**
```
var relativetimefmt = new Intl.RelativeTimeFormat("zh-CN");
relativetimefmt.format(3, "quarter")
```
### formatToParts8+
formatToParts(value: number, unit: string): Array<object>
返回一个对象数组,表示可用于自定义区域设置格式的相对时间格式。
**系统能力**:SystemCapability.Global.I18n
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| ----- | ------ | ---- | ---------------------------------------- |
| value | number | 是 | 相对时间格式化的数值。 |
| unit | string | 是 | 相对时间格式化的单位,取值包括:"year", "quarter", "month", "week", "day", "hour", "minute", "second"。 |
**返回值:**
| 类型 | 说明 |
| ------------------- | --------------------------- |
| Array<object> | 返回可用于自定义区域设置格式的相对时间格式的对象数组。 |
**示例:**
```
var relativetimefmt = new Intl.RelativeTimeFormat("en", {"numeric": "auto"});
var parts = relativetimefmt.format(10, "seconds");
```
### resolvedOptions8+
resolvedOptions(): RelativeTimeFormatResolvedOptions
获取RelativeTimeFormat对象的格式化选项。
**系统能力**:SystemCapability.Global.I18n
**返回值:**
| 类型 | 说明 |
| ---------------------------------------- | --------------------------------- |
| [RelativeTimeFormatResolvedOptions](#relativetimeformatresolvedoptions) | RelativeTimeFormat 对象的格式化选项。 |
**示例:**
```
var relativetimefmt= new Intl.RelativeTimeFormat("en-GB");
relativetimefmt.resolvedOptions();
```
## RelativeTimeFormatInputOptions8+
表示RelativeTimeFormat对象可设置的属性。
**系统能力**:以下各项对应的系统能力均为SystemCapability.Global.I18n
| 名称 | 参数类型 | 可读 | 可写 | 说明 |
| ------------- | ------ | ---- | ---- | ---------------------------------------- |
| localeMatcher | string | 是 | 是 | locale匹配算法,取值包括:"best fit", "lookup"。 |
| numeric | string | 是 | 是 | 输出消息的格式,取值包括:"always", "auto"。 |
| style | string | 是 | 是 | 国际化消息的长度,取值包括:"long", "short", "narrow"。 |
## RelativeTimeFormatResolvedOptions8+
表示RelativeTimeFormat对象可设置的属性。
**系统能力**:以下各项对应的系统能力均为SystemCapability.Global.I18n
| 名称 | 参数类型 | 可读 | 可写 | 说明 |
| --------------- | ------ | ---- | ---- | ---------------------------------------- |
| locale | string | 是 | 是 | 包含区域设置信息的字符串,包括语言以及可选的脚本和区域。 |
| numeric | string | 是 | 是 | 输出消息的格式,取值包括:"always", "auto"。 |
| style | string | 是 | 是 | 国际化消息的长度,取值包括:"long", "short", "narrow"。 |
| numberingSystem | string | 是 | 是 | 使用的数字系统。 |