前言

JavaScript中浮点数精度问题是经典难题，如 0.1 + 0.2 !== 0.3。@pura/harmony-utils 的 NumberUtil 封装了基于Decimal的精确计算方法，避免浮点精度问题。本文将从API说明、代码实战、进阶用法、常见问题等多个维度进行全面讲解，帮助开发者快速掌握并应用到实际项目中。

一、NumberUtil计算核心API

NumberUtil 提供了以下精确计算方法：

方法	说明	返回类型	使用场景
add(x, y)	精确加法	number	价格计算
sub(x, y)	精确减法	number	差值计算
sum(...n)	精确求和	number	批量求和
keepDecimals(value, digit)	保留小数位	number	金额格式化
average(...numbers)	计算平均值	number	统计分析

1.1 核心特性

• 简洁易用：封装复杂逻辑为一行调用，降低使用门槛
• 类型安全：完整的TypeScript类型定义，编译期即可发现错误
• 异常处理：内置异常捕获机制，避免运行时崩溃
• 精确计算：基于Decimal实现，避免浮点精度问题

1.2 精度问题对比

表达式	普通计算	NumberUtil	说明
0.1 + 0.2	0.30000000000000004	0.3	精确加法
1.5 - 1.2	0.30000000000000004	0.3	精确减法
0.07 * 100	7.000000000000001	7	精确乘法

二、完整使用步骤

2.1 安装依赖

ohpm install @pura/harmony-utils

2.2 精确加法

import { NumberUtil } from '@pura/harmony-utils';

Button('精确加法')
  .width('100%')
  .onClick(() => {
    try {
      let precise = NumberUtil.add(0.1, 0.2);
      let normal = 0.1 + 0.2;
      this.result = `精确: 0.1 + 0.2 = ${precise}\n普通: 0.1 + 0.2 = ${normal}\n✅ 精确计算避免了浮点误差`;
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

2.3 精确减法

Button('精确减法')
  .width('100%')
  .onClick(() => {
    try {
      let result = NumberUtil.sub(1.5, 1.2);
      this.result = `精确: 1.5 - 1.2 = ${result}`;
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

三、完整页面示例

import { NumberUtil } from '@pura/harmony-utils';

@Entry
@Component
struct NumberCalcDemo {
  @State result: string = '';

  build() {
    Column({ space: 12 }) {
      Button('精确加法').width('100%').onClick(() => {
        let precise = NumberUtil.add(0.1, 0.2);
        this.result = `0.1 + 0.2 = ${precise}`;
      });
      Button('精确求和').width('100%').onClick(() => {
        let total = NumberUtil.sum(0.1, 0.2, 0.3);
        this.result = `0.1+0.2+0.3 = ${total}`;
      });
      Button('保留小数').width('100%').onClick(() => {
        let val = NumberUtil.keepDecimals(3.14159, 2);
        this.result = `3.14159保留2位 = ${val}`;
      });
      Text(this.result).fontSize(14).fontColor('#333333')
    }
    .padding(16)
  }
}

四、进阶用法

4.1 购物车金额计算

import { NumberUtil } from '@pura/harmony-utils';

interface CartItem {
  price: number;
  quantity: number;
}

function calculateTotal(items: CartItem[]): number {
  let subtotal = items.reduce((sum, item) => {
    return NumberUtil.add(sum, NumberUtil.add(item.price, item.price) * item.quantity / 2);
  }, 0);
  return NumberUtil.keepDecimals(subtotal, 2);
}

4.2 成绩统计

function calculateAverageScore(scores: number[]): string {
  let avg = NumberUtil.average(...scores);
  return NumberUtil.keepDecimals(avg, 1).toString();
}

五、注意事项

1. 精度范围：极大或极小数可能仍有精度问题
2. 性能影响：精确计算比普通运算稍慢
3. 返回类型：所有方法返回number类型
4. 初始化依赖：使用前需确保 AppUtil.init() 已调用
5. keepDecimals：是截断而非四舍五入

六、常见问题

Q1: 为什么0.1+0.2不等于0.3？

这是IEEE 754浮点数标准的固有问题，二进制无法精确表示0.1。

Q2: NumberUtil的计算比普通运算慢多少？

精确计算约慢2-5倍，但换来了正确性，在金额计算中完全值得。

Q3: keepDecimals是四舍五入吗？

取决于实现，通常是截断或四舍五入，请查看具体文档。

Q4: 可以处理大数运算吗？

NumberUtil主要解决浮点精度，超大数运算建议使用BigInt。

总结

NumberUtil 的精确计算方法为浮点精度问题提供了可靠解决方案。本文详细介绍了核心API、使用步骤、完整示例、进阶用法以及常见问题的解决方案。开发者可以利用这些方法确保金额计算、统计分析等场景的数值精确性。

本文基于 @pura/harmony-utils 工具库，更多功能请参考官方文档与后续系列文章。