HMRouter是HarmonyOS上页面跳转的场景解决方案,主要解决页面间相互跳转的问题,开发者可以参考HMRouter使用说明进行安装配置与快速上手,本文主要以实际开发中的各项场景为例,介绍HMRouter路由框架的使用。HMRouter路由框架提供了下列功能特性:
该框架底层对Navigation相关能力进行了封装,帮助开发者减少对Navigation相关细节内容的关注、提高开发效率,同时该框架对页面跳转能力进行了增强,例如其中的路由拦截、单例页面等。下文以页面跳转、弹窗提示、转场动效、数据加载、维测场景为切入点,介绍HMRouter路由框架的使用。
HMRouter提供了基于自定义注解的页面跳转与返回功能,使用步骤如下:
@HMRouter({ pageUrl: 'ProductContent' })
@Component
export struct ProductContent {
// ...
@State param: ParamsType | null = null;
aboutToAppear(): void {
this.param = HMRouterMgr.getCurrentParam() as ParamsType;
}
// ...
} HMRouterMgr.to('ProductContent')
.withNavigation('mainNavigationId')
.withParam({ a: 1, b: 2 })
.onResult((popInfo: HMPopInfo) => {
const pageName = popInfo.srcPageInfo.name;
const params = popInfo.result;
})
.pushAsync(); @Component
export struct ProductContent {
// ...
@State param: ParamsType | null = null;
aboutToAppear(): void {
this.param = HMRouterMgr.getCurrentParam() as ParamsType;
}
// ...
} HMRouterMgr.pop({ navigationId: 'mainNavigationId', param: this.param }); 当页面跳转路径如HomePage->PageA->PageB->PageC,开发者希望在PageC的页面逻辑中直接返回到HomePage并携带参数,开发者仅需使用HMRouterMgr提供的to()方法,并传入需要返回的目标页面的地址以及携带的参数,即可直接带参返回到指定页面。
HMRouterMgr.to('MainPage')
.withNavigation('mainNavigationId')
.withParam(0)
.pushAsync(); 
应用中经常会有当用户未登录应用时,点击某些应用内容会自动跳转到登录页面的场景,在使用HMRouter对此场景进行实现时,可以采用以下步骤:
@HMInterceptor({ interceptorName: 'LoginCheckInterceptor' })
export class LoginCheckInterceptor implements IHMInterceptor {
async intercept(chain: IHMInterceptorChain): Promise<void> {
const info = chain.getRouterInfo();
const context = chain.getContext();
// ...
if (!!AppStorage.get('isLogin')) {
await chain.onContinue();
} else {
info.context.getPromptAction().showToast({ message: LoginConstants.LOGIN_TOAST });
HMRouterMgr.push({
pageUrl: 'loginPage',
skipAllInterceptor: true
});
await chain.onIntercept();
}
// ...
}
} 运行效果如下图所示。

当应用中存在初始化加载资源消耗大且有复用需求的页面时,就可以使用单例页面。典型的业务场景如视频类应用中的视频播放页面,此类页面通常需要加载视频解码器资源并对其初始化,且该页面在视频类应用中会频繁出现。实现上开发者只需要配置@HMRouter注解参数中的singleton参数为true即可。
@HMRouter({
pageUrl: 'liveHome',
singleton: true,
animator: 'liveInteractiveAnimator',
lifecycle: 'liveHomeLifecycle'
})
@Component
export struct LiveHome {
// ...
} 在HMRouter路由框架中,开发者只需要设置@HMRouter注解的dialog配置为true即可将当前页面作为弹窗使用。
@HMRouter({
pageUrl: PageConstant.PRIVACY_DIALOG_DETAIL,
dialog: true,
// ...
})
@Component
export struct PrivacyDialogDetail {
// ...
} @HMRouter({ pageUrl: 'PayCancel', dialog: true, animator:'PayCancelDialog' })
@Component
export struct PayCancel {
// ...
build() {
Stack({ alignContent: Alignment.Center }) {
ConfirmDialog({
title: PayConstants.PAY_CANCEL_TITLE,
content: PayConstants.PAY_CANCEL_CONTENT,
leftButtonName: PayConstants.PAY_CANCEL_BUTTON1,
rightButtonName: PayConstants.PAY_CANCEL_TITLE,
leftButtonFunc: () => {
HMRouterMgr.popAsync({
navigationId: this.queryNavigationInfo()?.navigationId
});
},
rightButtonFunc: () => {
// ...
}
});
}
.width('100%')
.height('100%')
.position({
x: '50%',
y: '50%'
})
.markAnchor({
x: '50%',
y: '50%'
});
}
} @HMLifecycle({ lifecycleName: 'ExitPayLifecycle' })
export class ExitPayLifecycle implements IHMLifecycle {
public model: ObservedModel = new ObservedModel();
onBackPressed(): boolean {
HMRouterMgr.to('PayCancel')
.withParam(this.model.pageUrl)
.pushAsync();
return true;
}
} @HMRouter({
pageUrl: 'PayDialogContent',
dialog: true,
lifecycle: 'ExitPayDialog',
interceptors: ['LoginCheckInterceptor']
})
@Component
export struct PayDialogContent {
// ...
} 运行效果如下图所示。

该场景下用户第一次触发应用返回退出时向用户提示“再次返回退出”,第二次用户触发返回操作时应用真正退出。实现上可参考以下步骤:
@HMLifecycle({ lifecycleName: 'ExitAppLifecycle' })
export class ExitAppLifecycle implements IHMLifecycle {
private lastTime: number = 0;
onBackPressed(ctx: HMLifecycleContext): boolean {
let time = new Date().getTime();
if (time - this.lastTime > 1000) {
this.lastTime = time;
ctx.uiContext.getPromptAction().showToast({
message: $r('app.string.HOME_EXIT_TOAST'),
duration: 1000
});
return true;
} else {
return false;
}
}
} 运行效果如下图所示。

const globalPageTransitionEffect: IHMAnimator.Effect = new IHMAnimator.Effect({
direction: IHMAnimator.Direction.BOTTOM_TO_TOP,
opacity: { opacity: 0.5 },
scale: { x: 0.5, y: 0.2 }
}); 定义完成后,只需要将实例传入HMNavigation组件的dialogAnimator参数即可。
HMNavigation({
navigationId: 'mainNavigationId', homePageUrl: 'HomeContent', options: {
dialogAnimator: globalPageTransitionEffect,
}
}); const globalPageTransitionEffect: IHMAnimator.Effect = new IHMAnimator.Effect({
direction: IHMAnimator.Direction.BOTTOM_TO_TOP,
opacity: { opacity: 0.5 },
scale: { x: 0.5, y: 0.2 }
}); 将创建好的实例作为dialogAnimator的参数进行传入即可。
HMNavigation({
navigationId: 'mainNavigationId', homePageUrl: 'HomeContent', options: {
dialogAnimator: globalPageTransitionEffect,
}
}); 开发者可以自定义动画类并实现IHMAnimator接口中的effect()方法,该方法会将页面进出场的效果对象enterHandle与exitHandle作为参数传入,可通过参数对象上的start、finish方法,设置对应效果的起止状态,支持设置的常用属性还有:
以下代码示例表示入场时由屏幕底部以线性速度向屏幕顶部运动,入场动画持续时长为400ms。出场时从屏幕顶部以线性速度向屏幕底部运动,出场动画持续时长也为400ms。
@HMAnimator({ animatorName: 'CustomAnimator' })
export class CustomAnimator implements IHMAnimator {
effect(enterHandle: HMAnimatorHandle, exitHandle: HMAnimatorHandle): void {
// to animator
enterHandle.start((modifier: AttributeUpdater<NavDestinationAttribute>) => {
modifier.attribute?.translate({ y: ANIMATOR_TRANSLATE_Y_START })
.scale({ x: ANIMATOR_SCALE_X })
.opacity(ANIMATOR_OPACITY_START);
}).finish((modifier: AttributeUpdater<NavDestinationAttribute>) => {
modifier.attribute?.translate({ y: ANIMATOR_TRANSLATE_Y_END })
.scale({ x: 1 })
.opacity(ANIMATOR_OPACITY_END);
});
enterHandle.duration = ANIMATOR_DURATION;
enterHandle.curve = Curve.Linear;
// cut animator
exitHandle.start((modifier: AttributeUpdater<NavDestinationAttribute>) => {
modifier.attribute?.translate({ y: ANIMATOR_TRANSLATE_Y_END })
.scale({ x: 1 })
.opacity(ANIMATOR_OPACITY_END);
}).finish((modifier: AttributeUpdater<NavDestinationAttribute>) => {
modifier.attribute?.translate({ y: ANIMATOR_TRANSLATE_Y_START })
.scale({ x: ANIMATOR_SCALE_X })
.opacity(ANIMATOR_OPACITY_START);
});
exitHandle.duration = ANIMATOR_DURATION;
enterHandle.curve = Curve.Linear;
}
} 自定义动画定义完成后,其实例可以作为新版链式API跳转方法的animator参数进行传入。
HMRouterMgr.to('ProductContent')
.withAnimator(new CustomAnimator())
.pushAsync(); 运行效果如下图所示。

相同的页面可能在不同情况下出现不同的转场效果,常见的有短视频播放时的评论页面弹出时的转场:
此处以评论区组件打开的视角进行动画定义,定义竖屏播放时评论区进出场动画如下:
@HMAnimator({ animatorName: 'myAnimator1' })
export class MyAnimator1 implements IHMAnimator {
effect(enterHandle: HMAnimatorHandle, exitHandle: HMAnimatorHandle): void {
enterHandle.start((modifier: AttributeUpdater<NavDestinationAttribute>) => {
modifier.attribute?.translate({ y: ANIMATOR_TRANSLATE_START });
}).finish((modifier: AttributeUpdater<NavDestinationAttribute>) => {
modifier.attribute?.translate({ y: ANIMATOR_TRANSLATE_END });
});
exitHandle.start((modifier: AttributeUpdater<NavDestinationAttribute>) => {
modifier.attribute?.translate({ y: ANIMATOR_TRANSLATE_END });
}).finish((modifier: AttributeUpdater<NavDestinationAttribute>) => {
modifier.attribute?.translate({ y: ANIMATOR_TRANSLATE_START });
});
}
} 定义短视频横屏播放时评论区进出场动画如下:
@HMAnimator({ animatorName: 'myAnimator2' })
export class MyAnimator2 implements IHMAnimator {
effect(enterHandle: HMAnimatorHandle, exitHandle: HMAnimatorHandle): void {
enterHandle.start((modifier: AttributeUpdater<NavDestinationAttribute>) => {
modifier.attribute?.translate({ x: ANIMATOR_TRANSLATE_START, y: ANIMATOR_TRANSLATE_END });
}).finish((modifier: AttributeUpdater<NavDestinationAttribute>) => {
modifier.attribute?.translate({ x: 0 });
});
enterHandle.duration = ANIMATOR_DURATION;
exitHandle.start((modifier: AttributeUpdater<NavDestinationAttribute>) => {
modifier.attribute?.translate({ x: ANIMATOR_TRANSLATE_END });
}).finish((modifier: AttributeUpdater<NavDestinationAttribute>) => {
modifier.attribute?.translate({ x: ANIMATOR_TRANSLATE_START });
});
exitHandle.duration = ANIMATOR_DURATION;
}
} 最后根据条件选择不同的动效,例如此处根据视频播放方向是否为横向,在页面跳转时使用不同的animator值。
@Component
export struct CommentInput {
// ...
build() {
Row() {
Image($r('app.media.icon_comments'))
.width(IMAGE_WIDTH_AND_HEIGHT)
.height(IMAGE_WIDTH_AND_HEIGHT)
.margin({ right: IMAGE_MARGIN_RIGHT })
.onClick(() => {
if (this.isLandscape) {
HMRouterMgr.to('liveComments')
.withNavigation(this.queryNavigationInfo()?.navigationId)
.withParam({commentRenderNode: ''})
.withAnimator(new MyAnimator2())
.onResult((paramInfo: PopInfo)=>{
this.videoWidth = VIDEO_WIDTH_FULL;
})
.pushAsync();
this.videoWidth = VIDEO_WIDTH_HALF;
} else {
HMRouterMgr.to('liveComments')
.withNavigation(this.queryNavigationInfo()?.navigationId)
.withParam({commentRenderNode: ''})
.withAnimator(new MyAnimator1())
.onResult((paramInfo: PopInfo)=>{
this.videoHeight = VIDEO_HEIGHT_FULL;
})
.pushAsync();
this.videoHeight = VIDEO_HEIGHT_MINI;
}
});
};
}
} 运行效果如下图所示。

当应用中有页面的进出场效果与用户手势操作同步的诉求时,即当用户手指在屏幕上移动时,页面跟随用户手势移动,可以参考以下实现,通过IHMAnimator的interactive函数控制动画播放进度,在actionStart中判断向右移动执行页面返回操作,在updateProgress更新动画进度,在actionEnd中获取到动画的最终状态,根据最终状态判断是继续执行动画与页面返回还是关闭动画取消页面返回。
@HMAnimator({ animatorName: 'liveInteractiveAnimator' })
export class LiveInteractiveAnimator implements IHMAnimator {
effect(enterHandle: HMAnimatorHandle, exitHandle: HMAnimatorHandle): void {
// ...
}
interactive(handle: HMAnimatorHandle): void {
handle.actionStart((event: GestureEvent) => {
if (event.offsetX > 0) {
HMRouterMgr.popAsync();
}
handle.startOffset = event.fingerList[0].localX;
});
handle.updateProgress((event, proxy, operation, startOffset) => {
if (!proxy?.updateTransition || !startOffset) {
return;
}
let offset = 0;
if (event.fingerList[0]) {
offset = Math.abs(event.fingerList[0].localX - startOffset);
}
if (offset < 0) {
proxy?.updateTransition(0);
return;
}
let rectWidth = event.target.area.width as number;
let rate = offset / rectWidth;
proxy?.updateTransition(rate);
});
handle.actionEnd((event, proxy, operation, startOffset) => {
if (!startOffset) {
return;
}
let rectWidth = event.target.area.width as number;
let rate = 0;
if (event.fingerList[0]) {
rate = Math.abs(event.fingerList[0].localX - startOffset) / rectWidth;
}
if (rate > 0.4) {
proxy?.finishTransition();
} else {
proxy?.cancelTransition?.();
}
});
}
} 运行效果如下图所示。

该场景下,开发者希望提前网络请求的位置并在其他线程中执行网络请求而不阻塞主线程,代码实现参考如下步骤。
@Concurrent
async function networkRequest(lifecycle: string): Promise<string> {
// ...
} @HMLifecycle({ lifecycleName: 'requestLifecycle' })
export class ExampleLifecycle implements IHMLifecycle {
private requestModel: RequestModel = new RequestModel();
onPrepare(): void {
let task: taskpool.Task = new taskpool.Task(networkRequest, 'onPrepare');
taskpool.execute(task).then((res: object) => {
});
}
// ...
} 
该场景下当页面关闭时,之前浏览的相关记录依然存在,典型的场景例如短视频评论,当用户打开评论区页进行翻阅后停留在某处,此时关闭评论区再打开,评论内容会仍然停留在上一次浏览的位置。实现上可以参考如下步骤。
@Builder
function buildComment(liveComments: LiveCommentsProduct[]) {
// ...
}
export class CommentNodeController extends NodeController {
public commentList: BuilderNode<[LiveCommentsProduct[]]> | null = null;
public commentListData: LiveCommentsProduct[] = new LiveCommentsModel().getLiveCommentsList();
constructor() {
super();
}
makeNode(context: UIContext): FrameNode | null {
if (this.commentList === null) {
this.nodeBuild(context);
}
return this.commentList!.getFrameNode();
}
nodeBuild(context: UIContext): void {
this.commentList = new BuilderNode(context);
if (this.commentList !== null) {
this.commentList.build(wrapBuilder<[LiveCommentsProduct[]]>(buildComment), this.commentListData);
}
}
dispose(): void {
if (this.commentList !== null) {
this.commentList.dispose();
}
}
} @HMLifecycle({ lifecycleName: 'liveHomeLifecycle' })
export class LiveHomeLifecycle implements IHMLifecycle {
public commentRenderNode: CommentNodeController = new CommentNodeController();
// ...
onAppear(ctx: HMLifecycleContext): void {
this.commentRenderNode.makeNode(ctx.uiContext);
}
onDisAppear(ctx: HMLifecycleContext): void {
this.commentRenderNode.dispose();
}
} @Component
export struct CommentInput {
@StorageLink('changeVideoHeight') videoHeight: string | number = CommonConstants.FULL_PERCENT;
commentRenderNode: CommentNodeController = new CommentNodeController();
// ...
} 
当需要统计类似于页面加载耗时等数据,或者有其他自定义打点数据需要统计时,可以使用生命周期回调,在对应的位置进行打点,以下示例为页面停留时长的数据打点统计,实现上参考以下步骤:
@HMLifecycle({ lifecycleName: 'PageDurationLifecycle', global: true })
export class PageDurationLifecycle implements IHMLifecycle {
private time: number = 0;
onShown(): void {
this.time = new Date().getTime();
}
onHidden(ctx: HMLifecycleContext): void {
const duration = new Date().getTime() - this.time;
console.log(`Page ${ctx.navContext?.pathInfo.name} stay ${duration}`);
}
} 