一笔通勤费用从二十四元改为三十四元,明细行、总支出和剩余预算应当一起变化。这三个位置看似只是三段文字,背后却要求同一个事实沿着明确的依赖关系传播。如果列表保存一份金额,汇总卡再保存一份总额,修改入口越多,需要维护的同步规则就越多。账本界面真正需要先确定的,是谁有权修改费用,以及其他区域如何读取它。

费用数据与界面依赖的技术封面

一、让页面持有事实,让组件读取结果

这套连载使用 PocketLedger 工程,业务范围限定为本地费用与预算编辑。第一篇建立数据归属,随后依次处理组件输入输出、监听排查、编辑草稿、派生计算和撤销。这里先保留午餐与通勤两笔费用,用一个修改按钮打通完整更新路径。这样的规模足以说明状态边界,又不会让数据库、网络和账号体系掩盖问题。

事实只有两类:费用集合与预算上限。总支出是费用金额之和,剩余预算是预算减去总支出,两者都不应独立成为可写状态。页面负责创建集合、查找费用和校验金额;费用对象负责提供可观测属性。以后拆出明细行组件时,归属仍然保持在页面,不能因为视觉拆分就复制一套业务数据。

示例采用 Stage 模型及 API 12 起提供的状态管理 V2。官方文档说明,类使用 @ObservedV2,需要观测的属性再使用 @Trace,二者配合才能建立类属性的变化观测;只给类加装饰器不会让所有字段自动可观测。页面内部变量使用 @Local,所在自定义组件使用 @ComponentV2。这些规则决定的是数据如何触发界面更新,并不替代业务上的修改权限。

创建 Empty Ability 工程后,保留生成的入口能力、资源和页面配置,将下面两个文件放入对应目录。示例不访问网络、不读取设备敏感信息,因此不需要额外权限。开发时应选择包含上述接口的 SDK,保持工程使用的编译版本与目标设备能力一致,而不是仅修改文章中的版本文字。

二、金额使用整数,观测落在变化字段上

entry/src/main/ets/common/Expense.ets 保存系列共用模型。金额的单位是分,显示时才换算为元;标识用于稳定定位,名称与金额属于可编辑数据。标识在本篇创建后不再修改,因此没有为它添加观测装饰器。

// entry/src/main/ets/common/Expense.ets
@ObservedV2
export class Expense {
  id: string;
  @Trace title: string;
  @Trace cents: number;

  constructor(id: string, title: string, cents: number) {
    this.id = id;
    this.title = title;
    this.cents = cents;
  }
}

export function money(cents: number): string {
  return (cents / 100).toFixed(2);
}

export function validCents(cents: number): boolean {
  return Number.isInteger(cents) && cents >= 0 && cents <= 100000000;
}

整数并不意味着可以无限增大。这里将单笔金额限制在零到一亿分,并在修改入口校验;真实账本应由产品规则统一定义上限。列表汇总同样需要评估最大记录数与数值范围,不能把单笔安全直接推导为任意数量的总和安全。本例只有两条固定记录,不把示例范围外的问题藏进数字格式函数。

money 只负责格式化,不能承担输入解析或者数据纠错。若把负数偷偷转成零,页面虽然看起来正常,错误事实却已经进入模型。金额是否合法必须由调用方明确决定,失败时保留原值并显示原因。后续表单篇会处理字符串到整数分的转换,本篇不提前混入另一套解析逻辑。

模型字段保持简短也有价值。没有增加仅供界面显示的金额字符串,更没有在对象里再保存一个与金额重复的“展示金额”。同一个业务事实越少副本,后续排查时需要追踪的赋值点越少。观测范围则围绕真实修改行为设置,既便于理解,也避免把不相关的临时信息混入响应关系。

对于初次接触深层观测的开发者,容易把数组本身和数组内对象视为一个整体。实际上,替换集合、替换某个元素以及修改元素属性是不同操作。页面上的集合归属与费用对象上的字段观测分别承担职责。我们选择给费用建类,而不是在任意位置创建松散对象,就是为了让这些职责通过类型结构表达出来,后续新增字段也能直接看出它是否参与响应。

三、用一个入口完成修改与汇总

下面是完整的 pages/Index.ets。totalCents() 每次根据费用集合计算总额,当前数据量下不需要额外缓存。点击按钮只修改目标费用的 cents,其余文字读取同一组状态。通过标识查找对象,也避免排序后把固定数组位置误当成业务身份。

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

@Entry
@ComponentV2
struct Index {
  @Local expenses: Expense[] = [
    new Expense('meal1', '午餐', 3800),
    new Expense('fare1', '通勤', 2400)
  ];
  @Local budgetCents: number = 20000;
  @Local message: string = '金额以分保存';

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

  addFare(): void {
    const item: Expense | undefined = this.expenses.find(
      (row: Expense) => row.id === 'fare1'
    );
    if (item === undefined || !validCents(item.cents + 1000)) {
      this.message = '费用不存在或金额超出范围';
      return;
    }
    item.cents += 1000;
    this.message = '已增加通勤费用';
  }

  build() {
    Column({ space: 18 }) {
      Text('口袋账本').fontSize(28).fontWeight(FontWeight.Bold)
      Text('费用与预算').fontSize(16).fontColor('#64748B')
      Column({ space: 8 }) {
        Text(`预算 ¥${money(this.budgetCents)}`).fontSize(20)
        Text(`总支出 ¥${money(this.totalCents())}`).fontSize(24)
        Text(`剩余 ¥${money(this.budgetCents - this.totalCents())}`)
      }.padding(20).width('100%').backgroundColor('#EAF2FF').borderRadius(20)
      ForEach(this.expenses, (item: Expense) => {
        Row() {
          Text(item.title).fontSize(18)
          Blank()
          Text(`¥${money(item.cents)}`).fontSize(18)
        }.padding(18).width('100%').backgroundColor('#FFFFFF').borderRadius(14)
      }, (item: Expense) => item.id)
      Button('通勤增加 ¥10').onClick(() => this.addFare())
      Text(this.message).fontColor('#64748B')
    }.padding(24).width('100%').height('100%').backgroundColor('#F4F7FC')
  }
}

PocketLedger 白色开发界面与费用更新代码

这里的稳定键采用费用标识,金额变化不会改变键。若把金额拼进键,编辑金额就同时改变了业务身份与渲染身份,列表项的局部状态可能随之重建。后续增加输入框或展开区域时,这种混用会让焦点和编辑状态变得难以解释。身份应回答“这是哪一笔”,金额应回答“这笔是多少”,两个问题需要分开。

页面没有缓存总额,但这并不代表所有业务都应在构建过程中反复遍历集合。当前方案首先保证依赖清楚,等到汇总逻辑确实被多个位置复用,再在第五篇引入计算属性。先建立正确的数据来源,再讨论计算策略,才有办法判断一次优化究竟减少了计算,还是增加了同步负担。

修改函数返回前就完成了业务判断,所以界面不需要猜测一次点击是否有效。如果以后增加远端保存,仍应明确区分本地修改与远端确认,不能把当前提示直接改成“上传成功”。这也是把反馈文字单独保存的原因:它描述操作结果,而不是金额事实本身。反馈可以变化、消失或替换,费用数据仍有独立且稳定的含义。

四、按依赖链验证,而不是只看按钮

初始两笔费用合计六十二元,预算为二百元,剩余一百三十八元。点击一次后,通勤为三十四元,总支出七十二元,剩余一百二十八元。验证时应同时观察明细、汇总与提示文字,不能因为其中一个区域变化就判定整条路径正确。图中的代码与页面用于说明这一预期交互关系。

费用对象、集合与派生显示之间的数据关系

可以先在 addFare 设置断点,核对找到的标识是否为通勤记录,再观察赋值前后的整数金额。若方法执行了而金额文字没有变化,检查页面读取的对象是否就是被修改的实例,以及 cents 是否仍然带有 @Trace。如果只是提示变化,费用没变,则优先检查查找结果和金额校验,不要先怀疑渲染引擎。

还需要验证拒绝路径。把初始通勤金额临时调整到上限附近,再触发增加操作,应保留原金额并显示范围提示。把目标标识改为不存在的值,应走同一个明确的失败分支,而不是访问空对象。完成验证后恢复示例数据,确保文章截图与最终代码保持一致。

验证集合身份时,可交换两笔费用在初始化数组中的顺序,然后再次点击增加通勤。预期改变的仍然是通勤记录,而不是第一行或第二行。这个小操作能较早暴露通过数组下标修改业务记录的问题。与此同时,核对两条记录的标识不能重复;稳定键解决的是身份连续性,无法替开发者修复重复身份。

还可以用连续点击观察累计规则。每次有效操作应只增加十元,初始值、点击次数与最终金额之间能够直接对应。无需为这个小页面虚构帧率或者响应耗时,先把功能不变量查清楚更有价值。当实际产品出现卡顿,再在目标设备上建立可重复的操作脚本、采样条件与测量记录,以免把功能正确和性能达标混成同一个结论。

最后检查状态的生命周期边界。@Local 表示组件内部状态,不等于持久存储;进程重建后不会因为使用了装饰器就自动恢复账本。该行为应作为工程范围的一部分写清楚,避免读者把页面更新机制误解为数据可靠性机制。本系列先解决当前页面会话中的一致性,持久保存需要另行设计存储协议与恢复策略。

五、把扩展点留在清楚的位置

后续增加删除或修改名称时,沿用页面入口、模型校验与稳定标识这条路径即可。需要跨页面共享时,再考虑把事实源提升到适当生命周期的模型中;不要为了未来可能共享,立即把所有内容放进全局变量。状态放得过低会产生重复副本,放得过高则会扩大修改范围,两者都让依赖难以掌握。

还应区分“能观测”与“应允许修改”。类字段被观测后,持有对象引用的代码仍然可能直接改它。装饰器并没有替团队建立业务权限边界。因此拆组件时,优先传递所需的基本值与明确事件,而不是把整个费用集合交给每一个按钮。下一篇会将预算控制抽成子组件,用实际接口把这一约束落下来。

多人协作时,可以在评审中围绕三件事讨论:新增字段究竟是事实还是派生值,新增按钮是否绕过已有校验,新增展示是否引用同一个数据来源。这样的检查比统一要求所有对象都加某个装饰器更具体。它也为后续重构提供判断标准:只要业务事实、修改入口与依赖关系没有发生隐式变化,视觉组件的拆分就更容易控制风险。

这篇留下的核心结构很小:一个费用模型、一组归属于页面的事实、一个经过校验的修改入口,以及从事实计算的显示结果。小结构的意义在于每次变化都能追溯来源。等页面越来越复杂,仍然能够说清哪一处写入、哪些位置依赖它,状态管理才没有沦为装饰器的堆叠。

官方参考

Logo

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

更多推荐