math-tool-chain

数字格式化工具，支持千分位、货币、百分比格式化，以及精度安全的算术运算。

安装依赖

pnpm install math-tool-chain

API

| 方法 | 参数 | 返回值 | 说明 | |------|------|--------|------| | thousands() | - | string | 千分位格式化，直接返回结果 | | currency() | currency?: 'CNY' | 'USD' | 'EUR' | 'GBP' (默认 'CNY') | string | 货币格式化，直接返回结果 | | percent() | decimals?: number (默认 2), strict?: boolean (默认 false) | string | 百分比格式化，直接返回结果。decimals 保留小数位数，strict 不足是否补0 | | int() | - | NumberFormatter | 保留整数部分，支持链式调用 | | round() | decimals?: number (默认 2) | NumberFormatter | 四舍五入，支持链式调用 | | add() | b: number | string | NumberFormatter | 精度安全加法，支持链式调用。b 支持千分位字符串、百分数字符串 | | subtract() | b: number | string | NumberFormatter | 精度安全减法，支持链式调用。b 支持千分位字符串、百分数字符串 | | multiply() | b: number | string | NumberFormatter | 精度安全乘法，支持链式调用。b 支持千分位字符串、百分数字符串 | | divide() | b: number | string | NumberFormatter | 精度安全除法，支持链式调用。b 支持千分位字符串、百分数字符串 | | get() | - | number | 获取最终计算结果 | | formula() | name: string, formula: string | NumberFormatter | 解析并存储数学公式，支持 +、-、*、/、()、[]、{} 运算符和变量占位符（如 $1, $2），支持链式调用 | | execFormula() | name: string, obj?: object | number | 执行已存储的公式，obj 用于替换公式中的变量（如 { $1: 10, $2: 5 }），返回计算结果 |

使用

千分位格式化

new NumberFormatter(1234567).thousands();              // "1,234,567"
new NumberFormatter(1234567.89).thousands();           // "1,234,567.89"
new NumberFormatter('1234567.89').thousands();         // "1,234,567.89"

参数说明： 无参数

货币格式化

new NumberFormatter(1234567.89).currency();          // "¥1,234,567.89"
new NumberFormatter(1234567.89).currency('USD');     // "$1,234,567.89"
new NumberFormatter(1234567.89).currency('EUR');     // "€1,234,567.89"
new NumberFormatter(1234567.89).currency('GBP');     // "£1,234,567.89"
new NumberFormatter(1234567.89).currency('CNY');     // "¥1,234,567.89"

参数说明：

• currency：货币类型，可选值 'USD' | 'EUR' | 'GBP' | 'CNY'，默认 'CNY'

百分比格式化

构造函数接收百分数、字符串、数字，自动转换为数字后再转换为百分比字符串。percent() 也可以作为链式运算的最终输出方法：

// 普通数字：乘以100
new NumberFormatter(25.6).percent();              // "2560%"
new NumberFormatter('25.6').percent();           // "2560%"
new NumberFormatter('2.56').percent(1, true);    // "256.0%"
new NumberFormatter('2.5678').percent(1, true);  // "256.7%"
new NumberFormatter(10).percent();               // "1000%"

// 百分数字符串：先转小数再乘以100
new NumberFormatter('2.5%').percent();           // "2.5%"

// 千分位字符串：先转数字再乘以100
new NumberFormatter('1,234.56').percent();       // "123456%"

// 保留0位小数
new NumberFormatter(10).percent(0);              // "1000%"

// 与链式调用组合使用
new NumberFormatter('12.5%').add('7.5%').percent(0);           // "20%"
new NumberFormatter('12.5%').multiply(2).percent(0);           // "25%"
new NumberFormatter(1).subtract('12.5%').round(3).percent(1, true); // "87.5%"
new NumberFormatter('12.34%').add('0.66%').percent(2, true);   // "13.00%"

参数说明：

• decimals：保留的小数位数，默认 2
• strict：是否严格保留小数位（不足补0），默认 false

精度安全的算术运算

// 加法
new NumberFormatter(0.1).add(0.2).get();                    // 0.3

// 减法
new NumberFormatter(0.3).subtract(0.1).get();                // 0.2

// 乘法
new NumberFormatter(0.1).multiply(0.2).get();                // 0.02

// 除法
new NumberFormatter(0.3).divide(0.1).get();                 // 3

// 链式调用
new NumberFormatter(0.1).add(0.2).multiply(3).get();        // 0.9
new NumberFormatter('12.5%').add('7.5%').get();             // 0.2
new NumberFormatter('12.5%').add('7.5%').percent(0);        // "20%"

参数说明：

• add(b) / subtract(b) / multiply(b) / divide(b)：b 支持 number | string（千分位字符串、百分数字符串）

四舍五入

new NumberFormatter(3.14159).round().get();                 // 3.14
new NumberFormatter(3.14159).round(3).get();                // 3.142
new NumberFormatter(3.14159).round(0).get();               // 3

参数说明：

• decimals：保留的小数位数，默认 2

保留整数

new NumberFormatter(3.7).int().get();                       // 3
new NumberFormatter(-3.7).int().get();                      // -3

参数说明： 无参数

获取最终结果

new NumberFormatter(0.1).add(0.2).multiply(3).get();        // 0.9

参数说明： 无参数

数学公式解析

formula() 方法用于解析并存储数学公式，execFormula() 方法用于执行已存储的公式。

支持的运算符：

• 括号：(), [], {}（三种括号可混合嵌套使用）
• 算术运算符：+（加）、-（减）、*（乘）、/（除）
• 变量：$1, $2, $3...（以 $ 开头后面跟数字，用于动态替换值）

公式定义：

const nf = new NumberFormatter();

// 基本运算
nf.formula('f1', '1+2').execFormula('f1');                          // 3
nf.formula('f2', '1+2*3').execFormula('f2');                       // 7
nf.formula('f3', '(1+2)*3').execFormula('f3');                     // 9

// 支持三种括号混合使用
nf.formula('f4', '[(1+2)*3]+4').execFormula('f4');                 // 13
nf.formula('f5', '{(1+2)*(3+4)}').execFormula('f5');               // 21
nf.formula('f6', '([1+2]+[3*4])').execFormula('f6');               // 15
nf.formula('f7', '{[1+2]*[3+4]}').execFormula('f7');               // 21

// 链式定义
nf
  .formula('f8', '1+2')
  .formula('f9', '(1+2)*3')
  .formula('f10', '[(1+2)*3]+4')
  .execFormula('f8');                                               // 3

支持变量替换：

使用 $1, $2, $3 等变量占位，在执行时通过 execFormula 的第二个参数传入具体值：

const nf = new NumberFormatter();

// 使用变量
nf.formula('f0', '1+2+$1+$2*$3');
nf.execFormula('f0', { $1: 10, $2: 2, $3: 3 });                     // 1+2+10+2*3 = 19
nf.execFormula('f0', { $1: 5, $2: 3, $3: 4 });                     // 1+2+5+3*4 = 20

// 变量与固定值混合
nf.formula('f1', '$1+$2*2');
nf.execFormula('f1', { $1: 10, $2: 5 });                           // 10+5*2 = 20

// 多个变量
nf.formula('f2', '($1+$2)*$3');
nf.execFormula('f2', { $1: 2, $2: 3, $3: 4 });                     // (2+3)*4 = 20

支持负数：

nf.formula('f11', '-5+3').execFormula('f11');                       // -2
nf.formula('f12', '(-5)*3').execFormula('f12');                    // -15
nf.formula('f13', '(-3)*(-4)').execFormula('f13');                 // 12
nf.formula('f14', '10--5').execFormula('f14');                     // 15
nf.formula('f15', '(-1-2)*(-3-4)').execFormula('f15');            // 21

复杂公式示例：

nf.formula('f16', '((1+2)*(3+4)*(5+6))/3').execFormula('f16');     // 77
nf.formula('f17', '{(1*2)+(2*3)+(3*4)}').execFormula('f17');     // 20
nf.formula('f18', '[10*(10-1)]-50').execFormula('f18');           // 40
nf.formula('f19', '((-3*-3)+(-4*-4))').execFormula('f19');        // 25
nf.formula('f20', '(((-1)*(-2)))+(((-3)*(-4)))').execFormula('f20'); // 14

注意事项：

• 公式中的空格会被自动忽略
• 支持连续减法如 10-2-3-4-1
• 支持连续除法如 100/10/2
• 支持混合负数如 1+-2, 3*-2, (-5)*(-2)

参数说明：

• formula(name, formula)：

  • name：公式名称，用于后续通过 execFormula(name) 调用，必填
  • formula：数学公式字符串，支持四则运算和括号，支持变量占位符（如 $1, $2），必填

• execFormula(name, obj?)：

  • name：已存储的公式名称，必填
  • obj：变量替换对象，用于替换公式中的 $1, $2 等变量，如 { $1: 10, $2: 5 }，可选