1# 数字与度量衡国际化 2 3## 使用场景 4 5在不同的国家和文化中，数字、货币和度量衡的表示方法不同，包括小数分隔符、小数位数、货币和度量衡单位等。例如，应用界面需要显示数字“1,000”（一千）表示商品价格。若采用固定格式“1,000”，在欧洲某些国家（如德国）用户会将其理解为“1”，因为这些国家使用逗号作为小数分隔符。为了确保界面符合当地习惯，需要对数字、货币和度量衡进行格式化。格式化后，界面会根据用户的语言和地区设置显示数字。 6 7## 开发步骤 8 9### 数字格式化 10 11数字格式化通过[NumberFormat](../reference/apis-localization-kit/js-apis-intl.md#numberformat)的[format](../reference/apis-localization-kit/js-apis-intl.md#format-1)接口实现，具体开发步骤如下： 12 131. 导入模块。 14 ```ts 15 import { intl } from '@kit.LocalizationKit'; 16 ``` 17 182. 创建NumberFormat对象。 19 传入区域ID列表时，使用第一个有效的区域ID创建对象。不传入区域参数时，使用系统当前的区域ID创建对象。 20 构造函数支持通过NumberOptions设置不同的数字格式化格式，具体请参考表1-表8。 21 22 ```ts 23 let numberFormat: intl.NumberFormat = new intl.NumberFormat(locale: string | Array<string>, options?: NumberOptions); 24 ``` 25 263. 数字格式化，根据numberFormat的设置格式化number。 27 ```ts 28 let formattedNumber: string = numberFormat.format(number: number); 29 ``` 30 314. 获取数字格式化选项，查看对象的设置信息。 32 ```ts 33 let options: intl.NumberOptions = numberFormat.resolvedOptions(); 34 ``` 35 36**数字格式化选项** 37 38通过[NumberOptions](../reference/apis-localization-kit/js-apis-intl.md#numberoptions)参数，可以设置数字的格式化选项，包括最小整数位数、最小小数位数、最大小数位数、最小有效位数、最大有效位数、是否分组显示、数字的表示方法、紧凑显示格式、舍入模式、舍入优先级、舍入增量以及数字的显示格式和数字系统。其中，数字的显示格式包括decimal(十进制)、percent(百分数)、currency(货币)和unit(单位)。 39 40以123000.123为例，各选项取值和显示效果如下表所示： 41 42**表1** 最小整数位数(minimumIntegerDigits) 43 44| 取值 | 显示效果 | 45| -------- | -------- | 46| 6 | 123,000.123 | 47| 7 | 0,123,000.123 | 48 49**表2** 最小小数位数(minimumFractionDigits) 50 51| 取值 | 显示效果 | 52| -------- | -------- | 53| 3 | 123,000.123 | 54| 4 | 123,000.1230 | 55 56**表3** 最大小数位数(maximumFractionDigits) 57 58| 取值 | 显示效果 | 59| -------- | -------- | 60| 3 | 123,000.123 | 61| 2 | 123,000.12 | 62 63**表4** 最小有效位数(minimumSignificantDigits) 64 65| 取值 | 显示效果 | 66| -------- | -------- | 67| 9 | 123,000.123 | 68| 10 | 123,000.1230 | 69 70**表5** 最大有效位数(maximumSignificantDigits) 71 72| 取值 | 显示效果 | 73| -------- | -------- | 74| 9 | 123,000.123 | 75| 8 | 123,000.12 | 76 77**表6** 是否分组显示(useGrouping) 78 79| 取值 | 显示效果 | 80| -------- | -------- | 81| true | 123,000.123 | 82| false | 123000.123 | 83 84**表7** 数字的表示方法(notation) 85 86| 取值 | 显示效果 | 87| -------- | -------- | 88| standard | 123,000.123 | 89| scientific | 1.230001E5 | 90| engineering | 123.000123E3 | 91| compact | 123K | 92 93**表8** 紧凑显示格式(compactDisplay) 94 95| 取值 | 显示效果 | 96| -------- | -------- | 97| short | 123K | 98| long | 123 thousand | 99 100 101**开发实例** 102 103```ts 104// 导入模块 105import { intl } from '@kit.LocalizationKit'; 106 107// 用科学计数法显示数字 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// 用紧凑的格式显示数字 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// 显示数字的符号 124let signFormat: intl.NumberFormat = new intl.NumberFormat('zh-CN', { signDisplay: 'always' }); 125formattedNumber = signFormat.format(123400); // formattedNumber = '+123,400' 126 127// 显示百分数 128let percentFormat: intl.NumberFormat = new intl.NumberFormat('zh-CN', { style: 'percent' }); 129formattedNumber = percentFormat.format(0.25); // formattedNumber = '25%' 130 131// 舍入模式 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// 舍入优先级 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// 舍入增量 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### 数字范围格式化 162 163数字范围格式化通过[NumberFormat](../reference/apis-localization-kit/js-apis-intl.md#numberformat)的[formatRange](../reference/apis-localization-kit/js-apis-intl.md#formatrange-1)接口实现，具体开发步骤如下： 164 1651. 导入模块。 166 ```ts 167 import { intl } from '@kit.LocalizationKit'; 168 ``` 169 1702. 创建NumberFormat对象。 171 传入区域ID列表时，使用第一个有效的区域ID创建对象。不传入区域参数时，使用系统当前的区域ID创建对象。 172 构造函数支持通过NumberOptions设置不同的数字格式化格式，具体请参考表1-表8。 173 174 ```ts 175 let numberFormat: intl.NumberFormat = new intl.NumberFormat(locale: string | Array<string>, options?: NumberOptions); 176 ``` 177 1783. 数字范围格式化，根据numberFormat的设置格式化开始和结束数字。 179 ```ts 180 let formattedNumber: string = numberFormat.formatRange(startRange: number, endRange: number); 181 ``` 182 183**开发实例** 184 185```ts 186// 导入模块 187import { intl } from '@kit.LocalizationKit'; 188 189// 数字范围格式化 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### 货币和单位格式化 202 203货币和单位的格式化基于数字格式化，在创建货币和单位格式化对象时，将数字的显示风格分别设置为“currency(货币)”和“unit(单位)”。同样，对货币和度量衡进行格式化时也支持通过[NumberOptions](../reference/apis-localization-kit/js-apis-intl.md#numberoptions)设置不同的格式，各属性参数取值和显示效果如下表所示： 204 205**货币格式化选项** 206 207以货币单位USD，数字大小-12300为例。 208 209**表9** 货币单位的符号(currencySign) 210 211| 取值 | 显示效果 | 212| -------- | -------- | 213| standard | -US$12,300.00 | 214| accounting | (US$12,300.00) | 215 216**表10** 货币的显示方式(currencyDisplay) 217 218| 取值 | 显示效果 | 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**单位格式化选项** 226 227以单位hectare，数字大小-12300为例。 228 229**表11** 单位的显示格式(unitDisplay) 230 231| 取值 | 显示效果 | 232| -------- | -------- | 233| long | -12,3000 hectares | 234| short | -12,300 ha | 235| narrow | -12,300ha | 236 237**表12** 单位的使用场景(unitUsage) 238 239| 取值 | 显示效果 | 240| -------- | -------- | 241| 未设置 | -12,300 ha | 242| default | -47.491 sq mi | 243| area-land-agricult | -30,393.962 ac | 244 245 246**开发实例** 247```ts 248// 导入模块 249import { intl } from '@kit.LocalizationKit'; 250 251// 格式化货币 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// 用名称表示货币 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// 格式化度量衡 265let unitFormat: intl.NumberFormat = new intl.NumberFormat('en-GB', { style: 'unit', unit: 'hectare' }); 266formattedNumber = unitFormat.format(123400); // formattedNumber = '123,400 ha' 267 268// 格式化特定场景下度量衡，如面积-土地-农业 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### 度量衡转换 280 281单位转换并根据区域和风格进行格式化，通过[I18NUtil](../reference/apis-localization-kit/js-apis-i18n.md#i18nutil9)类的[unitConvert](../reference/apis-localization-kit/js-apis-i18n.md#unitconvert9)接口实现，具体开发步骤如下： 282 2831. 导入模块。 284 ```ts 285 import { i18n } from '@kit.LocalizationKit'; 286 ``` 287 2882. 将度量衡从一个单位转换到另一个单位。 289 290 将度量衡从fromUnit转换到toUnit，数值为value，并根据区域和风格进行格式化。style可取不同的值，显示不同效果，具体请参考表13。 291 ```ts 292 let convertedUnit: string = i18n.I18NUtil.unitConvert(fromUnit: UnitInfo, toUnit: UnitInfo, value: number, locale: string, style?: string); 293 ``` 294 295**格式化风格** 296 297以fromUnit为美制单位cup，toUnit为公制单位liter，数字大小1000为例。 298 299**表13** 格式化使用的风格(style) 300 301| 取值 | 显示效果 | 302| -------- | -------- | 303| long | 236.588 liters | 304| short | 236.588 L | 305| narrow | 236.588L | 306 307**开发实例** 308 309```ts 310// 导入模块 311import { i18n } from '@kit.LocalizationKit'; 312 313// 设置要转换的单位和目标单位 314let fromUnit: i18n.UnitInfo = {unit: 'cup', measureSystem: 'US'}; 315let toUnit: i18n.UnitInfo = {unit: 'liter', measureSystem: 'SI'}; 316 317// 以en-US区域ID转换度量衡 318let convertedUnit: string = i18n.I18NUtil.unitConvert(fromUnit, toUnit, 1000, 'en-US'); // convertedUnit = '236.588 L' 319 320// 显示完整的度量衡 321convertedUnit = i18n.I18NUtil.unitConvert(fromUnit, toUnit, 1000, 'en-US', 'long'); // convertedUnit = '236.588 liters' 322``` 323