目录

前言

一、安装与配置

1. 安装

2. 配置插件依赖

3. 配置根目录 hvigorfile.ts

4. 配置模块级 hvigorfile.ts

场景 1：模块为 HAP（应用入口），使用 hapPlugin：

场景 2：模块为 HSP（动态特性包），使用 hspPlugin：

场景 3：模块为 HAR（静态特性包），使用 harPlugin：

如何查看模块类型

二、使用步骤

1. 初始化与路由入口

1.1 初始化

1.2 定义路由入口

1.3 编写代码

总结

前言

在项目中使用官方推荐的Navigation时，需要在所有的页面上都添加一层NavDestination，在代码阅读上会增加多个层级，而且还要在主页面设置对应名字的跳转等问题，配置起来比较繁琐。HMRouter是HarmonyOS上的页面跳转路由框架，主要解决应用内原生页面间相互跳转的问题，底层封装了Navigation能力，让开发者无需关心繁琐的导航逻辑。

一、安装与配置

1. 安装

首先需要在终端中运行以下命令，安装 HMRouter 的核心库：

ohpm install @hadss/hmrouter@1.2.4

2. 配置插件依赖

打开hvigor/hvigor-config.json5文件，在dependencies中添加@hadss/hmrouter-plugin插件，版本建议与 HMRouter 库保持一致：

{ "modelVersion": "6.0.1", "dependencies": { "@hadss/hmrouter-plugin": "^1.2.4" // 建议使用与库一致的版本 } }

注意：上面安装的ohpm install @hadss/hmrouter@1.2.4是在运行时使用，"@hadss/hmrouter-plugin": "^1.2.4"是在编译时使用。

3. 配置根目录 hvigorfile.ts

【只有当入口模块时，可以不配置】

修改项目根目录的hvigorfile.ts文件，需要正确导入并使用appPlugin，并传入配置参数：

import { appTasks } from '@ohos/hvigor-ohos-plugin'; // 注意：这里是从 '@hadss/hmrouter-plugin' 导入 appPlugin import { appPlugin } from '@hadss/hmrouter-plugin'; export default { system: appTasks, // 必须传入参数对象，否则会报错 plugins: [appPlugin({ ignoreModuleNames: [] })] };

特别注意：appPlugin在调用时必须传入参数对象（如{}或{ ignoreModuleNames: [] }），否则构建时会报错。

4. 配置模块级 hvigorfile.ts

修改你的模块（如 entry）目录下的hvigorfile.ts文件。根据你的模块类型选择对应的插件：

场景 1：模块为 HAP（应用入口），使用 hapPlugin：

import { hapTasks } from '@ohos/hvigor-ohos-plugin'; import { hapPlugin } from '@hadss/hmrouter-plugin'; export default { system: hapTasks, plugins: [hapPlugin()] };

场景 2：模块为 HSP（动态特性包），使用 hspPlugin：

import { hspTasks } from '@ohos/hvigor-ohos-plugin'; import { hspPlugin } from '@hadss/hmrouter-plugin'; export default { system: hspTasks, plugins: [hspPlugin()] };

场景 3：模块为 HAR（静态特性包），使用 harPlugin：

import { harTasks } from '@ohos/hvigor-ohos-plugin'; import { harPlugin } from '@hadss/hmrouter-plugin'; export default { system: harTasks, plugins: [harPlugin()] };

如何查看模块类型

打开模块的build-profile.json5文件，查看"type"字段：

{ "apiType": "stageMode", "buildOption": { }, "targets": [ { "name": "default" } ] }

注意：如果build-profile.json5中没有显式指定"type"，默认是"hap"类型。

二、使用步骤

1. 初始化与路由入口

1.1 初始化

在 EntryAbility 里的onCreate进行初始化：

HMRouterMgr.init({context: this.context}) // 初始化 HMRouter

1.2 定义路由入口

自定义一个NavModifier类，继承AttributeUpdater<NavigationAttribute>：

// 自定义 Navigation 属性，用于隐藏标题栏等 export class NavModifier extends AttributeUpdater<NavigationAttribute> { initializeModifier(instance: NavigationAttribute): void { // Stack：堆栈页面（多页面层级跳转）, Split：分栏导航（平板大屏左右分栏） instance.mode(NavigationMode.Stack); // 导航栏宽度铺满屏幕 instance.navBarWidth('100%'); // 隐藏顶部标题栏 instance.hideTitleBar(true); // 隐藏底部工具栏 instance.hideToolBar(true); } }

navigationId是 HMRouter 的导航容器标识符，区分不同的导航容器，告诉HMRouterMgr.push()往哪个容器里跳转，不同navigationId是不同的页面栈，互不影响。

1.3 编写代码

Column() { // 使用 HMNavigation 容器 HMNavigation({ navigationId: 'mainNavigation', // homePageUrl: 'MainPage', // 首页路由地址（可选，不传则显示 children 内容） options: { standardAnimator: HMDefaultGlobalAnimator.STANDARD_ANIMATOR, // 页面转场动画 dialogAnimator: HMDefaultGlobalAnimator.DIALOG_ANIMATOR, // 弹窗转场动画 modifier: this.modifier // 容器样式修饰 } }) { Column({space: 20}) { Button("TwoPage") .width("80%") .onClick(() => { HMRouterMgr.push({ navigationId: "mainNavigation", pageUrl: "TwoPage" }) }) } } }

HMNavigation({})后面包含的Column是一个children，是默认显示的内容。不传homePageUrl时它充当首页，如果pageUrl没有指定跳转的页面，就会跳转到这个子页面。

总结

HMRouter 通过封装 HarmonyOS 原生的 Navigation 能力，简化了页面路由的配置和使用流程。开发者无需在每个页面手动添加 NavDestination，也无需在主页面维护复杂的跳转逻辑，只需简单的初始化、配置和调用即可实现页面间的灵活跳转，有效提升了开发效率和代码可读性。