更新记录

1.1.0（2026-06-28） 下载此版本

v1.1.0 (2025-06-28)

新增

• 多条件链式守卫（MultiConditionGuard）
  • 支持按顺序检查多个用户状态
  • 遇到未通过条件立即拦截并引导用户
  • 支持自定义弹窗事件触发
  • 可为不同页面配置不同条件组合
• 用户状态检查器（UserStateChecker）
  • 完全可扩展的状态检查系统
  • 不预设业务状态类型，由使用者自定义
  • 支持链式检查多个状态
• 智能参数解析（smartParseValue）
  • URL 参数自动类型转换
  • 支持数字、布尔值、null、undefined 转换
• 完整 API 文档
  • 模块导出列表
  • 工具函数导出
  • 常量导出
• 多条件守卫详细文档（docs/MULTI_CONDITION_GUARD.md）

优化

• 路由对象结构优化
  • 添加 source 字段标识导航来源
  • query 参数支持智能类型转换
  • 添加 params 字段（预留动态路由支持）
• 配置读取器增强（PagesJsonReader）
  • 支持 tabBar 页面检测
  • 支持页面是否存在检查
  • 支持配置刷新
• 路由匹配器增强（RouteMatcher）
  • 支持动态添加/移除路由
  • 支持路由存在检查
  • 预留动态路由匹配扩展点

特性

• 自动读取 pages.json 配置
• 零侵入 uni API 拦截
• 完整的路由元信息支持
• 导航队列防止并发
• H5 平台 popstate 监听
• App 平台物理返回键监听
• 小程序页面栈限制检测
• Promise 异步守卫支持

平台兼容性

uni-app(4.61)

jz-route-guard

uni-app 路由守卫插件，提供类似 vue-router 的导航守卫功能，支持 App、小程序、H5 多端。

核心特性

• 自动读取路由配置：直接从 pages.json 读取路由，无需额外配置路由文件
• 完整的导航守卫：支持全局守卫、路由独享守卫、组件内守卫
• 多条件链式守卫：支持链式检查多个用户状态，适用于多步骤认证流程
• 多端兼容：App、小程序、H5 三端统一 API
• 纯 JS 实现：基于 Class 语法，无框架依赖
• 零侵入：通过拦截 uni 路由 API 实现守卫功能
• 组合式 API：提供 useRoute、useRouter、useRouteGuard、useLeaveGuard
• Promise 支持：守卫函数支持 async/await 和 Promise 返回
• 智能参数解析：自动转换 URL 参数类型（数字、布尔值等）

安装

在 main.js 中安装插件：

import { createSSRApp } from 'vue'
import App from './App.vue'
import RouterGuard, { getRouterGuard } from '@/uni_modules/jz-route-guard'

export function createApp() {
  const app = createSSRApp(App)

  // 安装路由守卫插件
  app.use(RouterGuard)

  // 配置全局守卫
  const router = getRouterGuard()

  // 全局前置守卫
  router.beforeEach((to, from, next) => {
    console.log('即将跳转:', to.path)
    next()
  })

  // 全局后置守卫
  router.afterEach((to, from) => {
    console.log('跳转完成:', to.path)
  })

  return { app }
}

使用方式

1. 全局守卫

import { getRouterGuard } from '@/uni_modules/jz-route-guard'

const router = getRouterGuard()

// 前置守卫
router.beforeEach((to, from, next) => {
  const token = uni.getStorageSync('token')
  if (to.meta.requiresAuth && !token) {
    next({ path: '/pages/login/login' })
  } else {
    next()
  }
})

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

// 支持 async/await
router.beforeEach(async (to, from, next) => {
  const hasPermission = await checkUserPermission(to.path)
  if (!hasPermission) {
    next(false)
  } else {
    next()
  }
})

2. 路由独享守卫

在 pages.json 中配置：

{
  "pages": [
    {
      "path": "pages/user/user",
      "style": {
        "navigationBarTitleText": "用户中心",
        "meta": {
          "requiresAuth": true,
          "beforeEnter": "checkAuth"
        }
      }
    }
  ]
}

注册命名守卫：

router.registerNamedGuard('checkAuth', (to, from, next) => {
  const token = uni.getStorageSync('token')
  if (!token) {
    next({ path: '/pages/login/login' })
  } else {
    next()
  }
})

3. 组件内守卫

使用组合式 API：

<script setup>
import { ref } from 'vue'
import { useLeaveGuard } from '@/uni_modules/jz-route-guard'

const formDirty = ref(false)

// 离开守卫
useLeaveGuard((to, from, next) => {
  if (formDirty.value) {
    uni.showModal({
      title: '提示',
      content: '表单未保存，确认离开？',
      success: (res) => {
        next(res.confirm)
      }
    })
  } else {
    next()
  }
})
</script>

使用 Options API（通过混入）：

<script>
import { RouteGuardMixin } from '@/uni_modules/jz-route-guard'

export default {
  mixins: [RouteGuardMixin],
  beforeRouteLeave(to, from, next) {
    if (this.formDirty) {
      uni.showModal({
        title: '提示',
        content: '表单未保存，确认离开？',
        success: (res) => {
          next(res.confirm)
        }
      })
    } else {
      next()
    }
  }
}
</script>

4. 组合式 API

<script setup>
import { useRoute, useRouter } from '@/uni_modules/jz-route-guard'

const route = useRoute()
const router = useRouter()

// 获取当前路由信息
console.log('当前路径:', route.value.path)
console.log('查询参数:', route.value.query)
console.log('路由元信息:', route.value.meta)

// 导航方法
const goUser = () => router.push('/pages/user/user', { id: 123 })
const goBack = () => router.back()
const replacePage = () => router.replace('/pages/home/home')
</script>

5. 多条件链式守卫

适用于需要多步骤认证的功能页面（如 VIP专区、金融功能等）：

import { getMultiConditionGuard, getUserStateChecker } from '@/uni_modules/jz-route-guard'

// 1. 定义状态类型（业务层自定义）
const UserStateType = {
  REAL_NAME: 'realName',
  PERSONAL_AUTH: 'personalAuth',
  PROFILE: 'profile'
}

// 2. 注册状态检查器
const checker = getUserStateChecker()
checker.registerChecker(UserStateType.REAL_NAME, {
  check: () => uni.getStorageSync('realNameVerified') === true,
  redirectPath: '/pages/auth/real-name-auth',
  title: '实名认证',
  message: '该功能需要完成实名认证，是否前往认证？'
})

checker.registerChecker(UserStateType.PERSONAL_AUTH, {
  check: () => uni.getStorageSync('personalAuthVerified') === true,
  redirectPath: '/pages/auth/personal-auth',
  title: '本人认证',
  message: '该功能需要完成本人认证，是否前往认证？'
})

// 3. 配置页面条件
const multiGuard = getMultiConditionGuard()
multiGuard.setPageConditions('/pages/vip/vip-content', [
  UserStateType.REAL_NAME,
  UserStateType.PERSONAL_AUTH
])

// 4. 在全局守卫中使用
router.beforeEach(multiGuard.createGuard())

详细使用说明请参考 多条件守卫文档。

API 文档

全局方法

RouterGuard 实例方法

RouteMatcher 方法

PagesJsonReader 方法

MultiConditionGuard 方法

UserStateChecker 方法

组合式 API

useRouter 导航方法

工具函数

路由对象

{
  type: 'navigateTo',           // 导航类型
  path: '/pages/user/user',     // 页面路径
  fullPath: '/pages/user/user?id=123', // 完整路径（含参数）
  params: {},                   // 路由参数（暂不支持）
  query: { id: 123 },           // 查询参数（智能类型转换）
  meta: { requiresAuth: true }, // 路由元信息
  matched: RouteRecord,         // 匹配的路由记录
  source: 'api'                 // 导航来源：api/popstate/gesture/user
}

导航来源类型

配置选项

{
  enable: true,           // 是否启用守卫
  enableGlobal: true,     // 是否启用全局守卫
  enableRouteGuard: true, // 是否启用路由独享守卫
  enableComponent: true   // 是否启用组件内守卫
}

平台支持

模块导出

// 组合式 API
export { useRouteGuard, useRoute, useRouter, useLeaveGuard }

// 混入
export { RouteGuardMixin }

// 核心模块
export { RouterGuard, RouteRecord, NavigationGuard, RouteMatcher }
export { PagesJsonReader, getPagesJsonReader }
export { MultiConditionGuard, getMultiConditionGuard }
export { UserStateChecker, getUserStateChecker }

// 工具函数
export { normalizePath, parseUrl, buildUrl, getCurrentPath, getPreviousPath }
export { smartParseValue, deepClone, merge }
export { getPlatform, isH5, isApp, isMiniProgram, isApiAvailable, getPlatformInfo }

// 常量
export { ROUTE_METHODS, GUARD_TYPES, NAVIGATION_SOURCE, PLATFORM_TYPES }
export { DEFAULT_CONFIG, ROUTER_GUARD_KEY, ROUTE_META_KEY }

// 全局方法
export { install, getRouterGuard }
export default { install, RouterGuard, version }

注意事项

1. 导航队列：插件内置导航队列，防止并发导航导致状态混乱
2. H5 后退：通过 popstate 监听 + history.forward 撤销实现后退拦截
3. 小程序栈限制：自动检测页面栈是否达到上限（10层）
4. 智能参数：URL 参数自动转换类型（'123' → 123, 'true' → true）
5. 业务无关：多条件守卫不预设任何业务状态，完全由使用者定义

License

MIT