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 format numbers, currencies, and units of measurement so that they 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 a list of locale IDs is passed, the first valid locale is used. If no locale is passed, the current system locale ID is 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 numeral 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 scientificFormat: intl.NumberFormat = new intl.NumberFormat('zh-CN', 109 { 110 notation: 'scientific', 111 maximumSignificantDigits: 3 112 }); 113let formattedNumber: string = scientificFormat.format(123400); // formattedNumber = '1.23E5' 114 115// Display numbers in the compact format. 116let compactFormat: intl.NumberFormat = new intl.NumberFormat('zh-CN', 117 { 118 notation: 'compact', 119 compactDisplay: 'short' 120 }); 121formattedNumber = compactFormat.format(123400); // formattedNumber = '12万)' 122 123// Display the signs in numbers. 124let signFormat: intl.NumberFormat = new intl.NumberFormat('zh-CN', { signDisplay: 'always' }); 125formattedNumber = signFormat.format(123400); // formattedNumber = '+123,400' 126 127// Display numbers in the percentage format. 128let percentFormat: intl.NumberFormat = new intl.NumberFormat('zh-CN', { style: 'percent' }); 129formattedNumber = percentFormat.format(0.25); // formattedNumber = '25%' 130 131// Rounding mode 132let truncFormat: intl.NumberFormat = new intl.NumberFormat('en', 133 { 134 roundingMode: 'trunc', 135 maximumSignificantDigits: 2 136 }); 137formattedNumber = truncFormat.format(2.28); // formattedNumber = '2.2' 138formattedNumber = truncFormat.format(-2.25); // formattedNumber = '-2.2' 139 140// Rounding priority 141let lessPrecisionOptions: intl.NumberOptions = { 142 roundingPriority: 'lessPrecision', 143 maximumFractionDigits: 3, 144 maximumSignificantDigits: 2 145}; 146let lessPrecisionFormat: intl.NumberFormat = new intl.NumberFormat('en', lessPrecisionOptions); 147formattedNumber = lessPrecisionFormat.format(1.23456); // formattedNumber = '1.2' 148 149// Rounding increment 150let halfCeilNumOptions: intl.NumberOptions = { 151 style: 'currency', 152 currency: 'USD', 153 roundingIncrement: 5, 154 maximumFractionDigits: 2, 155 roundingMode: 'halfCeil' 156}; 157let halfCeilFormat: intl.NumberFormat = new intl.NumberFormat('en-US', halfCeilNumOptions); 158formattedNumber = halfCeilFormat.format(11.21); // formattedNumber = '$11.20' 159``` 160 161### Number Range Formatting 162 163Number range formatting is implemented through the [formatRange](../reference/apis-localization-kit/js-apis-intl.md#formatrange18) API of the [NumberFormat](../reference/apis-localization-kit/js-apis-intl.md#numberformat) class. The development procedure is as follows: 164 1651. Import the **intl** module. 166 ```ts 167 import { intl } from '@kit.LocalizationKit'; 168 ``` 169 1702. Create a **NumberFormat** object. 171 If a list of locale IDs is passed, the first valid locale is used. If no locale is passed, the current system locale ID is used. 172 The **NumberFormat** constructor allows you to set different number formatting formats by using **NumberOptions**. For details, see Table 1 to Table 8. 173 174 ```ts 175 let numberFormat: intl.NumberFormat = new intl.NumberFormat(locale: string | Array<string>, options?: NumberOptions); 176 ``` 177 1783. Format the start and end numbers based on the configuration of **numberFormat**. 179 ```ts 180 let formattedNumber: string = numberFormat.formatRange(startRange: number, endRange: number); 181 ``` 182 183**Development Example** 184 185```ts 186// Import the intl module. 187import { intl } from '@kit.LocalizationKit'; 188 189// Number range formatting 190let options: intl.NumberOptions = { 191 style: 'currency', 192 currency: 'EUR', 193 maximumFractionDigits: 0 194}; 195let numberRangeFormat: intl.NumberFormat = new intl.NumberFormat('es-ES', options); 196let formattedRange: string = numberRangeFormat.formatRange(2, 8); // formattedRange = '2-8 €' 197formattedRange = numberRangeFormat.formatRange(2.9, 3.1); // formattedRange = '~3 €' 198``` 199 200 201### Currency and Unit Formatting 202 203Currency 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. 204 205**Currency Formatting Options** 206 207Assume that the currency unit is USD and the value is **-12300**. 208 209**Table 9** Currency sign (currencySign) 210 211| Value| Display Effect| 212| -------- | -------- | 213| standard | -US$12,300.00 | 214| accounting | (US$12,300.00) | 215 216**Table 10** Currency display (currencyDisplay) 217 218| Value| Display Effect| 219| -------- | -------- | 220| symbol | -US$12,300.00 | 221| narrowSymbol | -$12,300.00 | 222| code | -USD 12,300.00 | 223| name | -12,300.00 US dollars | 224 225**Unit Formatting Options** 226 227Assume that the unit name is **hectare** and the value is **-12300**. 228 229**Table 11** Unit display (unitDisplay) 230 231| Value| Display Effect| 232| -------- | -------- | 233| long | -12,3000 hectares | 234| short | -12,300 ha | 235| narrow | -12,300ha | 236 237**Table 12** Unit usage (unitUsage) 238 239| Value| Display Effect| 240| -------- | -------- | 241| Unspecified| -12,300 ha | 242| default | -47.491 sq mi | 243| area-land-agricult | -30,393.962 ac | 244 245 246**Development Example** 247```ts 248// Import the intl module. 249import { intl } from '@kit.LocalizationKit'; 250 251// Format the currency. 252let currencyFormat: intl.NumberFormat = new intl.NumberFormat('zh-CN', { style: 'currency', currency: 'USD' }); 253let formattedNumber: string = currencyFormat.format(123400); // formattedNumber = 'US$123,400.00' 254 255// Display the currency using its name. 256let currencyNameFormat: intl.NumberFormat = new intl.NumberFormat('zh-CN', 257 { 258 style: 'currency', 259 currency: 'USD', 260 currencyDisplay: 'name' 261 }); 262formattedNumber = currencyNameFormat.format(123400); // formattedNumber = '123,400.00美元' 263 264// Format units of measurement. 265let unitFormat: intl.NumberFormat = new intl.NumberFormat('en-GB', { style: 'unit', unit: 'hectare' }); 266formattedNumber = unitFormat.format(123400); // formattedNumber = '123,400 ha' 267 268// Format the units of measurement in the specified scenario, for example, area-land-agricult. 269let unitUsageFormat: intl.NumberFormat = new intl.NumberFormat('en-GB', 270 { 271 style: 'unit', 272 unit: 'hectare', 273 unitUsage: 'area-land-agricult' 274 }); 275formattedNumber = unitUsageFormat.format(123400); // formattedNumber = '304,928.041 ac' 276``` 277 278 279### Units of Measurement Conversion 280 281Units 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: 282 2831. Import the **intl** module. 284 ```ts 285 import { i18n } from '@kit.LocalizationKit'; 286 ``` 287 2882. Change the unit of measurement. 289 290 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. 291 ```ts 292 let convertedUnit: string = i18n.I18NUtil.unitConvert(fromUnit: UnitInfo, toUnit: UnitInfo, value: number, locale: string, style?: string); 293 ``` 294 295**Formatting Style** 296 297Assume that **fromUnit** is **cup** (US unit), **toUnit** is **liter** (SI unit), and the value is **1000**. 298 299**Table 13** Formatting style (style) 300 301| Value| Display Effect| 302| -------- | -------- | 303| long | 236.588 liters | 304| short | 236.588 L | 305| narrow | 236.588L | 306 307**Development Example** 308 309```ts 310// Import the i18n module. 311import { i18n } from '@kit.LocalizationKit'; 312 313// Set the fromUnit and toUnit. 314let fromUnit: i18n.UnitInfo = {unit: 'cup', measureSystem: 'US'}; 315let toUnit: i18n.UnitInfo = {unit: 'liter', measureSystem: 'SI'}; 316 317// Convert the unit based on the locale ID en-US. 318let convertedUnit: string = i18n.I18NUtil.unitConvert(fromUnit, toUnit, 1000, 'en-US'); // convertedUnit = '236.588 L' 319 320// Display the complete unit. 321convertedUnit = i18n.I18NUtil.unitConvert(fromUnit, toUnit, 1000, 'en-US', 'long'); // convertedUnit = '236.588 liters' 322``` 323<!--no_check-->