@meng-xi/uni-router

做自己喜欢的事就是幸福 · 发表于 2025-7-25 14:54:00

@meng-xi/uni-router 是一个专为 uni-app 开发的路由管理库，采用类似 vue-router 的设计风格，并提供丰富的工具函数，帮助开发者轻松实现跨平台路由管理。

npm包地址
github地址

核心功能

类 vue-router API：与 vue-router 相似的 API 设计，学习成本低，迁移简单
多种导航方式：
- push：保留当前页面的跳转
- replace：替换当前页面
- launch：重启应用并跳转
- tab：切换 tabBar 页面
- go/back：页面返回控制
路由守卫：
- beforeEach：导航前执行（适合权限验证）
- afterEach：导航后执行（适合埋点统计）
实用方法:
- getCurrentRoute: 获取当前路由信息
- setCustomGetCurrentRoute: 设置自定义获取当前路由的函数
实用工具：
- parseLocation：解析路由位置
- buildUrl：构建完整 URL
- getCurrentRoute：获取当前路由
Hooks：
- useMxRouter：获取 Router 实例
组件：
- Router：路由组件
全平台适配：完美支持 H5、小程序和 App

安装指南

使用 pnpm 安装：

pnpm install @meng-xi/uni-router

快速入门

初始化路由

import { Router } from '@meng-xi/uni-router'

const router = new Router({
	routes: [
		{ path: '/home', meta: { title: '首页' } },
		{ path: '/admin', meta: { requiresAuth: true } }
	]
})

配置路由守卫

// 认证状态检查
const isAuthenticated = () => !!localStorage.getItem('token')

// 前置守卫
router.beforeEach((to, from, next) => {
	if (to.meta?.requiresAuth && !isAuthenticated()) {
		next({ path: '/login', query: { redirect: to.fullPath } })
	} else {
		next()
	}
})

// 后置钩子
router.afterEach((to, from) => {
	console.log(`从 ${from?.path || '起始页'} 跳转到 ${to.path}`)
})

路由跳转示例

// 基本跳转
router.push('/products')

// 带参数跳转
router.push({
	path: '/search',
	query: { keyword: '手机' }
})

// 替换当前页
router.replace('/profile')

// 重启跳转
router.launch('/dashboard')

// 切换 tab 页
router.tab('/tabBar/cart')

// 页面返回
router.back()
router.go(-2)

单例模式

创建单例

import { Router } from '@meng-xi/uni-router'

Router.getInstance({
	routes: [
		{ path: '/home', meta: { title: '首页' } },
		{ path: '/admin', meta: { requiresAuth: true } }
	]
})

守卫配置

Router.beforeEach((to, from, next) => {
	if (to.meta?.requiresAuth && !isAuthenticated()) {
		next({ path: '/login', query: { redirect: to.fullPath } })
	} else {
		next()
	}
})

Router.afterEach((to, from) => {
	console.log(`路由跳转: ${from?.path || '起始页'} → ${to.path}`)
})

导航操作

Router.push('/products')
Router.push({ path: '/search', query: { keyword: '手机' } })
Router.replace('/profile')
Router.launch('/dashboard')
Router.tab('/tabBar/cart')
Router.back()
Router.go(-2)

API 参考

Router 类

实现 RouterInterface 接口，提供核心路由功能。

构造函数

constructor(options?: RouterOptions)

参数说明：

options（可选）：包含 routes 路由配置数组和 customGetCurrentRoute 自定义获取当前路由的函数的对象。

导航方法

方法	说明	参数	返回值
`push`	保留当前页面的跳转	`location: RouteLocationRaw`	`Promise<void>`
`replace`	替换当前页面	`location: RouteLocationRaw`	`Promise<void>`
`launch`	重启应用跳转	`location: RouteLocationRaw`	`Promise<void>`
`tab`	切换 tab 页面	`location: RouteLocationRaw`	`Promise<void>`
`go`	返回指定层数（默认-1）	`delta?: number`	`void`
`back`	返回上一页	-	`void`

路由守卫

方法	说明	参数	返回值
`beforeEach`	全局前置守卫	`guard: NavigationGuard`	`void`
`afterEach`	全局后置钩子	`hook: AfterEachHook`	`void`

实用方法

方法	说明	参数	返回值
`getCurrentRoute`	获取当前路由信息	-	`RouteLocation`
`setCustomGetCurrentRoute`	设置自定义获取当前路由的函数	`customFunction: () => Route \| null`	`void`

实用工具

`parseLocation`

parseLocation(location: RouteLocationRaw): { path: string; query?: Record<string, string> }

功能：将路由位置信息统一解析为路径和查询参数对象
参数：
- location：支持字符串或对象格式的路由位置信息
返回：包含路径字符串和可选查询参数的对象

`buildUrl`

buildUrl(path: string, query?: Record<string, string | number | boolean>): string

功能：根据路径和查询参数构建完整 URL
参数：
- path：目标路径字符串
- query（可选）：查询参数对象
返回：完整的 URL 字符串

`getCurrentRoute`

getCurrentRoute(currentPage: CurrentPage | null): Route | null

功能：获取当前页面的路由信息（支持多平台差异处理）
参数：
- currentPage：当前页面实例（可为 null）
返回：当前路由对象或 null（获取失败时）

Hooks

`useMxRouter` 用于管理 `Router` 组件实例并提供操作方法

注意：该 Hook 只支持 vue3 版本

<template>
	<mx-router @register="register">首页</mx-router>
</template>

<script setup lang="ts">
import { useMxRouter } from '@meng-xi/uni-router'

const [register, methods] = useMxRouter({
	to: '/pages/index/index'
})
</script>

参数

属性	描述	类型	默认值
to	路由地址	RouterLinkProps	-
method	跳转方式	'push' \| 'replace' \| 'tab' \| 'launch' \| 'back' \| 'exit'	'push'
delta	回退层数	number	-
animationType	窗口动画类型	UniApp.NavigateToOptions['animationType'] & UniApp.NavigateBackOptions['animationType']	pop-in/out
animationDuration	动画持续时间	number	300
renderLink	是否给 navigator 组件加一层 a 标签控制 ssr 渲染	boolean	true
hoverClass	自定义悬停样式类名	string	'none'
hoverStopPropagation	指定是否阻止本节点的祖先节点出现点击态	boolean	false
hoverStartTime	按住后多久出现点击态，单位毫秒	number	50
hoverStayTime	手指松开后点击态保留时间，单位毫秒	number	600
target	在哪个小程序目标上发生跳转，值域 self/miniProgram	string	'self'

组件

配置

建议使用 easycom 来简化组件的引入和注册

NPM

// pages.json
{
	"easycom": {
		"custom": {
			"^mx-(.*)": "@meng-xi/uni-router/components/$1/$1.vue"
		}
	}
}

HBuilderX

如果你是通过插件市场导入到 HBuilderX 的，需要修改一下组件路径

// pages.json
{
	"easycom": {
		"custom": {
			"^mx-(.*)": "@/js_sdk/PedroQue99-router/PedroQue99-router/components/$1/$1.vue"
		}
	}
}

配置全局组件类型

在 vscode 中使用时，为了有组件的类型提示和自动填充，需要配置全局组件类型声明。

// tsconfig.json
{
	"compilerOptions": {
		"types": ["@meng-xi/uni-router/components/index"]
	}
}

如果是使用 WebStorm，可能需要在 main.ts 文件中导入 index.d.ts 文件。

// main.ts
import '@meng-xi/uni-router/components/index.d.ts'

Router 组件

介绍

Router 组件用于在应用中进行路由导航。它提供了一种声明式的方式来定义路由链接和导航行为。

引入

import Router from '@meng-xi/uni-router/components/router/router.vue'

基础用法

<template>
	<mx-router to="/pages/index/index">首页</mx-router>
</template>

API

RouterProps

属性	描述	类型	默认值
to	路由地址	RouterLinkProps	-
method	跳转方式	'push' \| 'replace' \| 'tab' \| 'launch' \| 'back' \| 'exit'	'push'
delta	回退层数	number	-
animationType	窗口动画类型	UniApp.NavigateToOptions['animationType'] & UniApp.NavigateBackOptions['animationType']	pop-in/out
animationDuration	动画持续时间	number	300
renderLink	是否给 navigator 组件加一层 a 标签控制 ssr 渲染	boolean	true
hoverClass	自定义悬停样式类名	string	'none'
hoverStopPropagation	指定是否阻止本节点的祖先节点出现点击态	boolean	false
hoverStartTime	按住后多久出现点击态，单位毫秒	number	50
hoverStayTime	手指松开后点击态保留时间，单位毫秒	number	600
target	在哪个小程序目标上发生跳转，值域 self/miniProgram	string	'self'

RouterSlots

插槽	描述	属性
default	自定义默认内容	-

错误处理

MxRouterError类提供以下静态方法创建错误实例：

`navigationAborted`

static navigationAborted(): MxRouterError

用途：创建导航中止错误（用于前置守卫拦截场景）
返回：导航中止错误实例

`navigationRedirect`

static navigationRedirect(location: string | RouteLocationRaw): MxRouterError

用途：创建导航重定向错误（用于路由重定向场景）
参数：
- location：重定向目标位置
返回：导航重定向错误实例

`navigationFailed`

static navigationFailed(message: string): MxRouterError

用途：创建导航失败错误（用于导航异常场景）
参数：
- message：错误描述信息
返回：导航失败错误实例

`invalidMethod`

static invalidMethod(method: string): MxRouterError

用途：创建无效方法错误（用于调用非法导航方法场景）
参数：
- method：无效的方法名称
返回：无效方法错误实例

来源：https://www.cnblogs.com/PedroQue99/p/19004633