1# Number and Unit of Measurement Formatting 2 3## Use Cases 4 5In different countries and cultures, numbers, currencies, and units of measurement are expressed in different ways, including what symbols are used as decimal separators, how many digits are displayed after separators, and what currencies and units of measurement are used. Suppose you want to display the number 1000 on the application UI to indicate the price of a product. If the fixed format **1,000** is used, it may be considered as **1** in some European countries where a comma is used as a decimal point. Formatting is therefore needed to ensure that numbers, currencies, and units of measurement are displayed on the application UI in line with local user habits. 6 7## How to Develop 8 9### Number Formatting 10 11Number formatting is implemented through the [format](../reference/apis-localization-kit/js-apis-intl.md#format-1) API of the [NumberFormat](../reference/apis-localization-kit/js-apis-intl.md#numberformat) class. The development procedure is as follows: 12 131. Import the **intl** module. 14 ```ts 15 import { intl } from '@kit.LocalizationKit'; 16 ``` 17 182. Create a **NumberFormat** object. 19 If you pass in a list of locales, the first valid locale will be used. If you do not pass in any locale, the current system locale will be used. 20 The **NumberFormat** constructor allows you to set different number formatting formats by using **NumberOptions**. For details, see Table 1 to Table 8. 21 22 ```ts 23 let numberFormat: intl.NumberFormat = new intl.NumberFormat(locale: string | Array<string>, options?: NumberOptions); 24 ``` 25 263. Format numbers based on the configuration of **numberFormat**. 27 ```ts 28 let formattedNumber: string = numberFormat.format(number: number); 29 ``` 30 314. Obtain **NumberOptions** and view the configuration of formatting options. 32 ```ts 33 let options: intl.NumberOptions = numberFormat.resolvedOptions(); 34 ``` 35 36**Number Formatting Options** 37 38You can use [NumberOptions](../reference/apis-localization-kit/js-apis-intl.md#numberoptions) to configure number formatting options, including minimum number of integer digits, minimum and maximum numbers of fraction digits, minimum and maximum numbers of significant digits, use of grouping for display, number notation, and compact display. Supported number display formats include decimal, percent, currency, and unit. 39 40The following uses **123000.123** as an example to show the parameter values and corresponding display effects. 41 42**Table 1** Minimum number of integer digits (minimumIntegerDigits) 43 44| Value| Display Effect| 45| -------- | -------- | 46| 6 | 123,000.123 | 47| 7 | 0,123,000.123 | 48 49**Table 2** Minimum number of decimal places (minimumFractionDigits) 50 51| Value| Display Effect| 52| -------- | -------- | 53| 3 | 123,000.123 | 54| 4 | 123,000.1230 | 55 56**Table 3** Maximum number of fraction digits (maximumFractionDigits) 57 58| Value| Display Effect| 59| -------- | -------- | 60| 3 | 123,000.123 | 61| 2 | 123,000.12 | 62 63**Table 4** Minimum number of significant digits (minimumSignificantDigits) 64 65| Value| Display Effect| 66| -------- | -------- | 67| 9 | 123,000.123 | 68| 10 | 123,000.1230 | 69 70**Table 5** Maximum number of significant digits (maximumSignificantDigits) 71 72| Value| Display Effect| 73| -------- | -------- | 74| 9 | 123,000.123 | 75| 8 | 123,000.12 | 76 77**Table 6** Use of grouping for display (useGrouping) 78 79| Value| Display Effect| 80| -------- | -------- | 81| true | 123,000.123 | 82| false | 123000.123 | 83 84**Table 7** Number notation (notation) 85 86| Value| Display Effect| 87| -------- | -------- | 88| standard | 123,000.123 | 89| scientific | 1.230001E5 | 90| engineering | 123.000123E3 | 91| compact | 123K | 92 93**Table 8** Compact display (compactDisplay) 94 95| Value| Display Effect| 96| -------- | -------- | 97| short | 123K | 98| long | 123 thousand | 99 100 101**Development Example** 102 103```ts 104// Import the intl module. 105import { intl } from '@kit.LocalizationKit'; 106 107// Display numbers in scientific notation. 108let numberFormat1 = new intl.NumberFormat('zh-CN', {notation: 'scientific', maximumSignificantDigits: 3}); 109let formattedNumber1 = numberFormat1.format(123400); // formattedNumber1: 1.23E5 110 111// Display numbers in the compact format. 112let numberFormat2 = new intl.NumberFormat('zh-CN', {notation: 'compact', compactDisplay: 'short'}); 113let formattedNumber2 = numberFormat2.format(123400); // formattedNumber2: 120 thousand 114 115// Display the signs in numbers. 116let numberFormat3 = new intl.NumberFormat('zh-CN', {signDisplay: 'always'}); 117let formattedNumber3 = numberFormat3.format(123400); // formattedNumber3: +123,400 118 119// Display numbers in the percentage format. 120let numberFormat4 = new intl.NumberFormat('zh-CN', {style: 'percent'}); 121let formattedNumber4 = numberFormat4.format(0.25); // formattedNumber4: 25% 122``` 123 124 125### Currency and Unit Formatting 126 127Currency and unit formatting is based on number formatting. When creating a **NumberFormat** object for currency and unit formatting, set the number formatting style to currency and unit, respectively. Similarly, this can be done through [NumberOptions](../reference/apis-localization-kit/js-apis-intl.md#numberoptions). The following tables show the parameter values and corresponding display effects. 128 129**Currency Formatting Options** 130 131Assume that the currency unit is USD and the value is **-12300**. 132 133**Table 9** Currency sign (currencySign) 134 135| Value| Display Effect| 136| -------- | -------- | 137| standard | -US$12,300.00 | 138| accounting | (US$12,300.00) | 139 140**Table 10** Currency display (currencyDisplay) 141 142| Value| Display Effect| 143| -------- | -------- | 144| symbol | -US$12,300.00 | 145| narrowSymbol | -$12,300.00 | 146| code | -USD 12,300.00 | 147| name | -12,300.00 US dollars | 148 149**Unit Formatting Options** 150 151Assume that the unit name is hectare and the value is **-12300**. 152 153**Table 11** Unit display (unitDisplay) 154 155| Value| Display Effect| 156| -------- | -------- | 157| long | -12,3000 hectares | 158| short | -12,300 ha | 159| narrow | -12,300ha | 160 161**Table 12** Unit usage (unitUsage) 162 163| Value| Display Effect| 164| -------- | -------- | 165| Left unspecified| -12,300 ha | 166| default | -47.491 sq mi | 167| area-land-agricult | -30,393.962 ac | 168 169 170**Development Example** 171```ts 172// Import the intl module. 173import { intl } from '@kit.LocalizationKit'; 174 175// Format the currency. 176let numberFormat5 = new intl.NumberFormat('zh-CN', {style: 'currency', currency: 'USD'}); 177let formattedNumber5 = numberFormat5.format(123400); // formattedNumber5: US$123,400.00 178 179// Display the currency using its name. 180let numberFormat6 = new intl.NumberFormat('zh-CN', {style: 'currency', currency: 'USD', currencyDisplay: 'name'}); 181US$ let formattedNumber6 = numberFormat6.format(123400); // formattedNumber6: US$123,400.00 182 183// Format units of measurement. 184let numberFormat7 = new intl.NumberFormat('en-GB', {style: 'unit', unit: 'hectare'}); 185let formattedNumber7 = numberFormat7.format(123400); // formattedNumber7: 123,400 ha 186 187// Format the units of measurement in the specified scenario, for example, area-land-agricult. 188let numberFormat8 = new intl.NumberFormat('en-GB', {style: 'unit', unit: 'hectare', unitUsage: 'area-land-agricult'}); 189let formattedNumber8 = numberFormat8.format(123400); // formattedNumber8: 304,928.041 ac 190``` 191 192 193### Units of Measurement Conversion 194 195Units of measurement conversion and formatting are implemented by the [unitConvert](../reference/apis-localization-kit/js-apis-i18n.md#unitconvert9) API of the [I18NUtil](../reference/apis-localization-kit/js-apis-i18n.md#i18nutil9) class. The development procedure is as follows: 196 1971. Import the **i18n** module. 198 ```ts 199 import { i18n } from '@kit.LocalizationKit'; 200 ``` 201 2022. Convert the unit of measurement. 203 204 Convert the unit of measurement from **fromUnit** to **toUnit**, and format the unit based on the specified locale and formatting style. The display effect varies according to the style. For details, see Table 13. 205 ```ts 206 let convertedUnit: string = i18n.I18NUtil.unitConvert(fromUnit: UnitInfo, toUnit: UnitInfo, value: number, locale: string, style?: string); 207 ``` 208 209**Formatting Style** 210 211Assume that **fromUnit** is **cup** (US unit), **toUnit** is **liter** (SI unit), and the value is **1000**. 212 213**Table 13** Formatting style (style) 214 215| Value| Display Effect| 216| -------- | -------- | 217| long | 236.588 liters | 218| short | 236.588 L | 219| narrow | 236.588L | 220 221**Development Example** 222 223```ts 224// Import the i18n module. 225import { i18n } from '@kit.LocalizationKit'; 226 227// Set the fromUnit and toUnit. 228let fromUnit: i18n.UnitInfo = {unit: 'cup', measureSystem: 'US'}; 229let toUnit: i18n.UnitInfo = {unit: 'liter', measureSystem: 'SI'}; 230 231// Convert the unit based on the locale en-US. 232let convertedUnit1 = i18n.I18NUtil.unitConvert(fromUnit, toUnit, 1000, 'en-US'); // convertedUnit1: 236.588 L 233 234// Display the complete unit. 235let convertedUnit2 = i18n.I18NUtil.unitConvert(fromUnit, toUnit, 1000, 'en-US', 'long'); // convertedUnit2: 236.588 liters 236``` 237