uni-router:现代化uni-app路由解决方案

// 路径字符串await router.push('/pages/about/about')// 路径对象 + 查询参数await router.push({ path: '/pages/about/about', query: { id: '1' } })// 命名路由await router.push({ name: 'about' })// 带动画参数（仅 App 端生效）await router.push({ path: '/pages/about/about', animation: { type: 'slide-in-bottom', duration: 500 } })// 带页面间通信const result = await router.push({	path: '/pages/about/about',	events: {// 监听目标页面通过 eventChannel.emit 发送的事件receiveData: (data) => { console.log('收到数据:', data) }}})// 通过 eventChannel 向目标页面发送事件result.eventChannel?.emit('fromOpener', { msg: '你好' })

await router.replace('/pages/login/login')await router.replace({ name: 'home' })

// 路径字符串await router.relaunch('/pages/index/index')// 命名路由 + 查询参数await router.relaunch({ name: 'login', query: { redirect: '/about' } })

await router.back() // 返回上一页await router.back(2) // 返回两级await router.back(1, { type: 'slide-out-left' }) // 指定动画

// 发起页const result = await router.push({	path: '/pages/detail/detail',	query: { id: '1' },	events: {// 监听目标页面 emit 的事件acceptData: (data) => {console.log('收到详情页数据:', data)},// 监听详情页的编辑完成通知editComplete: (data) => {console.log('编辑完成:', data)// 刷新列表等操作}}})// 通过 eventChannel 向目标页面发送事件result.eventChannel?.emit('initData', { msg: '来自发起页的初始数据' })

// 目标页（detail）export default {onLoad() {const eventChannel = this.getOpenerEventChannel()// 监听发起页发来的事件		eventChannel.on('initData', (data) => {console.log('收到初始数据:', data)})// 向发起页发送数据		eventChannel.emit('acceptData', { msg: '详情页已加载' })},	methods: {onSave() {const eventChannel = this.getOpenerEventChannel()// 通知发起页编辑完成			eventChannel.emit('editComplete', { id: 1, action: 'saved' })}}}

<template>	<mxuni-router		:to="{ path: '/pages/detail/detail', query: { id: '1' } }"		:events="{ acceptData: (data) => onAcceptData(data) }"		@navigated="onNavigated"		@error="onNavError"	>		<view>跳转到详情页</view>	</mxuni-router></template><scriptsetup>function onAcceptData(data) {	console.log('收到详情页数据:', data)}function onNavigated(eventChannel) {	// 导航成功后，通过 eventChannel 向目标页面发送事件	eventChannel?.emit('initData', { msg: '来自 RouterLink 的初始数据' })}function onNavError(error) {	console.log('导航失败:', error.code)}</script>

interfaceEventChannel{/** 监听事件，每次 emit 都会触发 */on(event: string, callback: (...args: any[]) => void): EventChannel/** 监听事件，仅触发一次后自动移除 */once(event: string, callback: (...args: any[]) => void): EventChannel/** 取消监听事件 */off(event: string, callback?: (...args: any[]) => void): EventChannel/** 触发事件 */emit(event: string, ...args: any[]): EventChannel}

router.beforeEach((to, from, next) => {if(to.meta.requireAuth && !isLoggedIn()) {next({ name: 'login', query: { redirect: to.fullPath } })} else {next()}})

router.beforeResolve((to, from, next) => {// 所有前置守卫已通过，导航即将执行next()})

router.afterEach((to, from) => {if (to.meta.title) {		uni.setNavigationBarTitle({ title: to.meta.title as string })}})

const routes = [{		path: 'pages/admin/admin',		name: 'admin',		meta: { requireAuth: true },beforeEnter: (to, from, next) => {if (isAdmin()) next()else next({ name: 'forbidden' })}}]

const routes = [{		path: 'pages/admin/admin',		name: 'admin',		beforeEnter: [checkAuth, checkAdmin]}]

beforeEach → beforeEnter → beforeResolve → 导航执行 → afterEach

router.beforeEach((to, from, next) => {if (to.meta.requireAuth && !isLoggedIn()) {next({ name: 'login' }) // 重定向到登录页} else {next()}})

const router = createRouter({	routes,	guardTimeout: 15000 // 15 秒超时})

const removeGuard = router.beforeEach((to, from, next) => {// 临时守卫逻辑next()})// 不再需要时移除removeGuard()

// 路由配置const routes = [{ path: 'pages/index/index', name: 'home', meta: { isTab: true } },{ path: 'pages/about/about', name: 'about', meta: { title: '关于' } }]// 导航时使用名称await router.push({ name: 'about', query: { id: '1' } })

interface RouteMeta {	title?: string // 页面标题	isTab?: boolean // 是否为 TabBar 页面	requireAuth?: boolean // 是否需要登录认证	animation?: NavigationAnimation // 默认导航动画（仅 App 端）[key: string]: unknown // 自定义扩展字段}

const routes = [{ path: 'pages/index/index', name: 'home', meta: { isTab: true, title: '首页' } },{ path: 'pages/about/about', name: 'about', meta: { animation: { type: 'fade-in' } } },{ path: 'pages/admin/admin', name: 'admin', meta: { requireAuth: true } }]

interface NavigationAnimation {	type: UniAnimationType // 动画类型	duration?: number // 持续时间（ms），默认 300}

await router.push({ path: '/pages/about/about', animation: { type: 'slide-in-bottom' } })await router.back(1, { type: 'slide-out-left', duration: 500 })

const routes = [{ path: 'pages/about/about', name: 'about', meta: { animation: { type: 'fade-in' } } }]

<RouterLinkto="/pages/about/about":animation="{ type: 'slide-in-bottom' }">  底部滑入</RouterLink>

push/replace/back 调用时传入 > meta.animation > uni 默认值

const router = createRouter({	routes,	interceptUniApi: true // 拦截 uni.navigateTo 等原生 API})

// 这两种方式等价，都会经过守卫链uni.navigateTo({ url: '/pages/about/about' })router.push('/pages/about/about')

import { useRouter } from '@meng-xi/uni-router'const router = useRouter()await router.push('/pages/about/about')

import { useRoute } from '@meng-xi/uni-router'const route = useRoute()// route 是 Ref<RouteLocation>，路由变化时自动更新console.log(route.value.path)console.log(route.value.query)

export default {	methods: {goToAbout() {this.route.path}}}

<template>	<!-- 路径跳转 -->	<RouterLinkto="/pages/about/about">关于页面</RouterLink>	<!-- 命名路由 + 替换模式 -->	<RouterLink:to="{ name: 'about' }"replace>替换导航</RouterLink>	<!-- relaunch 模式（关闭所有页面并打开目标页面） -->	<RouterLinkto="/pages/index/index"relaunch>返回首页</RouterLink>	<!-- 带动画参数 -->	<RouterLinkto="/pages/about/about":animation="{ type: 'fade-in' }">淡入动画</RouterLink>	<!-- 带页面间通信 -->	<RouterLink		:to="{ path: '/pages/detail/detail', query: { id: '1' } }"		:events="{ acceptData: (data) => console.log(data) }"		@navigated="onNavigated"		@error="onNavError"	>		跳转并通信	</RouterLink></template><scriptsetup>import { RouterLink } from '@meng-xi/uni-router/components/RouterLink.vue'function onNavigated(eventChannel) {	// 向目标页面发送事件	eventChannel?.emit('initData', { msg: '来自 RouterLink' })}function onNavError(error) {	console.log('导航失败:', error.code)}</script>

// 在每个页面的 onShow 生命周期中调用import { onShow } from '@dcloudio/uni-app'import { useRouter } from '@meng-xi/uni-router'const router = useRouter()onShow(() => {	router.syncRoute()})

router.onRouteChange((to, from) => {console.log(`路由变化: {to.path}`)})

// RouterError — 路由错误基类classRouterErrorextendsError{readonly code: RouterErrorCode}// NavigationFailure — 导航失败，包含来源和目标信息classNavigationFailureextendsRouterError{readonly to: RouteLocationreadonly from: RouteLocationreadonly cause?: unknown}

router.onError((error, to, from) => {if (error.code === 'NAVIGATION_ABORTED') {console.log('导航被中止')}})

const removeHandler = router.onError((error, to, from) => {// 错误处理})removeHandler() // 移除此处理器

// 路由名称自动补全router.push({ name: 'pagesIndexIndex' }) // ✅ 自动补全router.push({ name: 'invalidName' }) // ❌ 类型错误// 路径自动补全router.push({ path: '/pages/index/index' }) // ✅ 自动补全router.push({ path: '/invalid/path' }) // ❌ 类型错误

declare module '@meng-xi/uni-router' {interface RouteNameMap {		pagesIndexIndex: { path: '/pages/index/index'; meta: { title: string; isTab: true } }		pagesAboutAbout: { path: '/pages/about/about'; meta: { title: string } }}}

pnpm add @meng-xi/uni-router

// src/router.config.tsimport type { RouteConfig } from '@meng-xi/uni-router'const routes: RouteConfig[] = [{ path: 'pages/index/index', name: 'home', meta: { isTab: true, title: '首页' } },{ path: 'pages/about/about', name: 'about', meta: { title: '关于' } },{ path: 'pages/login/login', name: 'login', meta: { title: '登录' } },{ path: 'pages/admin/admin', name: 'admin', meta: { requireAuth: true } }]export default routes

// src/main.tsimport { createSSRApp } from 'vue'import { createRouter } from '@meng-xi/uni-router'import routes from './router.config'import App from './App.vue'const router = createRouter({	routes,	strict: true,	interceptUniApi: true,	guardTimeout: 15000})// 注册全局守卫router.beforeEach((to, from, next) => {if (to.meta.requireAuth && !isLoggedIn()) {next({ name: 'login' })} else {next()}})router.afterEach(to => {if (to.meta.title) {		uni.setNavigationBarTitle({ title: to.meta.title as string })}})export function createApp() {const app = createSSRApp(App)	app.use(router)return { app }}

<template>	<view>		<text>当前路径: {{ route.path }}</text>		<button @click="goAbout">跳转关于</button>		<button @click="goAboutWithEvent">跳转并通信</button>		<button @click="goBack">返回</button>	</view></template><scriptsetup>import { useRouter, useRoute } from '@meng-xi/uni-router'const router = useRouter()const route = useRoute()async function goAbout() {	try {		await router.push({ name: 'about', query: { from: 'home' } })	} catch (e) {		console.log('导航失败:', e.code)	}}async function goAboutWithEvent() {	const result = await router.push({		path: '/pages/about/about',		events: {			replyFromAbout: (data) => {				console.log('收到关于页回复:', data)			}		}	})	// 向关于页发送消息	result.eventChannel?.emit('fromHome', { msg: '你好，关于页！' })}async function goBack() {	await router.back()}</script>