更新记录

1.0.1（2026-07-15） 下载此版本

更新文档

1.0.0（2026-07-15） 下载此版本

uni-app x 路由插件，类似 vue-router 的 API，纯 UTS 实现

平台兼容性

uni-app x(4.87)

wp-router

uni-app x 路由插件，提供类似 vue-router 的开发体验，语法完全兼容 UTS。

安装

插件已位于 uni_modules/wp-router 目录下，直接使用即可。

快速开始

1. 创建路由实例（推荐自动生成）

npm run gen-router

自动读取 pages.json（含 tabBar、requiresAuth 等 meta 字段）生成 router/router.uts，也可手动创建：

import { WpRouter } from '@/uni_modules/wp-router'

const router = new WpRouter({
    routes: [
        { path: '/pages/index/index', name: 'home', meta: { title: '首页', requiresAuth: false, isTabBar: true } as UTSJSONObject },
        { path: '/pages/user/login', name: 'login', meta: { title: '登录', requiresAuth: false } as UTSJSONObject },
        { path: '/pages/user/profile', name: 'profile', meta: { title: '个人中心', requiresAuth: true } as UTSJSONObject },
        { path: '/pages/goods/detail', name: 'goodsDetail', meta: { title: '商品详情', requiresAuth: false } as UTSJSONObject },
    ]
})

export default router

2. 在页面中使用

import router from '@/router/router'

// 按路径跳转
router.push({ path: '/pages/user/login' })

// 按名称跳转（带查询参数）
router.push({
    name: 'goodsDetail',
    query: { goodsId: '12345' } as UTSJSONObject
})

// 替换当前页面
router.replace({ path: '/pages/user/profile' })

// 切换到 tab 页面
router.switchTab({ path: '/pages/index/index' })

// 智能跳转：自动根据 meta.isTabBar 选择 switchTab / push
router.to({ name: 'home' })          // tabBar 页面 → switchTab
router.to({ name: 'goodsDetail' })   // 非 tabBar 页面 → push

// 返回上一页
router.back()
router.back(2)

// 获取当前路由信息
const route = router.currentRoute
console.log(route.path)
console.log(route.query.get('goodsId'))

3. 导航守卫（建议在 router/guards.uts 中注册）

import router from '@/router/router'

// 前置守卫
router.beforeEach((to, from, next) => {
    if (to.meta.get('requiresAuth') == true) {
        const token = getToken() // 检查登录状态
        if (token == null) {
            router.to({ name: 'login' }) // 直接跳转登录页
            return                        // 不调用 next，原始导航挂起
        }
    }
    next(null) // 放行
})

// 后置钩子
router.afterEach((to, from) => {
    console.log('导航完成:', to.path)
})

然后在 App.uvue 的 <script> 顶部引入一次即可生效：

import '@/router/guards'

API

WpRouter

WpRouteLocation

WpRoute

自动生成路由

通过 scripts/gen-router.js 脚本读取 pages.json 自动生成路由配置：

# 手动生成
npm run gen-router

# 监听 pages.json 变更，自动重新生成
npm run gen-router:watch

脚本自动提取 pages.json 中 style 下所有非 uni-app 内置字段到路由 meta 中，自动标记 tabBar 页面（isTabBar: true），requiresAuth 未定义时默认 false。

注意事项

1. WpRouteLocation.query 和 params 使用 UTSJSONObject 类型，设置时需用 as UTSJSONObject 断言
2. 路由守卫的 next() 不传参则放行，传入 WpRouteLocation 则重定向
3. 未在 routes 中注册的路径也可以跳转，但无法获取 meta 信息
4. 内部使用 uni.navigateTo / uni.redirectTo / uni.switchTab / uni.navigateBack 实现导航
5. 推荐使用 router.to() 替代 push/switchTab，由插件自动判断导航方式
6. router.back() 参数 delta 不传则默认返回 1 步