一个应用有四个底部页签、二十多个二级页面时，导航问题通常不会先表现为编译错误，而会变成更难复现的用户故障：点击“全部实验”偶尔没有切换选中态；新增一个页签后，首页快捷入口跳到了错误页面；桌面卡片传来不存在的实验编号，详情页却静默展示默认实验；路由失败后按钮没有任何反馈；从外部入口进入详情，再点返回时直接离开应用。

本文基于 化学实验室 1.0.5 的真实 HarmonyOS ArkTS 源码展开。当前主入口 Index.ets 使用 Tabs + TabsController 组织首页、实验室、学习和我的四个主页面；HomePage.ets 一部分入口通过 (index: number) => void 切换页签，另一部分入口直接调用 router.pushUrl()；main_pages.json 注册了 26 个页面；ExperimentSimPage.ets、ReadingDetailPage.ets 和 KnowledgeDetailPage.ets 在 aboutToAppear() 中读取路由参数。

这套实现能工作，但导航契约散落在 UI、字符串、数字和详情页默认值里。本文不把整个项目强行迁移到另一套路由框架，而是在现有 TabsController + router 基础上完成一轮可落地的增量治理：用稳定主标签代替裸索引，用路由目录代替自由字符串，用参数守卫阻断无效输入，用单一函数同步控制器与选中态，并把返回行为写成可验证策略。

主导航不是四个 TabContent 的排列，而是把入口身份、状态切换、参数校验和返回策略约束在同一份导航契约中。

本文唯一校验标记：CHEM-LAB-ONE12-NAVIGATION-CONTRACT-20260730

本文将完成以下内容：

• 还原 Index.ets 与 HomePage.ets 的真实入口关系。
• 解释为什么裸数字页签在功能增加后容易失控。
• 建立主标签 ID、索引和视觉配置的唯一映射。
• 把二级页面路径收进受控路由目录。
• 为实验、阅读和知识详情参数建立运行时守卫。
• 处理同页签重复点击、路由失败、无效参数和外部入口。
• 定义主标签与二级页面不同的返回策略。
• 给出可以在真机和自动化测试中复核的验收表。

一、先还原当前项目的导航结构

Index.ets 的核心结构很直接：

@State currentIndex: number = 0
private tabController: TabsController = new TabsController()

Tabs({
  barPosition: BarPosition.End,
  index: this.currentIndex,
  controller: this.tabController
}) {
  TabContent() {
    HomePage({
      onSwitchTab: (index: number) => {
        this.tabController.changeIndex(index)
      }
    })
  }
  .tabBar(this.TabBarBuilder('首页', 0,
    $r('app.media.ic_tab_home'),
    $r('app.media.ic_tab_home')))

  TabContent() { LabPage() }
    .tabBar(this.TabBarBuilder('实验室', 1,
      $r('app.media.ic_tab_lab'),
      $r('app.media.ic_tab_lab')))

  TabContent() { LearningPage() }
    .tabBar(this.TabBarBuilder('学习', 2,
      $r('app.media.ic_tab_learn'),
      $r('app.media.ic_tab_learn')))

  TabContent() { MinePage() }
    .tabBar(this.TabBarBuilder('我的', 3,
      $r('app.media.ic_tab_mine'),
      $r('app.media.ic_tab_mine')))
}
.onChange((index: number) => {
  this.currentIndex = index
})

这里至少存在三份相互依赖的信息：TabContent 的排列顺序、TabBarBuilder 的目标索引、首页回调传入的数字。只要其中一份发生变化而另外两份没同步，代码仍可能编译通过，错误却会在点击时出现。

HomePage.ets 同时存在两种导航方式。切主标签时传裸数字：

Text('全部实验 >')
  .onClick(() => {
    this.onSwitchTab(1)
  })

Button('去学习')
  .onClick(() => {
    this.onSwitchTab(2)
  })

进入二级页面时传自由路径：

private openPage(url: string): void {
  try {
    router.pushUrl({ url: url })
  } catch (_) {
  }
}

快捷入口把页面字符串直接写在视图中：

this.QuickAction('每日一题', '每日练习',
  $r('app.media.ic_tab_learn'),
  'views/learning/DailyQuizPage')

this.QuickAction('全局搜索', '快速查找',
  $r('app.media.ic_tab_learn'),
  'views/learning/GlobalSearchPage')

因此当前导航并不是一个系统，而是三类局部约定：数字代表主标签、字符串代表页面、对象字面量代表详情参数。文章后面的改造目标，就是把这三类约定集中到可以检查的类型和函数里。

二、问题一：裸数字没有业务语义

1 在首页代码里并不天然表示“实验室”，只有读者同时打开 Index.ets 才能知道它的含义。更麻烦的是，产品如果把“学习”移到第二个位置，或者插入“发现”页签，原有 onSwitchTab(1) 不会报错，只会跳到新的第 2 页。

裸数字还有两个测试盲点：

1. onSwitchTab(99) 在类型系统里完全合法。
2. 业务测试只能断言索引，不能表达“用户请求进入实验室”。

因此第一步不是写更多 if，而是把业务目标从 UI 索引中分离出来。

export enum MainTabId {
  HOME = 'home',
  LAB = 'lab',
  LEARNING = 'learning',
  MINE = 'mine'
}

export interface MainTabSpec {
  id: MainTabId
  index: number
  title: string
}

业务组件只知道 MainTabId.LAB，只有主入口知道它当前映射到索引 1。以后调整顺序时，只修改目录，不需要全局搜索所有 onSwitchTab(1)。

三、问题二：控制器与选中态存在两个写入口

当前首页回调只调用：

this.tabController.changeIndex(index)

而图标和文字的选中颜色依赖：

this.currentIndex === targetIndex

通常 Tabs 会在切换后触发 onChange，再把 currentIndex 更新回来。但从工程边界看，命令由控制器发出，视觉状态由事件回写，两者之间存在一个短暂窗口，也存在异常索引、重复点击和未来异步入口没有统一处理的问题。

更可靠的方式是只暴露一个 selectTab()：先校验目标，再同步业务状态和控制器。onChange 仍保留，用于接收用户直接点击页签产生的变化。

private selectTab(tabId: MainTabId): boolean {
  const target = MainTabCatalog.findById(tabId)
  if (!target) {
    this.navigationMessage = '目标页签不存在'
    return false
  }

  if (this.currentIndex === target.index) {
    return true
  }

  this.currentIndex = target.index
  this.tabController.changeIndex(target.index)
  this.navigationMessage = ''
  return true
}

同页签重复点击在这里被定义为幂等操作。是否需要“再次点击回到列表顶部”属于另一个明确需求，不能依靠控制器偶然重建页面来实现。

四、问题三：自由页面字符串无法集中校验

main_pages.json 注册了实验模拟、实验报告、每日一题、错题本、阅读详情、知识详情、设置和隐私协议等 26 个页面。当前 HomePage 直接传入字符串，只要路径少一个字符，错误就要到运行时才出现。

目录注册和业务打开还可能不同步：

• main_pages.json 新增了页面，UI 仍写旧路径。
• 页面文件移动后，某个角落里的快捷入口没有修改。
• 外部入口传来一个未注册路径，代码仍尝试打开。
• 测试无法直接列出应用允许跳转的业务目标。

在不迁移现有路由框架的前提下，可以先建立受控页面枚举：

export enum AppPage {
  EXPERIMENT_SIM = 'views/experiment/ExperimentSimPage',
  DAILY_QUIZ = 'views/learning/DailyQuizPage',
  WRONG_QUESTION = 'views/learning/WrongQuestionPage',
  READING_LIST = 'views/learning/ReadingListPage',
  READING_DETAIL = 'views/learning/ReadingDetailPage',
  FORMULA = 'views/learning/FormulaPage',
  EXAM_PRACTICE = 'views/learning/ExamPracticePage',
  LEARNING_STATS = 'views/mine/LearningStatsPage',
  UNIT_CONVERTER = 'views/learning/UnitConverterPage',
  GLOBAL_SEARCH = 'views/learning/GlobalSearchPage'
}

QuickAction 不再接收任意 string，而是接收 AppPage：

@Builder
QuickAction(
  title: string,
  subtitle: string,
  icon: Resource,
  page: AppPage
) {
  Row() {
    // 原有 UI 保持不变
  }
  .onClick(() => {
    this.openPage(page)
  })
}

这样拼写错误会在编译阶段暴露，页面目录也能参与单元测试。

五、问题四：空 catch 把失败变成“按钮没反应”

HomePage.openPage() 当前捕获异常后什么也不做。对开发者而言，日志里没有失败页面、参数和错误原因；对用户而言，点击后没有加载、错误或重试状态。导航异常被吞掉后，最容易被误判成触摸事件或性能问题。

导航服务至少应返回明确结果：

export interface NavigationResult {
  success: boolean
  message: string
}

export class AppNavigator {
  static async open(page: AppPage): Promise<NavigationResult> {
    try {
      await router.pushUrl({ url: page })
      return { success: true, message: '' }
    } catch (error) {
      const reason = error instanceof Error ? error.message : '未知路由错误'
      return {
        success: false,
        message: `页面打开失败：${reason}`
      }
    }
  }
}

页面不需要理解底层异常，但必须把失败转换成可见状态：

@State navigationMessage: string = ''
@State navigationBusy: boolean = false

private async openPage(page: AppPage): Promise<void> {
  if (this.navigationBusy) {
    return
  }

  this.navigationBusy = true
  const result = await AppNavigator.open(page)
  this.navigationBusy = false
  this.navigationMessage = result.message
}

UI 可以在快捷区下方显示轻量错误提示并提供重试。关键不是提示样式，而是不能让一次失败完全失去证据。

六、建立唯一的主标签目录

主标签目录同时承担 ID、索引和标题映射。为了符合 ArkTS 的静态类型边界，下面使用显式对象和方法，不依赖运行时修改对象布局。

export class MainTabCatalog {
  private static readonly ITEMS: MainTabSpec[] = [
    { id: MainTabId.HOME, index: 0, title: '首页' },
    { id: MainTabId.LAB, index: 1, title: '实验室' },
    { id: MainTabId.LEARNING, index: 2, title: '学习' },
    { id: MainTabId.MINE, index: 3, title: '我的' }
  ]

  static all(): MainTabSpec[] {
    return MainTabCatalog.ITEMS
  }

  static findById(id: MainTabId): MainTabSpec | undefined {
    return MainTabCatalog.ITEMS.find((item: MainTabSpec) => item.id === id)
  }

  static findByIndex(index: number): MainTabSpec | undefined {
    return MainTabCatalog.ITEMS.find((item: MainTabSpec) => item.index === index)
  }
}

目录必须满足三个不变量：索引从 0 连续、ID 不重复、索引不重复。可以写一个纯函数检查，在测试或开发构建中执行：

export function validateMainTabs(items: MainTabSpec[]): string[] {
  const errors: string[] = []
  const ids: string[] = []
  const indexes: number[] = []

  items.forEach((item: MainTabSpec, position: number) => {
    if (item.index !== position) {
      errors.push(`索引不连续：${item.id}`)
    }
    if (ids.includes(item.id)) {
      errors.push(`ID 重复：${item.id}`)
    }
    if (indexes.includes(item.index)) {
      errors.push(`索引重复：${item.index}`)
    }
    ids.push(item.id)
    indexes.push(item.index)
  })

  return errors
}

这一步把原本只能靠人工对照的隐含关系变成了可执行规则。

七、Index 只保留一个主标签切换入口

改造后的 Index 仍使用现有 TabsController，但业务组件不再接触索引：

@Entry
@Component
struct Index {
  @State currentIndex: number = 0
  @State navigationMessage: string = ''
  private tabController: TabsController = new TabsController()

  private selectTab(tabId: MainTabId): boolean {
    const target = MainTabCatalog.findById(tabId)
    if (!target) {
      this.navigationMessage = '无法识别目标页签'
      return false
    }

    if (this.currentIndex !== target.index) {
      this.currentIndex = target.index
      this.tabController.changeIndex(target.index)
    }
    this.navigationMessage = ''
    return true
  }

  private syncTabFromIndex(index: number): void {
    const target = MainTabCatalog.findByIndex(index)
    if (!target) {
      this.navigationMessage = `收到无效页签索引：${index}`
      return
    }
    this.currentIndex = target.index
  }
}

构建区只传语义化回调：

HomePage({
  onSwitchTab: (tabId: MainTabId) => {
    this.selectTab(tabId)
  }
})

// Tabs 的变化统一回写
.onChange((index: number) => {
  this.syncTabFromIndex(index)
})

HomePage 的接口随之收窄：

onSwitchTab: (tabId: MainTabId) => void = () => {}

// 全部实验
this.onSwitchTab(MainTabId.LAB)

// 去学习
this.onSwitchTab(MainTabId.LEARNING)

业务含义、组件接口和测试断言终于使用同一种语言。

八、主标签与二级页面不能混用同一种返回模型

四个主标签是同一级内容区域，切换主标签不应向页面栈持续压入记录。否则用户在首页、实验室、学习之间切换多次后，系统返回键可能逐个回放历史标签，体验与底部导航的常见预期不一致。

二级页面则不同。实验模拟、阅读详情、知识详情和设置页都需要可见返回入口，并且系统返回操作应回到来源页面。因此本文采用以下策略：

导航类型	实现	是否入栈	返回行为
主标签切换	TabsController.changeIndex()	否	根页面交给系统返回
首页到实验模拟	受控 router.pushUrl()	是	返回首页
学习列表到详情	受控 router.pushUrl()	是	返回原列表与滚动上下文
外部入口到详情	先建立根入口，再进入详情	是	返回应用根入口，不直接退出
无效目标	不跳转，显示可恢复错误	否	保持当前页面

这里最重要的不是某一个 API，而是“来源上下文必须可解释”。外部入口如果直接启动一个详情页而没有应用内来源栈，router.back() 可能无法回到预期页面。更稳妥的增量方案是：EntryAbility 只解析外部目标，先让 pages/Index 就绪并选择主标签，再由主入口消费一次待处理请求进入二级页。

九、为外部入口定义窄导航请求

外部启动参数不应该直接携带任意页面路径。可以定义一个受控请求：

export interface PendingNavigationRequest {
  requestId: string
  tabId: MainTabId
  page?: AppPage
  experimentId?: string
}

字段含义如下：

• requestId 用于防止冷启动和热启动重复消费同一请求。
• tabId 必须存在，保证任何请求都有安全根入口。
• page 只能取路由目录中的值。
• 业务参数使用明确字段，不接受任意对象拼接。

主入口消费请求时按固定顺序执行：

1. 校验 requestId 是否已处理。
2. 校验并切换 tabId。
3. 等待主标签状态稳定。
4. 校验 page 与对应参数。
5. 进入二级页面。
6. 记录已消费 ID 并清空待处理请求。

如果第 4 步失败，用户仍停留在可用主标签，而不是进入空白或错误详情页。

十、参数类型声明不等于运行时校验

ExperimentSimPage.ets 当前这样读取参数：

interface SimRouterParams {
  expId?: string
  expName?: string
}

const params = router.getParams() as SimRouterParams | undefined
if (params?.expId) {
  this.expId = params.expId
}
if (params?.expName) {
  this.title = params.expName
}

as SimRouterParams 只告诉编译器“把它当作这种类型”，并不会验证运行时对象。外部入口、旧版本卡片或错误调用仍可能传入未知 ID、空字符串、超长标题或类型不符的值。

当前页面还有一个业务特征：没有 expId 时会保留默认 acid_base，这使首页“开始探索”能直接打开默认实验。参数守卫不能破坏这个既有行为，应区分“未指定，使用默认值”和“明确指定了无效值”。

十一、实验参数守卫必须校验业务存在性

仅判断字符串非空不够，实验 ID 还必须存在于 getAllExperiments() 数据源。可以把解析器写成纯函数：

export interface ValidExperimentRoute {
  expId: string
  expName: string
  usedDefault: boolean
}

export interface ExperimentRouteResult {
  value?: ValidExperimentRoute
  error: string
}

export function parseExperimentRoute(
  params: SimRouterParams | undefined,
  experiments: Experiment[]
): ExperimentRouteResult {
  if (!params?.expId) {
    const fallback = experiments.find(
      (item: Experiment) => item.id === 'acid_base'
    )
    if (!fallback) {
      return { error: '默认实验不存在' }
    }
    return {
      value: {
        expId: fallback.id,
        expName: fallback.name,
        usedDefault: true
      },
      error: ''
    }
  }

  const target = experiments.find(
    (item: Experiment) => item.id === params.expId
  )
  if (!target) {
    return { error: `实验编号无效：${params.expId}` }
  }

  return {
    value: {
      expId: target.id,
      expName: target.name,
      usedDefault: false
    },
    error: ''
  }
}

标题不再相信调用方传入的 expName，而是从已验证的实验数据源读取，避免 ID 和标题互相矛盾。

页面生命周期中只消费验证结果：

@State pageError: string = ''

aboutToAppear(): void {
  const raw = router.getParams() as SimRouterParams | undefined
  const result = parseExperimentRoute(raw, getAllExperiments())

  if (!result.value) {
    this.pageError = result.error
    return
  }

  this.expId = result.value.expId
  this.title = result.value.expName
  this.initEngine()
  this.resetExperiment()
  this.loadFavoriteState()
}

当参数无效时，页面应显示错误态和“返回实验室”按钮，不能继续初始化一个与请求无关的引擎。

十二、阅读详情参数应阻断不存在的文章

ReadingDetailPage.ets 当前以第一篇文章作为初始值，只有找到目标时才替换：

@State article: ReadingArticle = getReadingArticles()[0]

const params = router.getParams() as ReadingDetailParams | undefined
if (params?.id) {
  const target = getReadingArticleById(params.id)
  if (target) {
    this.article = target
  }
}

如果传入不存在的 id，页面会静默展示第一篇文章。用户看到的是完整内容，很难意识到导航已经错了。这类“看起来正常”的错误比白屏更危险，因为收藏、朗读和学习记录都会落到错误文章上。

建议把文章状态改成可空或显式页面状态：

enum DetailPageState {
  LOADING = 'loading',
  CONTENT = 'content',
  ERROR = 'error'
}

@State pageState: DetailPageState = DetailPageState.LOADING
@State pageError: string = ''

private loadArticle(id: string | undefined): void {
  if (!id) {
    this.pageState = DetailPageState.ERROR
    this.pageError = '缺少文章编号'
    return
  }

  const target = getReadingArticleById(id)
  if (!target) {
    this.pageState = DetailPageState.ERROR
    this.pageError = `未找到文章：${id}`
    return
  }

  this.article = target
  this.pageState = DetailPageState.CONTENT
}

只有 CONTENT 状态才能启用朗读、收藏和阅读进度写入。

十三、知识详情不要信任调用方传来的整段正文

KnowledgeDetailPage.ets 当前允许路由参数直接覆盖标题、分类、摘要和正文：

if (params?.title) this.title = params.title
if (params?.category) this.category = params.category
if (params?.summary) this.summary = params.summary
if (params?.content) this.content = params.content

这会扩大参数面，也让同一知识点可能因为不同调用方传入内容不同而展示不一致。更稳妥的模式是只传稳定 id，详情页从唯一知识数据源读取完整内容。若暂时不能改数据模型，至少应限制字符串长度、拒绝空白内容，并确保 id 与收藏记录使用同一个规范化值。

推荐的目标接口只有：

export interface KnowledgeDetailParams {
  id: string
}

路由参数越窄，兼容、测试和回放越容易。

十四、把页面白名单与 main_pages.json 做一致性检查

路由目录不是 main_pages.json 的替代品。前者是业务允许打开的目标，后者是系统注册页面。两者必须保持一致：

export function findMissingRegisteredPages(
  businessPages: AppPage[],
  registeredPages: string[]
): string[] {
  return businessPages.filter((page: AppPage) => {
    return !registeredPages.includes(page)
  })
}

实际工程中可以在 Node 构建脚本或测试里读取 main_pages.json，校验 AppPage 中每个值都已注册。反向不要求完全一致，因为隐私协议等页面可能不从首页快捷入口打开，但“受控目录中存在、系统注册中缺失”必须让构建失败。

十五、导航结果需要最少可观测字段

为了定位真机问题，导航日志至少记录：

requestId=home-quiz-20260717-001
source=home.quick_action
targetTab=learning
targetPage=views/learning/DailyQuizPage
paramKeys=[]
result=success
durationMs=18

失败时记录错误码或异常消息，但不要记录用户隐私正文。对于实验参数，可记录 expId 这类非敏感业务标识；对于自由文本、笔记和搜索词，应避免原样写入生产日志。

建议把日志放在 AppNavigator 边界，而不是每个按钮各写一份。这样成功率、耗时和失败目标可以统一统计。

十六、页面状态要覆盖忙碌、错误和重复点击

首页快捷入口现在没有忙碌状态。连续点击可能重复压栈，导致返回时经过两个相同页面。简单的 navigationBusy 可以阻断同一个短时操作，但不要把整个页面永久锁住：

private async openExperiment(exp: Experiment): Promise<void> {
  if (this.navigationBusy) {
    return
  }

  this.navigationBusy = true
  const result = await AppNavigator.openExperiment(exp)
  this.navigationBusy = false

  if (!result.success) {
    this.navigationMessage = result.message
  }
}

按钮在忙碌时显示禁用或进度状态；失败后恢复可点击并保留重试入口。测试时要连续点击 5 次，确认页面栈只增加一次。

十七、底部导航本身也要做可用性复查

当前 TabBarBuilder 使用 24vp 图标、56vp 高度和 10vp 标签。布局稳定，但标签字号偏小。针对手机、折叠屏和平板，应验证以下内容：

• 四个标签在系统字体放大后仍不重叠。
• 标题至少保持单行省略，图标与文字不越界。
• 选中与未选中颜色在浅色背景上可辨认。
• 图标和文字共同响应点击，触摸目标保持足够大。
• 系统底部导航区与应用页签不发生遮挡。
• 横屏和小窗口下仍能进入全部四个主页面。

项目当前通过 statusBarHeight 与 bottomBarHeight 接收窗口策略。若窗口仍采用非沉浸模式，不能再盲目叠加一层固定安全区；若未来切换沉浸式，则必须从真实避让区计算，而不是写死设备高度。

十八、导航迁移要分阶段，不做一次性重写

华为当前文档将组件导航 Navigation 作为推荐方案，并把 @ohos.router 页面路由标记为不推荐。对现有项目，这不等于必须在一次文章改造里重写全部 26 个页面。更稳妥的顺序是：

1. 先建立 MainTabId、AppPage 和参数守卫。
2. 让所有 UI 只依赖导航契约，不直接依赖自由路径。
3. 补齐失败态、返回策略和自动化测试。
4. 再把 AppNavigator 的底层从 router 迁移到 Navigation/NavPathStack。
5. 业务页面与测试继续使用同一上层接口。

先隔离依赖再迁移框架，可以显著缩小回归范围。

十九、单元测试先覆盖纯映射与参数守卫

不需要启动 UI 就能验证的规则应优先写成纯函数测试：

describe('MainTabCatalog', () => {
  it('maps LAB to index 1', () => {
    const tab = MainTabCatalog.findById(MainTabId.LAB)
    expect(tab?.index).assertEqual(1)
  })

  it('rejects unknown index', () => {
    const tab = MainTabCatalog.findByIndex(99)
    expect(tab).assertUndefined()
  })
})

参数守卫至少覆盖：

用例	输入	预期
默认实验	无 expId	打开 acid_base，标记使用默认值
合法实验	已存在 ID	使用数据源中的 ID 与名称
未知实验	not_found	错误态，不初始化引擎
空阅读 ID	空或缺失	错误态，不启用朗读
未知阅读 ID	数据源不存在	错误态，不回落第一篇
页签越界	索引 99	保持当前页并记录错误
重复请求	相同 requestId	只消费一次

二十、真机交互测试要覆盖返回路径

纯函数通过后，再在真机或模拟器执行导航矩阵：

1. 冷启动进入首页，四个页签选中态与内容一致。
2. 首页点“全部实验”，只切到实验室，不增加二级页面栈。
3. 首页点“去学习”，学习页签选中态立即更新。
4. 首页打开每日一题，返回后仍回首页且滚动位置合理。
5. 实验卡片进入指定实验，标题和引擎都对应同一 expId。
6. 连续点击实验卡片五次，只生成一个详情实例。
7. 向实验页注入未知 ID，出现错误态，不展示酸碱默认实验冒充成功。
8. 向阅读详情注入未知 ID，不展示第一篇文章。
9. 从外部入口进入详情，返回后仍留在应用根入口。
10. 系统返回、页面返回按钮与手势返回结果一致。

测试记录要包含设备、HarmonyOS 版本、应用版本、入口、预期、实际和日志 requestId。

二十一、构建与静态检查不能省略

改造涉及公共类型和页面回调签名，最容易出现导入、可空类型和 @Builder 参数错误。至少执行项目约定的构建命令：

$env:DEVECO_SDK_HOME='D:\huawei\DevEco Studio\sdk'
$env:PATH='D:\huawei\DevEco Studio\jbr\bin;' + $env:PATH
& 'D:\huawei\DevEco Studio\tools\hvigor\bin\hvigorw.bat' --no-daemon assembleHap

构建通过只能证明静态与资源链路可用，不能替代真机返回测试。导航属于状态和交互功能，必须再完成安装、启动、主入口、二级入口、返回和卸载的最小烟测。

二十二、故障排查顺序

当导航仍不符合预期时，按以下顺序排查能减少误判：

1. 页签内容正确但选中态错误

检查是否仍有代码绕过 selectTab() 直接调用控制器，确认 onChange 只接收有效索引，并检查 TabBarBuilder 使用的是同一个 currentIndex。

2. 点击快捷入口没有反应

检查 navigationBusy 是否被异常路径永久留在 true，查看 NavigationResult.message，再确认目标值存在于 AppPage 与 main_pages.json。

3. 详情页内容与点击项不一致

检查调用方是否仍传整段标题或正文，确认详情页按 ID 从唯一数据源查询，未知 ID 不允许回落到第一条内容。

4. 返回直接退出应用

确认外部入口是否先建立了根页面上下文；不要直接把详情页当作无来源首屏。检查页面是否有可见返回操作，并让系统返回与页面返回走同一策略。

5. 偶发重复页面

检查重复点击保护、requestId 去重和异步结果回写。日志中若同一 requestId 出现两次成功，需要先修消费幂等，而不是修改动画。

二十三、改造前后的工程差异

维度	改造前	改造后
主标签目标	裸数字 1/2	MainTabId.LAB/LEARNING
索引映射	分散在 UI	MainTabCatalog 唯一维护
页面路径	任意字符串	AppPage 受控目录
切换状态	控制器与事件分离	selectTab() 统一同步
参数处理	类型断言加可选判断	数据源存在性与边界校验
路由失败	空 catch	结果对象、日志和可见错误
重复点击	可能重复压栈	忙碌状态与 requestId 幂等
返回策略	各页面局部决定	主标签与二级页面分层约定
框架迁移	业务直接依赖 router	业务依赖 AppNavigator 边界

二十四、落地顺序建议

这项改造不必一次触碰全部页面，可以按风险从小到大推进：

1. 新增 MainTabId、MainTabCatalog 与目录测试。
2. 修改 HomePage.onSwitchTab，消除裸数字。
3. 新增 AppPage 与 AppNavigator，替换首页快捷入口。
4. 去掉空 catch，补导航忙碌和错误状态。
5. 为实验详情增加业务 ID 守卫。
6. 为阅读详情去掉“错误时显示第一篇”的静默回落。
7. 收窄知识详情参数，只传稳定 ID。
8. 接入外部请求 requestId 去重与根入口策略。
9. 完成构建、真机矩阵和返回回归。
10. 最后评估迁移到 Navigation/NavPathStack 的范围。

每一步都能独立验证，也能在发现回归时快速定位。

二十五、验收清单

• [ ] 主页面不再传递裸页签索引。
• [ ] 所有页签 ID 与索引来自唯一目录。
• [ ] 无效页签不能改变当前状态。
• [ ] 二级页面路径不再由 UI 自由拼写。
• [ ] 路由目录中的页面全部存在于 main_pages.json。
• [ ] 路由失败有日志、错误态和重试入口。
• [ ] 实验 ID 必须存在于实验数据源。
• [ ] 阅读 ID 无效时不再静默展示第一篇。
• [ ] 知识详情优先只传稳定 ID。
• [ ] 连续点击不会重复压入同一页面。
• [ ] 外部入口有根页面和可预期返回路径。
• [ ] 页面返回、系统返回和手势返回结果一致。
• [ ] 底部标签在字体放大、小窗口和横屏下可读。
• [ ] assembleHap 通过，并完成安装启动核心流烟测。

二十六、源码事实与建议实现的边界

为了避免把增量治理方案误写成仓库已有能力，下面把 Index.ets、HomePage.ets 与 main_pages.json 中可以直接复核的事实，与本文建议结构明确分开。

观察维度	当前源码事实	建议实现
主页面结构	Index.ets 使用 Tabs + TabsController 组织首页、实验室、学习、我的 4 个主页面	保留现有组件，用稳定 MainTabId 与目录映射业务身份
当前页签状态	currentIndex 是数字，onChange 负责同步视觉选中态	由单一 selectTab 同时更新控制器与状态，并拒绝越界目标
首页切页	HomePage 通过 (index: number) => void 请求切换主标签	把裸索引回调改为稳定标签 ID，索引只留在适配层
二级页面	首页快捷入口通过字符串调用 router.pushUrl	使用受控 AppPage 目录和 AppNavigator 统一路径、参数与失败反馈
路由错误	openPage 捕获异常后不输出状态，直接路由调用也没有统一结果	返回结构化导航结果，记录受控日志并给用户可见重试入口
实验入口	热门实验传递 expId 与 expName	只把稳定 ID 作为身份，详情页从数据源校验并恢复展示字段
页面注册	main_pages.json 当前注册 26 个页面	增加目录与注册表一致性检查，防止路径存在于代码但未注册
参数消费	实验、阅读和知识详情页分别读取参数，校验策略分散	为每类目标建立运行时守卫，无效参数进入明确错误态
默认回落	部分详情页会用默认内容掩盖缺失或无效参数	外部入口失败时回退到安全根页面，不伪装成成功详情
返回策略	主标签切换与 router 页面栈由各入口自行决定	明确主标签、二级页面、外部直达的根页面与返回优先级

本文提出的 MainTabId、MainTabCatalog、AppPage、AppNavigator、参数守卫、去重入栈和外部入口返回策略，都是建议实现，当前源码尚未集成。本次精修没有执行 DevEco Studio 构建、安装、系统返回、手势返回、外部直达、小窗口或横屏测试，因此不能据此声称导航问题已经修复；实际落地仍需以编译、页面注册检查和真机导航栈行为为准。

二十七、总结

化学实验室当前主导航的问题不是页面数量太多，而是导航语义被拆散成裸数字、自由字符串、类型断言和默认回落。它们各自都很短，却共同制造了“编译通过、点击后才出错”的灰色区域。

增量治理的关键有四点：第一，用 MainTabId 把业务目标与 UI 索引分离；第二，用 MainTabCatalog 和 selectTab() 建立主标签的单一状态边界；第三，用 AppPage + AppNavigator 收拢页面路径与失败处理；第四，在详情页入口校验业务 ID，让未知参数进入错误态，而不是展示一份看似正常的默认内容。

完成这些边界后，现有 TabsController + router 可以继续稳定工作，未来迁移到 Navigation/NavPathStack 时也只需要替换导航适配层，不必再次修改每个业务按钮。导航由此从一组点击事件，变成可以测试、追踪、回放和演进的工程契约。

参考资料

1. Huawei Developer，ArkTS 语言与静态类型设计：https://developer.huawei.com/consumer/cn/arkts/
2. Huawei Developer，ArkUI 概述：https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkui-overview
3. Huawei Developer，组件导航和页面路由文档目录：https://developer.huawei.com/consumer/cn/doc/
4. 项目源码：entry/src/main/ets/pages/Index.ets
5. 项目源码：entry/src/main/ets/pages/HomePage.ets
6. 项目配置：entry/src/main/resources/base/profile/main_pages.json
7. 项目源码：entry/src/main/ets/views/experiment/ExperimentSimPage.ets

AI 辅助声明：本文由 AI 辅助完成源码梳理、结构校对与配图设计，技术结论均以文中列出的本地 ArkTS 源码为依据，并由作者复核后发布。