uni-app实现vue-router开发体验

# npm 包方式pnpm add @meng-xi/uni-router# 或使用 uni_modules# 将 mxuni-router 目录复制到项目的 uni_modules 目录下

// src/router/index.tsimport { createRouter } from '@meng-xi/uni-router'const router = createRouter({	routes: [{ path: 'pages/index/index', name: 'home', meta: { title: '首页', isTab: true } },{ path: 'pages/about/about', name: 'about', meta: { title: '关于' } },{ path: 'pages/user/user', name: 'user', meta: { title: '我的', isTab: true } },{ path: 'pages/detail/detail', name: 'detail', meta: { title: '详情', requireAuth: true } },{ path: 'pages/login/login', name: 'login', meta: { title: '登录' } }],	strict: true, // 严格模式，未匹配的命名路由将抛出异常	interceptUniApi: true, // 拦截 uni 原生导航 API，确保守卫始终生效	guardTimeout: 10000 // 守卫超时保护（毫秒），防止导航永久挂起})export default router

// main.tsimport { createSSRApp } from 'vue'import App from './App.vue'import router from './router'export function createApp() {const app = createSSRApp(App)	app.use(router)return { app }}

import { useRouter, useRoute } from '@meng-xi/uni-router'const router = useRouter()const route = useRoute()// 路径字符串导航await router.push('/pages/about/about')// 命名路由导航await router.push({ name: 'detail', query: { id: '1' } })// 替换当前页面await router.replace({ name: 'login' })// 返回上一页await router.back()// 读取当前路由信息console.log(route.value.path) // '/pages/detail/detail'console.log(route.value.query) // { id: '1' }console.log(route.value.meta) // { title: '详情', requireAuth: true }

// 自动使用 uni.switchTab（因为 meta.isTab = true）await router.push({ name: 'home' })// 自动使用 uni.navigateTo（普通页面）await router.push({ name: 'detail', query: { id: '1' } })

// 路径字符串router.push('/pages/about/about?id=1')// 路径对象router.push({ path: '/pages/about/about', query: { id: '1' } })// 命名对象router.push({ name: 'about', query: { id: '1' } })

导航触发  ↓全局前置守卫 beforeEach  ↓路由独享守卫 beforeEnter  ↓全局解析守卫 beforeResolve  ↓执行 uni 导航 API  ↓全局后置钩子 afterEach

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

const router = createRouter({	routes: [{			path: 'pages/admin/admin',			name: 'admin',			meta: { title: '管理后台' },beforeEnter: (to, from, next) => {if (isAdmin()) next()else next({ name: 'home' })}}]})

beforeEnter: [checkAuth, checkPermission]

router.beforeResolve(async (to, from, next) => {// 所有守卫已通过，可以安全地做数据预取await prefetchData(to)next()})

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

const router = createRouter({  routes: [...],  guardTimeout: 10000, // 10 秒超时（默认值），设为 0 可禁用})

[uni-router] Navigation guard "checkPermission" did not resolve within 10s. Make sure to call next() in your guard function.

const removeGuard = router.beforeEach((to, from, next) => {// 一次性守卫next()removeGuard() // 执行后立即移除})

// 定义{ path: 'pages/detail/detail', name: 'detail' }// 使用router.push({ name: 'detail', query: { id: '1' } })

{ path: 'pages/detail/detail', name: 'detail', meta: { title: '详情', requireAuth: true } }

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

const router = createRouter({  routes: [...],  interceptUniApi: true, // 启用拦截})

// 这两种写法效果相同，都会经过守卫链uni.navigateTo({ url: '/pages/about/about' })router.push('/pages/about/about')

// 每个页面的 onShow 中调用onShow(() => {	router.syncRoute()})

router.onRouteChange((to, from) => {// 导航完成和 syncRoute 同步都会触发	analytics.track('page_view', { from: from.path, to: to.path })})

router.onRouteChange((to, from) => {if (!to._synced) {// 真正的导航，记录页面浏览		analytics.track('page_view', { path: to.path })}// 状态同步（如物理返回键），仅更新 UI 状态updateActiveTab(to.path)})

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

import { useRoute } from '@meng-xi/uni-router'const route = useRoute()// 在模板中直接使用// {{ route.path }}// {{ route.query.id }}// {{ route.meta.title }}

<view>当前路径：{{ router.back()">返回</button>

<mxuni-routerto="/pages/about/about"><view>关于我们</view></mxuni-router><!-- 命名路由 --><mxuni-router:to="{ name: 'detail', query: { id: '1' } }"><view>查看详情</view></mxuni-router><!-- 替换模式 --><mxuni-routerto="/pages/login/login"replace><view>登录</view></mxuni-router><!-- 导航失败处理 --><mxuni-routerto="/pages/protected/index"@error="onNavError"><view>需要登录的页面</view></mxuni-router>

router.onError((error, to, from) => {if (error.code === 'NAVIGATION_ABORTED') {		uni.showToast({ title: '导航被拦截', icon: 'none' })}if (error.code === 'NAVIGATION_API_ERROR') {		uni.showToast({ title: '页面跳转失败', icon: 'none' })}// 上报错误trackError(error, to, from)})

try {await router.push({ name: 'detail', query: { id: '1' } })} catch (error) {if (error.code === 'NAVIGATION_DUPLICATED') {// 已在详情页，忽略}}

const location = router.resolve({ name: 'detail', query: { id: '1' } })// { path: '/pages/detail/detail', name: 'detail', meta: { ... }, query: { id: '1' }, fullPath: '/pages/detail/detail?id=1' }

if (router.hasRoute('admin')) {// 路由存在}

const routes = router.getRoutes()

// env.d.tsdeclare module '@meng-xi/uni-router' {interface RouteNameMap {		home: { path: '/pages/index/index'; meta: { title: string; isTab: true } }		about: { path: '/pages/about/about'; meta: { title: string } }		detail: { path: '/pages/detail/detail'; meta: { title: string; requireAuth: boolean } }}}

router.push({ name: 'detail' }) // ✅ 自动补全router.push({ name: 'detial' }) // ❌ 类型错误

export type {	RouteNameMap,	RouteName,	RoutePath,	RouteMeta,	RouteConfig,	RouteLocation,	RouteLocationPathRaw,	RouteLocationNamedRaw,	RouteLocationRaw,	NavigationGuardNext,	NavigationGuard,	PostNavigationGuard,	RouterOnError,	RouterOptions,	Router}export { RouterErrorCode }export { RouterError, NavigationFailure }

await router.isReady()// 路由器已就绪，可以安全访问 currentRoute

// src/router/index.tsimport { createRouter } from '@meng-xi/uni-router'const router = createRouter({	routes: [{ path: 'pages/index/index', name: 'home', meta: { title: '首页', isTab: true } },{ path: 'pages/about/about', name: 'about', meta: { title: '关于' } },{ path: 'pages/user/user', name: 'user', meta: { title: '我的', isTab: true } },{ path: 'pages/detail/detail', name: 'detail', meta: { title: '详情', requireAuth: true } },{ path: 'pages/login/login', name: 'login', meta: { title: '登录' } },{			path: 'pages/admin/admin',			name: 'admin',			meta: { title: '管理后台', requireAuth: true, requireAdmin: true },beforeEnter: (to, from, next) => {if (isAdmin()) next()else next({ name: 'home' })}}],	strict: true,	interceptUniApi: true,	guardTimeout: 10000})// 全局前置守卫：登录拦截router.beforeEach(async (to, from, next) => {if (to.meta.requireAuth && !isLoggedIn()) {next({ name: 'login', query: { redirect: to.fullPath } })} else {next()}})// 全局解析守卫：数据预取router.beforeResolve(async (to, from, next) => {if (to.name === 'detail' && to.query.id) {await prefetchDetail(to.query.id)}next()})// 全局后置钩子：页面标题router.afterEach(to => {if (to.meta.title) {		uni.setNavigationBarTitle({ title: to.meta.title as string })}})// 路由变化监听：埋点router.onRouteChange((to, from) => {if (!to._synced) {		analytics.track('page_view', { from: from.path, to: to.path })}})// 全局错误处理router.onError(error => {console.error('[Router Error]', error.code, error.message)})export default router