首页 › Vue › 路由与状态管理 › Vue Router 基础

Vue Router 是 Vue 的官方路由库，管理 SPA 中的 URL 与页面组件的映射关系。

路由配置

// router/index.ts
import { createRouter, createWebHistory } from 'vue-router'
import Home from '@/views/Home.vue'

const routes = [
  {
    path: '/',
    name: 'home',
    component: Home
  },
  {
    path: '/about',
    name: 'about',
    component: () => import('@/views/About.vue') // 懒加载
  },
  {
    path: '/users/:id',
    name: 'user-detail',
    component: () => import('@/views/UserDetail.vue'),
    props: true  // URL 参数作为 props 传入组件
  }
]

const router = createRouter({
  history: createWebHistory(),  // HTML5 模式（无 #）
  routes
})

export default router

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

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

路由出口与导航

<!-- App.vue -->
<template>
  <nav>
    <router-link to="/">首页</router-link>
    <router-link to="/about">关于</router-link>
    <router-link :to="{ name: 'user-detail', params: { id: 1 } }">用户1</router-link>
  </nav>

  <!-- 路由匹配的组件渲染到此 -->
  <router-view />
</template>

router-link 属性

<router-link to="/about">文本</router-link>
<router-link :to="{ path: '/about' }">对象</router-link>
<router-link :to="{ name: 'user-detail', params: { id: 1 } }">命名路由</router-link>
<router-link to="/about" replace>替换历史（无回退）</router-link>
<router-link to="/about" active-class="my-active">自定义激活 class</router-link>

编程式导航

<script setup>
import { useRouter, useRoute } from 'vue-router'

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

function goToUser(id) {
  // 字符串路径
  router.push(`/users/${id}`)

  // 对象路径
  router.push({ path: `/users/${id}` })

  // 命名路由
  router.push({ name: 'user-detail', params: { id } })

  // 带查询参数
  router.push({ path: '/users', query: { page: 1, sort: 'name' } })

  // 替换（不产生历史记录）
  router.replace({ name: 'user-detail', params: { id } })

  // 前进/后退
  router.go(-1)     // 回退一页
  router.go(1)      // 前进一页
}
</script>

路由参数与查询

<!-- 路由：/users/:id -->
<script setup>
import { useRoute, useRouter } from 'vue-router'
import { watch } from 'vue'

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

// params（路径参数）
console.log(route.params.id)    // 从 URL 中取

// 监听 param 变化（同一组件不同参数）
watch(() => route.params.id, (newId) => {
  fetchUser(newId)
})

// query（查询参数）
const page = computed(() => route.query.page || 1)

// 更新查询参数
function setPage(page) {
  router.push({ query: { ...route.query, page } })
}
</script>

<template>
  <p>用户 ID: {{ route.params.id }}</p>
</template>

Props 解耦

路由最好通过 props 将参数注入组件，使组件与路由解耦：

// router
{
  path: '/users/:id',
  component: UserDetail,
  props: true  // params → props
}

<!-- UserDetail.vue -->
<script setup>
const props = defineProps({
  id: { type: String, required: true }  // 直接通过 props 接收
})
</script>

嵌套路由

const routes = [
  {
    path: '/users',
    component: UserLayout,
    children: [
      { path: '', component: UserList },
      { path: ':id', component: UserDetail },
      { path: ':id/edit', component: UserEdit }
    ]
  }
]

<!-- UserLayout.vue -->
<template>
  <div class="user-layout">
    <aside>
      <router-link to="/users">用户列表</router-link>
    </aside>
    <main>
      <router-view />  <!-- 子路由渲染位置 -->
    </main>
  </div>
</template>

命名视图

同一个路由下显示多个视图：

{
  path: '/settings',
  components: {
    default: SettingsMain,
    sidebar: SettingsSidebar
  }
}

<template>
  <router-view />           <!-- default 视图 -->
  <router-view name="sidebar" />  <!-- sidebar 视图 -->
</template>

路由懒加载

通过动态 import 实现代码分割：

const routes = [
  {
    path: '/admin',
    component: () => import('@/views/Admin.vue')  // 按需加载
  }
]

小结

概念	关键 API
路由创建	createRouter + createWebHistory
导航	<router-link>、router.push / replace / go
参数	route.params、route.query、props: true
嵌套路由	children 配置 + <router-view>
命名视图	components 多视图
懒加载	动态 import()

上一节：Teleport / Suspense / 动态组件 下一节：导航守卫与权限路由

贡献者: 布欧-Lewyon