uni-app x 应用路由事件监听与路由重写onBeforeAppRoute、onAppRoute、rewriteRoute 实战指南【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app应用路由事件是 uni-app x 从应用级别监听主页面路由开始与完成、并在路由真正执行前重写目标页面的能力适用于路由上报、全局状态重置、访问控制、无效入口页纠正与页面迁移等一次路由级逻辑。本文将基于官方文档完整讲解uni.onBeforeAppRoute、uni.onAppRoute、uni.offBeforeAppRoute、uni.offAppRoute、uni.rewriteRoute五个 API 的时序、触发场景、事件参数、平台差异与重写规则并给出可直接运行的 UTS/Vue 示例帮助你掌握在 Web、AppAndroid/iOS/HarmonyOS与微信、支付宝等小程序端统一进行路由拦截和重定向的实战方案。应用路由事件概述应用路由事件用于从应用级别监听主页面路由的开始和完成也可以在路由真正执行前重写目标页面。它适合处理以下与一次路由相关的逻辑路由上报统计每次路由的目标页面、路由类型与参数全局状态重置路由切换时清理或初始化全局数据访问控制在路由执行前判断登录态、权限未通过时重写路由无效入口页纠正应用被直接启动到不存在的页面时重定向到有效页面页面迁移旧页面地址迁移到新页面地址。如果逻辑只与单个页面的创建、显示或销毁有关应优先使用对应的页面生命周期。例如onLoad只在新页面创建时触发一次、onShow在页面每次显示时触发二者与页面实例的创建销毁强绑定而应用路由事件是应用级的、面向一次路由的横切逻辑二者定位不同应根据业务归属选择。应用路由事件只作用于主页面路由。dialogPage 的打开、关闭以及随所属页面销毁均不会触发本页 API。这与 dialogPage 的设计一致dialogPage 不使用uni.navigateTo等路由 API而是单独提供openDialogPage和closeDialogPage不影响页面栈和路由地址因此也不参与应用路由事件的派发。API 列表API说明uni.onBeforeAppRoute监听路由执行前的事件uni.offBeforeAppRoute取消监听路由执行前的事件uni.onAppRoute监听路由成功后的事件uni.offAppRoute取消监听路由成功后的事件uni.rewriteRoute在路由执行前重写本次路由事件时序一次成功路由的主要执行顺序如下发起路由 - 解析路径并校验目标 - onBeforeAppRoute - 执行路由逻辑 - 目标页面 onShow - onAppRoute - 路由转场动画完成新页面创建时相关事件和页面生命周期的顺序为onBeforeAppRoute - onLoad - onShow - onAppRoute返回已有页面或切换到已存在的 tabBar 页面时不会再次触发onLoad顺序为onBeforeAppRoute - onShow - onAppRoute这里与页面生命周期中的说明相互印证onLoad只在页面创建时触发一次而页面从隐藏恢复显示时只触发onShow。关键时点语义onBeforeAppRoute在页面栈变化以及页面创建、销毁等实际副作用发生前触发onAppRoute在路由成功且目标页面的onShow执行后触发不等待路由转场动画完成。触发场景下表列出了各场景下两个事件与可重写的情况场景onBeforeAppRouteonAppRoute可重写应用启动并进入有效首页或二级页面触发路由成功后触发是应用直接启动到不存在的页面触发notFound为true支付宝小程序固定为false未重写时按缺页流程触发支付宝小程序不触发支持rewriteRoute的平台可重写navigateTo、redirectTo、reLaunch成功触发路由成功后触发是切换到其他 tabBar 页面触发路由成功后触发是且目标必须是 tabBar 页面switchTab到当前 tabBar 页面不触发不触发否navigateBack、系统返回、返回手势或 Web History 后退触发路由成功后触发否路由 API 参数错误或目标页面校验失败不触发支付宝小程序仍会触发且notFound为false不触发否onBeforeAppRoute已触发但路由随后取消或执行失败已触发不触发仅可在同步回调阶段重写应用从后台恢复但主页面路由未变化不触发不触发否dialogPage 打开、关闭或随所属页面销毁不触发不触发否两点需要特别留意监听器注册前已经发生的事件不会补发。如需监听或重写appLaunch应在onLaunch生命周期中或之前尽早注册监听器。正常调用路由 API 时参数错误或目标页面不存在会直接失败除支付宝小程序外此类失败不会产生应用路由事件。notFound主要用于应用直接启动到不存在页面等已经进入路由流程的场景。事件参数与路由类型onBeforeAppRoute和onAppRoute的公共事件参数含义如下属性说明path目标页面路径不包含开头的/query当前轮路由解析得到的页面参数openType路由类型。发生重写时保持原路由类型不变notFound当前目标页面是否不存在routeEventId应用实例内唯一的路由事件标识onAppRoute还会提供timeStamp表示当前轮路由事件生成时的时间戳。不同平台可能提供额外的事件字段。编写跨平台代码时应只依赖上述公共字段。routeEventId的关联规则未发生重写时同一次路由的onBeforeAppRoute与onAppRoute使用相同的routeEventId每次成功重写都会生成新的路由事件和新的routeEventId最终的onAppRoute使用最后一轮onBeforeAppRoute的routeEventId。路由类型openTypeopenType路由来源appLaunch应用首次启动Web 直接访问首页或二级页面等入口路由navigateTouni.navigateToWeb History 前进无法识别为其他类型的新增页面路由navigateBackuni.navigateBack系统返回、返回手势Web History 后退小程序系统返回redirectTouni.redirectToreLaunchuni.reLaunchswitchTabuni.switchTab用户切换到其他 tabBar 页面平台差异与版本要求::: warning 平台差异微信小程序的路由事件监听要求基础库3.5.5及以上版本rewriteRoute要求基础库3.8.0及以上版本并受微信客户端版本、运行平台和分包限制。微信开发者工具模拟器不支持rewriteRoute应在支持该能力的真机环境中验证。支付宝小程序通过my.createRouteObserver实现路由事件监听。支付宝小程序开发者工具目前未提供my.createRouteObserver无法在开发者工具中验证路由事件监听相关 API应在支持该能力的支付宝客户端真机环境中验证。支付宝的前置事件不提供目标页面是否存在的信息因此onBeforeAppRoute的notFound固定为false。当路由 API 的目标页面不存在时支付宝仍会触发onBeforeAppRoute但不会触发onAppRoute应用直接启动到不存在的页面时同样不会触发onAppRoute。支付宝小程序暂不支持rewriteRoute。:::从版本记录看本仓库的 release-note-alpha.md 明确记载了新增 API uni.onAppRoute、uni.onBeforeAppRoute、uni.rewriteRoute 支持页面路由监听及重写这一能力对应 issue 31599说明该系列 API 属于 uni-app x 的较新能力使用时建议保持 HBuilderX 与基础库处于较新版本并以各平台真机能力为准。事件相关 API 在 Web、微信小程序、Android、iOS、HarmonyOS 五个平台的一致性支持版本均为 5.25见下文各 API 的兼容性表。uni.onAppRoute(callback)监听应用路由成功后的事件。兼容性Web 5.25 / 微信小程序 5.25 / Android 5.25 / iOS 5.25 / HarmonyOS 5.25。参数| 名称 | 类型 | 必填 | 描述 | | :- | :- | :- | :- | | callback | (event: AppRouteEvent) void | 是 | 应用路由事件回调 |AppRouteEvent 的属性值| 名称 | 类型 | 必备 | 兼容性 | 描述 | | :- | :- | :- | :-: | :- | | path | string | 是 | Web: 5.25; 微信小程序: 5.25; Android: 5.25; iOS: 5.25; HarmonyOS: 5.25 | 路由页面路径不包含开头的斜杠 | | query | UTSJSONObject | 是 | Web: 5.25; 微信小程序: 5.25; Android: 5.25; iOS: 5.25; HarmonyOS: 5.25 | 路由页面参数 | | openType | string | 是 | Web: 5.25; 微信小程序: 5.25; Android: 5.25; iOS: 5.25; HarmonyOS: 5.25 | 应用路由类型 | | notFound | boolean | 是 | Web: 5.25; 微信小程序: 5.25; Android: 5.25; iOS: 5.25; HarmonyOS: 5.25 | 路由页面是否不存在。支付宝小程序不提供该信息固定为 false | | timeStamp | number | 是 | Web: 5.25; 微信小程序: 5.25; Android: 5.25; iOS: 5.25; HarmonyOS: 5.25 | 事件触发时的时间戳 | | routeEventId | string | 是 | Web: 5.25; 微信小程序: 5.25; Android: 5.25; iOS: 5.25; HarmonyOS: 5.25 | 路由事件唯一标识 | | page | IAnyObject | 否 | 微信小程序: 4.41 | 当前打开页面的相关配置 | | pipMode | string | 否 | 微信小程序: 4.41 | 可选值min视频页面缩小为小窗、max视频小窗还原为页面 | | renderer | string | 否 | 微信小程序: 4.41 | 渲染引擎。可选值webview、skyline、xr-frame| | webviewId | number | 否 | 微信小程序: 4.41 | 当前页面 id |其中page、pipMode、renderer、webviewId为微信小程序特有的扩展字段其他平台不会提供跨平台代码中不要依赖。使用说明onAppRoute只描述最终实际生效的路由。一次路由发生重写时被替换的中间目标不会触发onAppRoute只有最终成功进入的页面触发一次。监听器抛出的异常不会中断底层路由流程但应在监听器内部妥善处理业务异常。const appRouteCallback (event : AppRouteEvent) { console.log(路由完成${event.openType} ${event.path}) console.log(路由参数${JSON.stringify(event.query)}) } uni.onAppRoute(appRouteCallback) // 不再监听时传入注册时的同一个函数对象。 uni.offAppRoute(appRouteCallback)uni.offAppRoute(callback?)取消监听应用路由事件。不传 callback 时移除全部监听器。兼容性Web 5.25 / 微信小程序 5.25 / Android 5.25 / iOS 5.25 / HarmonyOS 5.25。参数callback类型为(event: AppRouteEvent) void可选。事件属性值与onAppRoute相同。移除监听器传入监听函数时只移除同一个函数对象对应的监听器不传参数或传入null时移除通过onAppRoute注册的全部监听器。const callback1 (event : AppRouteEvent) { console.log(event.path) } const callback2 (event : AppRouteEvent) { console.log(event.openType) } uni.onAppRoute(callback1) uni.onAppRoute(callback2) // 只移除 callback1。 uni.offAppRoute(callback1) // 移除全部 onAppRoute 监听器。 uni.offAppRoute()onAppRoute和onBeforeAppRoute的监听器相互独立清空其中一类不会影响另一类。uni.onBeforeAppRoute(callback)监听应用路由发生前的事件。兼容性Web 5.25 / 微信小程序 5.25 / Android 5.25 / iOS 5.25 / HarmonyOS 5.25。参数| 名称 | 类型 | 必填 | 描述 | | :- | :- | :- | :- | | callback | (event: BeforeAppRouteEvent) void | 是 | 应用路由前置事件回调 |BeforeAppRouteEvent 的属性值| 名称 | 类型 | 必备 | 兼容性 | 描述 | | :- | :- | :- | :-: | :- | | path | string | 是 | Web: 5.25; 微信小程序: 5.25; Android: 5.25; iOS: 5.25; HarmonyOS: 5.25 | 路由页面路径不包含开头的斜杠 | | query | UTSJSONObject | 是 | Web: 5.25; 微信小程序: 5.25; Android: 5.25; iOS: 5.25; HarmonyOS: 5.25 | 路由页面参数 | | openType | string | 是 | Web: 5.25; 微信小程序: 5.25; Android: 5.25; iOS: 5.25; HarmonyOS: 5.25 | 应用路由类型 | | notFound | boolean | 是 | Web: 5.25; 微信小程序: 5.25; Android: 5.25; iOS: 5.25; HarmonyOS: 5.25 | 路由页面是否不存在。支付宝小程序不提供该信息固定为 false | | routeEventId | string | 是 | Web: 5.25; 微信小程序: 5.25; Android: 5.25; iOS: 5.25; HarmonyOS: 5.25 | 路由事件唯一标识 | | page | IAnyObject | 否 | 微信小程序: 4.41 | 当前打开页面的相关配置 | | pipMode | string | 否 | 微信小程序: 4.41 | 可选值min、max| | renderer | string | 否 | 微信小程序: 4.41 | 渲染引擎。可选值webview、skyline、xr-frame| | webviewId | number | 否 | 微信小程序: 4.41 | 当前页面 id |注意与AppRouteEvent的区别BeforeAppRouteEvent不包含timeStamp字段。使用说明onBeforeAppRoute回调同步执行。可以根据目标页面、路由参数和路由类型记录信息也可以在该回调中同步调用rewriteRoute。const beforeAppRouteCallback (event : BeforeAppRouteEvent) { console.log(准备路由${event.openType} ${event.path}) console.log(路由参数${JSON.stringify(event.query)}) } // 如需处理 appLaunch应在 App.uvue 的 onLaunch 中尽早注册。 onLaunch(() { uni.onBeforeAppRoute(beforeAppRouteCallback) })同一个routeEventId对应的onBeforeAppRoute最多触发一次。重写后的目标会作为新一轮路由再次触发onBeforeAppRoute并使用新的routeEventId。uni.offBeforeAppRoute(callback?)取消监听应用路由前置事件。不传 callback 时移除全部监听器。兼容性Web 5.25 / 微信小程序 5.25 / Android 5.25 / iOS 5.25 / HarmonyOS 5.25。参数callback类型为(event: BeforeAppRouteEvent) void可选。事件属性值与onBeforeAppRoute相同。移除监听器offBeforeAppRoute的移除规则与offAppRoute相同传入注册时的同一个函数对象只移除该监听器不传参数或传入null移除全部前置路由监听器。const beforeAppRouteCallback (event : BeforeAppRouteEvent) { console.log(event.path) } uni.onBeforeAppRoute(beforeAppRouteCallback) uni.offBeforeAppRoute(beforeAppRouteCallback) // 移除全部 onBeforeAppRoute 监听器。 uni.offBeforeAppRoute()uni.rewriteRoute(options)在应用路由前置事件回调中重写当前路由。兼容性Web 5.25 / 微信小程序 5.25 / Android 5.25 / iOS 5.25 / HarmonyOS 5.25。参数| 名称 | 类型 | 必填 | | :- | :- | :- | | options |RewriteRouteOptions| 是 |options 的属性描述| 名称 | 类型 | 必备 | 兼容性 | 描述 | | :- | :- | :- | :-: | :- | | url | string (string.PageURIString) | 是 | Web: 5.25; 微信小程序: 5.25; Android: 5.25; iOS: 5.25; HarmonyOS: 5.25 | 重写后的页面路径 | | preserveQuery | boolean | 否 | Web: 5.25; 微信小程序: 5.25; Android: 5.25; iOS: 5.25; HarmonyOS: 5.25 | 是否保留原路由参数默认 false | | success | (result: RewriteRouteSuccess) void | 否 | Web: 5.25; 微信小程序: 5.25; Android: 5.25; iOS: 5.25; HarmonyOS: 5.25 | 接口调用成功的回调函数 | | fail | (result: RewriteRouteFail) void | 否 | Web: 5.25; 微信小程序: 5.25; Android: 5.25; iOS: 5.25; HarmonyOS: 5.25 | 接口调用失败的回调函数 | | complete | (result: RewriteRouteComplete) void | 否 | Web: 5.25; 微信小程序: 5.25; Android: 5.25; iOS: 5.25; HarmonyOS: 5.25 | 接口调用结束的回调函数 |RewriteRouteSuccess 的属性值| 名称 | 类型 | 必备 | | :- | :- | :- | | errMsg | string | 是 |RewriteRouteFail 的属性值| 名称 | 类型 | 必备 | 描述 | | :- | :- | :- | :- | | errCode | number | 是 | 路由错误码- 4: 框架内部异常 | | errSubject | string | 是 | 统一错误主题模块名称 | | data | any | 否 | 错误信息中包含的数据 | | cause | Error | 否 | 源错误信息可以包含多个错误详见 SourceError | | errMsg | string | 是 | 错误信息 |RewriteRouteComplete 的属性值| 名称 | 类型 | 必备 | | :- | :- | :- | | errMsg | string | 是 |路由重写规则rewriteRoute用于重写当前正在处理的路由事件且不支持 Promise 风格调用。调用时需遵守以下规则只能在onBeforeAppRoute回调中同步调用。在回调外调用或在回调中的异步任务内调用都会失败。同一个routeEventId只允许成功重写一次。存在多个前置监听器时首次重写成功后同一轮的后续重写调用会失败。重写只改变目标路径和参数不改变原路由的openType。navigateBack路由不允许重写。重写后的目标必须符合原路由类型的约束。例如switchTab只能重写到 tabBar 页面navigateTo不能重写到 tabBar 页面。重写目标会重新执行路径、页面存在性和路由类型校验。校验失败时保留当前轮的原目标并通过fail返回失败信息。框架会限制连续重写次数以避免循环重写超过限制时本次重写失败。微信小程序直接使用宿主的重写能力遵循微信小程序的限制。preserveQuery默认为false为false时使用url中携带的参数。为true时完整保留当前路由事件的参数并丢弃url中携带的参数。例如当前目标参数为a1重写地址为/pages/new/new?b2。preserveQuery为false时最终参数为b2为true时最终参数为a1。const beforeAppRouteCallback (event : BeforeAppRouteEvent) { if ( event.openType navigateTo event.path pages/old/old ) { uni.rewriteRoute({ url: /pages/new/new?fromrewrite, preserveQuery: false, success: (result) { console.log(result.errMsg) }, fail: (error) { console.error(error.errMsg) }, complete: (result) { console.log(result.errMsg) } }) } } uni.onBeforeAppRoute(beforeAppRouteCallback)回调语义success表示本次重写请求已被接受fail表示本次重写被拒绝无论成功或失败都会调用complete。连续重写重写后的目标会作为新的路由事件重新触发onBeforeAppRoute。因此同一个路由事件只允许成功重写一次不表示一次用户跳转只能重写一次。A - onBeforeAppRoute(routeEventId1) - 重写到 B B - onBeforeAppRoute(routeEventId2) - 重写到 C C - onBeforeAppRoute(routeEventId3) - 执行路由 C - onAppRoute(routeEventId3)业务代码应避免不同重写规则之间形成循环框架虽然会限制连续重写次数但循环重写仍会白白消耗一次用户跳转并产生失败日志。完整示例监听、记录与重写一次跳转下面是一个完整的可运行页面演示了开始/停止监听、记录onBeforeAppRoute与onAppRoute事件、以及将下一次navigateTo重写到目标页并附加fromrewrite参数的全过程template view classroute-page uni-theme-root page-head title应用路由事件/page-head view classuni-padding-wrap view classuni-list-cell-padding status-box text classuni-title-text监听状态/text text classstatus-text{{ data.isListening ? 监听中 : 已停止 }}/text text classstatus-textonBeforeAppRoute{{ data.beforeAppRouteCount }} 次/text text classstatus-textonAppRoute{{ data.appRouteCount }} 次/text /view view classuni-btn-v uni-common-mt button typeprimary clicknavigateToTarget普通跳转/button button clicknavigateToRewriteTarget重写下一次跳转/button button clickstartListen开始监听/button button clickstopListen停止监听/button button clickclearRecords清空记录/button /view view classevent-box uni-common-mt text classuni-title-textonBeforeAppRoute 记录/text text v-ifdata.beforeAppRouteEvents.length 0 classevent-text暂无记录/text view v-for(event, index) in data.beforeAppRouteEvents :keyindex classevent-item text classevent-index#{{ index 1 }}/text text classevent-text{{ event }}/text /view /view view classevent-box uni-common-mt text classuni-title-textonAppRoute 记录/text text v-ifdata.appRouteEvents.length 0 classevent-text暂无记录/text view v-for(event, index) in data.appRouteEvents :keyindex classevent-item text classevent-index#{{ index 1 }}/text text classevent-text{{ event }}/text /view /view view classevent-box uni-common-mt text classuni-title-text最近一次 rewriteRoute 结果/text text classevent-text{{ data.rewriteRouteResult }}/text /view /view /view /template script setup languts const TARGET_PATH pages/API/app-route/app-route-target const TARGET_URL /${TARGET_PATH} type DataType { isListening : boolean beforeAppRouteCount : number appRouteCount : number beforeAppRouteEvents : string[] appRouteEvents : string[] lastNavigateToBeforePath : string lastNavigateToAppRoutePath : string rewriteRouteResult : string } const data reactive({ isListening: false, beforeAppRouteCount: 0, appRouteCount: 0, beforeAppRouteEvents: [] as string[], appRouteEvents: [] as string[], lastNavigateToBeforePath: , lastNavigateToAppRoutePath: , rewriteRouteResult: } as DataType) let rewriteNextRoute false const appRouteCallback (event : AppRouteEvent) { data.appRouteCount data.appRouteEvents.push(JSON.stringify(event)) if (event.openType navigateTo) { data.lastNavigateToAppRoutePath event.path } } const beforeAppRouteCallback (event : BeforeAppRouteEvent) { data.beforeAppRouteCount data.beforeAppRouteEvents.push(JSON.stringify(event)) if (event.openType navigateTo) { data.lastNavigateToBeforePath event.path } if (rewriteNextRoute event.openType navigateTo event.path TARGET_PATH) { rewriteNextRoute false uni.rewriteRoute({ url: ${TARGET_URL}?fromrewrite, success: (result) { data.rewriteRouteResult result.errMsg }, fail: (error) { data.rewriteRouteResult error.errMsg } }) } } const startListen () { if (data.isListening) { return } uni.onAppRoute(appRouteCallback) uni.onBeforeAppRoute(beforeAppRouteCallback) data.isListening true } const stopListen () { if (!data.isListening) { return } uni.offAppRoute(appRouteCallback) uni.offBeforeAppRoute(beforeAppRouteCallback) data.isListening false rewriteNextRoute false } const clearRecords () { data.beforeAppRouteCount 0 data.appRouteCount 0 data.beforeAppRouteEvents.length 0 data.appRouteEvents.length 0 data.lastNavigateToBeforePath data.lastNavigateToAppRoutePath data.rewriteRouteResult } const navigateToTarget () { rewriteNextRoute false uni.navigateTo({ url: ${TARGET_URL}?fromnormal }) } const enableRewriteNextRoute () { rewriteNextRoute true } const navigateToRewriteTarget () { enableRewriteNextRoute() uni.navigateTo({ url: ${TARGET_URL}?fromsource, fail: () { rewriteNextRoute false } }) } onLoad(() { startListen() }) onUnload(() { stopListen() }) defineExpose({ data, startListen, stopListen, clearRecords, enableRewriteNextRoute, navigateToTarget, navigateToRewriteTarget }) /script style .status-box, .event-box { padding: 12px; background-color: var(--list-background-color, #ffffff); } .status-text, .event-text { margin-top: 8px; color: var(--text-color, #333333); } .event-text { width: 100%; } .event-item { padding-top: 8px; padding-bottom: 8px; border-bottom-width: 1px; border-bottom-style: solid; border-bottom-color: var(--border-color, #eeeeee); } .event-index { color: var(--active-color, #999999); } /style示例中的关键设计点startListen/stopListen成对注册与注销且传入的是同一个函数对象符合offAppRoute、offBeforeAppRoute的移除规则重写动作只对下一次navigateTo到目标路径生效rewriteNextRoute标志在成功重写后立即复位避免影响后续路由onLoad中开始监听、onUnload中停止监听页面销毁时不会残留监听器。通用类型GeneralCallbackResult| 名称 | 类型 | 必备 | 描述 | | :- | :- | :- | :- | | errMsg | string | 是 | 错误信息 |最佳实践小结按一次路由划分职责全局状态重置、埋点上报、登录态拦截等横切逻辑放进路由事件回调页面自身的数据加载、UI 初始化放到页面生命周期onLoad、onShow等。尽早注册以覆盖 appLaunch如需监听或重写应用启动路由应在App.uvue的onLaunch中或更早注册onBeforeAppRoute因为监听器注册前的事件不会补发。同步调用 rewriteRoute只能在onBeforeAppRoute同步回调中调用异步任务内调用会失败重写不改变openType且navigateBack不可重写。重写目标需符合路由类型约束switchTab只能重写到 tabBar 页面navigateTo不能重写到 tabBar 页面重写目标会重新走路径、存在性与类型校验。成对注册与注销注销时必须传入注册时的同一个函数对象onAppRoute与onBeforeAppRoute的监听器相互独立清空互不影响。关注平台差异微信小程序rewriteRoute要求基础库 3.8.0 且模拟器不支持支付宝小程序notFound恒为false且不支持rewriteRoute跨端代码只依赖公共字段。防止循环重写连续重写会产生新的routeEventId并再次触发前置事件业务规则之间应保证重写关系无环。参考文档应用路由事件官方文档本指南的原始依据包含全部 API 定义、兼容性与示例。页面生命周期路由事件与onLoad、onShow等页面生命周期的时序对照。dialogPage了解 dialogPage 为何不参与应用路由事件。UTSJSONObject事件参数query的类型说明。错误规范RewriteRouteFail.cause中Error的结构定义。release-note-alpha.mduni.onAppRoute、uni.onBeforeAppRoute、uni.rewriteRoute的版本引入记录。【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
uni-app x 应用路由事件监听与路由重写：onBeforeAppRoute、onAppRoute、rewriteRoute 实战指南
uni-app x 应用路由事件监听与路由重写onBeforeAppRoute、onAppRoute、rewriteRoute 实战指南【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app应用路由事件是 uni-app x 从应用级别监听主页面路由开始与完成、并在路由真正执行前重写目标页面的能力适用于路由上报、全局状态重置、访问控制、无效入口页纠正与页面迁移等一次路由级逻辑。本文将基于官方文档完整讲解uni.onBeforeAppRoute、uni.onAppRoute、uni.offBeforeAppRoute、uni.offAppRoute、uni.rewriteRoute五个 API 的时序、触发场景、事件参数、平台差异与重写规则并给出可直接运行的 UTS/Vue 示例帮助你掌握在 Web、AppAndroid/iOS/HarmonyOS与微信、支付宝等小程序端统一进行路由拦截和重定向的实战方案。应用路由事件概述应用路由事件用于从应用级别监听主页面路由的开始和完成也可以在路由真正执行前重写目标页面。它适合处理以下与一次路由相关的逻辑路由上报统计每次路由的目标页面、路由类型与参数全局状态重置路由切换时清理或初始化全局数据访问控制在路由执行前判断登录态、权限未通过时重写路由无效入口页纠正应用被直接启动到不存在的页面时重定向到有效页面页面迁移旧页面地址迁移到新页面地址。如果逻辑只与单个页面的创建、显示或销毁有关应优先使用对应的页面生命周期。例如onLoad只在新页面创建时触发一次、onShow在页面每次显示时触发二者与页面实例的创建销毁强绑定而应用路由事件是应用级的、面向一次路由的横切逻辑二者定位不同应根据业务归属选择。应用路由事件只作用于主页面路由。dialogPage 的打开、关闭以及随所属页面销毁均不会触发本页 API。这与 dialogPage 的设计一致dialogPage 不使用uni.navigateTo等路由 API而是单独提供openDialogPage和closeDialogPage不影响页面栈和路由地址因此也不参与应用路由事件的派发。API 列表API说明uni.onBeforeAppRoute监听路由执行前的事件uni.offBeforeAppRoute取消监听路由执行前的事件uni.onAppRoute监听路由成功后的事件uni.offAppRoute取消监听路由成功后的事件uni.rewriteRoute在路由执行前重写本次路由事件时序一次成功路由的主要执行顺序如下发起路由 - 解析路径并校验目标 - onBeforeAppRoute - 执行路由逻辑 - 目标页面 onShow - onAppRoute - 路由转场动画完成新页面创建时相关事件和页面生命周期的顺序为onBeforeAppRoute - onLoad - onShow - onAppRoute返回已有页面或切换到已存在的 tabBar 页面时不会再次触发onLoad顺序为onBeforeAppRoute - onShow - onAppRoute这里与页面生命周期中的说明相互印证onLoad只在页面创建时触发一次而页面从隐藏恢复显示时只触发onShow。关键时点语义onBeforeAppRoute在页面栈变化以及页面创建、销毁等实际副作用发生前触发onAppRoute在路由成功且目标页面的onShow执行后触发不等待路由转场动画完成。触发场景下表列出了各场景下两个事件与可重写的情况场景onBeforeAppRouteonAppRoute可重写应用启动并进入有效首页或二级页面触发路由成功后触发是应用直接启动到不存在的页面触发notFound为true支付宝小程序固定为false未重写时按缺页流程触发支付宝小程序不触发支持rewriteRoute的平台可重写navigateTo、redirectTo、reLaunch成功触发路由成功后触发是切换到其他 tabBar 页面触发路由成功后触发是且目标必须是 tabBar 页面switchTab到当前 tabBar 页面不触发不触发否navigateBack、系统返回、返回手势或 Web History 后退触发路由成功后触发否路由 API 参数错误或目标页面校验失败不触发支付宝小程序仍会触发且notFound为false不触发否onBeforeAppRoute已触发但路由随后取消或执行失败已触发不触发仅可在同步回调阶段重写应用从后台恢复但主页面路由未变化不触发不触发否dialogPage 打开、关闭或随所属页面销毁不触发不触发否两点需要特别留意监听器注册前已经发生的事件不会补发。如需监听或重写appLaunch应在onLaunch生命周期中或之前尽早注册监听器。正常调用路由 API 时参数错误或目标页面不存在会直接失败除支付宝小程序外此类失败不会产生应用路由事件。notFound主要用于应用直接启动到不存在页面等已经进入路由流程的场景。事件参数与路由类型onBeforeAppRoute和onAppRoute的公共事件参数含义如下属性说明path目标页面路径不包含开头的/query当前轮路由解析得到的页面参数openType路由类型。发生重写时保持原路由类型不变notFound当前目标页面是否不存在routeEventId应用实例内唯一的路由事件标识onAppRoute还会提供timeStamp表示当前轮路由事件生成时的时间戳。不同平台可能提供额外的事件字段。编写跨平台代码时应只依赖上述公共字段。routeEventId的关联规则未发生重写时同一次路由的onBeforeAppRoute与onAppRoute使用相同的routeEventId每次成功重写都会生成新的路由事件和新的routeEventId最终的onAppRoute使用最后一轮onBeforeAppRoute的routeEventId。路由类型openTypeopenType路由来源appLaunch应用首次启动Web 直接访问首页或二级页面等入口路由navigateTouni.navigateToWeb History 前进无法识别为其他类型的新增页面路由navigateBackuni.navigateBack系统返回、返回手势Web History 后退小程序系统返回redirectTouni.redirectToreLaunchuni.reLaunchswitchTabuni.switchTab用户切换到其他 tabBar 页面平台差异与版本要求::: warning 平台差异微信小程序的路由事件监听要求基础库3.5.5及以上版本rewriteRoute要求基础库3.8.0及以上版本并受微信客户端版本、运行平台和分包限制。微信开发者工具模拟器不支持rewriteRoute应在支持该能力的真机环境中验证。支付宝小程序通过my.createRouteObserver实现路由事件监听。支付宝小程序开发者工具目前未提供my.createRouteObserver无法在开发者工具中验证路由事件监听相关 API应在支持该能力的支付宝客户端真机环境中验证。支付宝的前置事件不提供目标页面是否存在的信息因此onBeforeAppRoute的notFound固定为false。当路由 API 的目标页面不存在时支付宝仍会触发onBeforeAppRoute但不会触发onAppRoute应用直接启动到不存在的页面时同样不会触发onAppRoute。支付宝小程序暂不支持rewriteRoute。:::从版本记录看本仓库的 release-note-alpha.md 明确记载了新增 API uni.onAppRoute、uni.onBeforeAppRoute、uni.rewriteRoute 支持页面路由监听及重写这一能力对应 issue 31599说明该系列 API 属于 uni-app x 的较新能力使用时建议保持 HBuilderX 与基础库处于较新版本并以各平台真机能力为准。事件相关 API 在 Web、微信小程序、Android、iOS、HarmonyOS 五个平台的一致性支持版本均为 5.25见下文各 API 的兼容性表。uni.onAppRoute(callback)监听应用路由成功后的事件。兼容性Web 5.25 / 微信小程序 5.25 / Android 5.25 / iOS 5.25 / HarmonyOS 5.25。参数| 名称 | 类型 | 必填 | 描述 | | :- | :- | :- | :- | | callback | (event: AppRouteEvent) void | 是 | 应用路由事件回调 |AppRouteEvent 的属性值| 名称 | 类型 | 必备 | 兼容性 | 描述 | | :- | :- | :- | :-: | :- | | path | string | 是 | Web: 5.25; 微信小程序: 5.25; Android: 5.25; iOS: 5.25; HarmonyOS: 5.25 | 路由页面路径不包含开头的斜杠 | | query | UTSJSONObject | 是 | Web: 5.25; 微信小程序: 5.25; Android: 5.25; iOS: 5.25; HarmonyOS: 5.25 | 路由页面参数 | | openType | string | 是 | Web: 5.25; 微信小程序: 5.25; Android: 5.25; iOS: 5.25; HarmonyOS: 5.25 | 应用路由类型 | | notFound | boolean | 是 | Web: 5.25; 微信小程序: 5.25; Android: 5.25; iOS: 5.25; HarmonyOS: 5.25 | 路由页面是否不存在。支付宝小程序不提供该信息固定为 false | | timeStamp | number | 是 | Web: 5.25; 微信小程序: 5.25; Android: 5.25; iOS: 5.25; HarmonyOS: 5.25 | 事件触发时的时间戳 | | routeEventId | string | 是 | Web: 5.25; 微信小程序: 5.25; Android: 5.25; iOS: 5.25; HarmonyOS: 5.25 | 路由事件唯一标识 | | page | IAnyObject | 否 | 微信小程序: 4.41 | 当前打开页面的相关配置 | | pipMode | string | 否 | 微信小程序: 4.41 | 可选值min视频页面缩小为小窗、max视频小窗还原为页面 | | renderer | string | 否 | 微信小程序: 4.41 | 渲染引擎。可选值webview、skyline、xr-frame| | webviewId | number | 否 | 微信小程序: 4.41 | 当前页面 id |其中page、pipMode、renderer、webviewId为微信小程序特有的扩展字段其他平台不会提供跨平台代码中不要依赖。使用说明onAppRoute只描述最终实际生效的路由。一次路由发生重写时被替换的中间目标不会触发onAppRoute只有最终成功进入的页面触发一次。监听器抛出的异常不会中断底层路由流程但应在监听器内部妥善处理业务异常。const appRouteCallback (event : AppRouteEvent) { console.log(路由完成${event.openType} ${event.path}) console.log(路由参数${JSON.stringify(event.query)}) } uni.onAppRoute(appRouteCallback) // 不再监听时传入注册时的同一个函数对象。 uni.offAppRoute(appRouteCallback)uni.offAppRoute(callback?)取消监听应用路由事件。不传 callback 时移除全部监听器。兼容性Web 5.25 / 微信小程序 5.25 / Android 5.25 / iOS 5.25 / HarmonyOS 5.25。参数callback类型为(event: AppRouteEvent) void可选。事件属性值与onAppRoute相同。移除监听器传入监听函数时只移除同一个函数对象对应的监听器不传参数或传入null时移除通过onAppRoute注册的全部监听器。const callback1 (event : AppRouteEvent) { console.log(event.path) } const callback2 (event : AppRouteEvent) { console.log(event.openType) } uni.onAppRoute(callback1) uni.onAppRoute(callback2) // 只移除 callback1。 uni.offAppRoute(callback1) // 移除全部 onAppRoute 监听器。 uni.offAppRoute()onAppRoute和onBeforeAppRoute的监听器相互独立清空其中一类不会影响另一类。uni.onBeforeAppRoute(callback)监听应用路由发生前的事件。兼容性Web 5.25 / 微信小程序 5.25 / Android 5.25 / iOS 5.25 / HarmonyOS 5.25。参数| 名称 | 类型 | 必填 | 描述 | | :- | :- | :- | :- | | callback | (event: BeforeAppRouteEvent) void | 是 | 应用路由前置事件回调 |BeforeAppRouteEvent 的属性值| 名称 | 类型 | 必备 | 兼容性 | 描述 | | :- | :- | :- | :-: | :- | | path | string | 是 | Web: 5.25; 微信小程序: 5.25; Android: 5.25; iOS: 5.25; HarmonyOS: 5.25 | 路由页面路径不包含开头的斜杠 | | query | UTSJSONObject | 是 | Web: 5.25; 微信小程序: 5.25; Android: 5.25; iOS: 5.25; HarmonyOS: 5.25 | 路由页面参数 | | openType | string | 是 | Web: 5.25; 微信小程序: 5.25; Android: 5.25; iOS: 5.25; HarmonyOS: 5.25 | 应用路由类型 | | notFound | boolean | 是 | Web: 5.25; 微信小程序: 5.25; Android: 5.25; iOS: 5.25; HarmonyOS: 5.25 | 路由页面是否不存在。支付宝小程序不提供该信息固定为 false | | routeEventId | string | 是 | Web: 5.25; 微信小程序: 5.25; Android: 5.25; iOS: 5.25; HarmonyOS: 5.25 | 路由事件唯一标识 | | page | IAnyObject | 否 | 微信小程序: 4.41 | 当前打开页面的相关配置 | | pipMode | string | 否 | 微信小程序: 4.41 | 可选值min、max| | renderer | string | 否 | 微信小程序: 4.41 | 渲染引擎。可选值webview、skyline、xr-frame| | webviewId | number | 否 | 微信小程序: 4.41 | 当前页面 id |注意与AppRouteEvent的区别BeforeAppRouteEvent不包含timeStamp字段。使用说明onBeforeAppRoute回调同步执行。可以根据目标页面、路由参数和路由类型记录信息也可以在该回调中同步调用rewriteRoute。const beforeAppRouteCallback (event : BeforeAppRouteEvent) { console.log(准备路由${event.openType} ${event.path}) console.log(路由参数${JSON.stringify(event.query)}) } // 如需处理 appLaunch应在 App.uvue 的 onLaunch 中尽早注册。 onLaunch(() { uni.onBeforeAppRoute(beforeAppRouteCallback) })同一个routeEventId对应的onBeforeAppRoute最多触发一次。重写后的目标会作为新一轮路由再次触发onBeforeAppRoute并使用新的routeEventId。uni.offBeforeAppRoute(callback?)取消监听应用路由前置事件。不传 callback 时移除全部监听器。兼容性Web 5.25 / 微信小程序 5.25 / Android 5.25 / iOS 5.25 / HarmonyOS 5.25。参数callback类型为(event: BeforeAppRouteEvent) void可选。事件属性值与onBeforeAppRoute相同。移除监听器offBeforeAppRoute的移除规则与offAppRoute相同传入注册时的同一个函数对象只移除该监听器不传参数或传入null移除全部前置路由监听器。const beforeAppRouteCallback (event : BeforeAppRouteEvent) { console.log(event.path) } uni.onBeforeAppRoute(beforeAppRouteCallback) uni.offBeforeAppRoute(beforeAppRouteCallback) // 移除全部 onBeforeAppRoute 监听器。 uni.offBeforeAppRoute()uni.rewriteRoute(options)在应用路由前置事件回调中重写当前路由。兼容性Web 5.25 / 微信小程序 5.25 / Android 5.25 / iOS 5.25 / HarmonyOS 5.25。参数| 名称 | 类型 | 必填 | | :- | :- | :- | | options |RewriteRouteOptions| 是 |options 的属性描述| 名称 | 类型 | 必备 | 兼容性 | 描述 | | :- | :- | :- | :-: | :- | | url | string (string.PageURIString) | 是 | Web: 5.25; 微信小程序: 5.25; Android: 5.25; iOS: 5.25; HarmonyOS: 5.25 | 重写后的页面路径 | | preserveQuery | boolean | 否 | Web: 5.25; 微信小程序: 5.25; Android: 5.25; iOS: 5.25; HarmonyOS: 5.25 | 是否保留原路由参数默认 false | | success | (result: RewriteRouteSuccess) void | 否 | Web: 5.25; 微信小程序: 5.25; Android: 5.25; iOS: 5.25; HarmonyOS: 5.25 | 接口调用成功的回调函数 | | fail | (result: RewriteRouteFail) void | 否 | Web: 5.25; 微信小程序: 5.25; Android: 5.25; iOS: 5.25; HarmonyOS: 5.25 | 接口调用失败的回调函数 | | complete | (result: RewriteRouteComplete) void | 否 | Web: 5.25; 微信小程序: 5.25; Android: 5.25; iOS: 5.25; HarmonyOS: 5.25 | 接口调用结束的回调函数 |RewriteRouteSuccess 的属性值| 名称 | 类型 | 必备 | | :- | :- | :- | | errMsg | string | 是 |RewriteRouteFail 的属性值| 名称 | 类型 | 必备 | 描述 | | :- | :- | :- | :- | | errCode | number | 是 | 路由错误码- 4: 框架内部异常 | | errSubject | string | 是 | 统一错误主题模块名称 | | data | any | 否 | 错误信息中包含的数据 | | cause | Error | 否 | 源错误信息可以包含多个错误详见 SourceError | | errMsg | string | 是 | 错误信息 |RewriteRouteComplete 的属性值| 名称 | 类型 | 必备 | | :- | :- | :- | | errMsg | string | 是 |路由重写规则rewriteRoute用于重写当前正在处理的路由事件且不支持 Promise 风格调用。调用时需遵守以下规则只能在onBeforeAppRoute回调中同步调用。在回调外调用或在回调中的异步任务内调用都会失败。同一个routeEventId只允许成功重写一次。存在多个前置监听器时首次重写成功后同一轮的后续重写调用会失败。重写只改变目标路径和参数不改变原路由的openType。navigateBack路由不允许重写。重写后的目标必须符合原路由类型的约束。例如switchTab只能重写到 tabBar 页面navigateTo不能重写到 tabBar 页面。重写目标会重新执行路径、页面存在性和路由类型校验。校验失败时保留当前轮的原目标并通过fail返回失败信息。框架会限制连续重写次数以避免循环重写超过限制时本次重写失败。微信小程序直接使用宿主的重写能力遵循微信小程序的限制。preserveQuery默认为false为false时使用url中携带的参数。为true时完整保留当前路由事件的参数并丢弃url中携带的参数。例如当前目标参数为a1重写地址为/pages/new/new?b2。preserveQuery为false时最终参数为b2为true时最终参数为a1。const beforeAppRouteCallback (event : BeforeAppRouteEvent) { if ( event.openType navigateTo event.path pages/old/old ) { uni.rewriteRoute({ url: /pages/new/new?fromrewrite, preserveQuery: false, success: (result) { console.log(result.errMsg) }, fail: (error) { console.error(error.errMsg) }, complete: (result) { console.log(result.errMsg) } }) } } uni.onBeforeAppRoute(beforeAppRouteCallback)回调语义success表示本次重写请求已被接受fail表示本次重写被拒绝无论成功或失败都会调用complete。连续重写重写后的目标会作为新的路由事件重新触发onBeforeAppRoute。因此同一个路由事件只允许成功重写一次不表示一次用户跳转只能重写一次。A - onBeforeAppRoute(routeEventId1) - 重写到 B B - onBeforeAppRoute(routeEventId2) - 重写到 C C - onBeforeAppRoute(routeEventId3) - 执行路由 C - onAppRoute(routeEventId3)业务代码应避免不同重写规则之间形成循环框架虽然会限制连续重写次数但循环重写仍会白白消耗一次用户跳转并产生失败日志。完整示例监听、记录与重写一次跳转下面是一个完整的可运行页面演示了开始/停止监听、记录onBeforeAppRoute与onAppRoute事件、以及将下一次navigateTo重写到目标页并附加fromrewrite参数的全过程template view classroute-page uni-theme-root page-head title应用路由事件/page-head view classuni-padding-wrap view classuni-list-cell-padding status-box text classuni-title-text监听状态/text text classstatus-text{{ data.isListening ? 监听中 : 已停止 }}/text text classstatus-textonBeforeAppRoute{{ data.beforeAppRouteCount }} 次/text text classstatus-textonAppRoute{{ data.appRouteCount }} 次/text /view view classuni-btn-v uni-common-mt button typeprimary clicknavigateToTarget普通跳转/button button clicknavigateToRewriteTarget重写下一次跳转/button button clickstartListen开始监听/button button clickstopListen停止监听/button button clickclearRecords清空记录/button /view view classevent-box uni-common-mt text classuni-title-textonBeforeAppRoute 记录/text text v-ifdata.beforeAppRouteEvents.length 0 classevent-text暂无记录/text view v-for(event, index) in data.beforeAppRouteEvents :keyindex classevent-item text classevent-index#{{ index 1 }}/text text classevent-text{{ event }}/text /view /view view classevent-box uni-common-mt text classuni-title-textonAppRoute 记录/text text v-ifdata.appRouteEvents.length 0 classevent-text暂无记录/text view v-for(event, index) in data.appRouteEvents :keyindex classevent-item text classevent-index#{{ index 1 }}/text text classevent-text{{ event }}/text /view /view view classevent-box uni-common-mt text classuni-title-text最近一次 rewriteRoute 结果/text text classevent-text{{ data.rewriteRouteResult }}/text /view /view /view /template script setup languts const TARGET_PATH pages/API/app-route/app-route-target const TARGET_URL /${TARGET_PATH} type DataType { isListening : boolean beforeAppRouteCount : number appRouteCount : number beforeAppRouteEvents : string[] appRouteEvents : string[] lastNavigateToBeforePath : string lastNavigateToAppRoutePath : string rewriteRouteResult : string } const data reactive({ isListening: false, beforeAppRouteCount: 0, appRouteCount: 0, beforeAppRouteEvents: [] as string[], appRouteEvents: [] as string[], lastNavigateToBeforePath: , lastNavigateToAppRoutePath: , rewriteRouteResult: } as DataType) let rewriteNextRoute false const appRouteCallback (event : AppRouteEvent) { data.appRouteCount data.appRouteEvents.push(JSON.stringify(event)) if (event.openType navigateTo) { data.lastNavigateToAppRoutePath event.path } } const beforeAppRouteCallback (event : BeforeAppRouteEvent) { data.beforeAppRouteCount data.beforeAppRouteEvents.push(JSON.stringify(event)) if (event.openType navigateTo) { data.lastNavigateToBeforePath event.path } if (rewriteNextRoute event.openType navigateTo event.path TARGET_PATH) { rewriteNextRoute false uni.rewriteRoute({ url: ${TARGET_URL}?fromrewrite, success: (result) { data.rewriteRouteResult result.errMsg }, fail: (error) { data.rewriteRouteResult error.errMsg } }) } } const startListen () { if (data.isListening) { return } uni.onAppRoute(appRouteCallback) uni.onBeforeAppRoute(beforeAppRouteCallback) data.isListening true } const stopListen () { if (!data.isListening) { return } uni.offAppRoute(appRouteCallback) uni.offBeforeAppRoute(beforeAppRouteCallback) data.isListening false rewriteNextRoute false } const clearRecords () { data.beforeAppRouteCount 0 data.appRouteCount 0 data.beforeAppRouteEvents.length 0 data.appRouteEvents.length 0 data.lastNavigateToBeforePath data.lastNavigateToAppRoutePath data.rewriteRouteResult } const navigateToTarget () { rewriteNextRoute false uni.navigateTo({ url: ${TARGET_URL}?fromnormal }) } const enableRewriteNextRoute () { rewriteNextRoute true } const navigateToRewriteTarget () { enableRewriteNextRoute() uni.navigateTo({ url: ${TARGET_URL}?fromsource, fail: () { rewriteNextRoute false } }) } onLoad(() { startListen() }) onUnload(() { stopListen() }) defineExpose({ data, startListen, stopListen, clearRecords, enableRewriteNextRoute, navigateToTarget, navigateToRewriteTarget }) /script style .status-box, .event-box { padding: 12px; background-color: var(--list-background-color, #ffffff); } .status-text, .event-text { margin-top: 8px; color: var(--text-color, #333333); } .event-text { width: 100%; } .event-item { padding-top: 8px; padding-bottom: 8px; border-bottom-width: 1px; border-bottom-style: solid; border-bottom-color: var(--border-color, #eeeeee); } .event-index { color: var(--active-color, #999999); } /style示例中的关键设计点startListen/stopListen成对注册与注销且传入的是同一个函数对象符合offAppRoute、offBeforeAppRoute的移除规则重写动作只对下一次navigateTo到目标路径生效rewriteNextRoute标志在成功重写后立即复位避免影响后续路由onLoad中开始监听、onUnload中停止监听页面销毁时不会残留监听器。通用类型GeneralCallbackResult| 名称 | 类型 | 必备 | 描述 | | :- | :- | :- | :- | | errMsg | string | 是 | 错误信息 |最佳实践小结按一次路由划分职责全局状态重置、埋点上报、登录态拦截等横切逻辑放进路由事件回调页面自身的数据加载、UI 初始化放到页面生命周期onLoad、onShow等。尽早注册以覆盖 appLaunch如需监听或重写应用启动路由应在App.uvue的onLaunch中或更早注册onBeforeAppRoute因为监听器注册前的事件不会补发。同步调用 rewriteRoute只能在onBeforeAppRoute同步回调中调用异步任务内调用会失败重写不改变openType且navigateBack不可重写。重写目标需符合路由类型约束switchTab只能重写到 tabBar 页面navigateTo不能重写到 tabBar 页面重写目标会重新走路径、存在性与类型校验。成对注册与注销注销时必须传入注册时的同一个函数对象onAppRoute与onBeforeAppRoute的监听器相互独立清空互不影响。关注平台差异微信小程序rewriteRoute要求基础库 3.8.0 且模拟器不支持支付宝小程序notFound恒为false且不支持rewriteRoute跨端代码只依赖公共字段。防止循环重写连续重写会产生新的routeEventId并再次触发前置事件业务规则之间应保证重写关系无环。参考文档应用路由事件官方文档本指南的原始依据包含全部 API 定义、兼容性与示例。页面生命周期路由事件与onLoad、onShow等页面生命周期的时序对照。dialogPage了解 dialogPage 为何不参与应用路由事件。UTSJSONObject事件参数query的类型说明。错误规范RewriteRouteFail.cause中Error的结构定义。release-note-alpha.mduni.onAppRoute、uni.onBeforeAppRoute、uni.rewriteRoute的版本引入记录。【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
