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, compact display, rounding mode, rounding priority, rounding increment, number display format, and numbering system. 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// Rounding mode 124let numberFormat5 : intl.NumberFormat = new intl.NumberFormat('en', 125 { 126 roundingMode: 'trunc', 127 maximumSignificantDigits: 2 128 }); 129console.log(numberFormat5.format(2.28)); // 2.2 130console.log(numberFormat5.format(-2.25)); // -2.2 131 132// Rounding priority 133let options : intl.NumberOptions = { 134 roundingPriority: 'lessPrecision', 135 maximumFractionDigits: 3, 136 maximumSignificantDigits: 2 137}; 138let numberFormat6 : intl.NumberFormat = new intl.NumberFormat('en', options); 139console.log(numberFormat6.format(1.23456)); // 1.2 140 141// Rounding increment 142let numOptions : intl.NumberOptions = { 143 style: "currency", 144 currency: "USD", 145 roundingIncrement: 5, 146 maximumFractionDigits: 2, 147 roundingMode: "halfCeil" 148}; 149let numberFormat7 : intl.NumberFormat = new intl.NumberFormat('en-US', numOptions); 150console.log(numberFormat7.format(11.21)); // $11.20 151``` 152 153### Number Range Formatting 154 155Number range formatting is implemented through the [formatRange](../reference/apis-localization-kit/js-apis-intl.md#formatrange-1) API of the [NumberFormat](../reference/apis-localization-kit/js-apis-intl.md#numberformat) class. The development procedure is as follows: 156 1571. Import the **intl** module. 158 ```ts 159 import { intl } from '@kit.LocalizationKit'; 160 ``` 161 1622. Create a **NumberFormat** object. 163 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. 164 The **NumberFormat** constructor allows you to set different number formatting formats by using **NumberOptions**. For details, see Table 1 to Table 8. 165 166 ```ts 167 let numberFormat: intl.NumberFormat = new intl.NumberFormat(locale: string | Array<string>, options?: NumberOptions); 168 ``` 169 1703. Format the start and end numbers based on the configuration of **numberFormat**. 171 ```ts 172 let formattedNumber: string = numberFormat.formatRange(startRange: number, endRange: number); 173 ``` 174 175**Development Example** 176 177```ts 178// Import the intl module. 179import { intl } from '@kit.LocalizationKit'; 180 181// Number range formatting 182let options : intl.NumberOptions = { 183 style: "currency", 184 currency: "EUR", 185 maximumFractionDigits: 0 186}; 187let numberRangeFormat : intl.NumberFormat = new intl.NumberFormat('es-ES', options); 188console.log(numberRangeFormat.formatRange(2, 8)); // 2-8 € 189console.log(numberRangeFormat.formatRange(2.9, 3.1)); // ~3 € 190``` 191 192 193### Currency and Unit Formatting 194 195Currency 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. 196 197**Currency Formatting Options** 198 199Assume that the currency unit is USD and the value is **-12300**. 200 201**Table 9** Currency sign (currencySign) 202 203| Value| Display Effect| 204| -------- | -------- | 205| standard | -US$12,300.00 | 206| accounting | (US$12,300.00) | 207 208**Table 10** Currency display (currencyDisplay) 209 210| Value| Display Effect| 211| -------- | -------- | 212| symbol | -US$12,300.00 | 213| narrowSymbol | -$12,300.00 | 214| code | -USD 12,300.00 | 215| name | -12,300.00 US dollars | 216 217**Unit Formatting Options** 218 219Assume that the unit name is hectare and the value is **-12300**. 220 221**Table 11** Unit display (unitDisplay) 222 223| Value| Display Effect| 224| -------- | -------- | 225| long | -12,3000 hectares | 226| short | -12,300 ha | 227| narrow | -12,300ha | 228 229**Table 12** Unit usage (unitUsage) 230 231| Value| Display Effect| 232| -------- | -------- | 233| Left unspecified| -12,300 ha | 234| default | -47.491 sq mi | 235| area-land-agricult | -30,393.962 ac | 236 237 238**Development Example** 239```ts 240// Import the intl module. 241import { intl } from '@kit.LocalizationKit'; 242 243// Format the currency. 244let numberFormat5 = new intl.NumberFormat('zh-CN', {style: 'currency', currency: 'USD'}); 245let formattedNumber5 = numberFormat5.format(123400); // formattedNumber5: US$123,400.00 246 247// Display the currency using its name. 248let numberFormat6 = new intl.NumberFormat('zh-CN', {style: 'currency', currency: 'USD', currencyDisplay: 'name'}); 249US$ let formattedNumber6 = numberFormat6.format(123400); // formattedNumber6: US$123,400.00 250 251// Format units of measurement. 252let numberFormat7 = new intl.NumberFormat('en-GB', {style: 'unit', unit: 'hectare'}); 253let formattedNumber7 = numberFormat7.format(123400); // formattedNumber7: 123,400 ha 254 255// Format the units of measurement in the specified scenario, for example, area-land-agricult. 256let numberFormat8 = new intl.NumberFormat('en-GB', {style: 'unit', unit: 'hectare', unitUsage: 'area-land-agricult'}); 257let formattedNumber8 = numberFormat8.format(123400); // formattedNumber8: 304,928.041 ac 258``` 259 260 261### Units of Measurement Conversion 262 263Units 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: 264 2651. Import the **i18n** module. 266 ```ts 267 import { i18n } from '@kit.LocalizationKit'; 268 ``` 269 2702. Convert the unit of measurement. 271 272 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. 273 ```ts 274 let convertedUnit: string = i18n.I18NUtil.unitConvert(fromUnit: UnitInfo, toUnit: UnitInfo, value: number, locale: string, style?: string); 275 ``` 276 277**Formatting Style** 278 279Assume that **fromUnit** is **cup** (US unit), **toUnit** is **liter** (SI unit), and the value is **1000**. 280 281**Table 13** Formatting style (style) 282 283| Value| Display Effect| 284| -------- | -------- | 285| long | 236.588 liters | 286| short | 236.588 L | 287| narrow | 236.588L | 288 289**Development Example** 290 291```ts 292// Import the i18n module. 293import { i18n } from '@kit.LocalizationKit'; 294 295// Set the fromUnit and toUnit. 296let fromUnit: i18n.UnitInfo = {unit: 'cup', measureSystem: 'US'}; 297let toUnit: i18n.UnitInfo = {unit: 'liter', measureSystem: 'SI'}; 298 299// Convert the unit based on the locale en-US. 300let convertedUnit1 = i18n.I18NUtil.unitConvert(fromUnit, toUnit, 1000, 'en-US'); // convertedUnit1: 236.588 L 301 302// Display the complete unit. 303let convertedUnit2 = i18n.I18NUtil.unitConvert(fromUnit, toUnit, 1000, 'en-US', 'long'); // convertedUnit2: 236.588 liters 304``` 305