118 lines
4.1 KiB
Markdown
118 lines
4.1 KiB
Markdown
|
## .currencyToPartsFormatter( currency [, options] ) ➜ function( value )
|
|||
|
|
|
|||
|
|
Return a function that formats a `currency` into parts tokens according to the given `options` or locale's defaults.
|
|||
|
|
|
|||
|
|
The returned function is invoked with one argument: the Number `value` to be formatted.
|
|||
|
|
|
|||
|
|
### Parameters
|
|||
|
|
|
|||
|
|
#### currency
|
|||
|
|
|
|||
|
|
3-letter currency code as defined by ISO 4217, eg. `"USD"`.
|
|||
|
|
|
|||
|
|
#### options
|
|||
|
|
|
|||
|
|
Please, see [.currencyFormatter() options](./currency-formatter.md#parameters).
|
|||
|
|
|
|||
|
|
#### value
|
|||
|
|
|
|||
|
|
Number to be formatted, eg. `9.99`.
|
|||
|
|
|
|||
|
|
### Returns
|
|||
|
|
|
|||
|
|
An Array of objects containing the formatted currency in parts. The returned structure looks like this:
|
|||
|
|
|
|||
|
|
```js
|
|||
|
|
[
|
|||
|
|
{ type: "day", value: "17" },
|
|||
|
|
{ type: "weekday", value: "Monday" }
|
|||
|
|
]
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Possible types are the following:
|
|||
|
|
|
|||
|
|
- `currency`
|
|||
|
|
|
|||
|
|
The currency string, such as the symbols `"$"` and `"€"` or the name `"Dollar"`, `"Euro"` depending on which style is used.
|
|||
|
|
|
|||
|
|
Please, see [.numberToPartsFormatter()](../number/number-to-parts-formatter.md#returns) for details about the inherited number parts such as `decimal`, `fraction`, `group`, `infinity`, `integer`, `literal`, `minusSign`, `nan`, `plusSign`, `percentSign`, and `compact`.
|
|||
|
|
|
|||
|
|
### Example
|
|||
|
|
|
|||
|
|
Prior to using any currency methods, you must load `cldr/main/{locale}/currencies.json`, `cldr/supplemental/currencyData.json`, and the CLDR content required by the number module. If using plural messages, you also must load the CLDR content required by the plural module. Read [CLDR content][] if you need more information.
|
|||
|
|
|
|||
|
|
[CLDR content]: ../../../README.md#2-cldr-content
|
|||
|
|
|
|||
|
|
#### Static Formatter
|
|||
|
|
|
|||
|
|
#### Using the default options
|
|||
|
|
|
|||
|
|
You can use the static method `Globalize.currencyToPartsFormatter()`, which uses the default locale.
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
var formatter;
|
|||
|
|
|
|||
|
|
Globalize.locale( "en" );
|
|||
|
|
formatter = Globalize.currencyToPartsFormatter( "USD" );
|
|||
|
|
|
|||
|
|
formatter( 9.99 );
|
|||
|
|
// > [
|
|||
|
|
// { "type": "currency", "value": "$" },
|
|||
|
|
// { "type": "integer", "value": "9" },
|
|||
|
|
// { "type": "decimal", "value": "." },
|
|||
|
|
// { "type": "fraction", "value": "99" }
|
|||
|
|
// ]
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
#### Instance Formatter
|
|||
|
|
|
|||
|
|
You can use the instance method `.currencyFormatter()`, which uses the instance locale.
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
var deFormatter = Globalize( "de" ).currencyToPartsFormatter( "EUR" ),
|
|||
|
|
zhFormatter = Globalize( "zh" ).currencyToPartsFormatter( "EUR" );
|
|||
|
|
|
|||
|
|
deFormatter( 9.99 );
|
|||
|
|
// > [
|
|||
|
|
// { "type": "integer", "value": "9" },
|
|||
|
|
// { "type": "decimal", "value": "," },
|
|||
|
|
// { "type": "fraction", "value": "99" },
|
|||
|
|
// { "type": "literal", "value": " " },
|
|||
|
|
// { "type": "currency", "value": "€" }
|
|||
|
|
// ]
|
|||
|
|
|
|||
|
|
zhFormatter( 9.99 );
|
|||
|
|
// > [
|
|||
|
|
// { "type": "currency", "value": "€" },
|
|||
|
|
// { "type": "integer", "value": "9" },
|
|||
|
|
// { "type": "decimal", "value": "." },
|
|||
|
|
// { "type": "fraction", "value": "99" }
|
|||
|
|
// ]
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
The information is available separately and it can be formatted and concatenated again in a customized way. For example by using [`Array.prototype.map()`][], [arrow functions][], a [switch statement][], [template literals][], and [`Array.prototype.reduce()`][].
|
|||
|
|
|
|||
|
|
[`Array.prototype.map()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map
|
|||
|
|
[arrow functions]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions
|
|||
|
|
[switch statement]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/switch
|
|||
|
|
[template literals]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals
|
|||
|
|
[`Array.prototype.reduce()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/reduce
|
|||
|
|
|
|||
|
|
#### More Examples
|
|||
|
|
|
|||
|
|
Please, see [.currencyFormatter() example](./currency-formatter.md#example) for additional examples such as using alternative `symbolForm`, configuring `style` (symbol, accounting, and name styles), and the inherited number options (e.g., compact numbers).
|
|||
|
|
|
|||
|
|
#### Performance Suggestion
|
|||
|
|
|
|||
|
|
For improved performance on iterations, first create the formatter. Then, reuse it on each loop.
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
var formatter = Globalize( "en" ).currencyToPartsFormatter( "USD" );
|
|||
|
|
|
|||
|
|
renderInvoice({
|
|||
|
|
prices: prices.map(function( price ) {
|
|||
|
|
return formatter( price );
|
|||
|
|
})
|
|||
|
|
});
|
|||
|
|
```
|