# 国际化-Intl > ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** > - 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 > > - Intl模块包含国际化能力基础接口（在ECMA 402中定义）。 ## 导入模块 ``` import Intl from '@ohos.intl'; ``` ## 权限列表 无 ## Locale ### 属性 | 名称 | 参数类型 | 可读 | 可写 | 说明 | | -------- | -------- | -------- | -------- | -------- | | 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 | 是 | 否 | 是否对数字字符具有特殊的排序规则处理。 | ### constructor constructor(locale: string, options?: options) 创建区域对象 - 参数： | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | | locale | string | 是 | 包含区域设置信息的字符串，包括语言以及可选的脚本和区域。 | | options | options | 否 | 用于创建区域对象的选项。 | - 示例： ``` var locale = new Intl.Locale("zh-CN"); ``` ### toString toString(): string 将区域信息转换为字符串 - 返回值： | 类型 | 说明 | | -------- | -------- | | string | 字符串形式的区域信息。 | - 示例： ``` var locale = new Intl.Locale("zh-CN"); locale.toString(); ``` ### maximize maximize(): Locale 最大化区域信息，若缺少脚本与地区信息，则补齐。 - 返回值： | 类型 | 说明 | | -------- | -------- | | [Locale](#locale) | 最大化后的区域对象。 | - 示例： ``` var locale = new Intl.Locale("zh-CN"); locale.maximize(); ``` ### minimize minimize(): Locale 最小化区域信息，若包含脚本与地区信息，则去除。 - 返回值： | 类型 | 说明 | | -------- | -------- | | [Locale](#locale) | 最小化后的区域对象。 | - 示例： ``` var locale = new Intl.Locale("zh-CN"); locale.minimize(); ``` ## DateTimeFormat ### constructor constructor(locale: string, options?: DateTimeOptions) 创建时间日期格式化对象。 - 参数： | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | | locale | string | 是 | 包含区域设置信息的字符串，包括语言以及可选的脚本和区域。 | | options | [DateTimeOptions](#datetimeoptions) | 否 | 用于创建时间日期格式化的选项。 | - 示例： ``` var datefmt= new Intl.DateTimeFormat("zh-CN", { dateStyle: 'full', timeStyle: 'medium' }); ``` ### constructor constructor(locales: Array<string>, options?: DateTimeOptions) 创建时间日期格式化对象。 - 参数： | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | | locales | Array<string> | 是 | 包含区域设置信息的字符串的数组。 | | options | [DateTimeOptions](#datetimeoptions) | 否 | 用于创建时间日期格式化的选项。 | - 示例： ``` var datefmt= new Intl.DateTimeFormat(["ban", "zh"], { dateStyle: 'full', timeStyle: 'medium' }); ``` ### format format(date: Date): string 格式化时间日期字符串。 - 参数： | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | | 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(fromDate: Date, toDate: Date): string 格式化时间日期段字符串。 - 参数： | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | | 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对象的格式化选项。 - 返回值： | 类型 | 说明 | | -------- | -------- | | [DateTimeOptions](#datetimeoptions) | DateTimeFormat 对象的格式化选项。 | - 示例： ``` var datefmt = new Intl.DateTimeFormat("en-GB"); datefmt.resolvedOptions(); ``` ## DateTimeOptions 表示时间日期格式化选项。 | 名称 | 参数类型 | 可读 | 可写 | 说明 | | -------- | -------- | -------- | -------- | -------- | | 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 ### constructor constructor(locale: string, options?: NumberOptions) 创建数字格式化对象。 参数： | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | | locale | string | 是 | 包含区域设置信息的字符串，包括语言以及可选的脚本和区域。 | | options | [NumberOptions](#numberoptions) | 否 | 用于创建数字格式化的选项。 | - 示例： ``` var numfmt = new Intl.NumberFormat("en-GB", {style:'decimal', notation:"scientific"}); ``` ### constructor constructor(locales: Array<string>, options?: NumberOptions) 创建数字格式化对象。 - 参数： | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | | locales | Array<string> | 是 | 包含区域设置信息的字符串的数组。 | | options | [NumberOptions](#numberoptions) | 否 | 用于创建数字格式化的选项。 | - 示例： ``` var numfmt = new Intl.NumberFormat(["en-GB", "zh"], {style:'decimal', notation:"scientific"}); ``` ### format format(number: number): string; 格式化数字字符串。 - 参数： | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | | number | number | 是 | 数字对象 | - 返回值： | 类型 | 说明 | | -------- | -------- | | string | 格式化后的数字字符串 | - 示例： ``` var numfmt = new Intl.NumberFormat(["en-GB", "zh"], {style:'decimal', notation:"scientific"}); numfmt.format(1223); ``` ### resolvedOptions resolvedOptions(): NumberOptions 获取NumberFormat 对象的格式化选项。 - 返回值： | 类型 | 说明 | | -------- | -------- | | [NumberOptions](#numberoptions) | NumberFormat 对象的格式化选项。 | - 示例： ``` var numfmt = new Intl.NumberFormat(["en-GB", "zh"], {style:'decimal', notation:"scientific"}); numfmt.resolvedOptions(); ``` ## NumberOptions 表示设备支持的能力。 | 名称 | 参数类型 | 可读 | 可写 | 说明 | | -------- | -------- | -------- | -------- | -------- | | 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 | 是 | 是 | 是否分组显示。 | | miniumumIntegerDigits | number | 是 | 是 | 表示要使用的最小整数位数，取值范围：1~21。 | | miniumumFractionDigits | number | 是 | 是 | 表示要使用的最小分数位数，取值范围：0~20。 | | maxiumumFractionDigits | number | 是 | 是 | 表示要使用的最大分数位数，取值范围：1~21。 | | miniumumSignificantDigits | number | 是 | 是 | 表示要使用的最低有效位数，取值范围：1~21。 | | maxiumumSignificantDigits | number | 是 | 是 | 表示要使用的最大有效位数，取值范围：1~21。 | ## Collator8+ ### constructor8+ constructor() 创建排序对象。 - 示例： ``` var collator = new Intl.Collator(); ``` ### constructor8+ constructor(locale: string | Array<string>, options?: CollatorOptions) 创建排序对象。 - 参数： | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | | 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的排序策略对两个字符串进行比较。 - 参数： | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | | 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对象的属性。 - 返回值： | 类型 | 说明 | | -------- | -------- | | [CollatorOptions](#collatoroptions) | 返回的Collator对象的属性。 | - 示例： ``` var collator = new Intl.Collator("zh-Hans"); var options = collator.resolvedOptions(); ``` ## CollatorOptions8+ 表示Collator可设置的属性。 | 名称 | 参数类型 | 可读 | 可写 | 说明 | | -------- | -------- | -------- | -------- | -------- | | 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对象。 - 示例： ``` var pluralRules = new Intl.PluralRules(); ``` ### constructor8+ constructor(locale: string | Array<string>, options?: PluralRulesOptions) 创建PluralRules对象。 参数： | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | | locale | string\|Array<string> | 是 | 包含区域设置信息的字符串，包括语言以及可选的脚本和区域。 | | options | [PluralRulesOptions](#pluralrulesoptions) | 否 | 用于创建单复数对象的选项。 | - 示例： ``` var pluralRules= new Intl.PluraRules("zh-CN", {"localeMatcher": "lookup", "type": "cardinal"}); ``` ### select8+ select(n: number): string 返回一个字符串表示该数字的单复数类别。 - 参数： | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | | n | number | 是 | 待获取单复数类别的数字。 | - 返回值： | 类型 | 说明 | | -------- | -------- | | string | 单复数类别，取值包括："zero"，"one"，"two", "few", "many", "others"。 | - 示例： ``` var pluralRules = new Intl.PluralRules("zh-Hans"); pluralRules.select(1); ``` ## PluralRulesOptions8+ 表示PluralRules对象可设置的属性。 | 名称 | 参数类型 | 可读 | 可写 | 说明 | | -------- | -------- | -------- | -------- | -------- | | 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() 创建相对时间格式化对象。 - 示例： ``` var relativetimefmt = new Intl.RelativeTimeFormat(); ``` ### constructor8+ constructor(locale: string | Array<string>, options?: RelativeTimeFormatInputOptions) 创建相对时间格式化对象。 参数： | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | | locale | string\|Array<string> | 是 | 包含区域设置信息的字符串，包括语言以及可选的脚本和区域。 | | options | [RelativeTimeFormatInputOptions](#relativetimeformatinputoptions) | 否 | 用于创建相对时间格式化对象的选项。 | - 示例： ``` var relativeTimeFormat = new Intl.RelativeTimeFormat("zh-CN", {"localeMatcher": "lookup", "numeric": "always", "style": "long"}); ``` ### format8+ format(value: numeric, unit: string): string 依据locale和格式化选项，对value和unit进行格式化。 - 参数： | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | | value | numeric | 是 | 相对时间格式化的数值。 | | 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: numeric, unit: string): Array<Object> 返回一个对象数组，表示可用于自定义区域设置格式的相对时间格式。 - 参数： | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | | value | numeric | 是 | 相对时间格式化的数值。 | | 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对象的格式化选项。 - 返回值： | 类型 | 说明 | | -------- | -------- | | [RelativeTimeFormatResolvedOptions](#relativetimeformatresolvedoptions) | RelativeTimeFormat 对象的格式化选项。 | - 示例： ``` var relativetimefmt= new Intl.RelativeTimeFormat("en-GB"); relativetimefmt.resolvedOptions(); ``` ## RelativeTimeFormatInputOptions8+ 表示RelativeTimeFormat对象可设置的属性。 | 名称 | 参数类型 | 可读 | 可写 | 说明 | | -------- | -------- | -------- | -------- | -------- | | localeMatcher | string | 是 | 是 | locale匹配算法，取值包括："best fit", "lookup"。 | | numeric | string | 是 | 是 | 输出消息的格式，取值包括："always", "auto"。 | | style | string | 是 | 是 | 国际化消息的长度，取值包括："long", "short", "narrow"。 | ## RelativeTimeFormatResolvedOptions8+ 表示RelativeTimeFormat对象可设置的属性。 | 名称 | 参数类型 | 可读 | 可写 | 说明 | | -------- | -------- | -------- | -------- | -------- | | locale | string | 是 | 是 | 包含区域设置信息的字符串，包括语言以及可选的脚本和区域。 | | numeric | string | 是 | 是 | 输出消息的格式，取值包括："always", "auto"。 | | style | string | 是 | 是 | 国际化消息的长度，取值包括："long", "short", "narrow"。 | | numberingSystem | string | 是 | 是 | 使用的数字系统。 |