uni-app 自定义路由封装模块详解（附源码逐行解读）

🚀uni-app 自定义路由封装模块详解（附源码逐行解读）

📌 请收藏 + 点赞 + 关注，获取更多 uni-app 项目实用技巧！

在实际 uni-app 项目中，我们常常需要对 uni.navigateTo、uni.switchTab 等 API 做一层封装，以便统一处理页面跳转、参数传递、登录拦截等逻辑。本篇将完整展示一份功能强大的路由封装方案，并逐行解释其实现逻辑，帮助你构建更可控、易扩展的项目架构。

📦源码展示（含说明性注释）

👇以下是完整源码，已集成：

页面路径分析
query 和 params 分离
登录拦截（导航守卫）
页面跳转封装（支持多种跳转模式）
首页识别与返回逻辑
页签识别
页面栈方法调用
登录回调钩子

📄 完整代码如下（点击右侧小箭头可展开逐行解读）：

点击展开完整源码逐行解读

// 引入 lodash 的 last 方法，返回数组最后一个元素
import { last } from "lodash-es";// 引入 ctx 插件中编译期注入的页面配置、tabBar、subPackages 等
import { ctx } from "virtual:ctx";// 项目中封装的 localStorage 工具
import { storage } from "../utils";// 引入全局 config 配置
import { config } from "../../config";type PushOptions = string | {path: string; // 路径mode?: "navigateTo" | "redirectTo" | "reLaunch" | "switchTab" | "preloadPage"; // 跳转方式events?: { [key: string]: (data: any) => void }; // 页面间事件通信query?: { [key: string]: any }; // URL 参数params?: { [key: string]: any }; // 缓存参数isGuard?: boolean; // 是否启用导航守卫[key: string]: any;
};type Tabs = {text?: string;pagePath: string;iconPath?: string;selectedIconPath?: string;[key: string]: any;
}[];// 获取所有页面配置
const routes = [...ctx.pages];// 处理子包中的页面路径
if (ctx.subPackages) {ctx.subPackages.forEach((a) => {a.pages.forEach((b) => {routes.push({...b,path: a.root + "/" + b.path,});});});
}// 注册钩子函数
const fn: { [key: string]: (...args: any[]) => any } = {};// 路由核心对象
const router = {// 读取 tabBar 配置get tabs(): Tabs {if (ctx.tabBar) {return ctx.tabBar.list || [];} else {return [];}},// 全局样式globalStyle: ctx.globalStyle,// 所有路由routes,// 当前页面 URL query 参数get query() {const info = this.info();return { ...info?.query };},// 非 URL 参数，通过缓存传递get params() {return storage.get("router-params") || {};},// 页面路径配置get pages() {return {home: "/" + (ctx.tabBar ? this.tabs[0].pagePath : ctx.pages[0].path),...config.app.pages,};},// 当前页面信息对象currentPage() {return last(getCurrentPages())!;},// 当前路径get path() {return router.info()?.path;},// 当前页面完整信息info() {const page = last(getCurrentPages());if (page) {const { route, $page, $vm, $getAppWebview }: any = page;const q: any = {};// 解析 query 参数try {$page?.fullPath.split("?")[1].split("&").forEach((e: string) => {const [k, v] = e.split("=");q[k] = decodeURIComponent(v);});} catch (e) {}const style = this.routes.find((e) => e.path == route)?.style;return {$vm,$getAppWebview,path: `/${route}`,fullPath: $page?.fullPath,query: q || {},isTab: this.isTab(route),style,isCustomNavbar: style?.navigationStyle == "custom",};}return null;},// 页面跳转主函数push(options: PushOptions) {if (typeof options === "string") {options = { path: options, mode: "navigateTo" };}let {path,mode = "navigateTo",animationType,animationDuration,events,success,fail,complete,query,params,isGuard = true,} = options;// 拼接 query 到 URLif (query) {let arr = [];for (let i in query) {if (query[i] !== undefined) arr.push(`${i}=${query[i]}`);}path += "?" + arr.join("&");}// 缓存传参if (params) {storage.set("router-params", params);}const data = {url: path,animationType,animationDuration,events,success,fail,complete,};// 如果目标是 tab 页，强制使用 switchTabif (this.isTab(path)) {mode = "switchTab";}const next = () => {switch (mode) {case "navigateTo":uni.navigateTo(data); break;case "redirectTo":uni.redirectTo(data); break;case "reLaunch":uni.reLaunch(data); break;case "switchTab":uni.switchTab(data); break;case "preloadPage":uni.preloadPage(data); break;}};// 启用导航守卫if (fn.beforeEach && isGuard) {fn.beforeEach({ path: options.path, query }, next, (opt) => this.push(opt));} else {next();}},// 返回上一页或首页back(options?: UniApp.NavigateBackOptions) {if (this.isFirstPage()) {this.home();} else {uni.navigateBack(options || {});}},// 执行当前页面某个方法callMethod(name: string, data?: any) {const { $vm } = this.info()!;if ($vm && $vm.$.exposed?.[name]) {return $vm.$.exposed[name](data);}},// 是否第一页（判断是否需要返回首页）isFirstPage() {return getCurrentPages().length == 1;},// 是否是当前路径isCurrentPage(path: string) {return this.info()?.path === path;},// 返回首页home() {this.push(this.pages.home);},// 跳转 Tab 页switchTab(name: string) {const item = this.tabs.find((e) => e.pagePath.includes(name));if (item) {this.push({path: `/${item.pagePath}`,mode: "switchTab",});} else {console.error("Not found tab", name);}},// 是否是 Tab 页isTab(path: string) {return !!this.tabs.find((e) => path === `/${e.pagePath}`);},// 跳转登录页（支持 reLaunch）login(options?: { reLaunch: boolean }) {const { reLaunch = false } = options || {};this.push({path: this.pages.login,mode: reLaunch ? "reLaunch" : "navigateTo",isGuard: false,});},// 登录成功后的回调处理nextLogin(type?: string) {const pages = getCurrentPages();const index = pages.findIndex((e) => this.pages.login.includes(e.route!));if (index <= 0) {this.home();} else {this.back({ delta: pages.length - index });}storage.set("loginType", type);if (fn.afterLogin) fn.afterLogin();uni.$emit("afterLogin", { type });},// 注册路由钩子函数（beforeEach）beforeEach(callback: (to: any, next: () => void, reject: (opt: PushOptions) => void) => void) {fn.beforeEach = callback;},// 登录后执行回调afterLogin(callback: () => void) {fn.afterLogin = callback;},
};export { router };

✍️ 核心功能说明（重点功能归纳）

功能模块	描述说明
`router.push()`	支持全模式页面跳转，封装 query/params，支持守卫
`router.info()`	获取当前页面详细信息
`router.callMethod()`	跨组件执行 exposed 方法
`router.isTab()`	判断路径是否为 Tab 页
`router.beforeEach()`	注册跳转拦截器
`router.nextLogin()`	登录回调重定向功能
`router.pages`	自动生成首页路径与配置路径