1# @ohos.intl (Internationalization) 2 3The **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. 4The [i18n](js-apis-i18n.md) 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. 5 6> **NOTE** 7> 8> - 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. 9> 10> - The APIs of this module conform to the [Common Locale Data Repository (CLDR)](https://cldr.unicode.org) internationalization database. The processing result may change with CLDR evolution. API version 12 corresponds to [CLDR 42](https://cldr.unicode.org/index/downloads/cldr-42). For details about data changes, visit the official website. 11> 12> - Since API version 11, some APIs of this module are supported in ArkTS widgets. 13> 14> - Since API version 12, the APIs of this module are supported in atomic services. 15 16 17## Modules to Import 18 19```ts 20import { intl } from '@kit.LocalizationKit'; 21``` 22 23## Locale<sup>(deprecated)</sup> 24 25### Attributes 26 27**Widget capability**: Since API version 11, this feature is supported in ArkTS widgets. 28 29**Atomic service API**: This API can be used in atomic services since API version 12. 30 31**System capability**: SystemCapability.Global.I18n 32 33| Name | Type | Mandatory | Description | 34| --------------- | ------- | -------- | ---------------------------------------- | 35| language | string | Yes | Language associated with the locale, for example, **zh**. The value complies with the ISO 639 standard.| 36| script | string | Yes | Script type of the language, for example, **Hans**. The value complies with the Unicode ISO 15924 standard.| 37| region | string | Yes | Country/region associated with the locale, for example, **CN**. The value complies with the ISO 3166 standard.| 38| baseName | string | Yes | Locale information, which consists of the language, script, and country/region, for example, **zh-Hans-CN**. | 39| caseFirst | string | Yes | Whether case is taken into account for the locale's collation rules. The value can be:<br>**upper**: Uppercase letters come first.<br>**lower**: Lowercase letters come first.<br>**false**: The default collation rules of the locale are used.| 40| calendar | string | Yes | Calendar for the locale. The value can be:<br>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**.<br>For details about their meanings, see Table 1 in [Calendar Setting](../../internationalization/i18n-calendar.md).| 41| collation | string | Yes | Collation rules for the locale. The value can be:<br>**big5han**: Pinyin sorting for Latin letters.<br>**compat**: compatibility sorting, only for Arabic.<br>**dict**: dictionary-style sorting, only for Singhalese.<br>**direct**: binary code point sorting.<br>**ducet**: sorting according to the Unicode collation element table.<br>**eor**: sorting according to the European collation rules.<br>**gb2312**: Pinyin sorting, only for Chinese.<br>**phonebk**: phone book-style sorting.<br>**phonetic**: phonetic sorting.<br>**pinyin**: Pinyin sorting.<br>**reformed**: reformed sorting, only for Swedish.<br>**searchjl**: special sorting for Korean initial consonant search.<br>**stroke**: stroke sorting for Chinese.<br>**trad**: traditional-style sorting, for example, Spanish.<br>unihan: radical-stroke sorting for Han characters, only for Chinese, Japanese, and Korean.<br>zhuyin: Zhuyin sorting, only for Chinese.| 42| hourCycle | string | Yes | Time system for the locale. The value can be:<br>"h11", "h12", "h23", or "h24".<br>For details about their display effects, see [Table 5](#appendix).| 43| numberingSystem | string | Yes | Numbering system for the locale. The value can be:<br>**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**.| 44| numeric | boolean | Yes | Whether 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.<br>The default value is **false**. | 45 46### constructor<sup>(deprecated)</sup> 47 48constructor() 49 50> This API is supported since API version 8 and deprecated since API version 20. You are advised to use [Intl.Locale() constructor](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/Locale) instead. 51 52Creates a **Locale** object. 53 54**Widget capability**: Since API version 11, this feature is supported in ArkTS widgets. 55 56**Atomic service API**: This API can be used in atomic services since API version 12. 57 58**System capability**: SystemCapability.Global.I18n 59 60**Example** 61 ```ts 62 // The current system locale is used by the default constructor. 63 let locale = new intl.Locale(); 64 // Return the current system locale ID. 65 let localeID = locale.toString(); 66 ``` 67 68### constructor<sup>(deprecated)</sup> 69 70constructor(locale: string, options?: LocaleOptions) 71 72> This API is supported since API version 8 and deprecated since API version 20. You are advised to use [Intl.Locale() constructor](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/Locale) instead. 73 74Creates a **Locale** object. 75 76**Widget capability**: Since API version 11, this feature is supported in ArkTS widgets. 77 78**Atomic service API**: This API can be used in atomic services since API version 12. 79 80**System capability**: SystemCapability.Global.I18n 81 82**Parameters** 83 84| Name | Type | Mandatory | Description | 85| -------------------- | -------------------------------- | ---- | ---------------------------- | 86| locale | string | Yes | Locale information, which consists of the language, script, and country/region.| 87| options | [LocaleOptions](#localeoptionsdeprecated) | No | Options for creating the **Locale** object.| 88 89**Example** 90 ```ts 91 // Create a zh-CN locale object. 92 let locale = new intl.Locale("zh-CN"); 93 let localeID = locale.toString(); // localeID = "zh-CN" 94 ``` 95 96 97### toString<sup>(deprecated)</sup> 98 99toString(): string 100 101> This API is supported since API version 8 and deprecated since API version 20. You are advised to use [Intl.Locale.prototype.toString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/toString) instead. 102 103Obtains the string that represents a **Locale** object. 104 105**Widget capability**: Since API version 11, this feature is supported in ArkTS widgets. 106 107**Atomic service API**: This API can be used in atomic services since API version 12. 108 109**System capability**: SystemCapability.Global.I18n 110 111**Return value** 112 113| Type | Description | 114| ------ | ----------- | 115| string | String that represents the **Locale** object.| 116 117**Example** 118 ```ts 119 // Create an en-GB locale object. 120 let locale = new intl.Locale("en-GB"); 121 let localeID = locale.toString(); // localeID = "en-GB" 122 ``` 123 124### maximize<sup>(deprecated)</sup> 125 126maximize(): Locale 127 128> This API is supported since API version 8 and deprecated since API version 20. You are advised to use [Intl.Locale.prototype.maximize()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/maximize) instead. 129 130Maximizes locale information by supplementing the missing script and country/region information. 131 132**Widget capability**: Since API version 11, this feature is supported in ArkTS widgets. 133 134**Atomic service API**: This API can be used in atomic services since API version 12. 135 136**System capability**: SystemCapability.Global.I18n 137 138**Return value** 139 140| Type | Description | 141| ----------------- | ---------- | 142| [Locale](#localedeprecated) | **Locale** object with the script and country/region information.| 143 144**Example** 145 ```ts 146 // Create a zh locale object. 147 let locale = new intl.Locale("zh"); 148 // Supplement the locale object's script and region. 149 let maximizedLocale = locale.maximize(); 150 let localeID = maximizedLocale.toString(); // localeID = "zh-Hans-CN" 151 152 // Create an en-US locale object. 153 locale = new intl.Locale("en-US"); 154 // Supplement the locale object's script. 155 maximizedLocale = locale.maximize(); 156 localeID = maximizedLocale.toString(); // localeID = "en-Latn-US" 157 ``` 158 159 160### minimize<sup>(deprecated)</sup> 161 162minimize(): Locale 163 164> This API is supported since API version 8 and deprecated since API version 20. You are advised to use [Intl.Locale.prototype.minimize()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/minimize) instead. 165 166Minimizes locale information by removing the script and country/region information. 167 168**Widget capability**: Since API version 11, this feature is supported in ArkTS widgets. 169 170**Atomic service API**: This API can be used in atomic services since API version 12. 171 172**System capability**: SystemCapability.Global.I18n 173 174**Return value** 175 176| Type | Description | 177| ----------------- | ---------- | 178| [Locale](#localedeprecated) | **Locale** object without the script and country/region information.| 179 180**Example** 181 ```ts 182 // Create a zh-Hans-CN locale object. 183 let locale = new intl.Locale("zh-Hans-CN"); 184 // Remove the locale object's script and region. 185 let minimizedLocale = locale.minimize(); 186 let localeID = minimizedLocale.toString(); // localeID = "zh" 187 188 // Create an en-US locale object. 189 locale = new intl.Locale("en-US"); 190 // Remove locale object's region. 191 minimizedLocale = locale.minimize(); 192 localeID = minimizedLocale.toString(); // localeID = "en" 193 ``` 194 195## LocaleOptions<sup>(deprecated)</sup> 196 197> This API is supported since API version 8 and is deprecated since API version 20. Taking calendar as an example, you are advised to use [Intl.Locale.prototype.calendar()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/calendar). 198 199Options for initializing the **Locale** object. Since API version 9, the **LocaleOptions** attribute is changed from mandatory to optional. 200 201**Widget capability**: Since API version 11, this feature is supported in ArkTS widgets. 202 203**Atomic service API**: This API can be used in atomic services since API version 12. 204 205**System capability**: SystemCapability.Global.I18n 206 207| Name | Type | Read-Only | Optional | Description | 208| --------------- | ------- | ---- | ---- |---------------------------------------- | 209| calendar | string | No | Yes |Calendar parameter. The value can be:<br>"buddhist", "chinese", "coptic", "dangi", "ethioaa", "ethiopic", "gregory", "hebrew", "indian", "islamic", "islamic-umalqura", "islamic-tbla", "islamic-civil", "islamic-rgsa", "iso8601", "japanese", "persian", "roc", or "islamicc".| 210| collation | string | No | Yes |Collation rules for the locale. The value can be:<br>**big5han**: Pinyin sorting for Latin letters.<br>**compat**: compatibility sorting, only for Arabic.<br>**dict**: dictionary-style sorting, only for Singhalese.<br>**direct**: binary code point sorting.<br>**ducet**: sorting according to the Unicode collation element table.<br>**eor**: sorting according to the European collation rules.<br>**gb2312**: Pinyin sorting, only for Chinese.<br>**phonebk**: phone book-style sorting.<br>**phonetic**: phonetic sorting.<br>**pinyin**: Pinyin sorting.<br>**reformed**: reformed sorting, only for Swedish.<br>**searchjl**: special sorting for Korean initial consonant search.<br>**stroke**: stroke sorting for Chinese.<br>**trad**: traditional-style sorting, for example, Spanish.<br>unihan: radical-stroke sorting for Han characters, only for Chinese, Japanese, and Korean.<br>zhuyin: Zhuyin sorting, only for Chinese.| 211| hourCycle | string | No | Yes |Hour cycle. The value can be:<br>"h11", "h12", "h23", or "h24".| 212| numberingSystem | string | No | Yes |Numbering system. The value can be:<br>**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**.| 213| numeric | boolean | No | Yes | Whether to treat numeric characters as numbers for sorting. The value true means to treat numeric characters as numbers for sorting, and the value **false** means to treat numeric characters as ordinary characters for sorting. For example, when this parameter is set to **true**, comparing the string **21** with the string **123** is equivalent to comparing the number 21 with the number 123. The default value is **false**. | 214| caseFirst | string | No | Yes | Whether case is taken into account for the locale's collation rules. The value can be:<br>**upper**: Uppercase letters come first.<br>**lower**: Lowercase letters come first.<br>**false**: The default collation rules of the locale are used.| 215 216> **NOTE** 217> 218> - For details about **calendar**, see Table 1 in [Calendar Setting](../../internationalization/i18n-calendar.md). 219 220## DateTimeFormat 221 222### constructor<sup>(deprecated)</sup> 223 224constructor() 225 226> This API is supported since API version 8 and deprecated since API version 20. You are advised to use [Intl.DateTimeFormat() constructor](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat) instead. 227 228Creates a **DateTimeOptions** object for the specified locale. 229 230**Widget capability**: Since API version 11, this feature is supported in ArkTS widgets. 231 232**Atomic service API**: This API can be used in atomic services since API version 12. 233 234**System capability**: SystemCapability.Global.I18n 235 236**Example** 237```ts 238// Create a DateTimeFormat object using the current system locale ID. 239let formatter: intl.DateTimeFormat = new intl.DateTimeFormat(); 240``` 241 242### constructor<sup>(deprecated)</sup> 243 244constructor(locale: string | Array<string>, options?: DateTimeOptions) 245 246> This API is supported since API version 8 and deprecated since API version 20. You are advised to use [Intl.DateTimeFormat() constructor](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat) instead. 247 248Creates a **DateTimeOptions** object for the specified locale. 249 250**Widget capability**: Since API version 11, this feature is supported in ArkTS widgets. 251 252**Atomic service API**: This API can be used in atomic services since API version 12. 253 254**System capability**: SystemCapability.Global.I18n 255 256**Parameters** 257 258| Name | Type | Mandatory | Description | 259| -------------------- | ------------------------------------ | ---- | ---------------------------- | 260| 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.| 261| options | [DateTimeOptions](#datetimeoptionsdeprecated) | No | Options for creating the **DateTimeOptions** object.<br>If no options are set, the default values of **year**, **month**, and **day** are **numeric**.| 262 263**Example** 264```ts 265// Create a DateTimeFormat object with locale ID being zh-CN, dateStyle being full, and timeStyle being medium. 266let formatter: intl.DateTimeFormat = new intl.DateTimeFormat('zh-CN', { dateStyle: 'full', timeStyle: 'medium' }); 267 268// Create a DateTimeFormat object with a locale ID array. The locale ID ban is invalid and therefore locale ID zh is used. 269formatter = new intl.DateTimeFormat(['ban', 'zh'], { dateStyle: 'full', timeStyle: 'medium' }); 270``` 271 272### format<sup>(deprecated)</sup> 273 274format(date: Date): string 275 276> This API is supported since API version 8 and deprecated since API version 20. You are advised to use [Intl.DateTimeFormat.prototype.format()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/format) instead. 277 278Formats the date and time. 279 280**Widget capability**: Since API version 11, this feature is supported in ArkTS widgets. 281 282**Atomic service API**: This API can be used in atomic services since API version 12. 283 284**System capability**: SystemCapability.Global.I18n 285 286**Parameters** 287 288| Name | Type | Mandatory | Description | 289| ---- | ---- | ---- | ------- | 290| date | Date | Yes | Date and time. Note: The month starts from **0**. For example, **0** indicates January.| 291 292**Return value** 293 294| Type | Description | 295| ------ | ------------ | 296| string | A string containing the formatted date and time.| 297 298**Example** 299```ts 300let date: Date = new Date(2021, 11, 17, 3, 24, 0); // The date and time is 2021.12.17 03:24:00. 301// Create a DateTimeFormat object with the locale ID being en-GB. 302let formatter: intl.DateTimeFormat = new intl.DateTimeFormat('en-GB'); 303let formattedDate: string = formatter.format(date); // formattedDate "17/12/2021" 304 305// Create a DateTimeFormat object with locale ID being en-GB, dateStyle being full, and timeStyle being medium. 306formatter = new intl.DateTimeFormat('en-GB', { dateStyle: 'full', timeStyle: 'medium' }); 307formattedDate = formatter.format(date); // formattedDate "Friday, 17 December 2021, 03:24:00" 308``` 309 310### formatRange<sup>(deprecated)</sup> 311 312formatRange(startDate: Date, endDate: Date): string 313 314> This API is supported since API version 8 and deprecated since API version 20. You are advised to use [Intl.DateTimeFormat.prototype.formatRange()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/formatRange) instead. 315 316Formats date and time ranges. 317 318**Widget capability**: Since API version 11, this feature is supported in ArkTS widgets. 319 320**Atomic service API**: This API can be used in atomic services since API version 12. 321 322**System capability**: SystemCapability.Global.I18n 323 324**Parameters** 325 326| Name | Type | Mandatory | Description | 327| --------- | ---- | ---- | -------- | 328| startDate | Date | Yes | Start date and time. Note: The month starts from **0**. For example, **0** indicates January.| 329| endDate | Date | Yes | End date and time. Note: The month starts from **0**. For example, **0** indicates January.| 330 331**Return value** 332 333| Type | Description | 334| ------ | -------------- | 335| string | A string containing the formatted date and time ranges.| 336 337**Example** 338```ts 339let startDate: Date = new Date(2021, 11, 17, 3, 24, 0); // The date and time is 2021.12.17 03:24:00. 340let endDate: Date = new Date(2021, 11, 18, 3, 24, 0); 341// Create a DateTimeFormat object with the locale ID being en-GB. 342let formatter: intl.DateTimeFormat = new intl.DateTimeFormat('en-GB'); 343let formattedDateRange: string = formatter.formatRange(startDate, endDate); // formattedDateRange = "17/12/2021 - 18/12/2021" 344``` 345 346### resolvedOptions<sup>(deprecated)</sup> 347 348resolvedOptions(): DateTimeOptions 349 350> This API is supported since API version 8 and deprecated since API version 20. You are advised to use [Intl.DateTimeFormat.prototype.resolvedOptions()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/resolvedOptions) instead. 351 352Obtains the options for creating a **DateTimeOptions** object. 353 354**Widget capability**: Since API version 11, this feature is supported in ArkTS widgets. 355 356**Atomic service API**: This API can be used in atomic services since API version 12. 357 358**System capability**: SystemCapability.Global.I18n 359 360**Return value** 361 362| Type | Description | 363| ------------------------------------ | ----------------------------- | 364| [DateTimeOptions](#datetimeoptionsdeprecated) | Options for the **DateTimeOptions** object.| 365 366**Example** 367```ts 368let formatter: intl.DateTimeFormat = new intl.DateTimeFormat("en-GB", { dateStyle: 'full', timeStyle: 'medium' }); 369// Obtain the options of the DateTimeFormat object. 370let options: intl.DateTimeOptions = formatter.resolvedOptions(); 371let dateStyle: string | undefined = options.dateStyle; // dateStyle = 'full' 372let timeStyle: string | undefined = options.timeStyle; // timeStyle = 'medium' 373``` 374 375 376## DateTimeOptions<sup>(deprecated)</sup> 377 378> This API is supported since API version 8 and is deprecated since API version 20. You are advised to use **Intl.DateTimeFormatOptions** or **Intl.ResolvedDateTimeFormatOptions** instead. For details, see [Intl.DateTimeFormat() constructor](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat) and [Intl.DateTimeFormat.prototype.resolvedOptions()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/resolvedOptions). 379 380Defines the options for a **DateTimeOptions** object. Since API version 9, the **DateTimeOptions** attribute is changed from mandatory to optional. 381 382**Widget capability**: Since API version 11, this feature is supported in ArkTS widgets. 383 384**Atomic service API**: This API can be used in atomic services since API version 12. 385 386**System capability**: SystemCapability.Global.I18n 387 388| Name | Type | Read-Only | Optional | Description | 389| --------------- | ------- | ---- | ---- | ---------------------------------------- | 390| locale | string | No | Yes |Valid locale ID, for example, **zh-Hans-CN**.<br>The default value is the current system locale. | 391| dateStyle | string | No | Yes |Date display format. The value can be:<br>"long", "short", "medium", "full", or "auto".<br>For details about their display effects, see [Table 1](#appendix).| 392| timeStyle | string | No | Yes |Time display format. The value can be:<br>"long", "short", "medium", "full", or "auto".<br>For details about their display effects, see [Table 2](#appendix).| 393| hourCycle | string | No | Yes |Hour cycle. The value can be:<br>"h11", "h12", "h23", or "h24".<br>For the display effects when **dateStyle** or **timeStyle** is not set, see [Table 5](#appendix).<br>For the display effects when **dateStyle** or **timeStyle** is not set, see [Table 6](#appendix).| 394| timeZone | string | No | Yes |Time zone in use. The value is a valid IANA time zone ID. | 395| numberingSystem | string | No | Yes |Numbering system. The value can be:<br>**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**.| 396| hour12 | boolean | No | Yes | Whether to use the 12-hour clock. The value **true** means to use the 12-hour clock, and the value **false** means the opposite.<br>If both **hour12** and **hourCycle** are set, **hourCycle** does not take effect.<br>If **hour12** and **hourCycle** are not set and the 24-hour clock is turned on, the default value of **hour12** is **false**.| 397| weekday | string | No | Yes | Week display format. The value can be:<br>"long", "short", "narrow", or "auto".<br>For details about their display effects, see [Table 4](#appendix).| 398| era | string | No | Yes | Epoch display format. The value can be:<br>"long", "short", "narrow", or "auto".<br>For details about their display effects, see [Table 9](#appendix).| 399| year | string | No | Yes | Year display format. The value can be:<br>"numeric" or "2-digit".<br>For details about their display effects, see [Table 3](#appendix). | 400| month | string | No | Yes | Month display format. The value can be:<br>"numeric", "2-digit", "long", "short", "narrow", or "auto".<br>For details about their display effects, see [Table 7](#appendix).| 401| day | string | No | Yes | Day display format. The value can be:<br>"numeric" or "2-digit". | 402| hour | string | No | Yes | Hour display format. The value can be:<br>"numeric" or "2-digit". | 403| minute | string | No | Yes | Minute display format. The value can be:<br>"numeric" or "2-digit". | 404| second | string | No | Yes | Second display format. The value can be:<br>"numeric" or "2-digit". | 405| timeZoneName | string | No | Yes | Localized representation of a time zone name. The value can be:<br>"long", "short", or "auto".<br>For details about their display effects, see [Table 8](#appendix). | 406| dayPeriod | string | No | Yes | Time period display format. The value can be:<br>"long", "short", "narrow", or "auto".<br>For details about their display effects, see [Table 10](#appendix).| 407| localeMatcher | string | No | Yes | Locale matching algorithm. The value can be:<br>- **lookup**: exact match.<br>- "best fit": best match.| 408| formatMatcher | string | No | Yes | Format matching algorithm. The value can be:<br>- **basic**: exact match.<br>- "best fit": best match.| 409 410## NumberFormat 411 412### constructor<sup>(deprecated)</sup> 413 414constructor() 415 416> This API is supported since API version 8 and deprecated since API version 20. You are advised to use [Intl.NumberFormat()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat) instead. 417 418Creates a **NumberFormat** object for the specified locale. 419 420**Atomic service API**: This API can be used in atomic services since API version 12. 421 422**System capability**: SystemCapability.Global.I18n 423 424**Example** 425```ts 426// Create a NumberFormat object using the current system locale ID. 427let formatter: intl.NumberFormat = new intl.NumberFormat(); 428``` 429 430 431### constructor<sup>(deprecated)</sup> 432 433constructor(locale: string | Array<string>, options?: NumberOptions) 434 435> This API is supported since API version 8 and deprecated since API version 20. You are advised to use [Intl.NumberFormat()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat) instead. 436 437Creates a **NumberFormat** object for the specified locale. 438 439**Atomic service API**: This API can be used in atomic services since API version 12. 440 441**System capability**: SystemCapability.Global.I18n 442 443**Parameters** 444 445| Name | Type | Mandatory | Description | 446| -------------------- | -------------------------------- | ---- | ---------------------------- | 447| 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.| 448| options | [NumberOptions](#numberoptionsdeprecated) | No | Options for creating the **NumberFormat** object. | 449 450**Example** 451```ts 452// Create a NumberFormat object with locale ID being en-GB, style being decimal, and notation being scientific. 453let formatter: intl.NumberFormat = new intl.NumberFormat('en-GB', { style: 'decimal', notation: 'scientific' }); 454``` 455 456### format<sup>(deprecated)</sup> 457 458format(number: number): string 459 460> This API is supported since API version 8 and deprecated since API version 20. You are advised to use [Intl.NumberFormat.format()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/format) instead. 461 462Formats a number. 463 464**Atomic service API**: This API can be used in atomic services since API version 12. 465 466**System capability**: SystemCapability.Global.I18n 467 468**Parameters** 469 470| Name | Type | Mandatory | Description | 471| ------ | ------ | ---- | ---- | 472| number | number | Yes | Number to be formatted.| 473 474**Return value** 475 476| Type | Description | 477| ------ | ---------- | 478| string | Formatted number.| 479 480 481**Example** 482```ts 483// Create a NumberFormat object with a locale ID array. The locale ID en-GB is valid and therefore is used. 484let formatter: intl.NumberFormat = new intl.NumberFormat(['en-GB', 'zh'], { style: 'decimal', notation: 'scientific' }); 485let formattedNumber: string = formatter.format(1223); // formattedNumber = 1.223E3 486let options : intl.NumberOptions = { 487 roundingPriority: "lessPrecision", 488 maximumFractionDigits: 3, 489 maximumSignificantDigits: 3 490} 491formatter = new intl.NumberFormat('en', options); 492let result: string = formatter.format(1.23456); // result = 1.23 493``` 494 495### formatRange<sup>(deprecated)</sup> 496 497formatRange(startRange: number, endRange: number): string 498 499> This API is supported since API version 8 and deprecated since API version 20. You are advised to use [Intl.NumberFormat.formatRange()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/formatRange) instead. 500 501Formats a number range. 502 503**Atomic service API**: This API can be used in atomic services since API version 18. 504 505**System capability**: SystemCapability.Global.I18n 506 507**Parameters** 508 509| Name | Type | Mandatory | Description | 510| ------ | ------ | ---- | ---- | 511| startRange | number | Yes | Start number.| 512| endRange | number | Yes | End number.| 513 514**Return value** 515 516| Type | Description | 517| ------ | ---------- | 518| string | Formatted number range.| 519 520 521**Example** 522```ts 523let formatter: intl.NumberFormat = new intl.NumberFormat('en-US', { style: 'unit', unit: 'meter' }); 524let formattedRange: string = formatter.formatRange(0, 3); // formattedRange: 0–3 m 525``` 526 527 528### resolvedOptions 529 530resolvedOptions(): NumberOptions 531 532Obtains the options for creating a **NumberFormat** object. 533 534**Atomic service API**: This API can be used in atomic services since API version 12. 535 536**System capability**: SystemCapability.Global.I18n 537 538**Return value** 539 540| Type | Description | 541| -------------------------------- | --------------------------- | 542| [NumberOptions](#numberoptionsdeprecated) | Options for creating the **NumberFormat** object.| 543 544 545**Example** 546```ts 547let formatter: intl.NumberFormat = new intl.NumberFormat(['en-GB', 'zh'], { style: 'decimal', notation: 'scientific' }); 548// Obtain the options of the NumberFormat object. 549let options: intl.NumberOptions = formatter.resolvedOptions(); 550let style: string | undefined = options.style; // style = 'decimal' 551let notation: string | undefined = options.notation; // notation = 'scientific' 552``` 553 554## NumberOptions<sup>(deprecated)</sup> 555 556> This API is supported since API version 8 and deprecated since API version 20. You are advised to use [Intl.NumberFormat#options](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#options) instead. 557 558Options for creating the **NumberFormat** object. Since API version 9, the **NumberOptions** attribute is changed from mandatory to optional. 559 560**System capability**: SystemCapability.Global.I18n 561 562| Name | Type | Read-Only | Optional | Description | 563| ------------------------ | ------- | ---- | ---- | ---------------------------------------- | 564| locale | string | No | Yes | Valid locale ID, for example, **zh-Hans-CN**.<br>The default value is the current system locale.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 565| currency | string | No | Yes | Currency unit. The value must comply with the [ISO-4217 standard](https://www.iso.org/iso-4217-currency-codes.html), for example, EUR, CNY, and USD.<br>From API version 12, a three-digit number is supported, for example, **978**, **156**, or **840**.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 566| currencySign | string | No | Yes | Currency unit symbol. The value can be **standard** or **accounting**.<br>The default value is **standard**.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 567| currencyDisplay | string | No | Yes | Currency display mode. The value can be **symbol**, **narrowSymbol**, **code**, or **name**.<br>The default value is **symbol**.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 568| unit | string | No | Yes | Unit name, for example, **meter**, **inch**, or **hectare**.<br>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.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 569| unitDisplay | string | No | Yes | Display format of units. The value can be **long**, **short**, or **narrow**.<br>The default value is **short**.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 570| unitUsage<sup>8+</sup> | string | No | Yes | 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**.<br>The default value is **default**.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 571| signDisplay | string | No | Yes | Number sign display format. The value can be:<br>- "auto": automatically determines whether to display the plus or minus sign.<br>- "never": do not display the plus or minus sign.<br>- "always": always displays the plus or minus sign.<br>- "exceptZero": displays the plus or minus sign for all values except 0.<br>Default value: **"auto"**<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 572| compactDisplay | string | No | Yes | Compact display format. The value can be **long** or **short**.<br>The default value is **short**.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 573| notation | string | No | Yes | Number notation. The value can be **standard**, **scientific**, **engineering**, or **compact**.<br>The default value is **standard**.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 574| localeMatcher | string | No | Yes | Locale matching algorithm. The value can be **lookup** or **best fit**.<br>The default value is **best fit**.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 575| style | string | No | Yes | Number display format. The value can be **decimal**, **currency**, **percent**, or **unit**.<br>The default value is **decimal**.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 576| numberingSystem | string | No | Yes | Numbering system. The value can be:<br>**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**.<br>The default value is the default numbering system of the locale.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 577| useGrouping | boolean | No | Yes | Whether to enable grouping for display. The value **true** means to enable grouping for display, and the value **false** means the opposite.<br>The default value is **true**.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 578| minimumIntegerDigits | number | No | Yes | Minimum number of digits allowed in the integer part of a number. The value ranges from **1** to **21**.<br>The default value is **1**.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 579| minimumFractionDigits | number | No | Yes | Minimum number of digits in the fraction part of a number. The value ranges from **0** to **20**.<br>The default value is **0**.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 580| maximumFractionDigits | number | No | Yes | Maximum number of digits in the fraction part of a number. The value ranges from **1** to **21**.<br>The default value is **3**.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 581| minimumSignificantDigits | number | No | Yes | Minimum number of the least significant digits. The value ranges from **1** to **21**.<br>The default value is **1**.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 582| maximumSignificantDigits | number | No | Yes | Maximum number of the least significant digits. The value ranges from **1** to **21**.<br>The default value is **21**.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 583| roundingPriority<sup>18+</sup> | string | No | Yes | 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.<br>The default value is **auto**.<br>**Atomic service API**: This API can be used in atomic services since API version 18. | 584| roundingIncrement<sup>18+</sup> | number | No | Yes | Rounding increment. The value can be **1**, **2**, **5**, **10**, **20**, **25**, **50**, **100**, **200**, **250**, **500**, **1000**, **2000**, **2500**, or **5000**.<br>The default value is **1**.<br>**Atomic service API**: This API can be used in atomic services since API version 18. | 585| roundingMode<sup>18+</sup> | string | No | Yes | Rounding mode. The value can be:<br>- **ceil**: rounding up.<br>- **floor**: rounding down.<br>- **expand**: rounding away from 0.<br>- **trunc**: rounding toward 0.<br>- **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.<br>- **halfFloor**: half-rounding down; that is, rounding up when the decimal number is greater than half of the increment, and rounding down otherwise.<br>- **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.<br>- **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.<br>- "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.<br>The default value is **halfExpand**.<br>**Atomic service API**: This API can be used in atomic services since API version 18.| 586 587> **NOTE** 588> 589> - For details about the meaning or display effect of different values, see [Number and Unit of Measurement Formatting](../../internationalization/i18n-numbers-weights-measures.md). 590 591## Collator<sup>8+</sup> 592 593### constructor<sup>(deprecated)</sup> 594 595constructor() 596 597> This API is supported since API version 8 and deprecated since API version 20. You are advised to use [Intl.Collator() constructor](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Collator/Collator) instead. 598 599Creates a **Collator** object. 600 601**Atomic service API**: This API can be used in atomic services since API version 12. 602 603**System capability**: SystemCapability.Global.I18n 604 605**Example** 606 ```ts 607 // Create a Collator object using the current system locale ID. 608 let collator = new intl.Collator(); 609 ``` 610 611 612### constructor<sup>(deprecated)</sup> 613 614constructor(locale: string | Array<string>, options?: CollatorOptions) 615 616> This method is supported since API version 8 and deprecated since API version 20. You are advised to use [Intl.Collator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Collator/Collator) instead. 617 618Creates a **Collator** object. 619 620**Atomic service API**: This API can be used in atomic services since API version 12. 621 622**System capability**: SystemCapability.Global.I18n 623 624**Parameters** 625 626| Name | Type | Mandatory | Description | 627| -------------------- | ------------------------------------ | ---- | ---------------------------- | 628| 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. | 629| options | [CollatorOptions](#collatoroptions8) | No | Options for creating a **Collator** object. | 630 631**Example** 632 ```ts 633 // Create a Collator object with the locale ID being zh-CN, localeMatcher being lookup, and usage being sort. 634 let collator = new intl.Collator("zh-CN", {localeMatcher: "lookup", usage: "sort"}); 635 ``` 636 637 638### compare<sup>(deprecated)</sup> 639 640compare(first: string, second: string): number 641 642> This API is supported since API version 8 and deprecated since API version 20. You are advised to use (https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Collator/compare) instead. 643 644Compares two strings based on the specified collation rules. 645 646**Atomic service API**: This API can be used in atomic services since API version 12. 647 648**System capability**: SystemCapability.Global.I18n 649 650**Parameters** 651 652| Name | Type | Mandatory | Description | 653| ------ | ------ | ---- | ------------ | 654| first | string | Yes | First string to compare. | 655| second | string | Yes | Second string to compare.| 656 657**Return value** 658 659| Type | Description | 660| ------ | ---------------------------------------- | 661| number | Comparison result.<br>- If the value is a negative number, the first string comes before the second string.<br>- If the value is **0**, the first and second strings are in the same sequence.<br>- If the value is a positive number, the first string is comes after the second string.| 662 663**Example** 664 ```ts 665 // Create a Collator object with the locale ID being en-GB. 666 let collator = new intl.Collator("en-GB"); 667 // Compare the sequence of the first and second strings. 668 let compareResult = collator.compare("first", "second"); // compareResult = -1 669 ``` 670 671 672### resolvedOptions<sup>(deprecated)</sup> 673 674resolvedOptions(): CollatorOptions 675 676> This API is supported since API version 8 and deprecated since API version 20. You are advised to use [Intl.Collator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Collator/resolvedOptions) instead. 677 678Obtains the options for creating a **Collator** object. 679 680**Atomic service API**: This API can be used in atomic services since API version 12. 681 682**System capability**: SystemCapability.Global.I18n 683 684**Return value** 685 686| Type | Description | 687| ------------------------------------ | ----------------- | 688| [CollatorOptions](#collatoroptions8) | Options for creating a **Collator** object.| 689 690**Example** 691 ```ts 692 let collator = new intl.Collator("zh-Hans", { usage: 'sort', ignorePunctuation: true }); 693 // Obtain the options of the Collator object. 694 let options = collator.resolvedOptions(); 695 let usage = options.usage; // usage = "sort" 696 let ignorePunctuation = options.ignorePunctuation; // ignorePunctuation = true 697 ``` 698 699 700## CollatorOptions<sup>8+</sup> 701 702Defines the options for creating a **Collator** object. 703 704Since API version 9, the attributes in **CollatorOptions** are optional. 705 706**Atomic service API**: This API can be used in atomic services since API version 12. 707 708**System capability**: SystemCapability.Global.I18n 709 710| Name | Type | Read-Only | Optional | Description | 711| ----------------- | ------- | ---- | ---- | ---------------------------------------- | 712| localeMatcher<sup>(deprecated)</sup> | string | No | Yes | This parameter is supported since API version 8 and is deprecated since API version 20. You are advised to use **Intl.CollatorOptions.localeMatcher** instead. For details, see [Intl.Collator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Collator/Collator#options).<br>Locale matching algorithm. The options are as follows:<br>**lookup**: fuzzy match.<br>**best fit**: exact match.<br>The default value is **best fit**.| 713| usage<sup>(deprecated)</sup> | string | No | Yes | This parameter is supported since API version 8 and is deprecated since API version 20. You are advised to use **Intl.CollatorOptions.usage** instead. For details, see [Intl.Collator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Collator/Collator#options).<br>Purpose of comparison. The options are as follows:<br>- **sort**: sorting.<br>- **search**: search for matched strings.<br>The default value is **sort**. | 714| sensitivity<sup>(deprecated)</sup> | string | No | Yes | This parameter is supported since API version 8 and is deprecated since API version 20. You are advised to use **Intl.CollatorOptions.sensitivity** instead. For details, see [Intl.Collator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Collator/Collator#options).<br>Differences in the strings that lead to non-zero return values. The options are as follows:<br>- **base**: Different letters are considered unequal, for example, 'a' ≠ 'b', 'a' = 'á', 'a' = 'A'.<br>- **accent**: Different letters or same letters with different pronunciations are considered unequal, for example, 'a' ≠ 'b', 'a' ≠ 'á', 'a' = 'A'.<br>- **case**: Different letters or same letters with different cases are considered unequal, for example, 'a' ≠ 'b', 'a' = 'á', 'a' ≠ 'A'.<br>- **variant**: Different letters, pronunciations, other distinguishing marks, or cases are all considered unequal, for example, 'a' ≠ 'b', 'a' ≠ 'á', 'a' ≠ 'A'.<br>The default value is **variant**. | 715| ignorePunctuation<sup>(deprecated)</sup> | boolean | No | Yes | This parameter is supported since API version 8 and is deprecated since API version 20. You are advised to use **Intl.CollatorOptions.ignorePunctuation** instead. For details, see [Intl.Collator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Collator/Collator#options).<br>Whether to ignore punctuation. The value **true** means to ignore punctuation, and the value **false** means the opposite.<br>The default value is **false**. | 716| collation<sup>(deprecated)</sup> | string | No | Yes | This parameter is supported since API version 8 and is deprecated since API version 20. You are advised to use **Intl.CollatorOptions.collation** instead. For details, see [Intl.Collator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Collator/Collator#options).<br>Collation rules for the locale. The value can be:<br>**big5han**: Pinyin sorting for Latin letters.<br>**compat**: compatibility sorting, only for Arabic.<br>**dict**: dictionary-style sorting, only for Singhalese.<br>**direct**: binary code point sorting.<br>**ducet**: sorting according to the Unicode collation element table.<br>**eor**: sorting according to the European collation rules.<br>**gb2312**: Pinyin sorting, only for Chinese.<br>**phonebk**: phone book-style sorting.<br>**phonetic**: phonetic sorting.<br>**pinyin**: Pinyin sorting.<br>**reformed**: reformed sorting, only for Swedish.<br>**searchjl**: special sorting for Korean initial consonant search.<br>**stroke**: stroke sorting for Chinese.<br>**trad**: traditional-style sorting, for example, Spanish.<br>unihan: radical-stroke sorting for Han characters, only for Chinese, Japanese, and Korean.<br>**zhuyin**: Zhuyin sorting, only for Chinese.<br>The default value is **default**.| 717| numeric<sup>(deprecated)</sup> | boolean | No | Yes | This parameter is supported since API version 8 and is deprecated since API version 20. You are advised to use **Intl.CollatorOptions.numeric** instead. For details, see [Intl.Collator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Collator/Collator#options).<br>Whether numeric sorting is used. The options are as follows:<br>- **true**: Numeric sorting is used. For example, '1' < '2' < '10' < '11'.<br>- **false**: Numeric sorting is not used. For example, '1' < '10' < '11' < '2'.<br>The default value is **false**. | 718| caseFirst<sup>(deprecated)</sup> | string | No | Yes | This parameter is supported since API version 8 and is deprecated since API version 20. You are advised to use **Intl.CollatorOptions.caseFirst** instead. For details, see [Intl.Collator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Collator/Collator#options).<br>Whether case is taken into account for the locale's collation rules. The value can be:<br>**upper**: Uppercase letters come first.<br>**lower**: Lowercase letters come first.<br>- **false**: The default collation rules of the locale are used.<br>The default value is **false**.| 719 720 721## PluralRules<sup>8+</sup> 722 723### constructor<sup>(deprecated)</sup> 724 725constructor() 726 727> This API is supported since API version 8 and deprecated since API version 20. You are advised to use [Intl.PluralRules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/PluralRules/PluralRules) instead. 728 729Creates a **PluralRules** object to obtain the singular-plural type of numbers. 730 731**Atomic service API**: This API can be used in atomic services since API version 12. 732 733**System capability**: SystemCapability.Global.I18n 734 735**Example** 736 ```ts 737 // Create a PluralRules object using the current system locale ID. 738 let pluralRules = new intl.PluralRules(); 739 ``` 740 741 742### constructor<sup>(deprecated)</sup> 743 744constructor(locale: string | Array<string>, options?: PluralRulesOptions) 745 746> This API is supported since API version 8 and deprecated since API version 20. You are advised to use [Intl.PluralRules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/PluralRules/PluralRules) instead. 747 748Creates a **PluralRules** object to obtain the singular-plural type of numbers. 749 750**Atomic service API**: This API can be used in atomic services since API version 12. 751 752**System capability**: SystemCapability.Global.I18n 753 754**Parameters** 755 756| Name | Type | Mandatory | Description | 757| -------------------- | ---------------------------------------- | ---- | ---------------------------- | 758| 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.| 759| options | [PluralRulesOptions](#pluralrulesoptions8) | No | Options for creating a **PluralRules** object. | 760 761**Example** 762```ts 763// Create a PluralRules object with the locale ID being zh-CN, localeMatcher being lookup, and type being cardinal. 764let pluralRules: intl.PluralRules = new intl.PluralRules('zh-CN', { localeMatcher: 'lookup', type: 'cardinal' }); 765``` 766 767### select<sup>(deprecated)</sup> 768 769select(n: number): string 770 771> This API is supported since API version 8 and deprecated since API version 20. You are advised to use [Intl.PluralRules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/PluralRules/select) instead. 772 773Obtains the singular-plural type of the specified number. 774 775**Atomic service API**: This API can be used in atomic services since API version 12. 776 777**System capability**: SystemCapability.Global.I18n 778 779**Parameters** 780 781| Name | Type | Mandatory | Description | 782| ---- | ------ | ---- | ------------ | 783| n | number | Yes | Number for which the singular-plural type is to be obtained.| 784 785**Return value** 786 787| Type | Description | 788| ------ | ---------------------------------------- | 789| string | Singular-plural type. The value can be any of the following: **zero**, **one**, **two**, **few**, **many**, **others**.<br>For details about the meanings of different values, see [Language Plural Rules](https://www.unicode.org/cldr/charts/45/supplemental/language_plural_rules.html).| 790 791**Example** 792 ```ts 793 // Create a PluralRules object with the locale ID being zh-Hans. 794 let zhPluralRules = new intl.PluralRules("zh-Hans"); 795 // Determine the singular-plural type corresponding to number 1 in locale zh-Hans. 796 let plural = zhPluralRules.select(1); // plural = other 797 798 // Create a PluralRules object with the locale ID being en-US. 799 let enPluralRules = new intl.PluralRules("en-US"); 800 // Determine the singular-plural type corresponding to number 1 in locale en-US. 801 plural = enPluralRules.select(1); // plural = one 802 ``` 803 804 805## PluralRulesOptions<sup>8+</sup> 806 807Defines the options for creating a **PluralRules** object. Since API version 9, the **PluralRulesOptions** attribute is changed from mandatory to optional. 808 809**Atomic service API**: This API can be used in atomic services since API version 12. 810 811**System capability**: SystemCapability.Global.I18n 812 813| Name | Type | Read-Only | Optional | Description | 814| ------------------------ | ------ | ---- | ---- | ---------------------------------------- | 815| localeMatcher<sup>(deprecated)</sup> | string | No | Yes | This parameter is supported since API version 8 and is deprecated since API version 20. You are advised to use **Intl.PluralRulesOptions.localeMatcher** instead. For details, see [Intl.PluralRules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/PluralRules/PluralRules#options).<br>Locale matching algorithm. The value can be **lookup** or **best fit**.<br>The default value is **best fit**.| 816| type<sup>(deprecated)</sup> | string | No | Yes | This parameter is supported since API version 8 and is deprecated since API version 20. You are advised to use **Intl.PluralRulesOptions.type** instead. For details, see [Intl.PluralRules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/PluralRules/PluralRules#options).<br>Collation type. The value can be **cardinal** or **ordinal**.<br>The default value is **cardinal**.<br>The value **cardinal** indicates a cardinal number and the value **ordinal** indicates an ordinal number. | 817| minimumIntegerDigits<sup>(deprecated)</sup> | number | No | Yes | This parameter is supported since API version 8 and is deprecated since API version 20. You are advised to use **Intl.PluralRulesOptions.minimumIntegerDigits** instead. For details, see [Intl.PluralRules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/PluralRules/PluralRules#options).<br>Minimum number of digits allowed in the integer part of a number. The value ranges from **1** to **21**.<br>The default value is **1**. | 818| minimumFractionDigits<sup>(deprecated)</sup> | number | No | Yes | This parameter is supported since API version 8 and is deprecated since API version 20. You are advised to use **Intl.PluralRulesOptions.minimumFractionDigits** instead. For details, see [Intl.PluralRules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/PluralRules/PluralRules#options).<br>Minimum number of digits in the fraction part of a number. The value ranges from **0** to **20**.<br>The default value is **0**. | 819| maximumFractionDigits<sup>(deprecated)</sup> | number | No | Yes | This parameter is supported since API version 8 and is deprecated since API version 20. You are advised to use **Intl.PluralRulesOptions.maximumFractionDigits** instead. For details, see [Intl.PluralRules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/PluralRules/PluralRules#options).<br>Maximum number of digits in the fraction part of a number. The value ranges from **1** to **21**.<br>The default value is **3**. | 820| minimumSignificantDigits<sup>(deprecated)</sup> | number | No | Yes | This parameter is supported since API version 8 and is deprecated since API version 20. You are advised to use **Intl.PluralRulesOptions.maximumFractionDigits** instead. For details, see [Intl.PluralRules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/PluralRules/PluralRules#options).<br>Minimum number of the least significant digits. The value ranges from **1** to **21**.<br>The default value is **1**. | 821| maximumSignificantDigits<sup>(deprecated)</sup> | number | No | Yes | This parameter is supported since API version 8 and is deprecated since API version 20. You are advised to use **Intl.PluralRulesOptions.maximumSignificantDigits** instead. For details, see [Intl.PluralRules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/PluralRules/PluralRules#options).<br>Maximum number of the least significant digits. The value ranges from **1** to **21**.<br>The default value is **21**. | 822 823 824## RelativeTimeFormat<sup>(deprecated)</sup> 825 826### constructor<sup>(deprecated)</sup> 827 828constructor() 829 830> This API is supported since API version 8 and deprecated since API version 20. You are advised to use [Intl.RelativeTimeFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat) instead. 831 832Creates a **RelativeTimeFormat** object. 833 834**Atomic service API**: This API can be used in atomic services since API version 12. 835 836**System capability**: SystemCapability.Global.I18n 837 838**Example** 839```ts 840// Create a RelativeTimeFormat object using the current system locale ID. 841let formatter: intl.RelativeTimeFormat = new intl.RelativeTimeFormat(); 842``` 843 844 845### constructor<sup>(deprecated)</sup> 846 847constructor(locale: string | Array<string>, options?: RelativeTimeFormatInputOptions) 848 849> This API is supported since API version 8 and deprecated since API version 20. You are advised to use [Intl.RelativeTimeFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat) instead. 850 851Creates a **RelativeTimeFormat** object. 852 853**Atomic service API**: This API can be used in atomic services since API version 12. 854 855**System capability**: SystemCapability.Global.I18n 856 857**Parameters** 858 859| Name | Type | Mandatory | Description | 860| -------------------- | ---------------------------------------- | ---- | ---------------------------- | 861| 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.| 862| options | [RelativeTimeFormatInputOptions](#relativetimeformatinputoptionsdeprecated) | No | Options for creating a **RelativeTimeFormat** object. | 863 864**Example** 865```ts 866// Create a RelativeTimeFormat object with the locale ID being zh-CN, localeMatcher being lookup, and style being long. 867let formatter: intl.RelativeTimeFormat = new intl.RelativeTimeFormat('zh-CN', { 868 localeMatcher: 'lookup', 869 numeric: 'always', 870 style: 'long' 871}); 872``` 873 874 875### format<sup>(deprecated)</sup> 876 877format(value: number, unit: string): string 878 879> This API is supported since API version 8 and deprecated since API version 20. You are advised to use [Intl.RelativeTimeFormat.format()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/format) instead. 880 881Formats a relative time. 882 883**Atomic service API**: This API can be used in atomic services since API version 12. 884 885**System capability**: SystemCapability.Global.I18n 886 887**Parameters** 888 889| Name | Type | Mandatory | Description | 890| ----- | ------ | ---- | ---------------------------------------- | 891| value | number | Yes | Value to format. | 892| unit | string | Yes | Unit of the relative time.<br>The value can be any of the following: **year**, **quarter**, month**, **week**, **day**, **hour**, **minute**, or **second**.| 893 894**Return value** 895 896| Type | Description | 897| ------ | ---------- | 898| string | Relative time after formatting.| 899 900**Example** 901```ts 902// Create a RelativeTimeFormat object with the locale ID being zh-CN. 903let formatter: intl.RelativeTimeFormat = new intl.RelativeTimeFormat('zh-CN'); 904// Obtain the localized representation (in unit of quarter) of number 3 in locale zh-CN. 905let formatResult: string = formatter.format(3, 'quarter'); // formatResult = '3 quarters later' 906``` 907 908 909### formatToParts<sup>(deprecated)</sup> 910 911formatToParts(value: number, unit: string): Array<object> 912 913> This API is supported since API version 8 and deprecated since API version 20. You are advised to use [Intl.RelativeTimeFormat.formatToParts()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/formatToParts) instead. 914 915Formats the relative time 916 917**Atomic service API**: This API can be used in atomic services since API version 12. 918 919**System capability**: SystemCapability.Global.I18n 920 921**Parameters** 922 923| Name | Type | Mandatory | Description | 924| ----- | ------ | ---- | ---------------------------------------- | 925| value | number | Yes | Value to format. | 926| unit | string | Yes | Unit of the relative time.<br>The value can be any of the following: **year**, **quarter**, month**, **week**, **day**, **hour**, **minute**, or **second**.| 927 928**Return value** 929 930| Type | Description | 931| ------------------- | --------------------------- | 932| Array<object> | to parts.| 933 934**Example** 935```ts 936// Create a RelativeTimeFormat object with the locale ID being en and numeric being auto. 937let formatter: intl.RelativeTimeFormat = new intl.RelativeTimeFormat('en', { numeric: 'auto' }); 938let parts: Array<object> = formatter.formatToParts(10, 'seconds'); // parts = [ {type: 'literal', value: 'in'}, {type: 'integer', value: 10, unit: 'second'}, {type: 'literal', value: 'seconds'} ] 939``` 940 941 942### resolvedOptions<sup>(deprecated)</sup> 943 944resolvedOptions(): RelativeTimeFormatResolvedOptions 945 946> This API is supported since API version 8 and deprecated since API version 20. You are advised to use [Intl.RelativeTimeFormat.resolvedOptions()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/resolvedOptions) instead. 947 948Defines the formatting options for a **RelativeTimeFormat** object. 949 950**Atomic service API**: This API can be used in atomic services since API version 12. 951 952**System capability**: SystemCapability.Global.I18n 953 954**Return value** 955 956| Type | Description | 957| ---------------------------------------- | --------------------------------- | 958| [RelativeTimeFormatResolvedOptions](#relativetimeformatresolvedoptionsdeprecated) | Options for the **RelativeTimeFormat** object.| 959 960**Example** 961```ts 962// Create a RelativeTimeFormat object with the locale ID being en-GB. 963let formatter: intl.RelativeTimeFormat = new intl.RelativeTimeFormat('en-GB', { style: 'short' }); 964// Obtain the options of the RelativeTimeFormat object. 965let options: intl.RelativeTimeFormatResolvedOptions = formatter.resolvedOptions(); 966let style: string = options.style; // style = 'short' 967``` 968 969 970## RelativeTimeFormatInputOptions<sup>(deprecated)</sup> 971 972> This API is supported since API version 8 and deprecated since API version 20. You are advised to use [Intl.RelativeTimeFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/RelativeTimeFormat#options) instead. 973 974Defines the configuration options for a **RelativeTimeFormat** object. 975 976Since API version 9, the attributes in **RelativeTimeFormatInputOptions** are optional. 977 978**Atomic service API**: This API can be used in atomic services since API version 12. 979 980**System capability**: SystemCapability.Global.I18n 981 982| Name | Type | Read-Only | Optional |Description | 983| ------------- | ------ | ---- | ---- | ---------------------------------------- | 984| localeMatcher | string | No | Yes | Locale matching algorithm. The value can be **lookup** or **best fit**.<br>The default value is **best fit**.| 985| numeric | string | No | Yes | Format of the output result. It determines whether numeric values are used to represent relative dates or times in the formatting result. The value can be **always** or **auto**.<br>The default value is **always**. | 986| style | string | No | Yes | Length of an internationalized message. The value can be **long**, **short**, or **narrow**.<br>The default value is **long**.| 987 988> **NOTE** 989> 990> For details about the display effects of **numeric** and **style**, see [Date and Time Formatting](../../internationalization/i18n-time-date.md#relative-time-formatting). 991 992## RelativeTimeFormatResolvedOptions<sup>(deprecated)</sup> 993 994> This API is supported since API version 8 and deprecated since API version 20. You are advised to use [Intl.RelativeTimeFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/resolvedOptions#return_value) instead. 995 996Represents the formatting options for the **RelativeTimeFormat** object. 997 998**Atomic service API**: This API can be used in atomic services since API version 12. 999 1000**System capability**: SystemCapability.Global.I18n 1001 1002| Name | Type | Read-Only | Optional |Description | 1003| --------------- | ------ | ---- | ---- | ---------------------------------------- | 1004| locale | string | No | No | Locale ID, including the language, script, and region. | 1005| numeric | string | No | No | Format of the output result. It determines whether numeric values are used to represent relative dates or times in the formatting result. The value can be **always** or **auto**. | 1006| style | string | No | No | Length of an internationalized message. The value can be **long**, **short**, or **narrow**.| 1007| numberingSystem | string | No | No | Numbering system. The value can be:<br>**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**.| 1008 1009> **NOTE** 1010> 1011> For details about the display effects of **numeric** and **style**, see [Date and Time Formatting](../../internationalization/i18n-time-date.md#relative-time-formatting). 1012 1013## Appendix 1014 1015**Date and Time Formatting Options** 1016 1017The following tables use 13:04:00 and 00:25:00 on September 17, 2021 and locales **zh-CN** and **en** as examples to illustrate the values and display results of [DateTimeOptions](#datetimeoptionsdeprecated). 1018 1019**Table 1** Date display format (dateStyle) 1020 1021| Value | Description | 2021-09-17 13:04:00 for Locale zh-CN| 2021-09-17 13:04:00 for Locale en| 1022| ------ | --------------------------------------- | ------------------------------------------ | ---------------------------------------- | 1023| full | Complete date display, including the year, month, day, and week.| 2021年9月17日星期五 | Friday, September 17, 2021 | 1024| long | Long date display, including the year, month, and day. | 2021年9月17日 | September 17, 2021 | 1025| short | Short date display, including the year, month, and day. | 2021/9/17 | 9/17/21 | 1026| medium | Medium date display, including the year, month, and day. | 2021年9月17日 | Sep 17, 2021 | 1027 1028**Table 2** Time display format (timeStyle) 1029 1030| Value | Description| 2021-09-17 13:04:00 for Locale zh-CN| 2021-09-17 13:04:00 for Locale en| 1031| ------ | ------------- | -------- | -------- | 1032| full | Complete time display, including the time zone and time accurate to seconds.| 中国标准时间 13:04:00 | 13:04:00 China Standard Time | 1033| long | Long time display, including the time zone expressed in the format of GMT + time zone offset and time accurate to seconds.| GMT+8 13:04:00 | 13:04:00 GMT+8 | 1034| short | Short time display, including hour and minute.| 13:04 | 13:04 | 1035| medium | Medium time display, including hour, minute, and second.| 13:04:00 | 13:04:00 | 1036 1037**Table 3** Year display format (year) 1038 1039| Value| Description| 2021-09-17 13:04:00 for Locale zh-CN| 2021-09-17 13:04:00 for Locale en| 1040| -------- | --------- | -------- | -------- | 1041| numeric | Complete year| 2021年 | 2021 | 1042| 2-digit | 2-digit year display| 21年 | 21 | 1043 1044**Table 4** Weekday display format (weekday) 1045 1046| Value| Description| 2021-09-17 13:04:00 for Locale zh-CN| 2021-09-17 13:04:00 for Locale en| 1047| -------- | ------- | -------- | -------- | 1048| long | Long weekday display| 星期五 | Friday | 1049| short | Short weekday display.| 周五 | Fri | 1050| narrow | Narrow weekday display.| 五 | F | 1051 1052**Table 5** Hour cycle format (hourCycle) 1053 1054| Value| Description | 2021-09-17 13:04:00 for Locale zh-CN| 2021-09-17 00:25:00 for Locale zh-CN| 1055| --- | --------------- | -------------------------------------------- | ------------------------------------------- | 1056| h11 | Use of 0 to 11 to indicate the hour| 下午1:04 | 上午0:25 | 1057| h12 | Use of 1 to 12 to indicate the hour| 下午1:04 | 上午12:25 | 1058| h23 | Use of 0 to 23 to indicate the hour| 13:04 | 00:25 | 1059| h24 | Use of 1 to 24 to indicate the hour| 13:04 | 24:25 | 1060 1061> **NOTE** 1062> 1063> The preceding table shows the display effect for different values of **hourCycle** when **dateStyle** or **timeStyle** is not set. 1064 1065 1066**Table 6** Hour cycle format (hourCycle) 1067 1068| Value| Description | 2021-09-17 13:04:00 for Locale zh-CN| 2021-09-17 00:25:00 for Locale zh-CN| 1069| --- | --------------- | -------------------------------------------- | ------------------------------------------- | 1070| h11 | Use of 1 to 24 to indicate the hour| 下午13:04 | 上午24:25 | 1071| h12 | Use of 1 to 12 to indicate the hour| 下午1:04 | 上午12:25 | 1072| h23 | Use of 0 to 11 to indicate the hour| 1:04 | 0:25 | 1073| h24 | Use of 0 to 23 to indicate the hour| 13:04 | 0:25 | 1074 1075> **NOTE** 1076> 1077> The preceding table shows the display effect for different values of **hourCycle** when **dateStyle** or **timeStyle** is set. 1078 1079**Table 7** Month format (month) 1080 1081| Value| Description| 2021-09-17 13:04:00 for Locale zh-CN| 2021-09-17 13:04:00 for Locale en| 1082| -------- | --------- | -------- | -------- | 1083| numeric | Display of the month as a number| 9月 | 9 | 1084| 2-digit | Display of the month in two digits| 09月 | 09 | 1085| long | Long month display| 九月 | September | 1086| short | Short month display| 9月 | Sep | 1087| narrow | Narrow month display| 9 | S | 1088 1089**Table 8** Localized representation of time zone names (timeZoneName) 1090 1091| Value | Description | 2021-09-17 13:04:00 for Locale zh-CN| 2021-09-17 13:04:00 for Locale en| 1092| ----- | ------------------ | -------------------------------------------- | ---------------------------------------- | 1093| long | Long time zone name| 中国标准时间 | China Standard Time | 1094| short | Short time zone name| GMT+8 | GMT+8 | 1095 1096**Table 9** Era display format (era) 1097 1098| Value| Description| 2021-09-17 13:04:00 for Locale zh-CN| 2021-09-17 13:04:00 for Locale en| 1099| -------- | ------ | -------- | -------- | 1100| long | Long epoch display| 公元 | Anno Domini | 1101| short | Short epoch display| 公元 | AD | 1102| narrow | Narrow epoch display| 公元 | A | 1103 1104**Table 10** Time period format (dayPeriod) 1105 1106| Value| Description| 2021-09-17 13:04:00 for Locale zh-CN| 2021-09-17 13:04:00 for Locale en| 1107| -------- | ------ | -------- | -------- | 1108| long | Long time period display| 下午 | in the afternoon | 1109| short | Short time period display| 下午 | in the afternoon | 1110| narrow | Narrow time period display| 下午 | in the afternoon | 1111 1112<!--no_check-->