safe-currency
Version:
currency tool
269 lines (190 loc) • 5.47 kB
Markdown
safe-currency API
# 初始化
自定义配置，默认以人民币为准，也可以根据设置覆盖。
```javascript
import currency from 'safe-currency'
new currency(value, opts)=> currencyObj
type valueType = {number|string|JSBD|BigInt}
defaultOpts=
{
symbol: '¥',
separator: ',',
decimal: '.',
precision: 2,
pattern: '!#',
format:null,
strict: false,
showTail0:false,
fromCents: false
}
```
### symbol 默认: "￥"
货币符号
```javascript
new currency(1.23).format(); // => "￥ 1.23"
```
### separator 默认: ","
千分位分隔符
```javascript
new currency(1234.56, { separator: "," }).format(); // => "￥ 1,234.56"
new currency(1234.56, { separator: " " }).format(); // => "￥ 1 234.56"
```
### decimal 默认: "."
小数点符号
```javascript
new currency(1.23, { decimal: "." }).format(); // => "￥ 1.23"
new currency(1.23, { decimal: "," }).format(); // => "￥ 1,23"
```
### precision 默认: 2
精度
```javascript
new currency(1.234, { precision: 2 }); // => "1.23"
new currency(1.234, { precision: 3 }); // => "1.234"
```
### pattern 默认: !#
!指代金额，#指代符号
```javascript
new currency(1.23, {
pattern: `# !`,
}).format(); // => "1.23 $"
```
### format 默认: null
自定义 format 函数
```javascript
function format(currency, options) {
return `${currency.yuan()}.${currency.cents()}`;
}
new currency(1234.56, { format: format }).format(); // => "1234.56"
```
### strict 默认: false
错误输入是否报错
```javascript
new currency("12 哈哈.2"); // 12.2
new currency(undefined); // 0
new currency("12 哈哈.2", { errorOnInvalid: true }); // throws an error
new currency(undefined, { errorOnInvalid: true }); // throws an error
```
### showTail0 默认: true
是否显示小数点后末尾零
```javascript
new currency("123.00").format(); // =>'￥ 123.00'
new currency("123.00", { showTail0: false }).format(); // =>'￥ 123'
```
### fromCents 默认: false
以分为单位创建 currency（运算后不继承）
```javascript
new currency("123").format(); // =>'￥ 123.00'
new currency("123", { fromCents: true }).format(); // =>'￥ 1.23'
```
# 属性
### JSBDVal
currency.JSBDVal
返回原始的 JSBD 类型
```javascript
new currency(123.45).JSBDVal; // => JSBD 对象
```
### value
currency.value
返回字符串表示
```javascript
new currency(123.45).value; // => '123.45'
```
# 方法
### add
```javascript
currency.add(value);
```
支持输入 string、number、currency、JSBD、BigInt，支持链式调用，运算结果继承配置
```javascript
new currency(123.45).add(0.01).toString(); // => "123.46"
```
### subtract
```javascript
currency.subtract(value);
```
支持输入 string、number、currency、JSBD、BigInt，支持链式调用，运算结果继承配置
```javascript
new currency(123.45).subtract(0.01).toString(); // => "123.44"
```
### multiply
```javascript
currency.multiply(number);
```
支持输入 string、number、currency、JSBD、BigInt，支持链式调用，运算结果继承配置
```javascript
new currency(123.45).multiply(2).toString(); // => "246.90"
```
### divide
```javascript
currency.divide(number);
```
支持输入 string、number、currency、JSBD、BigInt，支持链式调用，运算结果继承配置
```javascript
new currency(123.45).divide(2).toString(); // => "61.73"
```
### distribute
```javascript
currency.distribute(string | number | JSBD | BigInt);
```
不可被整除的场景，支持输入 string、number、JSBD、BigInt。（仅整数）
```javascript
new currency(1).distribute(3); // => [0.34, 0.33, 0.33]
new currency(12.35).distribute(3); // => [4.12, 4.12, 4.11]
new currency(12.0).distribute(3); // => [4.00, 4.00, 4.00]
```
### compareTo
```javascript
currency.compareTo(number);
```
比较大小，支持输入 string、number、currency、JSBD、BigInt，返回-1,0,1（可用于排序）
```javascript
new currency(1).compareTo(currency(2)); // =>-1
```
### chineseNumber
```javascript
currency.chineseNumber();
```
转中文数字
```javascript
new currency(12345.67).chineseNumber(); // =>"壹万贰仟叁佰肆拾伍元陆角柒分"
```
### format
```javascript
currency.format(options);
```
格式化，支持自定义配置，支持自动推断
```javascript
new currency(1000.0).format(); // => "￥ 1,000.00"
new currency(1000.0, { symbol: "￥", precision: 3 }).format(); // => "￥ 1,000.000"
new currency(1000.0).format({ symbol: "￥", precision: 3 }); // => "￥ 1,000.000"
new currency(1000.0).format({ formatter: () => "烫烫" }); // => "烫烫"
new currency("£1234.500").format(); // =>'£1,234.500' (自动推断货币为 £, 精度 3 位)
```
### toString
```javascript
currency.toString();
```
返回以元为单位的表示( 同 yuan() )
```javascript
new currency(123.45).toString(); // => 123.45
new currency("0.99").toString(); // => 0.99
new currency("1").toString(); // => 1
```
### yuan
currency.yuan()
返回以元为单位的表示，超出 2 位精度四舍五入
```javascript
new currency("0.99").yuan(); // => 0.99
new currency("1").yuan(); // => 1
new currency(123.45).yuan(); // => 123.45
new currency(123.459).yuan(); // => 123.46
```
### cents
currency.cents()
返回以分为单位的表示，超出 0 位精度四舍五入
```javascript
new currency("0.99").cents(); // => 99
new currency("1").cents(); // => 100
new currency(123.45).cents(); // => 12345
new currency(123.459).cents(); // => 12346
```