@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. |
constructor8+
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
constructor8+
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
constructor8+
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
formatRange18+
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. |
| unitUsage8+ | 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. |
| roundingPriority18+ | 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. |
| roundingIncrement18+ | 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. |
| roundingMode18+ | 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.
Collator8+
constructor8+
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();
constructor8+
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"});
compare8+
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
resolvedOptions8+
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
CollatorOptions8+
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.
PluralRules8+
constructor8+
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();
constructor8+
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"});
select8+
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
PluralRulesOptions8+
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. |
RelativeTimeFormat8+
constructor8+
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();
constructor8+
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"});
format8+
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"
formatToParts8+
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"} ]
resolvedOptions8+
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"
RelativeTimeFormatInputOptions8+
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.
RelativeTimeFormatResolvedOptions8+
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 鸿蒙ResourceManager_Configuration
harmony 鸿蒙Font Management Error Codes
harmony 鸿蒙Resource Manager Error Codes
harmony 鸿蒙@ohos.fontManager (Font Management)