鸿蒙 Navigation 冷启动白屏复盘:单例 NavPathStack 加一条目标总线
这篇的素材来自鸿蒙实践中心开源仓 harmony-practice-center/HarmonyOS-AtomSer-multi-server(四时集)的首页导航层。它是一个「一个元服务装四个场景」的架构:首页宫格四个入口,点进去各自是列表页。这类多模块元服务用 Navigation 路由再自然不过,而它恰恰在冷启动阶段踩到了导航栈最阴的坑——并且难得地在注释里把根因写清楚了。
一、症状与根因:@Provide 的栈在首帧被重赋值
Router.ets 全文只有一行导出,但注释里记着完整的事故链:
// 全局导航栈单例:四时集全应用共用一个 NavPathStack。
// 为什么不用 @Provide/@Consume 传栈:冷启动首帧 Navigation 会重赋 @Provide 值,触发
// "pathStack has changed during render",继而导致首个 NavDestination 路由解析失败建空节点(页面空白)。
// 单例让栈对象唯一稳定,根因规避(@Provide/@Consume 竞态)也最简单。
export const MAIN_STACK: NavPathStack = new NavPathStack();拆开说:@Provide/@Consume 的值在组件树首次渲染过程中可能被重赋一次,而 Navigation 内部对「栈对象变了」的反应是放弃当次路由解析——表现为首个 NavDestination 建出空节点,用户看到的就是一屏白。错误信息 pathStack has changed during render 在日志里一闪而过,界面层完全无感,特别难定位。
修法不是去跟竞态搏斗,而是让栈对象根本没有机会变:模块级单例。一个 module 的顶层 const 天然只有一个实例,谁 import 到的都是同一个对象,@Provide 首帧重赋值的问题从根上就不存在了。
二、第二层修法:四个模块折叠成一条路由
单例还不够。注释里提到的第二个坑是:这个 SDK 上冷启动后首个 push 只对 PageMap 的第 1 个分支稳定,首跳直推后面的分支同样可能建空节点。四时集的对策是把「四个模块四个路由」折叠成「一条路由一个目的地」,用一条全局总线在 push 前传目标:
// 导航目标总线:四时集首页 → ModuleHub 的单向传参(页面跳转前写入,渲染只读)。
// 作用:把"四个模块"折叠为同一个 branch-1 路由 'ModuleHub',规避本 SDK 冷启动 Navigation
// 首个 push 只对 PageMap 第 1 分支稳定的 bug(凡首次直推晚分支就会建空节点 → 白屏)。
export let moduleTarget: string = 'dining';
export function setModuleTarget(route: string): void {
moduleTarget = route;
}首页的 PageMap 只构造一个目的地节点,ModuleHub 内部再按目标名条件渲染。首页注释里也交代了为什么不用 navDestination 的多分支:
// 始终构造同一个目的地节点,再在组件内部按名称选择内容。
@Builder
PageMap(name: string) {
ModuleHub({ destination: name })
}
build() {
Navigation(MAIN_STACK) { /* 首页宫格 */ }
.mode(NavigationMode.Stack)
.hideTitleBar(true)
.navDestination(this.PageMap)
}跳转入口因此变成两行:先写总线、再 push 同一个名字。未就绪的模块走 Toast 占位,catch 静默——占位提示失败不该影响主流程:
openLauncher(l: ModuleTheme): void {
if (l.ready) {
setModuleTarget(l.route);
MAIN_STACK.pushPathByName('ModuleHub', null);
} else {
try {
this.getUIContext().getPromptAction().showToast({
message: '「' + l.title + '」正在装修中,敬请期待',
duration: 1500
});
} catch (e) {
// 占位 Toast 失败不影响使用,静默忽略
}
}
}注意传参方向:moduleTarget 是「跳转前写入、渲染时只读」的全局变量,不是双向状态。首跳竞态的根源是渲染期间传参,把传参挪到 push 之前同步完成,竞态就没有发生的窗口。代价是 ModuleHub 内部要自己管「当前显示哪个模块」,以及返回再进时目标已经就位——对固定几个入口的场景,这笔账划算。
三、入口注册表:ready 标记决定「能进」还是「占位」
首页宫格的数据源是一张模块注册表,路由名、品牌色、是否就绪全在数据里,加模块就是加一行注册,而不是复制一坨界面代码:
export interface ModuleTheme {
key: string; // dining | hotel | pet | book
title: string; // 模块名
slogan: string;
emoji: string;
accent: string;
accentSoft: string;
route: string; // NavDestination 路由名
ready: boolean; // 未建好的模块首页先 Toast 占位
}
export const LAUNCHERS: ModuleTheme[] = [
{ key: 'dining', title: '餐厅点餐', slogan: '鲜小馆 · 今日特惠', emoji: '🍜',
accent: '#FF6B35', accentSoft: '#FFF3EB', route: 'DiningList', ready: true },
{ key: 'hotel', title: '酒店房型', slogan: '云栖酒店 · 全景看房', emoji: '🏨',
accent: '#1F4E79', accentSoft: '#EAF1F8', route: 'HotelList', ready: true },
// pet / book 两项同构,略
];配套还有两个小件:一个十行的 TagChip 胶囊组件(文字、前景色、背景色三个属性,列表里的「招牌」「亲人」「在读」标签全用它),一份中性色 token(NEUTRAL)加模块品牌色的两层主题。复用粒度卡在「视觉最小单元」上——胶囊、色板、宫格卡——不抽象整个页面,这正是组件库长歪之前的健康形态。
四、给后来者的三句话
其一,Navigation 的栈不要用 @Provide/@Consume 传,直接模块级单例,省掉一类只在真机冷启动出现的白屏;其二,SDK 对「首个 push」的行为最敏感,多模块元服务可以把首跳折叠成单一目的地加总线传参,绕开分支稳定性问题;其三,把根因写进代码注释——这篇能写成文章,全靠原作者在 Router.ets 里留下那四行注释。踩坑注释不是代码债务,是给下一个人的文档。
- 点赞
- 收藏
- 关注作者
评论(0)