uni-app 路由库 uni-simple-router 最优雅的解决方案重磅来袭

uni-simple-router-v3 功能预览

2023年7月11日，uni-simple-router v3 发布了它的第一个版本，带来了对传统uni-app项目结构与模式的重要改变。从此版本开始，您无需再在每次操作中手动定义页面路由，而是统一由插件进行管理。这个改变为您提供了更加便捷和灵活的路由管理方式。此外，uni-simple-router v3 还引入了一系列强大的功能，让您能够在跨平台的环境下充分发挥它的优势，包括动态路由表、嵌套路由和路由守卫等等。下面将详细介绍 uni-simple-router 的主要功能，更多详细信息请参阅官方文档。

V3.X 版本 与 V2.X 版本对比

功能及权益	收费版 (V3版)	开源版 (V2版)
H5非手动导航拦截	✅	✅
H5自定义路径	✅	✅
H5动态路由匹配	✅	✅
H5动态增减路由表	✅	❌
H5多级嵌套路由	✅	❌
H5转场动画引擎	✅	❌
APP启动页面拦截	✅	✅
APP原生tabbar拦截	✅	✅
APP原生返回拦截	✅	✅
APP nvue深度兼容	✅	❌
APP动态路由匹配	✅	❌
APP动态增减路由表	✅	❌
APP多级嵌套路由	✅	❌
小程序启动页面拦截	✅	❌
小程序动态路由匹配	✅	❌
小程序动态增减路由表	✅	❌
小程序多级嵌套路由	✅	❌
响应式路由元对象	✅	❌
Vue3 + Vite 支持	✅	❌
无需管理pages.json	✅	❌
自定义路由表全端通用	✅	❌
全端通用动态权限认证	✅	❌
全端通用重定向	✅	❌
守卫 beforeRouteLeave	✅	✅
守卫 beforeEach	✅	✅
守卫 beforeEnter	✅	✅
守卫 beforeRouteUpdate	✅	❌
守卫 beforeRouteEnter	✅	❌
守卫 beforeResolve	✅	❌
客服支持	✅	❌
实时维护及更新	✅	❌
小程序原生tabbar拦截	❌	❌
小程序原生返回拦截	❌	❌

无需再将页面定义在 pages.json 中

不再为每次添加页面而繁琐地编辑庞大的pages.json文件，也不再为为某个页面添加页面属性而反复查找。uni-simple-router解决了这个问题。您只需要在构建路由时，将对应的路由表和组件的映射关系传递给插件即可。插件会自动处理路由配置，让您的路由管理变得更加简洁和高效。

假设你现在需要注册一个根页面(顶级页面)

传统方式

// pages.json
{
  "pages":[
    "path":"/pages/index/index",
    "style":{

    }
  ]
}

// 跳转
uni.navigateTo(`/pages/index/index`)

// H5 URL 表现
console.log(location.pathname) // ===> 输出：/pages/index/index

插件方式

// pages.json
{
  
}

// router.js
import {
  __dynamicImportComponent__
} from '@/uni-simple-router'

const router = createRouter({
  routes:[{
      path:`/`,
      component:__dynamicImportComponent__(`@/pages/index.vue`,{
        pageType:`top`
      }),
  }]
})

// 跳转
router.push(`/`)

// H5 URL 表现
console.log(location.pathname)  // ===> 输出：/

你还可以传递更复杂的路由表关系，例如嵌套路由表，或者设置根页面风格，及创建动态路由匹配。

创建高级路由匹配

有时我们可能需要在同一个组件下渲染不同ID或身份的数据，这时我们就需要用到高级路由匹配。

// router.js
import {
  __dynamicImportComponent__
} from '@/uni-simple-router'
import {
  unref
} from 'vue'

const router = createRouter({
  routes:[{
      path:`/desc/:id`,
      name:`desc`,
      component:__dynamicImportComponent__(`@/pages/index.vue`,{
        pageType:`top`
      }),
  }]
})

// 跳转
router.push({
  name:`desc`,
  params:{
    id:123
  }
})

// 获取id
unref(router.currentRoute).params

一些简单的匹配

const routes = [
  // 匹配 /home
  { path: '/home', component: Home }, // 静态路径匹配
  // 匹配 /user/3549
  { path: '/user/:id', component: User }, // 动态路由参数匹配
  // 匹配 /product/21312 或者 /product
  { path: '/product/:category?', component: Product }, // 可选参数匹配
  // 匹配 /admin/10086/111 或者 /admin/任何数据
  { path: '/admin/(.*)', component: Admin }, // 通配符匹配
  // 匹配 /posts/sdsad/11222 多个可重复的分组
  { path: '/posts/:id+', component: Posts }, // 可重复参数匹配
  // 匹配 /posts/1111 只匹配数字参数
  { path: '/users/:id(\\d+)', component: Users }, // 正则表达式匹配
]

更多复杂的匹配方式请查考官方文档。

命名视图与命名路由

• 命名视图： 在 uni-simple-router 中，命名视图（Named Views）允许我们在同一个路由中同时渲染多个视图，以实现更灵活和复杂的页面布局。通过命名视图，我们可以在一个页面中定义多个区域，每个区域可以渲染不同的组件或内容。
• 命名路由： 除了为路由提供 path 属性之外，你还可以为任何路由配置一个 name 属性。

定义一个默认的命名视图

// router.js
import {
  __dynamicImportComponent__
} from '@/uni-simple-router'

// 导入组件
const MainContent = __dynamicImportComponent__(`@/pages/mainContent.vue`,{
  pageType:`top`
})

const routes = [
  {
    path: '/dashboard',
    component:MainContent
  }
]

定义多个自定义名的命名视图

  
User Settings
  
  
  
  
  

// router.js
import {
  __dynamicImportComponent__
} from '@/uni-simple-router'

const UserEmailsSubscriptions = __dynamicImportComponent__(`@/pages/UserEmailsSubscriptions.vue`)
const UserProfile =  __dynamicImportComponent__(`@/pages/UserProfile.vue`)
const UserProfilePreview = __dynamicImportComponent__(`@/pages/UserProfilePreview.vue`)

const routes = [
  {
    path: '/settings',
    // 你也可以在顶级路由就配置命名视图
    component: UserSettings,
    children: [
      {
        path: 'emails',
        component: UserEmailsSubscriptions
      }, 
      {
        path: 'profile',
        components: {
          default:UserProfile,
          helper: UserProfilePreview
        }
      }
    ]
  }
]

了解更多细节可以查阅官方文档命名路由，命名视图。

路由表重定向及404捕捉

有时我们需要在用户访问某个路由时，自动将其重定向到另一个指定的路由，这时我们就需要用到 重定向。当用户访问不存在的页面路径时，我们需要给出一个友好的提示，而不是显示空白页面，这时我们就需要用到 404页面捕捉。

• 重定向

//router.js
const routes = [
  {
    path: '/',
    redirect: '/home',
    component:IndexComponent
  },
  {
    path: '/home',
    component: HomeComponent
  }
];

在上述示例中，当用户访问根路径 / 时，会自动重定向到 /home 路由。

• 404页面捕捉

import {
  createRouter,
  type platformRule
} from '@/uni-simple-router'

const router = createRouter({
    platform: process.env.VUE_APP_PLATFORM as platformRule,
    routeNotFound:(to)=>{
        console.log(to)
        return {
            name:`404`,
            query:{
              args:`routeNotFound`
            }
        }
    },
    routes:[{
        path: `/404`,
        name: `404`,
        component: __dynamicImportComponent__('@/components/404.vue',{
          pageType: `top`,
        })
    }]
})

如需了解更多详细，请查阅官方文档重定向及别名，捕捉路由404。

路由组件传参

在子路由中，你可以使用路由表中的 props 配置来自动解析参数，而无需手动获取参数。这种方式可以取代传统的手动获取参数的方式。但需要注意的是，这种自动解析参数的功能只适用于子路由，不适用于顶级页面。

/**
 * 该演示路由为子路由表
 * 为简化示例，移除了父级路由
 */
const routes = [
  {
    path: 'user/:id',
    component: UserComponent,
    props: true,  
  }
]

在 UserComponent 组件中，你可以直接访问 id 参数，它会自动作为组件的 props：

// UserComponent.vue
export default {
  props: ['id'],
  // ...
}

如需了解更多详细，请查阅官方文档路由组件传参。

创建深度嵌套路由

要创建嵌套路由，你需要在路由表中使用 children 字段来定义子路由。每个子路由都是一个对象，可以包含 path、component、props 等字段，类似于顶级路由的定义。

下面是一个示例，展示了如何使用嵌套路由创建一个后台管理系统的布局：

// router.js
import {
    __dynamicImportComponent__
} from '@/uni-simple-router'

const routes = [
  {
    path: '/admin',
    component: __dynamicImportComponent__(`@/pages/AdminLayout.vue`,{
      pageType:`top`,
    }),
    children: [
      {
        path: 'dashboard',
        component: __dynamicImportComponent__(`@/pages/DashboardPage.vue`)
      },
      {
        path: 'users',
        component: __dynamicImportComponent__(`@/pages/UsersPage.vue`)
      },
      {
        path: 'settings',
        component: __dynamicImportComponent__(`@/pages/SettingsPage.vue`)
      }
    ]
  }
];

在 AdminLayout 组件的模板中，可以使用 组件来显示当前活动的子路由组件：

如需了解更多详细，请查阅官方文档嵌套路由。

创建权限路由及动态路由表

在 uni-simple-router 中，你可以使用动态路由来实现根据不同的条件生成和注册路由。动态路由允许你根据需要在运行时动态添加、修改或删除路由配置。

• 添加路由

// router.js
const router = createRouter({
  // 其他配置
  routes: [{ path: '/articleName', component: Article }],
})

// 添加路由表
router.addRoute({ path: '/about', component: About })

• 删除路由

router.addRoute({ path: '/about', name: 'about', component: About })
// 删除路由
router.removeRoute('about')

• 添加嵌套路由
  要将嵌套路由添加到现有的路由中，可以将路由的 name 作为第一个参数传递给 router.addRoute()，这将有效地添加路由，就像通过 children 添加的一样：

router.addRoute({ name: 'admin', path: '/admin', component: Admin })
router.addRoute('admin', { path: 'settings', component: AdminSettings })

如需了解更多详细，请查阅官方文档动态路由。

编程式导航及参数处理

• 导航到新地址

import {
  createRouter
} from '@/uni-simple-router'

const router = createRouter({
    platform:process.env.VUE_APP_PLATFORM as platformRule,
    routes:[
      // ...
    ]
})

// 字符串路径
router.push('/users/eduardo')

// 带有路径的对象
router.push({ path: '/users/eduardo' })

// 命名的路由，并加上参数，让路由建立 url
router.push({ name: 'user', params: { username: 'eduardo' } })

// 带查询参数，结果是 /register?plan=private
router.push({ path: '/register', query: { plan: 'private' } })

// 跳转到原生Tabbar
router.pushTab({ name: 'tab1' })

// 关闭所有页面并打开指定页面
router.replaceAll({ name: 'my' })

// 替换当前页面栈并打开新页面
router.replace({ name: 'record' }).then(()=>{
  console.log(`导航完成`)
})

// 返回页面
router.back(1)

• 获取参数

// xxxx.vue 
export default {
  onShow(){
    // 如果你是在 vue 组件内部，你可以直接访问 $Route
    console.log(this.$Route)
  },
}

// xxxx.vue
import { useRoute } from '@/uni-simple-router';
export default {
  setup(){
    // 如果你正在使用 组合API 那么你可以使用 useRoute() 来获取
    const route = useRoute();
    console.log(route)
  },
}

// xxxx.js
/**
 * 如果你正在 js 文件中使用，你可以直接导入你创建的 router 实例
 * 然后访问 currentRoute 属性即可
 */
import { router } from '~@/router';
console.log(router.currentRoute)


// 任何地方
/**
 * 另外你还可以直接访问挂载到uni上的 $Route 属性
 * 它允许你在任何地方使用
 */
const route = uni.$Route
console.log(route)

如需了解更多详细，请查阅官方文档嵌套路由，当前路由信息

H5端转场动画引擎

在 uni-simple-router V3 版本中，默认为 H5 端加载了转场动画引擎，这使得你能够在 H5 端实现类似于 APP 的转场动画效果。转场动画引擎允许你使用任何 CSS3 动画来创建自定义的转场动画效果。

• 安装 animate.css

npm install animate.css --save

• 装载动画效果

// App.vue

• router.js

// router.js
import {
    createRouter,
    type platformRule
} from '@/uni-simple-router'

const router = createRouter({
    platform: process.env.VUE_APP_PLATFORM as platformRule,
    h5: {
        animation: {
            // 什么动作下执行动画
            includeNavtype: [`push`, `back`],
            // 动画时长单位秒
            animationTime: 0.3,
            // 做动画的节点 整个应用都做
            animationAppEl: `#app`,
            // 默认做动画名
            defaultAnimationType:`animate__slideInRight`,
            // 装载的动画库
            animationNodeMap: {
                // 动画名
                'animate__slideInRight': [
                    // 前进时触发的动画
                    [`animate__slideInRight`, `animate__slideOutLeft`],
                    // 后退时触发的动画
                    [`animate__slideInLeft`, `animate__slideOutRight`],
                ],
            }
        }
    },
    routes: [
      //...
    ]
})

• 效果图

如需了解更多详细，请查阅官方文档H5转场动画

导航路由锁

uni-simple-router 提供了导航路由锁的功能，它可以帮助你在特定情况下阻止路由的跳转，以避免在导航过程中再次进行导航。

• 路由错误码

  • 0 表示 在导航守卫中返回了 false 终止了导航
  • 1 表示 在导航守卫中返回 unknownType 不能识别的结果
  • 2 表示 正在导航中，禁止重复导航
  • 3 表示 在获取页面栈的时候，页面栈不够 level 获取
  • 4 表示 本次导航的 name 值在路由表中未找到
  • 5 表示 本次导航的 path 值在路由表中未找到
  • 6 表示 本次导航的 name 及 path 在路由表中未找到
  • 7 表示 app及小程序端缓存的顶级页面 currentRoute 不存在 可能是插件的问题
  • 8 表示 本次导航到了相同的路径下，你可能已经在本路径中
  • 9 表示 h5端动态组件加载失败，可能是网络问题，或者是服务器问题
• 自动解除路由锁

// router.js
const router = createRouter({
  // 其他配置...
  navigateLock:{
    // 默认配置即是如下，无需二次配置
    autoUnlock:[0,1,3,4,5,6,7,8,9]
  },
  // 路由配置...
});

如需了解更多详细，请查阅官方文档导航路由锁

上帝函数之组件之间的通信

在 uni-simple-router 中为解决导航方法中的 events 参数，诞生了上帝函数（God Function）。它是一种更高效的方式来进行页面间的通信。你可以使用它来完成传递参数、调用页面的方法、修改页面的数据等等。

使用上帝函数可以更方便地实现页面间的通信和操作，避免了传统的事件派发和监听的方式，提供了更高效和便捷的页面管理机制。

• parserInstance

// xxxx.js
import {parserInstance} from '@/uni-simple-router'

const result = parserInstance(`dashboard`,[
  // 调用 `SettingsPage.vue` 实例任务
  [
    (instance)=>instance.getData(), `settings`
  ],
  // 调用 `UsersPage.vue` 实例任务
  [
    (instance)=>instance.getData(), `users`
  ],
])
console.log(`执行结果：${result}`)

如需了解更多详细，请查阅官方文档组件之间的通信

路由导航守卫

在 uni-simple-router 中，导航守卫（Navigation Guards）是一组用于控制路由导航的钩子函数。它们可以在路由切换前、切换后以及切换过程中执行一些逻辑操作，用于实现权限控制、全局拦截、页面跳转等功能。

• 全局前置守卫

  • beforeEach

• 全局解析守卫

  • beforeResolve

• 全局后置钩子

  • afterEach

• 路由独享的守卫

  • beforeEnter

• 组件内的守卫

  • beforeRouteEnter
  • beforeRouteUpdate
  • beforeRouteLeave
• 示例

const router = createRouter({ ... })

router.beforeEach((to, from) => {
  // 执行一些全局逻辑操作
  console.log('Before navigation');

  // 进行权限验证或其他操作
  if (!checkUserAuthenticated()) {
    // 用户未登录，重定向到登录页或其他路由
    return { path: '/login' }
  }
  // 用户已经登录，继续导航
});

如需了解更多详细，请查阅官方文档导航守卫