【万能转换器|04】HarmonyOS ArkTS 实用计算器实战:设计表达式输入与错误状态

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

HarmonyOS ArkTS 结构化计算器封面

“实用计算器”很容易被理解成一个文本框加 eval():用户输入表达式,应用直接执行并展示结果。这条路在真实 HarmonyOS 工具应用里风险很高。自由表达式需要词法解析、运算符优先级、括号、函数白名单、除零、溢出和非法字符治理;如果直接执行字符串,还会把数据输入变成代码执行边界。

“万能转换器”的真实源码没有使用 eval,也没有实现任意数学表达式解释器。它把“表达式输入”收敛成领域表单:BMI 是身高和体重,欧姆定律是 V/I/R/P 中任意两个已知量,串并联电阻是数值列表加模式,日期、税费、利息、进制等各有独立组件。CalcPage.ets 只按类型派发表单,公式集中在 CalcEngine.ets,输入错误由表单在调用算子前处理。

本文面向 HarmonyOS 5.0 及以上版本,基于 CalcPage.ets、BMIForm.ets、OhmsLawForm.ets、CalcEngine.ets、HistoryService.ets 的真实实现,说明如何设计可验证的表达式输入、错误状态和路由兜底。不会把自由表达式、云计算或未实现的错误模型写成现有能力。

从路由到结果的计算闭环

路由只决定领域表单,表单负责解析与校验,CalcEngine 只接收类型化数据;结果更新后再异步保存历史,失败分支不会伪装成成功。

从路由到结果的计算闭环

结构化计算器的职责边界

CalcPage 是页面外壳,领域表单拥有字段状态和错误反馈,CalcEngine 与 ArkUI 解耦;历史保存由表单发起,不是计算引擎的职责。

结构化计算器的职责边界

一、先澄清“表达式输入”:这里是领域表达式,不是代码字符串

BMI 公式是:

BMI = weightKg / (heightM × heightM)

欧姆定律的关系是:

V = I × R
P = V × I = I² × R = V² / R

这些都是表达式,但用户不需要输入 65/(1.7*1.7) 或 sqrt(P*R)。页面把变量拆成带单位的字段,用户填写值,应用根据已知量选择公式。

结构化输入有四个收益:

  1. 字段含义清楚,可以直接显示 cm、kg、V、A、Ω。
  2. 每个变量可以独立验证正数、非零、范围和必填条件。
  3. 计算引擎接收类型化参数,不接收可执行字符串。
  4. 错误提示能指向具体字段,而不是笼统显示“表达式错误”。

这也是本文标题中“设计表达式输入”的真实含义:把数学表达式拆成稳定的数据契约,而不是发明一个源码中不存在的解析器。

二、CalcPage 是页面外壳,不是巨型计算器

CalcPage 的状态只有路由类型和标题:

@State calcType: CalcType = 'mortgage';
@State pageTitle: string = '计算';
aboutToAppear(): void {
  const raw = router.getParams() as CalcRouteParams;
  if (raw && raw.type) {
    this.calcType = raw.type;
  }
  if (raw && raw.title) {
    this.pageTitle = raw.title;
  }
}

它不保存所有计算器的输入,也不包含 BMI、税费、欧姆定律公式。组件树根据 calcType 选择具体表单:

if (this.calcType === 'mortgage') {
  MortgageForm()
} else if (this.calcType === 'bmi') {
  BMIForm()
} else if (
  this.calcType === 'resistor' ||
  this.calcType === 'voltage' ||
  this.calcType === 'power'
) {
  OhmsLawForm({ historyType: this.calcType })
} else if (this.calcType === 'circuit') {
  CircuitForm()
} else {
  this.PlaceholderBody()
}

真实 CalcType 联合类型有 21 个路由值,其中 fuel/fuel_2 复用 FuelForm,resistor/voltage/power 复用 OhmsLawForm,其余映射到对应表单。源码顶部注释写“全部 17 个 calcType”,兜底注释又写“所有 21 个类型”,与联合类型数量并不完全一致。发布文档和回归清单应以真实联合类型与分支为准,而不是依赖过期注释。

三、为什么不应该把 21 个工具的状态塞进 CalcPage

如果外壳同时声明房贷金额、BMI 身高、电路电阻、日期和进制输入,任何状态变化都可能让页面重组变得难以理解,错误提示也会耦合。当前工程让每个表单自己持有短期状态:

@State gender: Gender = 'male';
@State heightText: string = '170';
@State weightText: string = '65';
@State result: BMIResult | null = null;

欧姆定律表单则是:

@State texts: string[] = ['', '', '', ''];
@State result: OhmsResult | null = null;
historyType: string = 'resistor';

外壳只负责导航栏、滚动容器、背景和错误兜底。业务状态跟着表单组件的生命周期走,切换路由后不会保留另一个工具的输入。

这符合 ArkUI 页面职责:页面层做组合,字段输入和结果展示放在高内聚组件中,纯计算再下沉到可测试函数。

四、BMI 表单把语法错误和业务错误分开

BMI 点击计算时:

private handleCalculate(): void {
  const h = parseFloat(this.heightText);
  const w = parseFloat(this.weightText);
  if (!Number.isFinite(h) || h <= 0) {
    promptAction.showToast({
      message: '请输入有效的身高',
      duration: 1500,
    });
    return;
  }
  if (!Number.isFinite(w) || w <= 0) {
    promptAction.showToast({
      message: '请输入有效的体重',
      duration: 1500,
    });
    return;
  }
  const r = computeBMI(h, w);
  this.result = r;
  // 之后才写历史
}

这里有两层门槛:

  • Number.isFinite 拒绝空值解析后的 NaN 和无穷数;
  • h <= 0、w <= 0 拒绝数学上可表示但业务上无效的值。

错误提示指向字段,校验失败立即 return,不会展示一个伪结果,也不会写历史记录。

不过 parseFloat 接受可解析前缀,例如 170abc 会得到 170。InputType.NUMBER_DECIMAL 能减少普通软键盘产生非法字符,但不能替代粘贴和外接键盘的完整语法校验。若产品要求严格输入,应使用全字符串匹配或 Number(trimmed) 加语法规则。这是改进建议,不是当前源码已有行为。

五、旧结果必须在输入变化时立即失效

BMI 的输入回调:

LabeledInput({
  label: '身高',
  suffix: 'cm',
  value: this.heightText,
  onValueChange: (v: string) => {
    this.heightText = v;
    this.result = null;
  },
})

欧姆定律每个字段变化时也会:

.onChange((v: string) => {
  const next = this.texts.slice();
  next[idx] = v;
  this.texts = next;
  this.result = null;
})

result = null 是重要的错误状态治理。用户看到结果后修改输入,如果旧结果继续留在页面,它就不再对应当前字段,却仍看起来像有效输出。当前实现宁可先隐藏结果,等待再次点击计算,也不让旧结果与新输入同时存在。

数组更新使用 slice() 创建新引用,再赋回 this.texts。这让 ArkUI 更容易观察到状态变化,而不是原地修改数组某一项后依赖深层变更检测。

六、欧姆定律把“空”建模成未知量

欧姆定律表单有四个字段,placeholder 明确写“空表示未知”。用户填写任意两个非零有限值:

const known = new Map<OhmsTarget, number>();
let count = 0;
for (let i = 0; i < FIELDS.length; i++) {
  const v = parseFloat(this.texts[i]);
  if (Number.isFinite(v) && v !== 0) {
    known.set(FIELDS[i].key, v);
    count++;
  }
}
if (count < 2) {
  promptAction.showToast({
    message: '请至少填入 2 个已知量',
    duration: 1500,
  });
  return;
}

这里没有要求用户选择“求电压”或“求电阻”。字段是否为空就是表达式求解的输入结构。Map<OhmsTarget, number> 只允许 V/I/R/P 四类键,把动态表单转换为类型受限的数据。

“0”被当作未知而不是已知。这对“非零电路量求解”简化了除零处理,但它也是业务约定:真实电压、电流可能为 0。帮助文案和测试必须按源码行为描述,不能宣称支持任意零值组合。

七、纯算子用有限轮推导,而不是执行字符串

computeOhms 先把缺失值归一为 NaN:

V = (V !== undefined && Number.isFinite(V)) ? V : NaN;
I = (I !== undefined && Number.isFinite(I)) ? I : NaN;
R = (R !== undefined && Number.isFinite(R)) ? R : NaN;
P = (P !== undefined && Number.isFinite(P)) ? P : NaN;

然后最多迭代四次,根据当前已知量补齐其它值:

for (let i = 0; i < 4; i++) {
  if (Number.isNaN(V)) {
    if (!Number.isNaN(I) && !Number.isNaN(R)) {
      V = I * R;
    } else if (!Number.isNaN(P) && !Number.isNaN(I) && I !== 0) {
      V = P / I;
    } else if (!Number.isNaN(P) && !Number.isNaN(R) && R > 0) {
      V = Math.sqrt(P * R);
    }
  }
  // I、R、P 使用同类规则继续推导
}

这是一种小规模约束传播:每轮利用新得到的值继续推导,最多四个变量,所以固定上限足够防止无限循环。它没有动态拼装 "P / I" 再执行,所有允许公式都在代码中显式列出。

算子返回:

export interface OhmsResult {
  V: number;
  I: number;
  R: number;
  P: number;
}

表单得到类型化结果后再格式化和渲染。纯算子不弹 Toast、不访问路由、不写历史,便于 Hypium 独立测试。

八、输入足够不等于输入一致

当前表单只检查“至少两个非零有限值”。如果用户填了三个或四个互相矛盾的值,例如:

V = 10
I = 2
R = 100

理论上 V/I = 5 Ω,与输入的 100 Ω 冲突。当前 computeOhms 会保留已知字段,只填缺失字段,不验证已知量之间是否满足同一组方程。

因此当前能力应准确描述为“根据已知量推导缺失量”,不能写成“自动校验任意电路数据一致性”。后续可在表单提交前增加残差检查:

function isOhmsConsistent(
  V: number,
  I: number,
  R: number,
  tolerance: number,
): boolean {
  const expected = I * R;
  const scale = Math.max(1, Math.abs(V), Math.abs(expected));
  return Math.abs(V - expected) <= tolerance * scale;
}

若检测到冲突,应提示用户修改字段,而不是随意选择一条公式覆盖输入。这个增强尤其适合三个或四个已知量场景。

九、错误状态不是只有 Toast

当前计算表单使用了多种状态表达:

状态真实实现
初始提供默认值或空字段,result = null
输入中更新字符串状态,清除旧结果
字段非法Toast 指向具体字段并返回
已知量不足Toast“请至少填入 2 个已知量”
计算成功设置结果,结果卡出现
历史成功显示保存成功对话框
历史失败记录错误日志,计算结果仍保留
路由未知显示可返回的兜底页面

Toast 适合短暂、可立即纠正的问题。结果卡使用 if (this.result) 控制,不存在时不占空白。历史持久化是附加能力,失败不应该把已经算出的结果清空。

如果未来存在耗时计算或异步数据源,还需增加 loading 和重复点击禁用。当前本地纯计算非常快,源码没有 loading 状态,不能为了文章完整性虚构一个加载动画。

十、CalcPage 的未知路由兜底避免白屏和审核误判

当 calcType 未命中任何分支,页面渲染:

@Builder
PlaceholderBody() {
  Column({ space: 8 }) {
    Image($r('app.media.ic_tool_more'))
      .width(48)
      .height(48)
      .opacity(0.4)
    Text('无法打开此工具')
    Text('请返回首页重新选择')
    Button('返回')
      .onClick(() => {
        router.back();
      })
  }
}

这比空白页面或崩溃更可恢复。源码注释还明确不显示“建设中”,避免让审核人员误以为上架版本包含未完成功能。

兜底页不会“自动返回”,实际代码提供的是用户点击“返回”按钮;注释中的“自动返回上一页”与实现不一致。文章应按代码写“提供返回操作”,发布复查时也应修正文档,避免说明和行为不符。

十一、结果展示同时承担可读性和状态确认

BMI 成功后展示:

  • 大字号 BMI;
  • 分类文本和对应颜色;
  • 推荐体重范围;
  • BMI 范围参考;
  • “仅供参考,不构成医疗诊断”的免责声明。

欧姆定律结果用四个 MetricBox 显示 V/I/R/P,并给结果卡添加 220ms 的透明度与轻微缩放过渡:

.transition(
  TransitionEffect.OPACITY
    .combine(
      TransitionEffect.scale({ x: 0.96, y: 0.96 }),
    )
    .animation({
      duration: 220,
      curve: Curve.EaseOut,
    }),
)

动画不是计算状态本身,只是帮助用户确认结果区域刚刚出现。数值文本使用 maxLines(1) 和省略策略,防止极端结果撑坏卡片。

医疗类结果增加免责声明是必要边界。当前 BMI 性别状态并未参与 computeBMI 公式,源码注释也明确说明“保留以便后续扩展”。不能在产品介绍中宣称当前 BMI 已按性别调整公式。

十二、成功后写历史,失败时不能伪装保存完成

BMI 在计算成功后构造摘要与 payload:

const summary =
  `BMI ${formatOneDecimal(r.bmi)}(${r.category})`;
const payload = JSON.stringify({
  gender: this.gender,
  height: this.heightText,
  weight: this.weightText,
});

然后调用 HistoryService。只有 Promise 成功后才调用保存成功对话框。服务未初始化或写入失败时记录日志,但结果卡已经是本地计算成功的事实,因此保留。

这个顺序区分了两个完成状态:

  1. 计算完成;
  2. 历史保存完成。

如果一点击按钮就先弹“保存成功”,再异步写入,失败时用户会被误导。当前源码没有这样做。

十三、表单数组更新为什么要创建新引用

欧姆定律四个输入放在 string[] 中。事件里没有:

this.texts[idx] = v;

而是:

const next = this.texts.slice();
next[idx] = v;
this.texts = next;

ArkUI 状态系统更容易通过新数组引用识别变化,组件重组行为也更明确。这个模式适合字段数量固定、数据结构简单的动态表单。

但数组下标依赖 FIELDS 顺序。历史 payload 保存整个 texts 数组,未来若调整字段顺序,旧历史解释可能变化。更稳定的持久化格式应保存键值对,例如 V/I/R/P 显式字段,或者带 schema version 的数组。当前历史模型本身有 schema 版本,但表单 payload 的内部结构仍需要迁移意识。

十四、类型化路由仍需运行时验证

router.getParams() as CalcRouteParams 是类型断言,不会在运行时验证外部参数。理论上错误字符串仍可进入 calcType,这正是兜底分支存在的原因。

更严格的入口可以维护支持集合:

const SUPPORTED_CALC_TYPES: CalcType[] = [
  'mortgage',
  'bmi',
  'fuel',
  'exchange',
  // ...
];
function isCalcType(value: string): value is CalcType {
  return SUPPORTED_CALC_TYPES.includes(value as CalcType);
}

然后只在验证通过后赋值。这样日志可以记录未知路由,页面仍进入兜底。该方案是增强建议,当前源码依赖联合类型、集中路由 helper 和兜底 UI 共同降低风险。

十五、不要把分支派发误改成动态执行

看到长 if/else 链后,很容易想用字符串动态加载组件或动态执行函数。ArkUI 声明式组件树对类型和构建期可见性有明确要求,盲目把组件名拼成字符串并不会自动变得更优雅。

当前分支有三个实际优点:

  • 每个 CalcType 对应哪个组件一眼可查;
  • 组件引用在编译期可见;
  • 未命中时明确进入兜底。

如果未来工具继续增加,可以按已有模式拆成分组页面,或使用 ArkUI 支持的类型化 builder 映射;目标应是减少维护复杂度,而不是引入反射式动态执行。

十六、针对计算器最值得补的 Hypium 用例

BMI

expect(computeBMI(170, 65).category)
  .assertEqual('正常');
expect(computeBMI(0, 65).bmi)
  .assertEqual(0);

还应覆盖分类阈值前后、推荐体重范围和极大输入。

欧姆定律

  • I + R 推导 V + P;
  • P + R 使用平方根推导;
  • V + I 推导 R + P;
  • 除数为 0 时不产生无穷;
  • 已知量不足由表单拦截;
  • 三个已知量冲突时,未来一致性校验应拒绝。

串并联

真实 combineResistors 会忽略非正和非有限值:

if (Number.isFinite(v) && v > 0) {
  valid.push(v);
}

应测试全部无效返回 0、串联求和、并联倒数和、单个电阻,以及极端值。

路由

  • 21 个合法值都能命中预期表单或共享表单;
  • 未知值出现可恢复兜底;
  • 返回按钮调用 router.back();
  • 页面标题来自路由参数。

十七、真机验收要关注键盘、滚动和错误恢复

CalcPage 把表单放进 Scroll,根容器占满页面。不同计算器字段数量差异很大,发布前至少验证:

  1. 软键盘弹出后最后一个字段和计算按钮仍可达。
  2. 手机横屏、小窗和平板宽度下卡片不被拉伸或截断。
  3. 输入非法值后 Toast 可读,用户能继续修改。
  4. 修改输入后旧结果立即消失。
  5. 连续快速点击计算不会产生重复成功对话框。
  6. 结果大数在 MetricBox 中不会覆盖单位。
  7. 深浅色下错误提示、免责声明和禁用状态对比足够。
  8. 系统返回和页面可见返回都能退出。
  9. 历史服务失败不影响核心计算。

这些是 HarmonyOS AppGallery 兼容性与运行稳定性的重要证据。源码存在错误处理不等于真机流程已经通过,测试结果必须按实际执行记录。

十八、可复用的结构化计算器清单

  1. 不执行用户输入字符串,先把公式拆成领域字段。
  2. 页面外壳只处理路由、导航、滚动和兜底。
  3. 每个表单拥有自己的短期 @State。
  4. 字段变化立即清除旧结果,避免结果与输入错位。
  5. 语法有限性和业务范围分别校验。
  6. 校验失败立即返回,不写结果、不写历史。
  7. 纯计算函数不访问 UI、路由和持久化。
  8. 类型化结果在组件中统一格式化。
  9. 对多已知量场景检查输入一致性,而不仅是数量。
  10. 未知路由显示可恢复错误页,不白屏、不崩溃。
  11. 只有持久化成功后才提示保存完成。
  12. 注释、联合类型数量和真实派发分支必须同步复查。

十九、把“能计算”拆成五个可复核的运行时检查

静态源码能够证明表单、校验分支和纯函数存在,却不能自动证明用户在软键盘、小窗、重复点击和异常持久化场景下仍能得到一致结果。结构化计算器至少要同时核对原始文本、解析后的数值、表单 result、展示文案和历史记录五份状态。只验证公式返回一个数字,很容易漏掉输入被错误接受、旧结果未失效或保存反馈失真的问题。

第一项是完整字符串解析。BMIForm 当前使用 parseFloat,因此 170abc 可能被解析为 170,65kg 可能被解析为 65;Number.isFinite 只检查解析后的 number,无法证明原字符串完全合法。运行时用例应覆盖空串、前后空格、单个小数点、多个小数点、科学计数法、单位后缀、负号和超长数字。若产品只接受普通十进制,可以先用完整正则或受控解析器验证整个字符串,再转换为 number,并把“格式错误”和“超出业务范围”分别提示。该方案是建议实现,不是当前已有能力。

第二项是旧结果失效。先输入 170 cm 与 65 kg 得到 BMI 约 22.49,再把体重改为非法值。onValueChange 当前会立即把 result 置空,所以旧卡片应消失;随后点击计算只显示“请输入有效的体重”,不得重新出现旧结果,也不得写历史。欧姆定律数组使用 slice 创建新引用后同样清空 result。验收记录应截取修改前后的 result 状态,而不是只看 Toast 一闪而过。

第三项是多已知量一致性。computeOhms 的设计目标是“给定任意两个值,推导另外两个”,但表单允许用户填写三个或四个值。当前算法只填补 NaN,不会检查已有 V、I、R、P 是否互相满足。例如 V=12、I=2、R=10 时,已知 R 不会被覆盖,P 会根据 V 与 I 得到 24,最终结果内部不一致。建议在调用纯算子前选择两种契约之一:严格限制恰好两个已知量,或允许更多已知量但按容差验证所有等式;冲突时保持 result 为空,并指出冲突字段。

第四项是路由白名单。CalcType 联合类型只在编译期约束项目内代码,router.getParams 的类型断言不会清洗运行时值。测试应直接传入未知 type、缺失 title 和空对象,确认页面进入“无法打开此工具”的可恢复兜底,返回按钮有效,且不会把默认 mortgage 表单与错误标题混合展示。建议增加 SUPPORTED_CALC_TYPES 与 isCalcType 守卫,让日志能记录非法值,同时保留当前 PlaceholderBody 作为最终防线。

第五项是计算成功与保存成功分离。BMIForm 先设置 result,再调用 HistoryService.add;只有 Promise 成功才调用 showSaveSuccessDialog,失败分支仅写日志。因此计算结果可以成功显示,而历史保存可能失败。故障注入应分别让 HistoryService 未初始化和 Repository 写入失败,验证核心计算不崩溃、不误报“保存成功”,并检查用户是否获得可理解反馈。当前源码没有可见失败提示,正式产品可增加非阻塞提示或重试入口,但不要让历史故障阻断计算本身。

本轮没有执行项目构建、模拟器、真机、软键盘回归、故障注入或性能采样。以上是基于 CalcPage、BMIForm、OhmsLawForm、CalcEngine 与 HistoryService 当前静态源码得出的测试设计和改进建议,不是已通过的运行结果。正式验收应记录输入原文、解析值、result、页面文案、历史条目、设备形态和失败日志,才能证明错误状态与计算结果保持同一份业务事实。

二十、结语:错误状态要比公式更早进入架构

“万能转换器”的实用计算器不是一个自由表达式执行器,而是一组由 CalcPage 派发的领域表单。BMI 把身高和体重单独校验,欧姆定律把空字段建模为未知量,CalcEngine 用类型化公式推导结果,输入变化立即清除旧结果,未知路由则进入可返回的兜底页。

这种设计牺牲了“什么都能输入”的表面自由,换来了可解释的字段、可定位的错误、可测试的纯函数和更清楚的审核边界。源码仍有注释数量不一致、parseFloat 前缀解析、欧姆定律多输入冲突未校验等改进空间,但这些问题都暴露在明确边界上,不需要重写整个页面体系。

对 HarmonyOS 5.0+ 工具应用而言,可靠计算器的起点不是更复杂的表达式语法,而是先决定什么输入合法、错误如何恢复、结果何时失效,以及哪些状态能够被测试证明。

参考资料

https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkui-overview

https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-overview

  • 华为开发者文档:ArkUI 概述
  • 华为开发者文档:ArkTS 概述
  • 本文核对的真实源码:entry/src/main/ets/pages/CalcPage.ets
  • 本文核对的真实源码:entry/src/main/ets/components/BMIForm.ets
  • 本文核对的真实源码:entry/src/main/ets/components/OhmsLawForm.ets
  • 本文核对的真实源码:entry/src/main/ets/common/CalcEngine.ets
Logo

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

更多推荐