鸿蒙 Navigation 冷启动白屏复盘:单例 NavPathStack 加一条目标总线

举报
yd_241537561 发表于 2026/11/18 07:04:43 2026/11/18
【摘要】 元服务首页按官方推荐用 @Provide 传 NavPathStack,真机上首个 NavDestination 偶发白屏:冷启动首帧栈对象被重赋值,首个 push 撞上渲染竞态。四时集案例的两层修法——栈改模块级单例、四个模块折叠成一条路由——都写成了可以直接抄的代码。

这篇的素材来自鸿蒙实践中心开源仓 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 里留下那四行注释。踩坑注释不是代码债务,是给下一个人的文档。

【声明】本内容来自华为云开发者社区博主,不代表华为云及华为云开发者社区的观点和立场。转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息,否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0)

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。