在uniapp引入并使用 VueRouter

'# 在uniapp引入并使用 VueRouter

一、背景与问题

在uniapp开发中，虽然框架本身提供了页面跳转机制（如uni.navigateTo），但随着项目规模扩大，开发者常面临以下问题：

页面间参数传递复杂度高
动态路由管理困难
前后端分离场景下的路由同步需求
带状态的页面导航需求

传统uniapp的页面跳转方式（如uni.navigateTo）虽然简单，但难以满足复杂路由场景。此时引入VueRouter可以实现：

基于URL的路由管理
动态路由参数解析
路由守卫机制
懒加载模块化
历史记录控制

但需要注意uniapp与VueRouter的兼容性问题，以及在小程序环境下的特殊限制。

二、基本原理

VueRouter的工作原理可以分为三个核心部分：

路由表：定义URL路径与组件的映射关系
路由实例：管理路由状态和导航行为
路由组件：动态渲染对应组件

在uniapp中，由于框架本身不支持Vue的<router-view>和<router-link>，需要通过自定义组件实现类似功能。同时，uniapp的页面跳转机制与Vue的路由机制存在差异，需要特殊处理。

三、环境准备

确保项目满足以下条件：

使用uniapp 3.x版本（支持Vue3）
安装依赖：
```
npm install vue-router@4
```

注意：uniapp的manifest.json中需配置easycom模块，以便按需加载组件。

四、核心实现

1. 基础路由配置

创建src/router/index.js文件：

// src/router/index.js
import { createRouter, createWebHashHistory } from 'vue-router'
import Home from '@/pages/Home.vue'
import About from '@/pages/About.vue'

const routes = [
  { path: '/', component: Home },
  { path: '/about', component: About }
]

const router = createRouter({
  history: createWebHashHistory(),
  routes
})

export default router

关键点说明：

使用createWebHashHistory而非createWebHistory，因为小程序环境不支持HTML5 History API
路由组件需使用@/pages/路径（需在manifest.json中配置pages字段）

2. 路由组件封装

创建src/components/RouterView.vue：

<!-- src/components/RouterView.vue -->
<template>
  <view class="router-view">
    <slot />
  </view>
</template>

<script>
export default {
  name: 'RouterView'
}
</script>

3. 页面跳转封装

创建src/utils/router.js：

// src/utils/router.js
import { useRouter } from 'vue-router'
import { uni } from '@dcloudio/uni-app'

export function useRouterHelper() {
  const router = useRouter()
  
  const navigateTo = (path, options) => {
    // 保留原始参数
    const query = new URLSearchParams(window.location.hash.split('?')[1] || '')
    
    // 构造新URL
    const newHash = `/${path}?${Object.entries(options || {})
      .map(([key, value]) => `${key}=${encodeURIComponent(value)}`)
      .join('&')}`
    
    // 更新URL
    window.location.hash = newHash
    
    // 呼叫uni-app的跳转API
    uni.navigateTo({
      url: `/pages/${path}.vue?${query.toString()}`
    })
  }
  
  return {
    navigateTo
  }
}

关键点说明：

组合使用Vue Router的路由控制和uni-app的页面跳转API
通过URL hash实现路由状态同步
保留原始参数防止覆盖

五、完整案例

1. 项目结构

├── pages
│   ├── Home.vue
│   └── About.vue
├── components
│   └── RouterView.vue
├── utils
│   └── router.js
├── App.vue
└── main.js

2. 主程序配置

// src/main.js
import { createApp } from 'vue'
import App from './App.vue'
import router from './router'

createApp(App)
  .use(router)
  .mount('#app')

3. 页面组件示例

<!-- pages/Home.vue -->
<template>
  <view>
    <RouterView />
    <button @click="navigateToAbout">跳转到About</button>
  </view>
</template>

<script>
import { useRouterHelper } from '@/utils/router'

export default {
  setup() {
    const { navigateTo } = useRouterHelper()
    
    const navigateToAbout = () => {
      navigateTo('about', { from: 'home' })
    }
    
    return { navigateToAbout }
  }
}
</script>

4. 路由守卫示例

// src/router/index.js
// ... (之前的代码)

router.beforeEach((to, from, next) => {
  console.log('路由守卫:', to, from)
  
  // 模拟权限验证
  if (to.path === '/about' && !localStorage.getItem('authToken')) {
    uni.showToast({
      title: '未授权',
      icon: 'none'
    })
    next('/login')
  } else {
    next()
  }
})

六、源码解析

1. 路由实例创建

const router = createRouter({
  history: createWebHashHistory(),
  routes
})

createWebHashHistory创建基于hash的路由历史对象
当URL hash变化时，会触发路由更新

2. 路由守卫机制

router.beforeEach((to, from, next) => {
  // 逻辑处理
  next()
})

beforeEach是全局前置守卫
next()控制路由跳转
可以在守卫中进行权限校验、数据预加载等操作

3. 路由参数处理

const query = new URLSearchParams(window.location.hash.split('?')[1] || '')

通过URLSearchParams解析hash中的查询参数
可以获取如from=home等参数

七、进阶使用

1. 动态路由

const routes = [
  { 
    path: '/user/:id', 
    component: UserDetail 
  }
]

在页面中获取参数：

const { id } = useParams()

2. 路由懒加载

const routes = [
  {
    path: '/about',
    component: () => import('@/pages/About.vue')
  }
]

3. 嵌套路由

const routes = [
  {
    path: '/',
    component: Layout,
    children: [
      { path: 'home', component: Home },
      { path: 'about', component: About }
    ]
  }
]

八、性能与工程实践

1. 性能优化

路由懒加载：按需加载组件
缓存机制：使用keep-alive缓存页面
预加载：通过router.preload预加载路由
减少hash变化：避免频繁的URL hash更新

2. 异常处理

router.onError((err) => {
  console.error('路由错误:', err)
  uni.showToast({
    title: '路由错误',
    icon: 'none'
  })
})

3. 安全风险

路由参数注入：使用encodeURIComponent处理用户输入
权限校验：在路由守卫中进行严格的权限验证
防止路径遍历：限制路由路径的范围

九、常见问题与踩坑

1. 常见错误

问题	原因	解决方案
路由未生效	未正确配置路由实例	确认`main.js`中调用了`use(router)`
页面无法跳转	使用了`createWebHistory`	改用`createWebHashHistory`
参数丢失	未正确编码参数	使用`encodeURIComponent`处理参数
路由重复	未正确配置路由	检查路由路径是否唯一

2. 典型问题

问题描述：在uniapp中使用createWebHistory导致页面无法正常跳转

解决方法：

// 修改为hash模式
const router = createRouter({
  history: createWebHashHistory(),
  routes
})

问题描述：路由参数在跳转后丢失