先做一个小动作:把上一篇的预算显示从页面里拿出来,放进一个能够增加或减少十元的子组件。拆分之后,页面依旧拥有预算,子组件只负责展示金额和表达调整意图。这个看似简单的约定,能够避免组件越拆越多、预算却越来越难追踪的问题。

预算输入与事件回传的技术封面

一、先说清楚两端各自负责什么

在 PocketLedger 中,预算会影响剩余金额,也会影响以后增加的超支提醒。它属于页面级业务事实,不能因为两个按钮被移动到另一个文件,就顺手移交给按钮所在组件。子组件可以知道当前预算,但是否接受一次调整,应当由拥有预算的页面决定。

我们把接口压缩为一个输入和一个输出:输入是以分表示的预算,输出是以分表示的变化量。这样,子组件无需拿到费用集合,不需要知道汇总算法,也不会依赖页面内部字段名称。组件只认识自己显示的值和能够发出的动作,页面则保留完整的业务判断。

本文继续使用第一篇建立的 Stage 工程及 API 12 以上 SDK,共用 common/Expense.ets 中的 Expense、money 和 validCents。下面给出子组件完整文件与页面替换内容,没有新增系统权限。官方将 @Param 定义为组件外部输入,将 @Event 用于组件输出;两者适合把这条边界直接写进代码。

这里的“单向”需要理解准确。它指的是本组件约定的数据修改路径,不意味着传进来的对象被自动深度冻结。官方文档指出,复杂对象的参数可以保留来源引用。若把整份账本对象传入子组件,子组件仍有机会经对象属性修改源数据。因此本例选择基本数值作为输入,主动缩小接口范围。

如果把预算再复制成子组件的内部状态,首次显示往往没有问题,父页面后来重置预算时才会暴露不同步。为了修补这份副本,又要增加监听和回写,原本的一条路径就变成了两条。只有用户确实需要未提交的编辑草稿时,局部副本才有独立语义;单纯显示和步进操作不需要它。

二、让子组件只发出调整意图

新建 entry/src/main/ets/components/BudgetStepper.ets。输入参数提供零作为默认值,输出函数提供空实现,保证组件有明确的初始形态。正式页面必须连接事件,默认空函数只用于让组件定义完整,不代表业务已经具备修改能力。

// entry/src/main/ets/components/BudgetStepper.ets
import { money } from '../common/Expense';

@ComponentV2
export struct BudgetStepper {
  @Param budgetCents: number = 0;
  @Event onStep: (deltaCents: number) => void = () => {};

  build() {
    Column({ space: 16 }) {
      Text('本次预算').fontSize(16).fontColor('#64748B')
      Text(`¥${money(this.budgetCents)}`)
        .fontSize(36).fontWeight(FontWeight.Bold)
      Row({ space: 12 }) {
        Button('减少 ¥10').onClick(() => this.onStep(-1000))
        Button('增加 ¥10').onClick(() => this.onStep(1000))
      }
    }.padding(24).width('100%').backgroundColor('#EAF2FF').borderRadius(20)
  }
}

注意按钮没有写 this.budgetCents += 1000。输入值由外部提供,子组件发出事件后,页面可以接受、拒绝或者增加额外约束。被拒绝的操作不会先在子组件显示成功,再被页面纠正回来,界面的变化始终取决于权威状态是否真的改变。

输出变化量而不是子组件计算后的目标值,还有一个实际好处:页面用自己的当前预算完成累加。连续点击时,事件不依赖某次界面同步前读到的旧输入值。这里没有把事件写成异步,也没有网络竞争,但接口依旧避免了把展示快照误当成更新基准。

变化量需要有明确语义。它是一次业务动作的参数,不是一个任意函数执行器,也不是把页面对象传回去让调用方自行修改。以后若产品需要“直接输入预算”,可以增加独立的提交事件,区分设置值与增量操作,不应让同一参数有时代表目标、有时代表差值。

组件文件向外导出结构,页面通过相对路径导入。两处都使用状态管理第二版,避免在同一个组件声明中混入第一版的状态装饰器。若旧工程尚未完成迁移,应先核对组件边界和版本混用限制,不能仅把某个字段改名为输入参数就当作迁移完成。本文从新建工程开始,减少与既有状态体系交叉的干扰。

三、在页面收口校验与反馈

使用下面内容替换第一篇的 pages/Index.ets。费用模型和初始两笔数据保持一致。页面在收到事件时计算目标预算,校验通过后才赋值;汇总与剩余金额继续由当前费用计算。

// entry/src/main/ets/pages/Index.ets
import { Expense, money, validCents } from '../common/Expense';
import { BudgetStepper } from '../components/BudgetStepper';

@Entry
@ComponentV2
struct Index {
  @Local budgetCents: number = 20000;
  @Local message: string = '每次调整 ¥10';
  @Local expenses: Expense[] = [
    new Expense('meal1', '午餐', 3800),
    new Expense('fare1', '通勤', 2400)
  ];

  totalCents(): number {
    let total: number = 0;
    for (let item of this.expenses) {
      total += item.cents;
    }
    return total;
  }

  changeBudget(deltaCents: number): void {
    if (deltaCents !== 1000 && deltaCents !== -1000) {
      this.message = '不支持的调整幅度';
      return;
    }
    const next: number = this.budgetCents + deltaCents;
    if (!validCents(next)) {
      this.message = '预算必须在允许范围内';
      return;
    }
    this.budgetCents = next;
    this.message = '预算已更新';
  }

  build() {
    Column({ space: 20 }) {
      Text('口袋账本').fontSize(28).fontWeight(FontWeight.Bold)
      Text('预算控制').fontSize(16).fontColor('#64748B')
      BudgetStepper({
        budgetCents: this.budgetCents,
        onStep: (delta: number) => this.changeBudget(delta)
      })
      Text(`总支出 ¥${money(this.totalCents())}`).fontSize(20)
      Text(`剩余 ¥${money(this.budgetCents - this.totalCents())}`).fontSize(20)
      Text(this.message).fontColor('#64748B')
    }.padding(24).width('100%').height('100%').backgroundColor('#F4F7FC')
  }
}

预算步进器的竖屏示例界面

父组件既校验目标值,也校验变化量。前者保护金额范围,后者保护事件契约。如果以后另一个调用方意外传入三元或小数分,不会因为最后结果仍在范围内就悄悄接受。按钮界面的限制不能替代业务入口的限制,尤其在组件开始复用以后。

这里允许预算低于已经发生的支出,所以剩余金额可以为负数。这并不是校验遗漏,而是明确的产品规则:预算描述计划上限,支出描述已发生事实,不能为了让剩余始终好看而拒绝合理调整。若产品要求预算不得低于支出,应在同一个入口增加该规则,并同步修改提示、验证步骤与图示。

页面中的提示文字只表达最近一次操作,子组件没有再维护“更新成功”的局部状态。否则页面拒绝后,子组件仍可能显示自己认为的成功。让结果反馈来自实际处理动作的一方,能够减少这种不一致,也让后续加入加载、错误和重试时保留明确的责任位置。

这段校验还把展示单位与业务单位分开。按钮写十元,回调传一千分,金额格式化只出现在显示位置。不要一会儿把参数当元,一会儿又乘一百,否则组件复用时很难从类型看出问题。数字类型不会携带货币单位,清楚的参数名称和统一约定仍然是必要约束。

剩余金额没有独立的更新语句,这一点值得保留。若在预算更新后再手工更新剩余,后来新增支出入口时就必须记得补同样的同步代码。现在它由预算和费用直接计算,新的合法修改只需改变相应事实即可。组件接口越清楚,派生信息就越没有理由再维护第二份可写副本。

四、沿着输入与输出做四组检查

首先检查输入同步。把页面的初始预算改为一百元,子组件应显示一百元,剩余应是三十八元。这个检查不需要点击任何按钮,它验证组件是否真正在读取外部输入,而不是保留了一个忘记删除的内部初始值。确认后恢复二百元,保持示例画面一致。

第二组检查事件方向。从二百元开始增加一次,页面预算变为二百一十元,剩余一百四十八元;减少一次回到初始状态。断点可以放在父组件的 changeBudget,核对收到的变化量和赋值发生的位置。子组件不应出现第二个用于写预算的入口。

第三组检查拒绝路径。将预算暂时设为零,点击减少,预算仍然是零,同时显示范围提示。再让按钮的测试事件传入不支持的幅度,检查是否在计算目标前拒绝。完成检查后恢复正式按钮代码,不能把用于验证的异常输入留在最终组件中。

第四组检查接口缺失。临时移除父组件传入的事件,按钮只会调用默认空实现,预算保持不变。这个结果说明事件连接是业务闭环的一部分。若团队希望缺少回调尽早暴露,可通过组件使用约定和静态检查约束调用方;不要把默认值误当成连接完整的证据。

预算输入、调整事件与页面校验的组件关系

排查时还可以按层拆开问题。按钮没有触发,检查点击绑定;回调执行但预算不变,检查拒绝分支;父状态改变而显示不对,检查传入参数是否仍指向该状态。这样的顺序围绕真实数据流推进,比在父子两侧同时增加临时变量更容易保留因果关系。

检查还应覆盖组件重新创建的场景。临时切换显示条件,使步进器销毁后再次出现,预算应继续来自页面当前值,而不是恢复为组件默认的零。这能够帮助确认状态归属是否真的留在页面。当然,若整个页面也被销毁,页面内部状态同样会重新初始化,不能把子组件重建与页面生命周期混为一谈。

五、组件可复用,业务规则仍有归属

预算步进器能够复用,不是因为它提供了很多配置,而是因为它没有夹带账本之外的职责。颜色、间距和按钮文本可以逐步抽象,但没有必要一开始就增加十几个可选参数。先保证接口语义稳定,复用时才不会把每一个新需求都变成一次兼容性修补。

对于可能快速连续发生的操作,还要分清“同步累加”和“远端确认”。本例的事件由页面同步处理,所以每次都读取当前预算。若改成请求服务器后再确认,应该另行设计待处理状态、请求标识和返回顺序,不能仅在现有方法前面加一个异步关键字就认为问题解决。

事件也不天然具有去重能力。同一个动作若被错误绑定两次,页面会忠实执行两次增量。排查预算跳变时,应先核对事件触发次数与调用链,别把所有重复结果都归咎于状态同步。等业务扩展到跨进程或跨网络提交,再引入请求标识与幂等语义;当前页面只解决一次回调对应一次本地调整。

有时团队会希望直接用双向绑定语法减少代码。它适合接口简单且修改规则明确的场合,但本例刻意保留事件入口,因为幅度、范围和提示都需要集中处理。是否减少几行样板代码,应服从边界是否清楚,而不是让语法便利替产品规则做决定。

把组件拆开之后,回头查看页面会发现,预算仍然只有一个写入点,费用仍然只有一组事实,剩余也仍从二者推导。这就是本次重构要守住的结果。下一篇转向监听排查:当金额已改变、提示却停留在旧状态时,如何判断是观测字段、监听路径还是业务依赖出了问题。

官方参考

Logo

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

更多推荐