uni-simple-router-v3 功能预览

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

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

无需再将页面定义在 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  
  }  
]

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

<!-- UserSettings.vue -->  
<div>  
  <h1>User Settings</h1>  
  <NavBar />  
  <!-- UserEmailsSubscriptions / UserProfile 将会渲染到这里  -->  
  <simple-router-view />  
  <!-- UserProfilePreview 将会渲染到这里  -->  
  <simple-router-view name="helper" />  
</div>

// 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 组件的模板中，可以使用 <simple-router-view> 组件来显示当前活动的子路由组件：

<!-- AdminLayout.vue -->  
<template>  
  <div>  
    <sidebar></sidebar>  
    <main>  
      <simple-router-view></simple-router-view>  
    </main>  
  </div>  
</template>

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

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

在 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  
<script setup lang="ts">  
  import { onLaunch, onShow, onHide } from "@dcloudio/uni-app";  
  onLaunch(() => {  
    console.log("App Launch");  
  });  
</script>  
<style>  
  @import "animate.css";    
</style>

• 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: [  
      //...  
    ]  
})

• 效果图

<div>
<img src="https://ask.dcloud.net.cn/uploads/article/20230712/db453a8cf74490cc89a224110c32103d.gif" width="342" height="666">
</div>

如需了解更多详细，请查阅官方文档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' }  
  }  
  // 用户已经登录，继续导航  
});

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