鸿蒙三方库 | harmony-utils之NumberUtil数值精确计算详解

前言

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 安装依赖

bash 复制代码

ohpm install @pura/harmony-utils

2.2 精确加法

typescript 复制代码

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 精确减法

typescript 复制代码

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;
    }
  })

三、完整页面示例

typescript 复制代码

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 购物车金额计算

typescript 复制代码

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 成绩统计

typescript 复制代码

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

五、注意事项

精度范围：极大或极小数可能仍有精度问题
性能影响：精确计算比普通运算稍慢
返回类型：所有方法返回number类型
初始化依赖 ：使用前需确保 AppUtil.init() 已调用
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 工具库，更多功能请参考官方文档与后续系列文章。