鸿蒙ArkUI实战：构建最近账单列表

鸿蒙ArkUI实战：构建最近账单列表

技术栈：HarmonyOS · ArkUI · ArkTS

在首页总览场景中，核心问题是：首页不是卡片陈列柜，而是用户打开账本后的第一条阅读路径。主结果、解释信息和后续操作必须有明确先后。
本文以“随手账本”为示例，围绕“构建最近账单列表”展开，重点讲解界面结构、状态组织、交互逻辑与测试方法。
实现目标是：用列表结构展示最近账单，让首页从静态总览进入真实业务数据展示；当前实现关注列表容器、标题与行间距。

1. 运行效果

2. 实现目标

完成本文后，可以掌握以下内容：

• 理解“构建最近账单列表”在记账应用中的界面职责和信息层级；
• 掌握相关 ArkUI 组件的组合方式与样式设置；
• 梳理@State状态、事件回调和界面刷新之间的关系；
• 通过正常路径、边界输入和页面回归验证实现结果。

3. 开发环境

4. 方案设计

从业务流程看，该功能位于以下链路中：

信息优先级 → 视觉层级 → 快捷操作 → 最近记录

实现“最近账单”前，可以先拆解以下四个问题：

1. 输入是什么：已有账单、页面偏好、用户输入，还是固定演示数据；
2. 状态放哪里：是否需要@State，还是只做单向展示；
3. 结果在哪里可见：文字、颜色、列表、进度或页面分支如何变化；
4. 失败时怎么办：空输入、取消、越界、异常或未接入系统能力如何说明。

本文采用的设计方案是：用列表结构展示最近账单，让首页从静态总览进入真实业务数据展示；本文关注列表容器、标题与行间距。

实现时尤其需要注意：最近账单只截取前三项；如果直接修改原数组，会影响全部账单页的数据顺序。这既关系到代码正确性，也直接影响最终的使用体验。

5. 核心代码解析

以下代码展示了该功能的核心实现：

Row(){Text('最近账单').fontSize(19).fontWeight(FontWeight.Bold).fontColor(this.mainText());Blank();Text('查看全部').fontSize(13).fontColor('#315BEA').onClick(()=>{this.activeTab='bills'})}.width('100%')

组件与状态说明

阅读代码时，不要只关注组件数量，还要检查数据从哪里来、状态在哪里读取、事件如何写回，以及最终由哪个组件呈现结果。

6. 状态与交互

ArkUI 的响应式更新可以按照“状态声明 → 组件读取 → 事件写入 → 界面刷新”理解。本文涉及的主要状态如下：

@StateprivateactiveTab:string='home';@StateprivatedarkMode:boolean=false;@Stateprivatecurrency:string='CNY';

交互由onClick回调触发。回调更新相关状态后，依赖这些状态的文字、颜色、列表或页面分支会自动重新渲染。实现时应同时处理有效操作、取消操作和无效输入，避免只覆盖理想路径。

7. 深入实现：从可运行到可维护

7.1 先明确功能边界

“最近账单列表”真正需要解决的数据是按时间倒序排列的近期账单，状态核心是账单数组与列表展示数量。界面完成的标准不只是能看到对应组件，而是从数据进入页面开始，到用户操作、状态更新、结果渲染形成完整闭环。本文实现中的主路径是：新增或编辑账单后更新首屏列表。如果只验证静态截图，而没有检查状态变化后的结果，就很容易遗漏看得见但用不稳的问题。

验收时可以把功能拆成四个层次：

1. 数据层：确认字段来源、默认值和计算口径，避免页面中出现多份互相独立的“同一数据”；
2. 状态层：只保存真正会变化且需要驱动界面的值，可由已有数据计算出的结果不重复保存；
3. 视图层：通过组件层级、字号、间距和语义颜色呈现主次关系；
4. 交互层：明确点击、输入、取消、确认和失败后的状态去向。

首页类功能要先处理信息优先级，再处理装饰。标题和关键金额属于第一层，解释文字与时间属于第二层，操作入口属于第三层。组件树如果没有体现这种层级，即使颜色和圆角做得很完整，页面仍会显得拥挤。布局上应让主要内容拥有稳定空间，同时给小屏、分屏和字体放大留下伸缩余量。

7.2 组件树与职责划分

当前核心区域使用了Row× 1、Text× 2、Blank× 1，相关属性和事件包括fontSize、fontWeight、fontColor、mainText、onClick、width。这些组件不应该平铺在一个超长的build()方法中。更稳妥的拆分方式，是让页面组件负责整体布局，让业务组件接收展示数据和回调，让纯函数负责计算与格式化。例如，页面只把“当前值、是否选中、点击后做什么”传给子组件，子组件不直接修改不属于自己的账单、预算或账户集合。

可以把调用关系整理为：

原始业务数据 ↓ 格式化 / 筛选 / 汇总等纯计算 ↓ 页面展示模型 ↓ ArkUI 组件读取状态 ↓ 事件回调更新唯一数据源 ↓ 依赖该数据的组件重新渲染

这条链路中最需要避免的是“双向手工同步”。例如同一个结果既保存在页面字段中，又能由账单数组计算得到，那么任何一次新增、编辑或删除都可能只更新其中一份。对于本功能，建议围绕“账单数组与列表展示数量”建立唯一入口，并让其他显示值按需派生。

7.3 状态更新为什么能驱动界面

文章代码中读取的状态包括this.mainText、this.activeTab。ArkUI 会跟踪组件在构建阶段读取的响应式状态；当事件回调写入新值后，相关界面会重新计算。这里的重点不是把所有变量都标记为@State，而是保持状态最小化。临时输入、页面选择和异步结果可以是状态，固定配置、格式化规则和可计算结果则更适合使用普通字段或方法。

首页与导航区域的更新应从唯一数据源开始：先得到新的账单或选中栏目，再计算结余、收支指标和最近记录，最后交给组件统一刷新。静态文案和主题令牌不参与业务写入；派生金额也不单独保存，从而避免首页多个卡片显示不同版本的数据。

本功能的重点边界是：空列表、长备注和大量记录要有明确策略。边界处理不应只靠禁用按钮，还需要在真正的提交函数中再次校验，因为业务方法未来可能从其他入口被调用。对于金额、比例和日期等数据，还应在进入模型时完成标准化，页面层只负责展示已经可信的结果。

7.4 交互反馈与异常路径

这类功能的专项验证集中在信息层级与页面切换。切换栏目后，选中颜色、文字字重和实际内容必须同时变化；账单数据更新后，汇总卡与最近记录必须来自同一批数据。还要在窄屏、长金额和深色主题下检查遮挡、换行与对比度，而不是只看默认设备截图。

建议至少补充下面这组专项检查：

7.5 面向真实项目的改进方向

首页会不断吸收新模块，因此最重要的工程约束是单向数据流。账单数组是事实数据，结余、收入、支出和最近记录都是派生结果，不应被分别手工维护。否则新增账单后很容易只刷新列表，却忘记刷新汇总卡。建议使用只读计算方法或 ViewModel 集中生成首页展示模型。

针对“最近账单列表”，推荐的重构方向是：用稳定 id 作为列表键并限制首屏渲染数量。重构时不要一次改动所有层，可以先把纯计算提取出来并补测试，再拆业务组件，最后接入持久化或系统能力。这样每次调整都有可验证结果，也能减少界面代码与数据逻辑相互牵连。

当首页模块继续增加时，应建立 HomeViewModel 或页面展示模型，集中输出标题、汇总指标、快捷入口和最近记录。各卡片只接收展示值与回调，不自行读取或修改账单集合。这样既能控制首屏复杂度，也方便单独测试每个派生结果。

8. 关键实现推演

8.1 数据流不能停留在截图层面

“鸿蒙ArkUI实战：构建最近账单列表”是否真正完成，不能只看目标区域是否已经出现，还要检查数据从产生到显示的全过程。最近账单先按时间倒序得到稳定副本，再截取固定数量；每一行通过账单 id 关联分类、账户和详情操作。

首页区域的数据应采用单向流动：账单集合与当前导航项是事实状态，结余、收支合计、最近记录和选中样式属于派生结果。派生结果可以通过只读方法或页面展示模型统一生成，避免多个卡片分别过滤同一份数组。这样新增账单、切换栏目或恢复本地数据时，只需更新事实状态，依赖它的区域就会按照同一口径刷新。对 ArkUI 页面而言，@State更适合保存会被交互修改、并且确实需要驱动界面的最小状态；能够由现有数据计算出的标题、金额、选中样式或列表结果，应尽量按需派生。这样既减少同步点，也让问题出现时能够沿着“输入—规则—状态—视图”快速定位。

8.2 设计取舍决定后续维护成本

本功能需要特别坚持的一项取舍是：截取应发生在排序之后，否则原数组顺序变化会导致所谓最近记录并不真实；首页也不应直接修改完整列表。这种约束看似比直接把逻辑写进组件多了一层，但它能避免页面同时承担数据校验、业务计算和视觉呈现，后续修改也更容易控制影响范围。

首页设计需要控制首屏信息密度。并不是卡片越多越完整，而是要让用户在短时间内识别当前账期、核心金额和下一项可执行操作。次要说明可以通过字号、颜色和间距降低视觉权重，但不能依赖颜色单独传达含义；底部导航、悬浮按钮和滚动内容还要共同处理安全区，避免关键内容被固定组件遮挡。实现过程中可以先保证业务语义准确，再逐步调整视觉细节。若数据口径、状态归属或失败路径仍不明确，单纯增加圆角、阴影和动画只会把问题隐藏得更深。

8.3 边界场景要按连续操作验证

本功能的重点边界包括：无账单、记录不足设定数量、同一时间多条记录和超长备注都需要检查，列表尾部不应被浮动按钮遮挡。验证时不应只做一次静态操作，而要组成连续路径，例如先改变条件、再执行核心动作、随后切换页面并返回，最后重新启动应用检查状态是否符合预期。连续路径更容易暴露草稿污染、异步覆盖、列表位置变化和派生结果未刷新等问题。

性能上应避免在每个组件的构建过程中重复执行全量汇总或排序。数据规模较小时差异并不明显，但功能继续增加后，重复计算会让状态来源变得难以追踪。更稳妥的做法是先生成一次首页展示模型，再把只读结果传给各区域。验证时除默认尺寸外，还要覆盖小窗口、大字体、长金额、深色主题和快速切换栏目。每次修复后，除了重测当前功能，还应回归与它共享同一数据源的首页、列表、统计、账户或设置区域，防止局部正确而全局口径失配。

8.4 从示例代码演进到真实项目

继续扩展时，可以生成 RecentTransactionItem 展示模型，预先准备标题、时间、金额和语义样式，降低行组件复杂度。组件输入尽量保持只读，操作通过语义清晰的回调或命令向上提交；业务层返回成功结果或结构化错误，页面根据结果决定刷新、保留草稿、显示反馈还是允许重试。

工程化后可将首页拆成 Header、Summary、QuickAction、RecentList 与 BottomNavigation 等职责明确的组件。页面层只负责组合和状态连接，金额格式、日期范围与汇总规则放入独立工具或 ViewModel。这样后续替换视觉样式、接入持久化或增加新的统计卡片时，不会把整个首页重新改写一遍。完成重构后，可以用四个问题做验收：事实数据是否只有一个可信来源、派生结果是否使用统一规则、失败后是否保留可恢复状态、跨页面结果是否保持一致。四项都能回答清楚，功能才算从演示效果进入可维护状态。

9. 测试要点

测试时重点观察：最近账单只截取前三项；如果直接修改原数组，会影响全部账单页的数据顺序。

展示型功能应检查数据口径、文字换行和不同窗口下的可读性；交互型功能还应覆盖空值、取消、重复点击和返回页面后的状态一致性。

10. 常见问题与排查

坑一：最近账单只截取前三项；如果直接修改原数组，会影响全部账单页的数据顺序。

定位“最近账单只截取前三项；如果直接修改原数组，会影响全部账单页的数据顺序”时，先复现操作并记录“账单数组与列表展示数量”变化，再沿事件回调、业务计算和组件渲染逐层检查。对于“最近账单列表”，不要先用样式调整掩盖问题；只有数据与状态正确后，再处理尺寸、颜色和反馈文案。

坑二：多个金额使用相同字号和颜色，会让结余、收入、支出争抢注意力。

排查“多个金额使用相同字号和颜色，会让结余、收入、支出争抢注意力”时，先分别记录原始金额、计算中间值和最终展示值，确认单位与精度没有在中途变化。“最近账单列表”应围绕“账单数组与列表展示数量”保持单一口径；分母为零、负值和超大数值要单独覆盖，不能只观察正常示例。

坑三：只用红绿区分收支不够，仍要保留文字标签、正负号或图标语义。

视觉问题应同时检查语义样式和组件约束。先切换深浅主题与窗口宽度，再放大字体并观察换行、对比度和点击区域。“最近账单列表”不能只在单一设备尺寸上成立，“账单数组与列表展示数量”变化后所有相关组件都要使用同一套样式令牌。

11. 工程化建议

示例代码可以集中在Index.ets中便于理解，但随着功能增加，建议逐步按职责拆分：

• 页面层：负责页面结构与路由切换；
• 业务组件层：封装卡片、表单、列表项和状态提示；
• 模型与计算层：管理账单、账户、预算等数据结构和纯计算逻辑；
• 基础服务层：处理 Preferences、文件导入导出、通知和认证；
• 测试层：覆盖纯函数、组件交互和设备端关键路径。

对于“构建最近账单列表”，优先保证组件输入、输出和回调职责清晰，避免页面组件直接承担全部业务状态。

12. 总结

本文围绕“最近账单列表”完成了界面与状态逻辑。实现关键是让按时间倒序排列的近期账单拥有明确来源，并由“账单数组与列表展示数量”驱动 ArkUI 组件刷新。完成主路径后，还需要验证空列表、长备注和大量记录要有明确策略。如果继续用于真实项目，建议用稳定 id 作为列表键并限制首屏渲染数量，使界面代码、业务计算与数据保存保持清晰边界。

官方参考资料

• ArkUI 开发指南
• ArkTS 状态管理概述