当前位置：首页 > news >正文

鸿蒙技术分享：Navigation页面管理-鸿蒙@fw/router框架源码解析（二）

news 来源：原创 2025/5/7 23:02:12

本文是系列文章，其他文章见：
鸿蒙@fw/router框架源码解析（一）-Router页面管理
鸿蒙@fw/router框架源码解析（三）-Navigation页面容器封装
鸿蒙@fw/router框架源码解析（四）-路由Hvigor插件实现原理
鸿蒙@fw/router框架源码解析（五）-无代码依赖如何实现拦截器逻辑
鸿蒙@fw/router框架源码解析（六）-模块化开发如何实现代码解耦

鸿蒙@fw/router框架源码解析

介绍

@fw/router是在HarmonyOS鸿蒙系统中开发应用所使用的开源模块化路由框架。
该路由框架基于模块化开发思想设计，支持页面路由和服务路由，支持自定义装饰器自动注册，与系统路由相比使用更便捷，功能更丰富。

具体功能介绍见@fw/router：鸿蒙模块化路由框架，助力开发者实现高效模块化开发！

基于模块化的开发需求，本框架支持以下功能：

支持页面路由和服务路由；
页面路由支持多种模式（router模式，Navigation模式，混合模式）；
router模式支持打开非命名路由页面；
页面打开支持多种方式（push/replace），参数传递；关闭页面，返回指定页面，获取返回值，跨页面获取返回值；
支持服务路由，可使用路由url调用公共方法，达到跨技术栈调用以及代码解耦的目的；
支持页面路由/服务路由通过装饰器自动注册；
支持动态导入（在打开路由时才import对应har包），支持自定义动态导入逻辑；
支持添加拦截器（打开路由，关闭路由，获取返回值）；
Navigation模式下支持自定义Dialog对话框；

详见gitee传送门

代码解析

Navigation页面

页面注册@NavigationRoute

@NavigationRoute({ routeName: "testPage", hasParams: true })
@Component
export struct TestDestination {@Prop params?: Record<string, ESObject>build() {Column() {NavDestination() {TestPageContent({ pageName: 'TestDestination', params: this.params })}}}
}

Navigation页面注册使用了自定义的类装饰器@NavigationRoute。我们来看一下其实现：

export function NavigationRoute(options: RouteRegisterOptions) {return (target: ESObject) => {}
}

我们发现，该装饰器的实现代码是个空方法，空方法的话如何实现页面注册呢？

这是因为在ArkTS中，struct无法使用自定义的装饰器，虽然IDE编译不会报错，但是这个装饰器代码根本不会执行。

那么，Navigation页面到底是怎么完成注册的？

答案是：FWRouterHvigorPlugin。

在这个hvigor插件中，插件代码扫描模块中的.eta文件，解析ts语法，当发现装饰器@NavigationRoute时，就会将它所装饰的类名提取出来，然后生成对应的builder和自动注册代码。具体如下：

@Builder
function testDestinationBuilder(params: ESObject) {TestDestination({ params: params });
}@RouterClassProvider({ routeName: 'testPage', builder: wrapBuilder(testDestinationBuilder) })
export class TestDestinationProvider {
}

我们看到插件生成了两部分代码，testDestinationBuilder是对Navigation页面TestDestination的包装，这是ArkTS的要求。
具体原因可以查看鸿蒙应用开发从入门到入魔：Navigation路由管理为什么这么麻烦？

这里有一个细节，就是TestDestination({ params: params })的参数params。因为不是所有的页面都是有入参的，那理论上params是有时候需要传值，有时候不需要传值。
虽然我们可以简化逻辑，强制所有页面都传递params，但这样就导致了即便是不需要参数的页面也需要增加定义@Prop params?: Record<string, ESObject>。
这种处理方法无疑有点粗暴，所以我们选择给NavigationRoute的入参增加hasParams参数，当参数值为true时，传值params参数，当值为false时，不传值，比如TestDestination()。

插件生成的代码中还有一个TestDestinationProvider，它的作用是什么？
其实，testDestinationBuilder只是必须的代码模板，不是我们自己想要的。@RouterClassProvider({ routeName: 'testPage', builder: wrapBuilder(testDestinationBuilder) })这是核心逻辑。

我们来看@RouterClassProvider的实现代码：

export function RouterClassProvider(options: RouterClassProviderOptions) {return (target: ESObject) => {RouterManagerForNavigation.getInstance().registerBuilder(options.routeName, options.builder)}
}

我们看到这个装饰器真正调用了RouterManagerForNavigation中的注册方法，将路由名和页面builder的匹配关系注册到了管理器中。

那么，为什么要这样实现呢？

我们想要的其实就只有一个@RouterClassProvider装饰器，但装饰器不能单独使用，必须装饰在一个类上，所以我们定义了TestDestinationProvider类。
而TestDestination不能直接拿来注册，必须包装进@builder，所以我们定义了testDestinationBuilder。

除此之外，@RouterClassProvider装饰器的触发时机是其所在的文件被import的时候。

因此，在har包中，我们需要将生成的代码文件自动添加到模块的index.ets中去。

export * from './src/main/ets/generated/RouterBuilder';

在entry中，我们需要在EntryAbility.ets中导入。

import('../generated/RouterBuilder');

以上是hvigor插件为了完成Navigation页面所做的事情，至于方案为什么是这样，建议详细查看具体原因可以查看鸿蒙应用开发从入门到入魔：Navigation路由管理为什么这么麻烦？。

打开页面

对于@fw/router而言，打开router页面和Navigation页面都是一样，因此使用完全相同的api，所以前面的openWithRequest、_realOpen、open等方法逻辑完全一致，此处不再赘述。

RouterManagerForNavigation.open

  open(request: RouterRequestWrapper): Promise<RouterResponse> {return new Promise((resolve, reject) => {if (!this.currentNavPathStack) {resolve(RouterResponseError.RequestNotFoundResponsor)return}if (!this.canOpen(request.routeName)) {resolve(RouterResponseError.RequestNotFoundResponsor)return}switch (request.rawRequest.openMode) {case PageRouteOpenMode.replace:this.currentNavPathStack!.replacePath({name: request.routeName, param: request.params})request.resolve = resolve;this.inject(request)break;default:this.currentNavPathStack!.pushDestination({name: request.routeName, param: request.params}).then(() => {request.resolve = resolve;this.inject(request)}).catch((e: ESObject) => {console.log(`${e}`)if (e.code == 100005) {resolve(RouterResponseError.RequestNotFoundResponsor)} else {resolve(RouterResponseError.UnknownError)}})break;}})}

RouterManagerForNavigation.open方法，主要是处理了replace和push两种不同的打开模式。

页面返回值

系统的返回监听

我们可以看到，在push页面时，我们调用了pushDestination方法，而它的入参其实是支持获取页面返回值的。

declare class NavPathInfo {constructor(name: string, param: unknown, onPop?: import('../api/@ohos.base').Callback<PopInfo>);name: string;param?: unknown;/*** The callback when next page returns.** @type { ?import('../api/@ohos.base').Callback<PopInfo> }* @syscap SystemCapability.ArkUI.ArkUI.Full* @crossplatform* @atomicservice* @since 12*/onPop?: import('../api/@ohos.base').Callback<PopInfo>;
}

onPop会在页面关闭时被处罚，而且支持返回值。
但是，我们并没有使用该参数，因为它在跨页面返回值存在逻辑问题。

当页面A打开页面B，页面B打开页面C，然后页面C直接返回页面A并传递返回值时，我们期望的效果是页面A拿到页面C的返回值。

比如，课程详情页打开支付中间页，然后打开付款页面；付款成功或失败后返回课程详情页；课程详情页需要通过付款是否成功来判断页面是否刷新页面。

但是，onPop目前的逻辑是页面C直接返回页面A并带返回值时，页面B的onPop会被触发，页面A的onPop并不会被触发。

所以，虽然onPop用起来非常方便，但为了功能的完整性，我们还是放弃了使用该参数。

返回值实现逻辑

最终的实现逻辑和router类似，即通过监听页面生命周期来手动触发回调。

  close(options?: RouterBackOptionsWrapper | undefined): boolean {// ...this.resultStrategy = RouterResultStrategy.onPagePop// `NavPathStack.pop/popToName`方法`result`参数为undefined时无法触发其push方法的onPop回调；if (options && options.routeName && options.routeName.length > 0) {let routeInfo = this.getRequest(options.routeName)if (routeInfo?.destinationInfo) {this.resultStrategy = RouterResultStrategy.onPageShowthis.backToRouteName = options.routeNamethis.backToIndex = routeInfo?.destinationInfo.index}let result = this.currentNavPathStack!.popToName(options.routeName, backParams, true)if (result == -1) {// 失败后清空，防止影响其他场景的返回值取值（比如侧滑返回，点系统返回按钮等）this.backParams = undefined}return result != -1} else {let result = this.currentNavPathStack!.pop(backParams, true)if (result == undefined) {// 失败后清空，防止影响其他场景的返回值取值（比如侧滑返回，点系统返回按钮等）this.backParams = undefined}return result != undefined}}

首先看一下close方法，因为返回上一页和返回指定页面在返回值处理逻辑上存在很大差异，所以我们单独定义了resultStrategy返回值策略属性。
这是为了加强代码的可读性，否则无论是使用者还是开发者都容易在各种条件判断中迷失。

/*** 页面路由返回值处理策略*/
export enum RouterResultStrategy {/*** 在被打开的页面pop出栈时，触发打开该页面对应的回调方法。*/onPagePop,/*** 返回指定页面routeName时，当routeName onShow时，触发最后获取到的回调方法（即routeName打开页面时传入的回调方法）。*/onPageShow,
}

然后我们看一下最核心的生命周期监听逻辑：

observerPageLifecycle(uiAbility: UIAbility) {observer.on("navDestinationUpdate", (navDestinationInfo: observer.NavDestinationInfo) => {const name = navDestinationInfo.name.toString()const id = navDestinationInfo.navDestinationId// 通过监听页面生命周期方法，将系统堆栈和routes保持一致，用来处理返回值回调switch (navDestinationInfo.state) {case observer.NavDestinationState.ON_APPEAR:if (!this.hasRequest(name, id)) {let request = this.hasUndefinedRequest(name)if (request) {request.destinationInfo = navDestinationInfo} else {this.inject(new RouterRequestWrapper({ url: "other/" + name }), navDestinationInfo)}}breakcase observer.NavDestinationState.ON_SHOWN: {if (this.resultStrategy == RouterResultStrategy.onPageShow && this.backToRouteName === name) {this.lastResolve?.({code: RouterResponseError.Success.code,msg: RouterResponseError.Success.msg,data: this.backParams})// 使用后清空，防止影响其他场景的返回值取值（比如侧滑返回，点系统返回按钮等）this.backParams = undefined}break}case observer.NavDestinationState.ON_WILL_DISAPPEAR: {if (this.resultStrategy == RouterResultStrategy.onPagePop) {this.getRequest(name, id)?.request?.resolve?.({code: RouterResponseError.Success.code,msg: RouterResponseError.Success.msg,data: this.backParams})// 使用后清空，防止影响其他场景的返回值取值（比如侧滑返回，点系统返回按钮等）this.backParams = undefined} else {if (this.backToIndex != undefined && navDestinationInfo.index == this.backToIndex + 1) {this.lastResolve = this.getRequest(name, id)?.request?.resolve}}this.removeRequest(name, id)break}case observer.NavDestinationState.ON_BACKPRESS: {// api12.beta2 该状态不会被触发this.getRequest(name, id)?.request?.resolve?.({code: RouterResponseError.Success.code,msg: RouterResponseError.Success.msg})this.removeRequest(name, id)break}}})}

监听ON_APPEAR状态，将页面与open方法的request参数（inject方法）绑定；
监听ON_SHOWN状态，处理RouterResultStrategy.onPageShow策略，当指定页面触发该状态，则找到该页面发起的请求（这其实是在ON_WILL_DISAPPEAR状态中完成），并触发其revolve回调，回传参数；
监听ON_WILL_DISAPPEAR状态，处理RouterResultStrategy.onPagePop策略，在本页面消失时，获取到打开本页面的请求，并触发其resolve回调，回传参数；
监听ON_BACK_PRESS状态，api12.beta2该状态不会被触发，其实是无效逻辑；因此，当页面侧滑返回或者点击导航栏返回按钮时，实际走的还是ON_WILL_DISAPPEAR状态的逻辑。

总结

我们可以看到，Navigation的页面封装其实router更为复杂，主要是其相比router页面，系统并没有给与原生的自动注册逻辑，从而导致了巨大的复杂性。
除此之外，动态导入也增加了很多复杂度。
如果官方可以自己解决掉自动注册和动态导入两个问题，我相信对于绝大多数人而言，路由框架就没有封装的必要了。