HarmonyOS 6.0页面跳转天花板！带你吃透HMRouter，告别官方导航的繁琐

用户76493280768
306 阅读6分钟

大家好，我是Feri，深耕鸿蒙、嵌入式、Java及人工智能领域的资深程序员，带过团队创过业，踩遍了鸿蒙开发的大小坑！最近做HarmonyOS 6.0 App开发时，发现官方提供的2种页面跳转方式——组件导航（Navigation）和页面路由（@ohos.router），要么配置繁琐、上手成本高，要么功能单一、动效/生命周期支持弱，尤其是组件导航，普通项目用起来简直是“杀鸡用牛刀”。

直到我挖到了HMRouter这个宝藏路由框架，直接把页面跳转效率拉满！今天就出一期保姆级教程，10分钟搞定HMRouter，君志所向，一往无前！

一、先吐槽：官方页面跳转的“槽点”

官方虽为HarmonyOS 6.0提供了两种页面跳转方案，但实际用起来都有明显短板：

  • 页面路由（@ohos.router）：仅能满足基础跳转需求，动效定制、路由生命周期、拦截等能力几乎为零；
  • 组件导航（Navigation）：虽具备多端部署、灵活的页面栈操作能力，但配置复杂、学习成本高，普通小项目用着太折腾。

而HMRouter作为鸿蒙专属的页面跳转解决方案，完美补齐这些短板，堪称“官方方案的平替+升级”！

二、HMRouter是什么？—— 鸿蒙页面跳转的“万能方案”

HMRouter是HarmonyOS上针对应用内原生页面跳转的场景化解决方案，核心解决官方方案的痛点，让页面跳转更简单、更灵活！

1. 核心特性（亮点拉满）

✅ 自定义注解实现跳转，代码量直接减少50%； ✅ 完美兼容HAR/HSP，适配多模块开发场景； ✅ 支持路由拦截、路由生命周期，满足复杂业务逻辑； ✅ 动画配置极简：全局统一动画/单页面专属动画一键配置； ✅ 适配多页面类型：单例页面、Dialog页面全覆盖。

2. 核心功能（覆盖90%跳转场景）

① 页面跳转：支持基础跳转/返回、多页面连续跳转、指定页面返回、登录拦截跳转、单例页面跳转； ② 弹窗交互：快速实现Dialog类型页面、返回时确认弹窗等； ③ 转场动效：全局自定义动效、特定页面专属动效、条件化动效、交互式转场； ④ 数据处理：数据请求预加载（跳转+请求并行）、页面重开数据自动恢复； ⑤ 维测埋点：便捷实现页面埋点，满足数据分析需求。

三、保姆级教程：HMRouter使用全步骤

跟着我一步步操作，新手也能快速上手，关键踩坑点都给你标出来了！

步骤1：下载依赖（终端一键搞定）

打开项目终端，执行以下命令安装HMRouter：

ohpm install @hadss/hmrouter

⚠️ 关键提醒：务必记住安装时终端显示的版本号，后续配置插件要保持一致！

步骤2：配置路由编译插件（修改hvigor-config.json）

找到项目根目录下的​​hvigor/hvigor-config.json​​​文件，在​​dependencies​​中添加路由插件依赖，版本号与上一步保持一致：

"dependencies": {
    "@hadss/hmrouter-plugin": "^1.0.0-rc.10"
}

步骤3：引入路由编译插件（修改hvigorfile.ts）

⚠️ 核心踩坑点：根据项目类型选择插件！

  • HAP项目 → 用​​hapPlugin​​；
  • HAR项目 → 用​​harPlugin​​。

修改​​hvigorfile.ts​​代码如下：

import { hapTasks } from '@ohos/hvigor-ohos-plugin';
import { hapPlugin } from '@hadss/hmrouter-plugin'; // HAP用这个，HAR替换为harPlugin
export default {
    system: hapTasks, 
    plugins:[hapPlugin()]   // 配置插件
}

步骤4：实战配置&页面跳转（核心步骤）

以“Index→Test1→Test2”的跳转场景为例，手把手教你配置：

子步骤4.1：初始化HMRouter（EntryAbility中）

在​​EntryAbility​​​的​​onCreate​​方法中完成全局初始化，这是HMRouter生效的关键：

import { HMRouterMgr } from '@hadss/hmrouter'; // 导入核心类

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    this.context.getApplicationContext().setColorMode(ConfigurationConstant.ColorMode.COLOR_MODE_NOT_SET);
    // HMRouter初始化
    HMRouterMgr.init({
      context: this.context
    })
    hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onCreate');
  }
  // 其他生命周期方法保持不变...
}
子步骤4.2：首页（Index）配置导航容器

首页需配置HMNavigation容器，共4步，代码+注释清晰标注：

// 1. 导入核心依赖
import { HMDefaultGlobalAnimator, HMNavigation, HMRouterMgr } from '@hadss/hmrouter';
import { AttributeUpdater } from '@kit.ArkUI';
import { hilog } from '@kit.PerformanceAnalysisKit';

@Entry
@Component
struct Index {
  @State message: string = '程序员Feri，首页';
  // 2. 自定义导航属性
  modifier: NavModifier = new NavModifier();

  build() {
    Column(){
      // 3. 配置HMNavigation容器（核心）
      HMNavigation({
        navigationId: 'main', // 导航ID，全局唯一
        options: {
          standardAnimator: HMDefaultGlobalAnimator.STANDARD_ANIMATOR, // 全局标准动画
          dialogAnimator: HMDefaultGlobalAnimator.DIALOG_ANIMATOR, // 弹窗动画
          modifier: this.modifier
        }
      }){
        Column() {
          Text(this.message)
            .fontSize(30)
            .fontWeight(FontWeight.Bold)
            .margin(20);
          // 4. 实现页面跳转按钮
          Button("跳转测试页面")
            .onClick(()=>{
              hilog.info(1000,"rmr","点击跳转了");
              HMRouterMgr.push({
                navigationId:"main", // 与容器的navigationId一致
                pageUrl:"test1" // 目标页面的自定义路径
              });
            });
        }
      }
    }
  }
}

// 自定义导航属性类
class NavModifier extends AttributeUpdater {
  initializeModifier(instance: NavigationAttribute): void {
    instance.mode(NavigationMode.Stack); // 栈式导航模式
    instance.navBarWidth('100%');
    instance.hideTitleBar(true); // 隐藏标题栏
    instance.hideToolBar(true); // 隐藏工具栏
  }
}
子步骤4.3：目标页面声明路由路径

在Test1、Test2页面中，先导入依赖，再用​​@HMRouter​​注解声明页面路径（pageUrl需与跳转时的参数一致）：

👉 Test1页面完整代码：

import { HMRouter, HMRouterMgr } from '@hadss/hmrouter'; // 导入

@HMRouter({ pageUrl: 'test1' }) // 声明页面路径，与跳转时的pageUrl一致
@Entry
@Component
export struct Test1{
  build() {
    Column(){
      Text("程序员Feri,第一个页面").margin(10);

      // 返回上一页
      Button("回到上一页")
        .onClick(()=>{
          HMRouterMgr.pop({navigationId:"main"});
        }).margin(10);
      
      // 跳转到Test2页面
      Button("跳转第二个页面")
        .onClick(()=>{
          HMRouterMgr.push({
            pageUrl: "test2" // Test2的自定义路径
          });
        }).margin(20);
    }
  }
}

👉 Test2页面完整代码：

import { HMRouter, HMRouterMgr } from '@hadss/hmrouter'; // 导入

@HMRouter({ pageUrl: 'test2' }) // 声明页面路径
@Entry
@Component
export struct Test2{
  build() {
    Column(){
      Text("程序员Feri,第二个页面").margin(10);
      
      Button("跳转到第一个页面")
        .onClick(()=>{
          // 跳转到Test1
          HMRouterMgr.push({
            pageUrl: "test1"
          });
          // 若需返回上一页，取消注释即可
          // HMRouterMgr.pop({navigationId:"main"});
        }).margin(20);
    }
  }
}

四、HMRouter核心跳转方式（3种，按需选择）

HMRouter提供3种核心跳转方式，覆盖所有业务场景，区别一目了然：

跳转方式

核心逻辑

适用场景

push

目标页面插入页面栈，不销毁当前页

普通跳转（如列表→详情），需返回原页面

replace

目标页面替换当前页，销毁当前页并释放资源

无需返回的跳转（如登录→首页）

pop

返回页面栈指定层级（默认返回上一级）

页面返回，skipedLayerNumber=0返回上一级，=1跳过一级返回

五、最后说两句

HMRouter作为鸿蒙专属的路由框架，完美解决了官方跳转方式的繁琐问题，不管是简单的页面跳转，还是复杂的动效定制、路由拦截、埋点需求，都能轻松搞定。

如果大家想考取鸿蒙开发者认证的，欢迎加入我的专属考试链接中：​​​​https://developer.huawei.com/consumer/cn/training/classDetail/6ce9d5a998724a849ec634f318107d37?type=1?ha_source=hmosclass&ha_sourceId=89000248​​​

后续还会分享更多鸿蒙开发的实战干货，帮你少踩坑、多提效，君志所向，一往无前！

avatar
文章
阅读
粉丝