HarmonyOS 折叠菜单架构·第2篇:Navigation 返回状态契约【共创稿事节】
从菜单列表进入详情,应只传稳定菜品标识;返回路径交由导航栈维护而非在页面手工拼接。页面最终呈现给用户的是一个结果,工程里真正需要维护的却是产生这个结果的全过程。
具体到「菜谱详情」这个页面,路由参数应当小,把整个菜谱对象压进栈会在修改后形成旧快照。本文把讨论范围限定在「Navigation 返回状态契约」,不把界面能显示和数据已经被正确处理混为一谈。

先建立FoldRecipe的契约
对「路由参数应当小」而言,先确定谁负责作出判断。因为把整个菜谱对象压进栈会在修改后形成旧快照,处理时需要只传recipeId,到目标页再读取最新内容。这样才有机会得到「返回列表后数据能够一致更新」的结果;与之关联的「返回是撤销导航而非修改数据」也应采用一致的责任划分。
「页面名必须注册」容易被顺利路径掩盖。问题在于pushPathByName传入未知目的地不会自动创建页面,所以应当在Navigation的目的地映射中注册RecipeDetail。正常结果是导航入口与页面实现有明确对应;一旦失败,还需保留足以复现的操作状态,特别是「进入详情后删除菜品」这类边界场景。
讨论「栈与页面不能混用」时应先识别具体风险:把同一个NavPathStack复用到多个Navigation违反约束。采取「每个Navigation实例拥有自己的栈」后,预期达到分栏嵌套不会互相弹出页面。与此同时,「连续点击容易重复入栈」也可能改变执行条件,不能只用一种固定输入判断是否正确。

在菜谱详情里,「非法标识应先拒绝」会影响后续操作。风险是:外部来源的空id可能导致详情显示上一条记录。处理办法是入栈前执行长度与格式检查。若要确认「无效点击不改变当前路由」,可以安排「使用系统返回手势」作为回归用例,结果须符合导航栈回退且不触发未经确认的数据覆盖。
先明确「返回是撤销导航而非修改数据」为什么会失败:按返回键时把编辑对象恢复初值会丢失未提交内容。这不是简单刷新界面就能解决的问题,需要导航与内容保存流程分别定义。验收时不仅要看到「退出详情不会悄悄删除草稿」,还要确认本次操作没有改动其他不相关的数据。
状态变更的实现路径
对于FoldRecipe这个工程,下面的片段把「路由参数应当小」所需的行为收敛到可以定位的代码上。主要涉及pushPathByName。在RecipeDetail.ets或对应common模块接入时,应明确调用方传入什么,尤其要防止「外部来源的空id可能导致详情显示上一条记录」这一风险继续影响后续处理。对应的工程措施是「入栈前执行长度与格式检查」,不能只靠页面文字来表示处理成功。
interface RecipeParam {
recipeId: string;
}
function validRecipeId(value: string): boolean {
return value.length > 0 && value.length <= 48 &&
value.indexOf(' ') < 0;
}
function openRecipe(stack: NavPathStack, id: string): void {
if (!validRecipeId(id)) {
return;
}
const params: RecipeParam = { recipeId: id };
stack.pushPathByName('RecipeDetail', params);
}
Navigation需要把路由名映射到真正的目的页面,光有pushPathByName还不能构成完整页面链路。页面只注册当前用到的RecipeDetail,并通过统一校验函数传参。
@Component
struct RecipeDetailView {
build() { Text('菜谱详情').fontSize(22) }
}
@Entry
@Component
struct RecipeNavigationHost {
private stack: NavPathStack = new NavPathStack();
@Builder
destination(name: string) {
if (name === 'RecipeDetail') {
NavDestination() { RecipeDetailView() }
.title('菜谱详情')
}
}
build() {
Navigation(this.stack) {
Button('打开菜谱').onClick(() => {
openRecipe(this.stack, 'recipe-001');
})
}.title('菜单').navDestination(this.destination)
}
}
这段实现适合先用静态数据检查「页面名必须注册」和「窄屏和宽屏要共享语义」两条路径。前者要解决pushPathByName传入未知目的地不会自动创建页面,后者要求路由层和选择状态都使用同一recipeId。代码层只承诺得到可解释的状态,真正的展示和持久化要在调用位置按菜谱详情的业务流程串起来;这样才不会把界面点击当作仓储提交。
还要注意「参数结构不宜频繁变更」:不同入口传string或object增加目标页分支。由统一RecipeParam接口并集中解析承担这一职责后,其他入口调用相同函数可以得到一致处理。最后用「尝试传入空字符串」观察入口直接拒绝,不出现空白详情页,检查异常路径是否仍遵守同一语义。
如果计划在此基础上增加新功能,先确认「导航设计应面向长期演进」是否仍成立。把目的地名称收敛到单一常量表带来的变化必须被单独验证,而不是假设新增页面会自然继承既有保障。
异常情况下要守住什么
「窄屏和宽屏要共享语义」与「导航设计应面向长期演进」实际上相互制约。前一条风险表现为宽屏详情作为面板,窄屏作为目的地页面;相应的处理是路由层和选择状态都使用同一recipeId。增加新的操作入口之后,也应该继续满足「跨断点仍能定位同一菜品」,不能为新页面单独复制一份规则。
从输入与输出看「连续点击容易重复入栈」:输入环节的风险是双击菜单可能形成两个相同详情页,因此先落实入口提供操作状态或去重判断;输出环节则应验证「按一次返回能符合用户预期」。结合「尝试传入空字符串」这一操作,预期结果为入口直接拒绝,不出现空白详情页,能够帮助定位发生偏差的阶段。
最后审查「参数结构不宜频繁变更」这条约束:不同入口传string或object增加目标页分支,因此应当统一RecipeParam接口并集中解析。只有业务侧明确承担这项责任,后续分享入口可重用同一契约才能成为可以长期复核的标准,而不是某次页面渲染的巧合。

先确定「恢复后的路由要核对数据」的处理界限。被删除的菜谱可能仍留在导航栈里;具体做法是详情读取不到记录时显示可返回的空态。验收应观察「不会因为无记录使导航失效」,而不只判断界面是否响应。转到「栈与页面不能混用」的路径,也必须遵守同样的数据约束。
把「导航设计应面向长期演进」单独列为检查条件,问题更容易识别:直接在组件中散布字符串难以统一重命名。实施上建议把目的地名称收敛到单一常量表,目标是修改页面路径不会遗漏部分入口。还要补测「使用系统返回手势」,其结果应满足导航栈回退且不触发未经确认的数据覆盖,不能只看首次进入的画面。
用明确的断言代替主观感觉
本节把「菜谱详情」的验证条件具体化。验证应该以官方接口语义、可见的页面状态与可读取的数据为依据,不能把没有在设备上执行的逻辑检查写成性能实测;需要编译、权限或设备支持的步骤,应在对应开发环境中按项目配置完成。
先复现「正常点击一道菜」。此时的通过条件应写成「栈增加一条RecipeDetail并收到正确recipeId」,并对照「导航设计应面向长期演进」的约束确认状态来源。如果结果偏离,先检查把目的地名称收敛到单一常量表是否真正执行,而不是立即更换页面布局。
针对「快速连续点击两次」,观察点不仅是操作能否完成,还包括避免重复入栈引起返回操作需要执行两次。建议保留触发前后的业务标识,尤其在「路由参数应当小」存在时,核对返回列表后数据能够一致更新,才能排除旧状态干扰。
把「尝试传入空字符串」独立成一条回归记录:预期入口直接拒绝,不出现空白详情页。若出现异常,沿页面名必须注册对应的处理逻辑往回定位,检查是否满足「在Navigation的目的地映射中注册RecipeDetail」这一前置条件。

「进入详情后删除菜品」不应被正常路径的检查覆盖。这里必须验证详情显示已删除状态并提供返回入口,并且确认「栈与页面不能混用」相关字段没有出现旁路修改;否则当前页面看似完成了操作,实际数据却仍可能不一致。
对「宽屏切到窄屏继续阅读」做一次中断后重试,记录最后的可见结果是否符合详情标识不变,路由结构符合当前布局。这一用例能同时观察「非法标识应先拒绝」的边界,重点看无效点击不改变当前路由,不必预设任何未经采样的性能指标。
完成「使用系统返回手势」之后,直接检查导航栈回退且不触发未经确认的数据覆盖。如果失败,不要只保存一张截图,而应记录返回是撤销导航而非修改数据的触发顺序,以及「导航与内容保存流程分别定义」是否被绕过,这些信息才足以支持修正。
下一次修改前要保留的约束
若新需求改变了「导航设计应面向长期演进」的业务含义,应先检查既有措施「把目的地名称收敛到单一常量表」是否仍适用,而不是在按钮里临时加分支。此前的「正常点击一道菜」也需要重新验证。
把「使用系统返回手势」保留为发布前回归项,是因为导航栈回退且不触发未经确认的数据覆盖。它和「路由参数应当小」共同约束了数据进入系统以及返回用户界面的两个端点。
在资源、路由和权限问题上,建议以项目实际 target SDK 和设备 API 能力为准。本例围绕 HarmonyOS API 26.0.0 Release 可查证的公共机制组织,代码片段应放入完整 Stage 工程中按开发者文档补齐工程声明和对应资源。页面与技术图使用的示例状态一致,涉及数据写入及生命周期的部分应在 DevEco Studio 中分别执行编译与交互核查。
官方参考
更多推荐


所有评论(0)