harmony 鸿蒙@ohos.intl (Internationalization)

2025-06-12
浏览 (2)

@ohos.intl (Internationalization)

The intl module provides basic i18n capabilities, such as time and date formatting, number formatting, and string sorting, through the standard i18n APIs defined in ECMA 402. The i18n module provides enhanced i18n capabilities through supplementary interfaces that are not defined in ECMA 402. It works with the intl module to provide a complete suite of i18n capabilities.

NOTE

The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version.

The APIs of this module conform to the Common Locale Data Repository (CLDR) internationalization database. The processing result may change with CLDR evolution. API version 12 corresponds to CLDR 42. For details about data changes, visit the official website.

Since API version 11, some APIs of this module are supported in ArkTS widgets.

Since API version 12, the APIs of this module are supported in atomic services.

Modules to Import

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

Locale

Attributes

Widget capability: Since API version 11, this feature is supported in ArkTS widgets.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Global.I18n

Name	Type	Mandatory	Description
language	string	Yes	Language associated with the locale, for example, zh. The value complies with the ISO 639 standard.
script	string	Yes	Script type of the language, for example, Hans. The value complies with the Unicode ISO 15924 standard.
region	string	Yes	Country/region associated with the locale, for example, CN. The value complies with the ISO 3166 standard.
baseName	string	Yes	Locale information, which consists of the language, script, and country/region, for example, zh-Hans-CN.
caseFirst	string	Yes	Whether case is taken into account for the locale’s collation rules. The value can be: “upper”, “lower”, or  “false”. For details about their meanings, see Table 1 in Sorting by Local Habits .
calendar	string	Yes	Calendar for the locale. The value can be: The value can be any of the following: buddhist, chinese, coptic, dangi, ethioaa, ethiopic, gregory, hebrew, indian, islamic, islamic-umalqura, islamic-tbla, islamic-civil, islamic-rgsa, iso8601, japanese, persian, roc, or islamicc. For details about their meanings, see Table 1 in Calendar Setting.
collation	string	Yes	Collation rules for the locale. The value can be: The value can be any of the following: big5han, compat, dict, direct, ducet, eor, gb2312, phonebk, phonetic, pinyin, reformed, searchjl, stroke, trad, unihan, or zhuyin. For details about their meanings, see Table 1 in Sorting by Local Habits .
hourCycle	string	Yes	Time system for the locale. The value can be: “h11”, “h12”, “h23”, or “h24”. For details about their display effects, see Table 5 in Date and Time Formatting.
numberingSystem	string	Yes	Numbering system for the locale. The value can be: 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, or wcho.
numeric	boolean	Yes	Wether to use special sorting rules for digits. The value true means to use special sorting rules for digits, and the value false means the opposite. The default value is false.

constructor⁸⁺

constructor()

Creates a Locale object.

Widget capability: Since API version 11, this feature is supported in ArkTS widgets.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Global.I18n

Example

  // The current system locale is used by the default constructor.
  let locale = new intl.Locale();
  // Return the current system locale ID.
  let localeID = locale.toString();

constructor

constructor(locale: string, options?: LocaleOptions)

Creates a Locale object.

Widget capability: Since API version 11, this feature is supported in ArkTS widgets.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Global.I18n

Parameters

Name	Type	Mandatory	Description
locale	string	Yes	Locale information, which consists of the language, script, and country/region.
options	LocaleOptions	No	Options for creating the Locale object.

Example

  // Create a zh-CN locale object.
  let locale = new intl.Locale("zh-CN");
  let localeID = locale.toString(); // localeID = "zh-CN"

toString

toString(): string

Obtains the string that represents a Locale object.

Widget capability: Since API version 11, this feature is supported in ArkTS widgets.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Global.I18n

Return value

Type	Description
string	String that represents the Locale object.

Example

  // Create an en-GB locale object.
  let locale = new intl.Locale("en-GB");
  let localeID = locale.toString(); // localeID = "en-GB"

maximize

maximize(): Locale

Maximizes locale information by supplementing the missing script and country/region information.

Widget capability: Since API version 11, this feature is supported in ArkTS widgets.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Global.I18n

Return value

Type	Description
Locale	Locale object with the script and country/region information.

Example

  // Create a zh locale object.
  let locale = new intl.Locale("zh");
  // Supplement the locale object's script and region.
  let maximizedLocale = locale.maximize();
  let localeID = maximizedLocale.toString(); // localeID = "zh-Hans-CN"

  // Create an en-US locale object.
  locale = new intl.Locale("en-US");
  // Supplement the locale object's script.
  maximizedLocale = locale.maximize();
  localeID = maximizedLocale.toString(); // localeID = "en-Latn-US"

minimize

minimize(): Locale

Minimizes locale information by removing the script and country/region information.

Widget capability: Since API version 11, this feature is supported in ArkTS widgets.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Global.I18n

Return value

Type	Description
Locale	Locale object without the script and country/region information.

Example

  // Create a zh-Hans-CN locale object.
  let locale = new intl.Locale("zh-Hans-CN");
  // Remove the locale object's script and region.
  let minimizedLocale = locale.minimize();
  let localeID = minimizedLocale.toString(); // localeID = "zh"

  // Create an en-US locale object.
  locale = new intl.Locale("en-US");
  // Remove locale object's region.
  minimizedLocale = locale.minimize();
  localeID = minimizedLocale.toString(); // localeID = "en"

LocaleOptions

Options for initializing the Locale object. Since API version 9, the LocaleOptions attribute is changed from mandatory to optional.

Widget capability: Since API version 11, this feature is supported in ArkTS widgets.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Global.I18n

Name	Type	Mandatory	Description
calendar	string	No	Calendar parameter. The value can be: “buddhist”, “chinese”, “coptic”, “dangi”, “ethioaa”, “ethiopic”, “gregory”, “hebrew”, “indian”, “islamic”, “islamic-umalqura”, “islamic-tbla”, “islamic-civil”, “islamic-rgsa”, “iso8601”, “japanese”, “persian”, “roc”, or “islamicc”.
collation	string	No	Collation parameter. The value can be: “big5han”, “compat”, “dict”, “direct”, “ducet”, “emoji”, “eor”, “gb2312”, “phonebk”, “phonetic”, “pinyin”, “reformed search, searchjl, standard, stroke, trad, unihan, zhuyin.
hourCycle	string	No	Hour cycle. The value can be: “h11”, “h12”, “h23”, or  “h24”.
numberingSystem	string	No	Numbering system. The value can be: 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, or wcho.
numeric	boolean	No	Wether to use special sorting rules for digits. The value true means to use special sorting rules for digits, and the value false means the opposite. The default value is false.
caseFirst	string	No	Whether upper case or lower case is sorted first. The value can be upper, lower, or false.

NOTE

For details about calendar, see Table 1 in Calendar Setting.

For details about hourCycle, see Table 5 in Date and Time Formatting.

For details about caseFirst and collation, see Table 1 in Sorting by Local Habits .

DateTimeFormat

constructor⁸⁺

constructor()

Creates a DateTimeOptions object for the specified locale.

Widget capability: Since API version 11, this feature is supported in ArkTS widgets.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Global.I18n

Example

  // Create a DateTimeFormat object using the current system locale ID.
  let datefmt= new intl.DateTimeFormat();

constructor

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

Creates a DateTimeOptions object for the specified locale.

Widget capability: Since API version 11, this feature is supported in ArkTS widgets.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Global.I18n

Parameters

Name	Type	Mandatory	Description
locale	string \|Array<string>	Yes	Locale ID or locale ID array. If the input is a locale ID array, the first valid locale ID is used.
options	DateTimeOptions	No	Options for creating the DateTimeOptions object. If no options are set, the default values of year, month, and day are numeric.

Example

  // Create a DateTimeFormat object with locale ID being zh-CN, dateStyle being full, and timeStyle being medium.
  let datefmt= new intl.DateTimeFormat("zh-CN", { dateStyle: 'full', timeStyle: 'medium' });

  // Create a DateTimeFormat object with a locale ID array. The locale ID ban is invalid and therefore locale ID zh is used.
  let datefmt= new intl.DateTimeFormat(["ban", "zh"], { dateStyle: 'full', timeStyle: 'medium' });

format

format(date: Date): string

Formats the date and time.

Widget capability: Since API version 11, this feature is supported in ArkTS widgets.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Global.I18n

Parameters

Name	Type	Mandatory	Description
date	Date	Yes	Date and time. Note: The month starts from 0. For example, 0 indicates January.

Return value

Type	Description
string	A string containing the formatted date and time.

Example

  let date = new Date (2021, 11, 17, 3, 24, 0); // The date and time is 2021.12.17 03:24:00.
  // Create a DateTimeFormat object with the locale ID being en-GB.
  let datefmt = new intl.DateTimeFormat("en-GB");
  let formattedDate = datefmt.format(date); // formattedDate "17/12/2021"

  // Create a DateTimeFormat object with locale ID being en-GB, dateStyle being full, and timeStyle being 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

Formats date and time ranges.

Widget capability: Since API version 11, this feature is supported in ArkTS widgets.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Global.I18n

Parameters

Name	Type	Mandatory	Description
startDate	Date	Yes	Start date and time. Note: The month starts from 0. For example, 0 indicates January.
endDate	Date	Yes	End date and time. Note: The month starts from 0. For example, 0 indicates January.

Return value

Type	Description
string	A string containing the formatted date and time ranges.

Example

  let startDate = new Date(2021, 11, 17, 3, 24, 0); // The date and time is 2021.12.17 03:24:00.
  let endDate = new Date(2021, 11, 18, 3, 24, 0);
  // Create a DateTimeFormat object with the locale ID being en-GB.
  let datefmt = new intl.DateTimeFormat("en-GB");
  let formattedDateRange = datefmt.formatRange(startDate, endDate); // formattedDateRange = "17/12/2021 - 18/12/2021"

resolvedOptions

resolvedOptions(): DateTimeOptions

Obtains the options for creating a DateTimeOptions object.

Widget capability: Since API version 11, this feature is supported in ArkTS widgets.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Global.I18n

Return value

Type	Description
DateTimeOptions	Options for the DateTimeOptions object.

Example

  let datefmt = new intl.DateTimeFormat("en-GB", { dateStyle: 'full', timeStyle: 'medium' });
  // Obtain the options of the DateTimeFormat object.
  let options = datefmt.resolvedOptions();
  let dateStyle = options.dateStyle; // dateStyle = "full"
  let timeStyle = options.timeStyle; // timeStyle = "medium"

DateTimeOptions

Defines the options for a DateTimeOptions object. Since API version 9, the DateTimeOptions attribute is changed from mandatory to optional.

Widget capability: Since API version 11, this feature is supported in ArkTS widgets.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Global.I18n

Name	Type	Mandatory	Description
locale	string	No	Valid locale ID, for example, zh-Hans-CN. The default value is the current system locale.
dateStyle	string	No	Date display format. The value can be: “long”, “short”, “medium”, “full”, or  “auto”. For details about their display effects, see Table 1 in Date and Time Formatting.
timeStyle	string	No	Time display format. The value can be: “long”, “short”, “medium”, “full”, or  “auto”. For details about their display effects, see Table 2 in Date and Time Formatting.
hourCycle	string	No	Hour cycle. The value can be: “h11”, “h12”, “h23”, or  “h24”. For details about the display effect when dateStyle or timeStyle is not set, see Table 5 in Date and Time Formatting. For details about the display effect when dateStyle or timeStyle is set, see Table 6 in Date and Time Formatting.
timeZone	string	No	Time zone in use. The value is a valid IANA time zone ID.
numberingSystem	string	No	Numbering system. The value can be: 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, or wcho.
hour12	boolean	No	Whether to use the 12-hour clock. The value true means to use the 12-hour clock, and the value false means the opposite. If both hour12 and hourCycle are set, hourCycle does not take effect. If hour12 and hourCycle are not set and the 24-hour clock is turned on, the default value of hour12 is false.
weekday	string	No	Week display format. The value can be: “long”, “short”, “narrow”, or  “auto”. For details about their display effects, see Table 4 in Date and Time Formatting.
era	string	No	Epoch display format. The value can be: “long”, “short”, “narrow”, or  “auto”. For details about their display effects, see Table 9 in Date and Time Formatting.
year	string	No	Year display format. The value can be: “numeric” or  “2-digit”. For details about their display effects, see Table 3 in Date and Time Formatting.
month	string	No	Month display format. The value can be: “numeric”, “2-digit”, “long”, “short”, “narrow”, or  “auto”. For details about their display effects, see Table 6 in Date and Time Formatting.
day	string	No	Day display format. The value can be: “numeric” or  “2-digit”.
hour	string	No	Hour display format. The value can be: “numeric” or  “2-digit”.
minute	string	No	Minute display format. The value can be: “numeric” or  “2-digit”.
second	string	No	Second display format. The value can be: “numeric” or  “2-digit”.
timeZoneName	string	No	Localized representation of a time zone name. The value can be: “long”, “short”, or  “auto”. For details about their display effects, see Table 8 in Date and Time Formatting.
dayPeriod	string	No	Time period display format. The value can be: “long”, “short”, “narrow”, or  “auto”. For details about their display effects, see Table 10 in Date and Time Formatting.
localeMatcher	string	No	Locale matching algorithm. The value can be: - “lookup”: exact match. - “best fit”: best match.
formatMatcher	string	No	Format matching algorithm. The value can be: - “basic”: exact match. - “best fit”: best match.

NumberFormat

constructor⁸⁺

constructor()

Creates a NumberFormat object for the specified locale.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Global.I18n

Example

  // Create a NumberFormat object using the current system locale ID.
  let numfmt = new intl.NumberFormat();

constructor

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

Creates a NumberFormat object for the specified locale.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Global.I18n

Parameters

Name	Type	Mandatory	Description
locale	string \|Array<string>	Yes	Locale ID or locale ID array. If the input is a locale ID array, the first valid locale ID is used.
options	NumberOptions	No	Options for creating the NumberFormat object.

Example

  // Create a NumberFormat object with locale ID being en-GB, style being decimal, and notation being scientific.
  let numfmt = new intl.NumberFormat("en-GB", {style:'decimal', notation:"scientific"});

format

format(number: number): string

Formats a number.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Global.I18n

Parameters

Name	Type	Mandatory	Description
number	number	Yes	Number to be formatted.

Return value

Type	Description
string	Formatted number.

Example

  // Create a NumberFormat object with a locale ID array. The locale ID en-GB is valid and therefore is used.
  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

Formats a number range.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.Global.I18n

Parameters

Name	Type	Mandatory	Description
startRange	number	Yes	Start number.
endRange	number	Yes	End number.

Return value

Type	Description
string	Formatted number range.

Example

  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

Obtains the options for creating a NumberFormat object.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Global.I18n

Return value

Type	Description
NumberOptions	Options for creating the NumberFormat object.

Example

  let numfmt = new intl.NumberFormat(["en-GB", "zh"], {style:'decimal', notation:"scientific"});
  // Obtain the options of the NumberFormat object.
  let options = numfmt.resolvedOptions();
  let style = options.style; // style = decimal
  let notation = options.notation; // notation = scientific

NumberOptions

Options for creating the NumberFormat object. Since API version 9, the NumberOptions attribute is changed from mandatory to optional.

System capability: SystemCapability.Global.I18n

Name	Type	Mandatory	Description
locale	string	No	Valid locale ID, for example, zh-Hans-CN. The default value is the current system locale. Atomic service API: This API can be used in atomic services since API version 12.
currency	string	No	Currency unit. The value must comply with the ISO-4217 standard, for example, EUR, CNY, and USD. From API version 12, a three-digit number is supported, for example, 978, 156, or 840. Atomic service API: This API can be used in atomic services since API version 12.
currencySign	string	No	Currency unit symbol. The value can be standard or accounting. The default value is standard. Atomic service API: This API can be used in atomic services since API version 12.
currencyDisplay	string	No	Currency display mode. The value can be symbol, narrowSymbol, code, or name. The default value is symbol. Atomic service API: This API can be used in atomic services since API version 12.
unit	string	No	Unit name, for example, meter, inch, or hectare. The combination units supported since API version 18 are as follows: 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, and stroke-per-minute. Atomic service API: This API can be used in atomic services since API version 12.
unitDisplay	string	No	Display format of units. The value can be long, short, or narrow. The default value is short. Atomic service API: This API can be used in atomic services since API version 12.
unitUsage⁸⁺	string	No	Application scenario of units. The value can be any of the following: “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, or size-shortfile-byte. The default value is default. Atomic service API**: This API can be used in atomic services since API version 12.
signDisplay	string	No	Number sign display format. The value can be: - “auto”: automatically determines whether to display the plus or minus sign. - “never”: do not display the plus or minus sign. - “always”: always displays the plus or minus sign. - “exceptZero”: displays the plus or minus sign for all values except 0. Default value: “auto” Atomic service API: This API can be used in atomic services since API version 12.
compactDisplay	string	No	Compact display format. The value can be long or short. The default value is short. Atomic service API: This API can be used in atomic services since API version 12.
notation	string	No	Number notation. The value can be standard, scientific, engineering, or compact. The default value is standard. Atomic service API: This API can be used in atomic services since API version 12.
localeMatcher	string	No	Locale matching algorithm. The value can be lookup or best fit. The default value is best fit. Atomic service API: This API can be used in atomic services since API version 12.
style	string	No	Number display format. The value can be decimal, currency, percent, or unit. The default value is decimal. Atomic service API: This API can be used in atomic services since API version 12.
numberingSystem	string	No	Numbering system. The value can be: 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, or wcho. The default value is the default numbering system of the locale. Atomic service API: This API can be used in atomic services since API version 12.
useGrouping	boolean	No	Whether to enable grouping for display. The value true means to enable grouping for display, and the value false means the opposite. The default value is true. Atomic service API: This API can be used in atomic services since API version 12.
minimumIntegerDigits	number	No	Minimum number of digits allowed in the integer part of a number. The value ranges from 1 to 21. The default value is 1. Atomic service API: This API can be used in atomic services since API version 12.
minimumFractionDigits	number	No	Minimum number of digits in the fraction part of a number. The value ranges from 0 to 20. The default value is 0. Atomic service API: This API can be used in atomic services since API version 12.
maximumFractionDigits	number	No	Maximum number of digits in the fraction part of a number. The value ranges from 1 to 21. The default value is 3. Atomic service API: This API can be used in atomic services since API version 12.
minimumSignificantDigits	number	No	Minimum number of the least significant digits. The value ranges from 1 to 21. The default value is 1. Atomic service API: This API can be used in atomic services since API version 12.
maximumSignificantDigits	number	No	Maximum number of the least significant digits. The value ranges from 1 to 21. The default value is 21. Atomic service API: This API can be used in atomic services since API version 12.
roundingPriority¹⁸⁺	string	No	Rounding priority used when both the maximum number of fraction digits and the maximum number of valid digits are set. The value can be auto, morePrecision, or lessPrecision. The value morePrecision indicates that the maximum number of fraction digits is used. The value lessPrecision indicates that the maximum number of valid digits is used. The default value is auto. Atomic service API: This API can be used in atomic services since API version 18.
roundingIncrement¹⁸⁺	number	No	Rounding increment. The value can be 1, 2, 5, 10, 20, 25, 50, 100, 200, 250, 500, 1000, 2000, 2500, or 5000. The default value is 1. Atomic service API: This API can be used in atomic services since API version 18.
roundingMode¹⁸⁺	string	No	Rounding mode. The value can be: - “ceil”: rounding up. - “floor”: rounding down. - “expand”: rounding away from 0. - “trunc”: rounding toward 0. - “halfCeil”: half-rounding up; that is, rounding up when the decimal number is greater than or equal to half of the increment, and rounding down otherwise. - “halfFloor”: half-rounding down; that is, rounding up when the decimal number is greater than half of the increment, and rounding down otherwise. - “halfExpand”: half-rounding away from 0; that is, rounding away from 0 when the decimal number is greater than or equal to half of the increment, and rounding toward 0 otherwise. - “halfTrunc”: half-rounding toward 0; that is, rounding away from 0 when the decimal number is greater than half of the increment, and rounding toward 0 otherwise. - “halfEven”: half-rounding to the nearest even number; that is, rounding away from 0 when the decimal number is greater than half of the increment, rounding toward 0 when the decimal number is less than half of the increment, and rounding to the nearest even number when the decimal number is exactly half of the increment. The default value is halfExpand. Atomic service API: This API can be used in atomic services since API version 18.

NOTE

For details about the meaning or display effect of different values, see Number and Unit of Measurement Formatting.

Collator⁸⁺

constructor⁸⁺

constructor()

Creates a Collator object.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Global.I18n

Example

  // Create a Collator object using the current system locale ID.
  let collator = new intl.Collator();

constructor⁸⁺

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

Creates a Collator object.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Global.I18n

Parameters

Name	Type	Mandatory	Description
locale	string \|Array<string>	Yes	Locale ID or locale ID array. If the input is a locale ID array, the first valid locale ID is used.
options	CollatorOptions	No	Options for creating a Collator object.

Example

  // Create a Collator object with the locale ID being zh-CN, localeMatcher being lookup, and usage being sort.
  let collator = new intl.Collator("zh-CN", {localeMatcher: "lookup", usage: "sort"});

compare⁸⁺

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

Compares two strings based on the specified collation rules.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Global.I18n

Parameters

Name	Type	Mandatory	Description
first	string	Yes	First string to compare.
second	string	Yes	Second string to compare.

Return value

Type	Description
number	Comparison result. - If the value is a negative number, the first string comes before the second string. - If the value is 0, the first and second strings are in the same sequence. - If the value is a positive number, the first string is comes after the second string.

Example

  // Create a Collator object with the locale ID being en-GB.
  let collator = new intl.Collator("en-GB");
  // Compare the sequence of the first and second strings.
  let compareResult = collator.compare("first", "second"); // compareResult = -1

resolvedOptions⁸⁺

resolvedOptions(): CollatorOptions

Obtains the options for creating a Collator object.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Global.I18n

Return value

Type	Description
CollatorOptions	Options for creating a Collator object.

Example

  let collator = new intl.Collator("zh-Hans", { usage: 'sort', ignorePunctuation: true });
  // Obtain the options of the Collator object.
  let options = collator.resolvedOptions();
  let usage = options.usage; // usage = "sort"
  let ignorePunctuation = options.ignorePunctuation; // ignorePunctuation = true

CollatorOptions⁸⁺

Defines the options for creating a Collator object.

Since API version 9, the attributes in CollatorOptions are optional.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Global.I18n

Name	Type	Mandatory	Description
localeMatcher	string	No	Locale matching algorithm. The value can be lookup or best fit. The default value is best fit.
usage	string	No	Whether the comparison is for sorting or for searching. The value can be sort or search. The default value is sort.
sensitivity	string	No	Differences in the strings that lead to non-zero return values. The value can be base, accent, case, or letiant. The default value is variant.
ignorePunctuation	boolean	No	Whether to ignore punctuation. The value true means to ignore punctuation, and the value false means the opposite. The default value is false.
collation	string	No	Collation rule. The value can be any of the following: big5han, compat, dict, direct, ducet, eor, gb2312, phonebk, phonetic, pinyin, reformed, searchjl, stroke, trad, unihan, or zhuyin. The default value is default.
numeric	boolean	No	Whether to use numeric collation. The value true means to use numeric collation, and the value false means the opposite. The default value is false.
caseFirst	string	No	Whether upper case or lower case is sorted first. The value can be upper, lower, or false. The default value is false.

NOTE

For details about the meanings of different field values, see Sorting by Local Habits.

PluralRules⁸⁺

constructor⁸⁺

constructor()

Creates a PluralRules object to obtain the singular-plural type of numbers.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Global.I18n

Example

  // Create a PluralRules object using the current system locale ID.
  let pluralRules = new intl.PluralRules();

constructor⁸⁺

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

Creates a PluralRules object to obtain the singular-plural type of numbers.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Global.I18n

Parameters

Name	Type	Mandatory	Description
locale	string \|Array<string>	Yes	Locale ID or locale ID array. If the input is a locale ID array, the first valid locale ID is used.
options	PluralRulesOptions	No	Options for creating a PluralRules object.

Example

  // Create a PluralRules object with the locale ID being zh-CN, localeMatcher being lookup, and type being cardinal.
  let pluralRules= new intl.PluralRules("zh-CN", {"localeMatcher": "lookup", "type": "cardinal"});

select⁸⁺

select(n: number): string

Obtains the singular-plural type of the specified number.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Global.I18n

Parameters

Name	Type	Mandatory	Description
n	number	Yes	Number for which the singular-plural type is to be obtained.

Return value

Type	Description
string	Singular-plural type. The value can be any of the following: zero, one, two, few, many, others. For details about the meanings of different values, see Language Plural Rules.

Example

  // Create a PluralRules object with the locale ID being zh-Hans.
  let zhPluralRules = new intl.PluralRules("zh-Hans");
  // Determine the singular-plural type corresponding to number 1 in locale zh-Hans.
  let plural = zhPluralRules.select(1); // plural = other

  // Create a PluralRules object with the locale ID being en-US.
  let enPluralRules = new intl.PluralRules("en-US");
  // Determine the singular-plural type corresponding to number 1 in locale en-US.
  plural = enPluralRules.select(1); // plural = one

PluralRulesOptions⁸⁺

Defines the options for creating a PluralRules object. Since API version 9, the PluralRulesOptions attribute is changed from mandatory to optional.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Global.I18n

Name	Type	Readable	Writable	Description
localeMatcher	string	Yes	Yes	Locale matching algorithm. The value can be lookup or best fit. The default value is best fit.
type	string	Yes	Yes	Collation type. The value can be cardinal or ordinal. The default value is cardinal. The value cardinal indicates a cardinal number and the value ordinal indicates an ordinal number.
minimumIntegerDigits	number	Yes	Yes	Minimum number of digits allowed in the integer part of a number. The value ranges from 1 to 21. The default value is 1.
minimumFractionDigits	number	Yes	Yes	Minimum number of digits in the fraction part of a number. The value ranges from 0 to 20. The default value is 0.
maximumFractionDigits	number	Yes	Yes	Maximum number of digits in the fraction part of a number. The value ranges from 1 to 21. The default value is 3.
minimumSignificantDigits	number	Yes	Yes	Minimum number of the least significant digits. The value ranges from 1 to 21. The default value is 1.
maximumSignificantDigits	number	Yes	Yes	Maximum number of the least significant digits. The value ranges from 1 to 21. The default value is 21.

RelativeTimeFormat⁸⁺

constructor⁸⁺

constructor()

Creates a RelativeTimeFormat object.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Global.I18n

Example

  // Create a RelativeTimeFormat object using the current system locale ID.
  let relativetimefmt = new intl.RelativeTimeFormat();

constructor⁸⁺

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

Creates a RelativeTimeFormat object.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Global.I18n

Parameters

Name	Type	Mandatory	Description
locale	string \|Array<string>	Yes	Locale ID or locale ID array. If the input is a locale ID array, the first valid locale ID is used.
options	RelativeTimeFormatInputOptions	No	Options for creating a RelativeTimeFormat object.

Example

  // Create a RelativeTimeFormat object with the locale ID being zh-CN, localeMatcher being lookup, and style being long.
  let relativeTimeFormat = new intl.RelativeTimeFormat("zh-CN", {"localeMatcher": "lookup", "numeric": "always", "style": "long"});

format⁸⁺

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

Formats a relative time.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Global.I18n

Parameters

Name	Type	Mandatory	Description
value	number	Yes	Value to format.
unit	string	Yes	Unit of the relative time. The value can be any of the following: year, quarter, month, week, day, hour, minute, or second**.

Return value

Type	Description
string	Relative time after formatting.

Example

  // Create a RelativeTimeFormat object with the locale ID being zh-CN.
  let relativetimefmt = new intl.RelativeTimeFormat("zh-CN");
  // Obtain the localized representation (in unit of quarter) of number 3 in locale zh-CN.
  let formatResult = relativetimefmt.format(3, "quarter"); // formatResult = "3 quarters later"

formatToParts⁸⁺

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

Formats the relative time

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Global.I18n

Parameters

Name	Type	Mandatory	Description
value	number	Yes	Value to format.
unit	string	Yes	Unit of the relative time. The value can be any of the following: year, quarter, month, week, day, hour, minute, or second**.

Return value

Type	Description
Array<object>	to parts.

Example

  // Create a RelativeTimeFormat object with the locale ID being en and numeric being 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

Defines the formatting options for a RelativeTimeFormat object.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Global.I18n

Return value

Type	Description
RelativeTimeFormatResolvedOptions	Options for the RelativeTimeFormat object.

Example

  // Create a RelativeTimeFormat object with the locale ID being en-GB.
  let relativetimefmt= new intl.RelativeTimeFormat("en-GB", { style: "short" });
  // Obtain the options of the RelativeTimeFormat object.
  let options = relativetimefmt.resolvedOptions();
  let style = options.style; // style = "short"

RelativeTimeFormatInputOptions⁸⁺

Defines the configuration options for a RelativeTimeFormat object.

Since API version 9, the attributes in RelativeTimeFormatInputOptions are optional.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Global.I18n

Name	Type	Mandatory	Description
localeMatcher	string	No	Locale matching algorithm. The value can be lookup or best fit. The default value is best fit.
numeric	string	No	Format of the output message. The value can be always or auto. The default value is always.
style	string	No	Length of an internationalized message. The value can be long, short, or narrow. The default value is long.

NOTE

For details about the display effects of numeric and style, see Date and Time Formatting.

RelativeTimeFormatResolvedOptions⁸⁺

Represents the formatting options for the RelativeTimeFormat object.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Global.I18n

Name	Type	Mandatory	Description
locale	string	Yes	Locale ID, including the language, script, and region.
numeric	string	Yes	Format of the output message. The value can be always or auto.
style	string	Yes	Length of an internationalized message. The value can be long, short, or narrow.
numberingSystem	string	Yes	Numbering system. The value can be: 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, or wcho.

NOTE

For details about the display effects of numeric and style, see Date and Time Formatting.

你可能感兴趣的鸿蒙文章

harmony 鸿蒙Localization Kit

harmony 鸿蒙RawFileDescriptor

harmony 鸿蒙RawFileDescriptor64

harmony 鸿蒙ResourceManager_Configuration

harmony 鸿蒙Font Management Error Codes

harmony 鸿蒙I18N Error Codes

harmony 鸿蒙Resource Manager Error Codes

harmony 鸿蒙@ohos.fontManager (Font Management)

harmony 鸿蒙@ohos.i18n (Internationalization) (System API)

harmony 鸿蒙@ohos.i18n (Internationalization)

0 赞

所属分类： 后端技术
本文标签：
版权声明： 原创文章如转载，请注明本文链接: https://www.seaxiang.com/blog/9yZQl4

harmony 鸿蒙@ohos.intl (Internationalization)

@ohos.intl (Internationalization)

Modules to Import

Locale

Attributes

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