HarmonyOS 展馆导览工程·第6篇:入口去重与会话恢复的边界验收【共创稿事节】
导览工程已经有了详情路由、自适应布局、资源化外壳、可见期间的提示计时器和增量列表。最后一篇不再增加一个孤立能力,而是把这些能力放进同一组边界条件:重复点击会不会叠出多层详情,返回按钮能不能兑现文案,恢复入口遇到不存在的展品时怎么办,布局和前后台变化是否偷偷改写用户的选择。验收要检验这些交界处,不能只检查各个按钮单独可用。

先明确最终返回规则
前五篇采用最直接的 push 行为,连续点击不同展品可以形成详情历史。本篇收尾时做一个明确的产品选择:导览主界面只保留当前展品详情,侧栏选择另一件展品就替换当前选择;返回展品列表清空目的页栈。这个规则适合展馆列表与详情的主从关系,也使按钮上的“返回展品列表”在单栏和分栏中都有一致目标。
规则变化必须集中实现,不能只修改某一个按钮。否则列表点击采用替换,恢复入口仍然采用追加,重复操作后又会形成多层详情。这里新增 GallerySession 统一处理打开与恢复,页面不再自行拼路由记录。NavPathStack 仍属于一个 Navigation,数据仓库仍通过第1篇的稳定标识查询,没有引入全局共享导航栈。
会话恢复也先定义范围:本篇保存当前 Index 实例内的最后一次有效选择,用户返回列表后可以重新打开。根组件重建或进程结束都会丢失这份记录,因此它不是跨进程备份;API 12 工程中的这份内存记录与较新系统提供的 UIAbility 备份恢复能力是不同层次。未来需要持久化时,可以沿用下面的快照结构,再增加存储、校验与迁移,不能直接把计时器和组件对象序列化。
把范围写清楚会减少验收争议。列表查看标记属于第5篇的数据源会话,当前展品属于导航选择,提示索引属于详情组件,它们不必拥有相同寿命。恢复展品时重新创建详情并从第一条提示开始,是当前实现的自然结果;不能因为恢复了展品标识,就宣称所有局部界面状态也被恢复。
用集中入口维护一个详情的不变量
新增 entry/src/main/ets/common/GallerySession.ets。类只接收导航栈并查询已有展品,不依赖 UI 组件。快照包含结构版本和展品标识,snapshot 返回新对象,避免外部调用者修改内部记录。所有方法都在界面线程调用,保持栈操作与界面事件处于同一执行环境。
import { findExhibit } from './Exhibit';
export interface GuideCheckpoint {
schema: number;
exhibitId: string;
}
export class GallerySession {
private stack: NavPathStack;
private last: GuideCheckpoint = { schema: 1, exhibitId: '' };
constructor(stack: NavPathStack) {
this.stack = stack;
}
open(id: string): boolean {
if (findExhibit(id) === undefined) {
return false;
}
const names = this.stack.getAllPathName();
const alreadyOpen = names.length === 1 && names[0] === 'ExhibitDetail'
&& this.stack.getParamByIndex(0) === id;
this.last = { schema: 1, exhibitId: id };
if (alreadyOpen) {
return true;
}
this.stack.clear(false);
this.stack.pushPath({ name: 'ExhibitDetail', param: id }, false);
return true;
}
snapshot(): GuideCheckpoint {
return { schema: this.last.schema, exhibitId: this.last.exhibitId };
}
restore(checkpoint: GuideCheckpoint): boolean {
if (checkpoint.schema !== 1) {
return false;
}
return this.open(checkpoint.exhibitId);
}
}
先验证实体,再操作栈,是第一条边界。无效输入返回 false,当前有效详情不会被提前清空。第二条边界是重复打开:栈中只有同一个详情且参数相同,直接返回,不重建页面。第三条边界是不同选择:清空旧目的页再压入唯一新详情,明确放弃旧详情历史。本例关闭这组程序化替换的转场动画,让操作语义保持直接。
检查栈的名字与参数,比单独缓存一个“正在打开的标识”更接近当前事实。用户可能通过系统返回清空了栈,而缓存字段仍然保留上次选择;如果只比较那个字段,再次点击同一展品就可能错误地被当成重复操作。这里把 last 用于恢复意图,把栈用于判断当前页面,两种信息各有职责,不混成一个字段。
快照版本并不是安全校验的全部。当前 restore 接收的是内部创建的结构化对象,因此检查版本和实体存在性即可覆盖这个闭环。以后从文件或网络读入 JSON 时,还需要先验证对象形状、字段类型和长度,再进入恢复方法;把任意对象强制断言成 GuideCheckpoint 不会自动完成这些校验。版本号是迁移入口,不是可信来源证明。
把所有入口接到同一条路径
在第5篇 Index 文件顶部导入 GallerySession,并在已有 stack 字段之后新增 session。source、notice 和 destination 保持原有定义,顺序上让 session 使用已经创建的栈。随后将列表项的点击处理替换成以下代码,避免保留旧的 pushPath 形成旁路。
import { GallerySession } from '../common/GallerySession';
private session: GallerySession = new GallerySession(this.stack);
.onClick(() => {
const opened = this.session.open(row.item.id);
if (!opened) {
this.notice = '展品已不可用,请重新选择';
}
})
在第5篇 Index 的 Column 内,将下面这个按钮放在现有双按钮 Row 之后、notice 文本之前。它只恢复本次会话的最后有效选择。首次启动尚未打开任何展品时,恢复失败显示清楚的提示;这比放一个永远跳到第一件展品的“恢复”按钮更符合动作名称。
Button('恢复上次展品').onClick(() => {
const restored = this.session.restore(this.session.snapshot());
this.notice = restored ? '已恢复上次有效选择' : '暂无可恢复的有效展品';
})
最后,在第4篇延续下来的 ExhibitDetail 中,将返回按钮的处理改为清空所属栈。其他资源化文字、有效性查询和计时器清理保持原样。页面隐藏时仍由已有 onHidden 关闭提示,组件销毁时还有最终清理,不需要在 GallerySession 中触碰页面的计时器句柄。
Button($r('app.string.guide_back_to_list'))
.onClick(() => this.stack.clear())

系统返回继续采用 NavDestination 默认行为。不要在自定义 onBackPressed 中先手动 pop,又返回表示继续默认处理的结果,否则返回路径会有重复处理风险。如果确实需要退出确认,应把是否拦截和何时执行返回作为一项独立设计,并按接口语义返回结果。本工程没有未提交表单,不增加没有业务必要的确认弹窗。
按边界逐项验收
先验证普通链路:冷启动显示列表,点击彩陶打开对应详情,返回后列表仍有原来的三件展品。再点击恢复按钮,应回到彩陶;回到列表并选择青铜,恢复目标随最后一次有效选择变化。每一步检查标题、展厅和说明是否指向同一个实体,不用“页面打开了”代替内容一致性检查。
接着验证重复输入。在分栏中重复点击已经打开的展品,栈应保持一条详情记录,提示轮换不应因每次点击重新开始。切换另一件展品后,原详情退出,新详情取得自己的上下文,旧计时器应停止。这里没有设置时间窗口式点击锁,所以正常的快速切换不会因为固定防抖间隔被吞掉。
然后验证无效快照。尚未打开过任何展品时点击恢复,保持列表并显示“暂无可恢复的有效展品”。在开发验证中,可以给 restore 传入不同的结构版本或不存在的标识,确认它返回 false 且不改变当前栈。修改测试输入后应恢复正式调用,不能把故障注入对象留在用户按钮中。
再验证新增条目的闭环。使用第5篇的追加按钮加入刻纹石片,点击它打开详情,再返回并恢复。这个用例同时检查数据源、实体仓库和导航入口是否使用同一标识。若列表能看到新条目而详情显示不存在,优先检查追加是否只修改了展示数组;不要先修改详情的空结果判断来隐藏仓库缺项。

布局回归沿用第2篇的操作:打开有效详情后扩大和缩小窗口,观察选择是否保持;分栏下再次选择另一件展品,确认返回列表清理的是目的页而非整个应用。语言回归沿用第3篇,检查外壳资源与无效详情说明,不要求样例业务内容自动翻译。将这些断言放在同一份流程中,可以发现模块各自正常、组合后却失去一致性的情况。
生命周期回归则从有效详情切后台,再回前台,观察提示是否继续按单一节奏轮换。首次恢复创建的新详情从第一条提示开始,后台往返保留同一实例时继续已有索引。两种结果来自不同的实例寿命,应分别记录。根组件重建或完整结束进程后重新启动,内存快照为空,这是本次会话设计的预期边界。
收尾时留下可扩展的结构
检查最终工程,应能找到清楚的责任链:Exhibit 定义实体,ExhibitSource 维护列表投影,GallerySession 约束导航意图,Index 组织布局,ExhibitDetail 展示内容并管理自己的轻量资源,EntryAbility 发布能力层前后台事实。资源目录承载应用外壳文案,业务内容继续通过实体模型取得。没有一个模块需要同时解释所有生命周期。
收尾还要删除过渡实现。全局检索旧的直接 pushPath 调用,确认列表正式入口已经统一;检查 Index 是否只实例化一个 source 和一个 session;确认没有在尺寸变化时清空栈,也没有在资源切换时修改业务标识。这些检查针对的是系列演进容易留下的旁路,不是要求所有工程都只能有一个导航入口。当前规则明确以后,新增入口才知道必须遵守哪份协议。
验收记录应保留失败输入和期望结果,而不只写“通过”。例如无效标识保持当前页面、重复选择不增栈、退出进程后快照为空,都能让后来修改代码的人判断行为是否仍然一致。发现问题时先定位被破坏的不变量,再决定修改哪个模块;若直接在界面里补一个条件,往往只是把同一个缺陷转移到另一个入口。
跨进程恢复可以作为后续需求,但必须单独决定保存时机、隐私范围、内容过期和恢复失败行为。系统 UIAbility 备份恢复有自己的版本条件与触发规则,不能仅增加一个配置就承诺所有正常启动都恢复;普通持久化则需要在业务操作时有明确写入策略。无论选择哪条路线,都应恢复可验证的业务意图,再重新建立组件和资源,而不是保存运行时句柄。
这六篇形成的闭环是可解释的:用户选择稳定实体,页面根据自身上下文展示,布局和文案独立适配,资源按当前许可运行,列表按真实变化通知,入口和恢复共同维护导航约束。验收通过的标准应是这些行为在规定输入下成立,并且失败输入有可返回的结果。之后再增加讲解媒体、远端内容或多窗口,每项扩展都能找到自己的接入边界,而不必推翻整个导览工程。
官方参考
更多推荐

所有评论(0)