【万能转换器|02】HarmonyOS ArkTS 精度规则实战:处理小数位、科学计数和极端数值

证据边界:本文基于 D:\huawei\one3(万能转换器) 当前源码进行静态核对。“当前事实”来自 UnitConverter、ConvertPage 与 UnitConverter.test;“历史证据”仅指原草稿及其既有平台记录;“建议实现”和“验收设计”均明确标注。本轮未执行 Hypium、项目构建、模拟器、真机、极端值脚本或性能采样。

HarmonyOS ArkTS 精度规则封面

很多单位换算应用的精度问题,并不是公式错了,而是“太早格式化”:计算刚结束就 toFixed(2),页面看起来整齐,用户点击结果切换输入单位后,截断值又被送进下一轮计算;或者所有数字都保留八位小数,1 PB 展开成超长整数,小于百万分之一的结果却显示成 0。更麻烦的是,代码注释写着“大于 1e15 才使用科学计数法”,实际 toPrecision(8) 可能在 1e8 左右就主动输出指数形式。

本文继续基于“万能转换器”的真实 HarmonyOS 5.0+ ArkTS 工程,重点复核 UnitConverter.ets 中的 formatNumber、ConvertPage.ets 中的输入解析与 formatForInput,以及 Hypium 现有测试。文章会明确区分三件事:源码已经实现的规则、JavaScript/ArkTS number 的真实行为、建议补充的严格校验与回归用例。

formatNumber 的真实决策链

非有限值、零和显式指数阈值先分流,普通分支再执行八位有效数字、尾零处理与千分位。需要注意,toPrecision 自身仍可能选择指数形式。

formatNumber 的真实决策链

计算精度、展示精度与测试边界

UnitConverter 保留原始 number,ConversionResult 同时承载 value 与 display;页面展示读取 display,结果回填始终从 value 出发,现有 Hypium 用例只覆盖部分边界。

计算精度、展示精度与测试边界

一、精度设计先回答三个问题,而不是先选小数位

一个换算结果在应用里至少有三种形态:

形态目标当前工程策略
计算值尽量保留可继续计算的信息使用原始 number,核心引擎不主动舍入
展示值在有限宽度内便于阅读formatNumber,最多 8 位有效数字并按条件使用科学计数法
回填值点击结果后可成为下一轮输入formatForInput,常规路径使用 12 位有效数字

这三种形态不能共用一个字符串。展示值可能含千分位逗号,回填到 TextInput 后不一定能正确解析;展示值还可能为了可读性丢弃低位,继续计算会把显示误差变成业务误差。反过来,直接把原始双精度数完整铺到页面,又会出现很长的尾数和布局压力。

当前项目的 ConversionResult 同时保存原始数和展示串:

export interface ConversionResult {
  unit: Unit;
  value: number;
  display: string;
}

这条边界是整套精度规则成立的前提。页面渲染使用 display,点击结果切换单位时使用 value,不会把 1,234,567.9 这样的文本重新当作计算输入。

二、ArkTS number 的能力边界:高精度显示不等于高精度计算

当前换算引擎使用 ArkTS number。在数值语义上,它面对的是 IEEE 754 双精度浮点数:能够覆盖极大的数量级,也能表示小数,但多数十进制小数不能被二进制精确存储。典型现象是:

const value = 0.1 + 0.2;
// 数学期望为 0.3,底层浮点结果并非十进制精确的 0.3

因此,toPrecision(8) 只能决定输出字符串保留多少有效数字,不能把此前已经产生的浮点误差“修复”为十进制精确值。类似地,toFixed(2) 是格式化和舍入策略,不是更高精度的数据类型。

对于长度、重量、温度等通用换算,双精度通常足够,关键是把舍入限制在展示边界。对于金额结算、计费、会计或法规要求的十进制计算,则应改用最小货币单位整数或经过验证的十进制定点方案。本文不会把通用单位换算的 number 宣称为财务级精度。

三、当前 formatNumber 的四个分支

真实源码的格式化函数如下:

export function formatNumber(value: number): string {
  if (!Number.isFinite(value)) {
    return '-';
  }
  if (value === 0) {
    return '0';
  }
  const abs = Math.abs(value);
  if (abs >= 1e15 || abs < 1e-6) {
    return value.toExponential(6);
  }
  let str = value.toPrecision(8);
  if (str.indexOf('.') >= 0 && str.indexOf('e') < 0) {
    str = str.replace(/0+$/, '').replace(/\.$/, '');
  }
  const parts = str.split('.');
  parts[0] = parts[0].replace(/\B(?=(\d{3})+(?!\d))/g, ',');
  return parts.join('.');
}

从代码意图看,可以拆成四层:

  1. NaN、正负无穷都展示为 -。
  2. 零单独展示为 0,避免进入极小值分支。
  3. 绝对值大于等于 1e15,或小于 1e-6,显式调用 toExponential(6)。
  4. 其它值调用
`toPrecision(8)`,清理尾零并给普通十进制整数部分添加千分位。

这里采用的是“有效数字”而不是“固定小数位”。例如 1234567.891 的整数部分已经很长,8 位有效数字会得到 1234567.9,加千分位后显示 1,234,567.9。同一策略用于 0.00000123456789 时,会保留更多小数位,使有效信息量大致相当。

四、源码注释和真实输出之间有一个值得测试的细节

源码注释写的是:

|v| >= 1e15 或 |v| < 1e-6 → 科学计数法
其它 → 最多 8 位有效数字 + 千分位

但 toPrecision(8) 自己也会选择科学计数法。当指数大于等于精度参数时,普通分支可能输出指数形式。按当前函数实际运行,代表值如下:

输入当前实际输出
1234567.8911,234,567.9
12345678.912,345,679
1234567891.2345679e+8
1e141.0000000e+14
1e151.000000e+15
1e-71.000000e-7

也就是说,当前系统不是“只有越过 1e15 才科学计数”,而是:

  • 显式极值分支使用 6 位小数的指数形式;
  • 常规分支交给 toPrecision(8),它仍可能返回 8 位有效数字的指数形式。

这不是虚构缺陷,而是从当前源码和运行结果得到的可复核结论。它未必影响正确性,但会影响产品一致性:1e14 与 1e15 的指数尾数位数不同,某些接近阈值的结果可能突然改变样式。精度规则必须测试真实字符串,不能只看 if 条件推断界面。

五、如果产品要求“阈值之外绝不显示指数”,应该显式实现

如果设计目标真的是 1e-6 到 1e15 之间始终使用十进制形式,就不能只依赖 toPrecision。一种思路是先按数量级计算允许的小数位,再使用定点格式化:

function formatPlainWithSignificantDigits(
  value: number,
  digits: number,
): string {
  if (value === 0) return '0';
  const magnitude = Math.floor(Math.log10(Math.abs(value)));
  const fractionDigits = Math.max(0, digits - magnitude - 1);
  return value.toFixed(fractionDigits);
}

但这段示例也有边界:toFixed 支持的小数位范围有限,极端数量级会产生很长字符串;随后还要处理尾零、负零、千分位和内存成本。因此更稳妥的做法是先写清产品契约:

  • 哪些数量级强制科学计数法;
  • 指数形式保留几位有效数字;
  • 普通形式最多占多少字符;
  • 是否允许用户切换精度;
  • 复制结果是复制展示值还是原始值。

当前工程没有用户可调精度,也没有实现上述替代函数。这里是面向后续迭代的设计建议。

六、极小值、极大值、负值和负零要分别处理

极端值不是只测 NaN 和 Infinity。至少应考虑:

1. 极小非零值

Number.MIN_VALUE 是最小的正次正规数。当前函数会进入 toExponential(6),实际可能显示为 4.940656e-324。这不是 6 位有效数字的常规舍入直觉,而是底层数值边界的表现。应用是否允许这么极端的输入,应由输入策略决定。

2. 最大有限值

Number.MAX_VALUE 仍然通过 Number.isFinite,会显示成大约 1.797693e+308。但是单位转换再乘以较大的 factor 可能溢出为 Infinity,最终降级成 -。所以“输入是有限数”不能证明结果仍然有限。

3. 负值

长度和重量通常不接受负值,温度的摄氏和华氏可以为负。当前通用换算页只检查有限性,没有按类目禁止负值。这是合理的通用引擎边界,但页面若要表达物理限制,需要按类目增加校验,而不是在 formatNumber 中统一取绝对值。

4. 负零

JavaScript 中 -0 === 0 为真。当前 value === 0 会把负零统一显示为 0。对普通换算工具这是友好行为,也避免出现 -0 °C 的视觉噪声;如果某个科学场景必须保留符号,则要用 Object.is(value, -0) 单独识别。

七、Number.isFinite 是结果门槛,不是完整输入语法

ConvertPage 当前通过:

const value = parseFloat(this.inputText);
this.results = convertAll(
  this.group,
  this.fromKey,
  Number.isFinite(value) ? value : NaN,
);

按钮可用性也采用同样思路:

private canConvert(): boolean {
  const v = parseFloat(this.inputText);
  return Number.isFinite(v);
}

这能挡住空字符串、纯字母和无穷值,但 parseFloat 接受“可解析前缀”。例如:

parseFloat('12abc')   -> 12
parseFloat('1.2.3')   -> 1.2
parseFloat('  7.5 ')  -> 7.5

当前 TextInput 使用 InputType.NUMBER_DECIMAL,正常软键盘会减少混入字母的机会,但粘贴、外接键盘和不同设备输入法仍需考虑。如果产品要求整个字符串必须是合法十进制,可在页面层使用完整匹配:

function parseStrictDecimal(text: string): number {
  const normalized = text.trim();
  const pattern = /^[+-]?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?$/;
  if (!pattern.test(normalized)) return NaN;
  const value = Number(normalized);
  return Number.isFinite(value) ? value : NaN;
}

是否允许科学计数输入、前导加号或只有小数点前后某一侧有数字,必须由产品规则决定。这段严格解析器是建议,不是当前源码已有能力。

八、显示值不能直接回填,当前源码用 12 位有效数字隔离了两者

页面点击结果行时,不使用 r.display,而是:

this.fromKey = r.unit.key;
this.inputText = Number.isFinite(r.value)
  ? formatForInput(r.value)
  : '';

真实 formatForInput 如下:

function formatForInput(v: number): string {
  if (!Number.isFinite(v)) return '';
  let s = v.toPrecision(12);
  if (s.indexOf('e') >= 0) return v.toString();
  if (s.indexOf('.') >= 0) {
    s = s.replace(/0+$/, '').replace(/\.$/, '');
  }
  return s;
}

它和展示函数有三点差异:

  1. 回填使用 12 位有效数字,展示使用 8 位。
  2. 回填不加千分位,保证输入框可继续解析。
  3. toPrecision(12) 一旦返回科学计数法,函数改用 v.toString()。

第三点很细。Number.toString() 通常生成足以往返到同一浮点数的最短字符串,可能比固定 12 位保留更多或更少字符。它避免把指数形式硬截到 12 位后再输入,但也意味着回填策略不是绝对统一的“12 位有效数字”。文章和测试都应按真实行为描述。

九、为什么原始结果绝不能在 convert 中 toFixed

假设把英寸转换成米时立即保留两位:

1 in = 0.0254 m
toFixed(2) -> 0.03 m

用户再切换到厘米:

0.03 m -> 3 cm

正确结果本应是 2.54 cm。这不是浮点尾差,而是展示舍入侵入计算造成的数量级可见错误。

当前 convert 返回原始 number:

const base = toBase(group, from, value);
return fromBase(group, to, base);

convertAll 也同时保留:

return {
  unit: u,
  value: v,
  display: formatNumber(v),
} as ConversionResult;

因此点击结果行时可基于 value 继续计算。这个设计比“把小数位调大一点”更关键,因为再多固定小数位也只是推迟误差累积,不能消除错误边界。

十、页面布局必须承认结果字符串长度不可预测

数值策略最终会落在 ArkUI 文本组件上。当前结果行没有给数值固定宽度,而是:

Text(r.display)
  .layoutWeight(1)
  .constraintSize({ minWidth: 0 })
  .textAlign(TextAlign.End)
  .maxLines(1)
  .textOverflow({ overflow: TextOverflow.Ellipsis })

这套组合允许左侧单位说明占固定区域,右侧结果使用剩余空间,极端数字不把整行撑出屏幕。科学计数法不仅是数学表达,也是移动端布局策略:1.797693e+308 比展开 309 位整数更可控。

但省略号会隐藏低位或指数后缀,因此复制功能不能从界面可见文本抓取。当前复制逻辑遍历 results 并使用每项的 display,不会复制被 UI 省略后的视觉片段。若后续要求复制完整原始精度,应再定义专用 copyValue,不能默认复用展示串。

在手机横竖屏、分屏和 2in1 小窗口中,应重点验证:

  • 最大指数结果是否仍能看到指数部分;
  • 单位符号和结果是否相互遮挡;
  • 系统字体放大后是否仍可操作;
  • 点击被省略的结果行后,输入框能否显示回填值;
  • 深浅色下占位符、无效值 - 和正文对比度是否足够。

十一、现有 Hypium 测试已覆盖什么,尚缺什么

当前 UnitConverter.test.ets 已验证:

expect(formatNumber(0)).assertEqual('0');
expect(formatNumber(100)).assertEqual('100');
expect(formatNumber(1234567.891))
  .assertEqual('1,234,567.9');
expect(formatNumber(NaN)).assertEqual('-');
expect(formatNumber(Infinity)).assertEqual('-');

还验证了 1e16 与 1e-7 的结果包含 e。这些用例覆盖了零、普通数、千分位、非法值以及明确极值分支。

精度策略真正容易回归的地方在阈值两侧,建议补充表驱动用例:

interface FormatCase {
  input: number;
  expected: string;
}
const cases: FormatCase[] = [
  { input: 1e-6, expected: '0.000001' },
  { input: 1e-7, expected: '1.000000e-7' },
  { input: 12345678.9, expected: '12,345,679' },
  { input: 123456789, expected: '1.2345679e+8' },
  { input: -1234567.891, expected: '-1,234,567.9' },
];

如果团队决定修正规则,让 1e8 到 1e15 之间保持普通十进制,那么测试期望也应和实现一起改。不能只改注释,因为用户真实看到的是字符串。

十二、极端运算还需要测试溢出和下溢

输入有限不代表换算结果有限。以数据存储为例,极大数乘以 PB 的系数可能超过 Number.MAX_VALUE;极小值除以巨大系数可能下溢成 0。

建议补充三类测试:

溢出

const result = convert(group, sourceKey, targetKey, hugeValue);
expect(Number.isFinite(result)).assertFalse();
expect(formatNumber(result)).assertEqual('-');

下溢

const result = convert(group, sourceKey, targetKey, tinyValue);
// 明确产品是接受 0,还是提示超出可表示范围

往返

const target = convert(group, fromKey, toKey, source);
const restored = convert(group, toKey, fromKey, target);
expect(almostEqual(restored, source)).assertTrue();

当前产品选择将非有限结果展示为 -,没有专门区分“输入非法”和“计算溢出”。这简化了页面状态,但诊断信息有限。后续如果要给用户明确反馈,可以把结果从裸 number 升级为带状态的模型:

type NumericState = 'valid' | 'invalid-input' | 'overflow';
interface NumericResult {
  state: NumericState;
  value: number;
}

同样,这是演进方案,不是现有工程已经实现的能力。

十三、有效数字、固定小数位和业务精度应该如何选

三种常见策略没有绝对优劣:

策略优点风险适用场景
固定小数位列表整齐、易理解大数浪费位数,小数可能变 0金额展示、固定测量精度
有效数字跨数量级信息密度稳定整数位变长时小数位减少通用科学和单位换算
科学计数法极端值紧凑普通用户阅读成本更高极大、极小数

当前工程选择“8 位有效数字 + 极值科学计数”,符合通用换算工具定位。真正要改时,不应该在多个页面各自散落 toFixed,而应把规则集中到格式化模块,并把以下参数显式化:

interface PrecisionPolicy {
  significantDigits: number;
  exponentialDigits: number;
  scientificLower: number;
  scientificUpper: number;
  useGrouping: boolean;
}

然后由同一个纯函数执行。这样设置页、无障碍朗读、复制结果和历史记录才能共享明确口径。

十四、从输入到回填的完整验收矩阵

针对当前 HarmonyOS 页面,可以建立一张最小但有效的验收表:

场景输入期望
空输入''按钮禁用,结果显示 -
普通整数1000结果使用有效数字和千分位
普通小数2.54不补无意义尾零
极小值0.0000001科学计数法
大整数123456789按当前实现为指数形式
非法粘贴12abc当前会解析 12;若采用严格规则应拒绝
无穷文本Infinity非有限,按钮禁用
负温度-40摄氏与华氏可正常换算
点击结果任意有效结果使用原始值生成回填文本
横屏小窗超长指数单行省略,不遮挡单位和操作

其中“非法粘贴”必须写清现状,不能在测试报告里把建议行为当成已实现。发布前真机测试还应覆盖不同输入法、复制粘贴、连续删除、快速切换单位和字体放大。

十五、可直接复用的精度治理清单

  1. 计算层返回原始数值,不返回 toFixed 字符串。
  2. 展示层与回填层使用不同格式化函数。
  3. 非有限输入和非有限结果分别纳入测试。
  4. 不从带千分位的展示字符串继续计算。
  5. 对 toPrecision 的实际指数切换行为写测试。
  6. 同时测试科学计数阈值的前一个、等于和后一个值。
  7. 对负值、负零、最大值、最小值、溢出和下溢定义策略。
  8. 输入语法不能只依赖键盘类型,粘贴路径要单独验证。
  9. 长数字用响应式约束和溢出策略保护 ArkUI 布局。
  10. 任何精度规则变更都同步修改帮助文案、复制、历史和 Hypium 期望。

十六、把精度规则落成六组可执行断言

精度治理不能停在“看起来小数位够用”。真正可复核的验收对象包括输入原文、解析后的 number、base 中间值、目标 raw value、display 和回填文本。六者处于不同层次:输入原文属于语法边界,number 与 raw value 属于计算边界,display 属于阅读边界,回填文本则负责开启下一轮计算。测试必须分别断言,不能只截一张结果页截图。

第一组是格式阈值。当前源码先排除非有限值与零,再判断 abs >= 1e15 || abs < 1e-6。因此 1e15 与 1e-7 应走 toExponential(6),1e-6 则进入 toPrecision(8) 分支。每个阈值至少要测前一格、精确值和后一格,并同时覆盖负数。断言不能只写“包含 e”,还应核对有效数字数量、指数符号和零的处理。特别要记录 toPrecision(8) 自身也会根据数量级选择指数形式,所以“没有进入显式指数分支”不等于“输出一定是普通十进制”。若产品要求阈值之外绝不出现 e,应在格式层显式决定固定格式,而不是依赖语言内建函数的选择。

第二组是特殊数值。Number.isFinite 会把 NaN、正无穷和负无穷挡在展示层之外,当前约定统一显示 -。value === 0 同时命中 0 与 -0,因此负零也显示为 0。这可能符合工具页直觉,但应作为明确产品规则测试,而不是偶然结果。还要覆盖 Number.MAX_VALUE、Number.MIN_VALUE 和接近安全整数边界的值,确认返回的是预期展示串,而不是把“可表示”误写成“业务上精确”。MAX_VALUE 与 MIN_VALUE 是浮点范围边界,不代表整数运算或十进制金额可以无损保存。

第三组是溢出与下溢。convert 只在入口检查 value 是否有限;乘以 factor 得到 base 后,极端值仍可能溢出为 Infinity,极小值也可能下溢到 0。convertAll 会把非有限 base 继续映射为 NaN 结果,display 最终成为 -,但下溢为 0 时可能显示为正常的 0。测试应选择因子最大的单位组合,分别记录输入、base、目标 raw value 和 display,并区分“数学结果接近零”和“浮点下溢丢失信息”。若业务不能接受静默下溢,建议在算子层返回带状态的结果,而不是仅靠字符串猜测。

第四组是比较策略。当前 Hypium 辅助函数使用固定绝对误差 1e-9。它适合部分常见单位样例,却无法覆盖所有数量级:对巨大结果可能过严,对非常小的结果又可能把明显的相对误差判为通过。建议采用 abs(a-b) <= absTol + relTol * max(abs(a), abs(b)),并为温度这类带偏移的非线性换算单独选择容差。容差是测试契约,不应反向改变生产结果;每个断言还要保留实际差值,失败时才能判断是公式、因子还是浮点舍入问题。

第五组是往返与展示隔离。对每个 UnitGroup 选择源单位 A 和目标单位 B,执行 A → B → A,并把最终 raw value 与原始输入按组合容差比较。随后单独测试 display:千分位、尾零裁剪和指数形式只服务阅读,不能再送回 convert。页面点击结果行使用 ConversionResult.value 经 formatForInput 回填,这条路径应覆盖长小数、指数值与极端数量级。测试还要证明列表显示被省略时,原始 value 仍未被截断;若用户需要查看完整值,应新增详情或复制入口,而不是让布局取消所有长度约束。

第六组是输入语法。页面使用 parseFloat 加 Number.isFinite,所以 12abc 这类带合法数值前缀的字符串可能被接受。格式化测试通过并不能证明输入边界正确。验收矩阵应加入空串、纯空格、多个小数点、指数符号、单位后缀、正负号和超长文本。若产品只接受普通十进制,建议先验证完整字符串,再转换为 number,并让实时换算、主按钮、复制和历史记录共用同一校验函数。

本轮只核对了 UnitConverter、ConvertPage 与 UnitConverter.test 的静态源码,没有执行 Hypium、项目构建、模拟器、真机、性能采样或极端值脚本。测试文件中已有常见换算、NaN 传播和指数形式用例,只能证明代码仓库存在这些断言,不能描述为本轮已经通过。正式验收应保存测试命令、环境、输入、raw value、display、回填文本和失败日志,再据此判断规则是否成立。

十七、结语:精度规则的核心是信息在哪一层被丢弃

“万能转换器”的真实实现把原始 number、8 位有效数字展示串和 12 位有效数字回填串分开,避免了最常见的“展示舍入继续参与计算”。它还对 NaN、无穷、零、极大和极小数建立了清晰分支,并通过 ArkUI 文本约束承接不可预测的结果长度。

复核也发现一个很有工程价值的细节:显式阈值并不是科学计数法的唯一入口,toPrecision(8) 会在更早的数量级自行切换。高质量精度设计不能只读注释,而要用代表值运行、截图和测试真实输出。

最终,精度不是“保留几位小数”这一个设置。它是一条从文本语法、浮点计算、展示格式、页面布局、结果复制到再次输入的完整契约。只要每层何时丢弃信息都可解释、可测试,单位换算才真正可靠。

参考资料

文档中心

文档中心

  • 华为开发者文档:ArkTS 概述
  • 华为开发者文档:ArkUI 概述
  • 本文核对的真实源码:entry/src/main/ets/common/UnitConverter.ets
  • 本文核对的真实源码:entry/src/main/ets/pages/ConvertPage.ets
  • 本文核对的真实测试:entry/src/ohosTest/ets/test/UnitConverter.test.ets
Logo

讨论HarmonyOS开发技术,专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐