Skip to content

4. 路由

一个 [Vue.js] 应用只加载一个 HTML 页面。然而,[RdvMedecins] 应用有登录页、日程页、“我的空间”页……每个页面都有自己的 URL([/login]、[/schedule]、[/my-area]),可以加书签,并且浏览器的后退和前进按钮也能正常工作。这是 路由器 的工作,即 [vue-router] 库。

4.1. 示例 13:路由器

路由器在 [main.ts] 中添加到应用里:

// =========================================================================
// 13-router/src/main.ts
// -------------------------------------------------------------------------
// app.use(router):把路由器添加到应用中。组件
// <RouterLink> 和 <RouterView> 随即在所有地方都可以使用。
// =========================================================================

import { createApp } from 'vue';
import 'bootstrap/dist/css/bootstrap.min.css';
import App from './App.vue';
import { router } from './router';

createApp(App).use(router).mount('#app');
  • 第 13 行:[app.use(...)] 安装一个 扩展 ([plugin]):组件 [<RouterLink>] 和 [<RouterView>],以及函数 [useRoute()] 和 [useRouter()] 在所有地方都可用了。

示例数据,“硬编码”:

// “硬编码”的数据,这样本示例就不依赖服务器
export interface Doctor {
  id: number;
  title: string;
  firstName: string;
  lastName: string;
  specialty: string;
}

export const DOCTORS: Doctor[] = [
  { id: 1, title: 'Mme', firstName: 'Marie', lastName: 'PELISSIER', specialty: 'general practitioner' },
  { id: 2, title: 'Mr', firstName: 'Paul', lastName: 'TATOU', specialty: 'pediatrician' },
  { id: 3, title: 'Melle', firstName: 'Sophie', lastName: 'DUPONT', specialty: 'general practitioner' },
];

路由:

// =========================================================================
// 13-router/src/router.ts - 应用的路由
// -------------------------------------------------------------------------
// Vue.js 应用是单页应用(SPA:Single
// Page Application):浏览器只加载一个 HTML 页面。当点击
// 内部链接时,不会向服务器发送请求:
// 路由器会更改浏览器显示的地址,并替换
// <RouterView> 中显示的组件。
//
// 一条路由把一个路径与一个组件(称为“视图”,指应用的
// 某个屏幕)关联起来:
//   '/doctors/:id'        :id 是一个参数(/doctors/2 -> id = "2");
//   '/:pathMatch(.*)*'    任意路径:“页面未找到”页面
//                         (最精确的路由总是优先)。
//
// createWebHashHistory:地址形如 /13-router/#/doctors/2。
// # 之后的所有内容都留在浏览器中:重新加载页面(F5)
// 请求的始终是 /13-router/,而它是存在的。当服务器对路由器一无所知时,
// 这是最简单的模式——这里就是 Vite 服务器,它
// 一次要为二十个示例提供服务。案例研究将使用“干净”的
// 地址(createWebHistory:/schedule、/doctors……)。
// =========================================================================

import { createRouter, createWebHashHistory } from 'vue-router';
import Home from './views/Home.vue';
import DoctorList from './views/DoctorList.vue';
import DoctorDetail from './views/DoctorDetail.vue';
import Search from './views/Search.vue';
import NotFoundPage from './views/NotFoundPage.vue';

export const router = createRouter({
  history: createWebHashHistory(),
  routes: [
    { path: '/', name: 'home', component: Home },
    { path: '/doctors', name: 'doctors', component: DoctorList },
    // props: true -> :id 参数会作为 prop 传给组件
    // (这样组件就不再依赖路由器:更易于复用)
    { path: '/doctors/:id', name: 'doctor', component: DoctorDetail, props: true },
    { path: '/search', name: 'search', component: Search },
    // 重定向:旧地址指向新地址
    { path: '/physicians', redirect: '/doctors' },
    { path: '/:pathMatch(.*)*', name: 'not-found', component: NotFoundPage },
  ],
});
  • 第 33–43 行:一条 路由 把一个路径与一个组件关联起来,这个组件称为“视图”(指应用的屏幕,与 [Handlebars] 视图,即 [NestJS] 课程中的视图毫无关系,只是它们的作用相似);
  • 第 34 行:路由可以有一个名称,用它创建链接比用路径更稳定;
  • 第 38 行:[:id] 是一个 参数:[/doctors/2] 会显示 [DoctorDetail] ,并带有 [id = "2"]。选项 [props: true] 把它作为 prop 传给组件:这样组件就不再依赖路由器;
  • 第 41 行:重定向:地址 [/physicians] 会导向 [/doctors];
  • 第 42 行:通配路径:“页面未找到”页面。它只接收其他路由都无法识别的地址:[vue-router] 按路径的精确程度对路由排序;最精确的优先(为了便于阅读,仍把它放在最后);
  • 第 32 行:历史模式。使用 [createWebHashHistory] 时,地址的形式为 [/13-router/#/doctors/2]:[#] 之后的任何内容都不会发送给服务器,重新加载页面(F5)时请求的始终是 [/13-router/],而它是存在的。当服务器不认识客户端的路由时,这是最简单的做法,[Vite] 的服务器就是这种情况,它一次要为二十个示例提供服务。案例研究将使用 [createWebHistory] 以及“干净”的地址([/schedule]),这需要服务器一方付出一点额外的努力。

应用的“外壳”:

<!--
  =========================================================================
  13-router/src/App.vue - the "shell" of the application
  -------------------------------------------------------------------------
    - <RouterLink to="...">: an internal link. It produces an <a> tag,
      but a click does not reload the page: it is the router that acts.
      The link of the displayed page receives the class "router-link-active"
      (here replaced by "active", the Bootstrap one);
    - <RouterView />: the place where the component of the current route
      is displayed.
  =========================================================================
-->
<script setup lang="ts">
import { RouterLink, RouterView, useRoute } from 'vue-router';

// useRoute():当前路由(路径、参数、query 等),是响应式的
const route = useRoute();
</script>

<template>
  <div class="container py-4">
    <h1 class="h3 mb-3">Example 13 - the router</h1>
    <nav class="nav nav-pills mb-3">
      <RouterLink class="nav-link" active-class="active" to="/">Home</RouterLink>
      <!-- to 可以是一个对象:使用路由的名称而不是它的路径 -->
      <RouterLink class="nav-link" active-class="active" :to="{ name: 'doctors' }">Doctors</RouterLink>
      <RouterLink class="nav-link" active-class="active" :to="{ name: 'search', query: { q: 'general practitioner' } }">Search</RouterLink>
      <RouterLink class="nav-link" to="/physicians">/physicians (redirection)</RouterLink>
      <RouterLink class="nav-link" to="/unknown-page">Broken link</RouterLink>
    </nav>
    <p class="small text-muted">current route: <code>{{ route.fullPath }}</code> (name: {{ String(route.name) }})</p>
    <div class="card p-3">
      <RouterView />
    </div>
  </div>
</template>
  • 第 17 行:当前路由(路径、参数、[query]……),它是动态的:它变化时,模板会更新;
  • 第 24 行:[<RouterLink>] 生成一个 [<a>] 标签,但点击它不会重新加载页面:路由器会更改地址和显示的组件。当前页面的链接会被赋予由 [active-class] 指定的类(这里是 [active],即 [Bootstrap] 的类);
  • 第 26 行:目标可以是一个对象:使用路由名称而不是路径;
  • 第 27 行:带查询参数的链接:[/search?q=general practitioner];
  • 第 33 行:显示当前路由组件的位置。

各个页面。医生列表生成带参数的链接:

<!-- 13-router/src/views/DoctorList.vue - 带参数的链接 -->
<script setup lang="ts">
import { RouterLink } from 'vue-router';
import { DOCTORS } from '../data';
</script>

<template>
  <ul class="mb-0">
    <li v-for="m in DOCTORS" :key="m.id">
      <!-- { name, params }:路由器自己构造地址 /doctors/2 -->
      <RouterLink :to="{ name: 'doctor', params: { id: m.id } }">{{ m.title }} {{ m.firstName }} {{ m.lastName }}</RouterLink>
    </li>
  </ul>
</template>
  • 第 11 行:路由器本身根据路由名称及其参数构造地址 [/doctors/2] 。

医生页面:

<!--
  13-router/src/views/DoctorDetail.vue - a page with a parameter
  The id arrives as a PROP (props: true in router.ts), as a string.
  useRouter() gives the router itself, to navigate BY CODE.
-->
<script setup lang="ts">
import { computed } from 'vue';
import { useRouter } from 'vue-router';
import { DOCTORS } from '../data';

const props = defineProps<{ id: string }>();
const router = useRouter();

// computed:从 /doctors/1 切换到 /doctors/2 时,Vue 会复用
// 同一个组件,只更改 prop——computed 会随之更新
const doctor = computed(() => DOCTORS.find((m) => m.id === Number(props.id)) ?? null);
const next = computed(() => (Number(props.id) % DOCTORS.length) + 1);
</script>

<template>
  <div v-if="doctor">
    <h2 class="h5">{{ doctor.title }} {{ doctor.firstName }} {{ doctor.lastName }}</h2>
    <p>Specialty: {{ doctor.specialty }}</p>
    <div class="d-flex gap-2">
      <!-- 通过代码导航:router.push(...) 或 router.back() -->
      <button class="btn btn-sm btn-outline-secondary" @click="router.back()">Back</button>
      <button class="btn btn-sm btn-outline-primary" @click="router.push({ name: 'doctor', params: { id: next } })">Next doctor</button>
    </div>
  </div>
  <p v-else class="text-danger mb-0">Doctor no. {{ id }} does not exist.</p>
</template>
  • 第 11 行:参数 [:id] 以字符串形式作为 prop 传入;
  • 第 12 行:路由器本身,用于 通过代码进行导航;
  • 第 16 行:从 [/doctors/1] 切换到 [/doctors/2] 不会重新创建组件:[Vue.js] 会复用当前显示的那个组件,只更改它的 prop。[computed] 会跟随这一变化;而放在 [onMounted] 中的代码则只会执行一次;
  • 第 26 和 27 行:返回上一页,前往另一页。

Image

搜索是一个完全由其 URL 描述的页面,就像 [NestJS] 课程中的 GET 表单一样:

<!--
  13-router/src/views/Search.vue - a page driven by the QUERY of the URL
  (/search?q=pediatrician). As with the GET form of the NestJS course, the
  page is entirely described by its address: it can be
  bookmarked, reloaded, navigated back to.
-->
<script setup lang="ts">
import { computed, ref, watch } from 'vue';
import { useRoute, useRouter } from 'vue-router';
import { DOCTORS } from '../data';

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

// 输入框以 URL 中的值开始……
const input = ref(String(route.query.q ?? ''));
// ……并在 URL 变化时跟随变化(例如点击后退按钮)
watch(() => route.query.q, (q) => (input.value = String(q ?? '')));

const results = computed(() => {
  const q = String(route.query.q ?? '').toLowerCase();
  return DOCTORS.filter((m) => `${m.firstName} ${m.lastName} ${m.specialty}`.toLowerCase().includes(q));
});

function search(): void {
  // 我们改变 URL;显示内容跟随 URL(上面的 computed)
  router.push({ name: 'search', query: { q: input.value } });
}
</script>

<template>
  <form class="d-flex gap-2 mb-3" @submit.prevent="search">
    <input v-model="input" class="form-control" placeholder="name or specialty">
    <button class="btn btn-primary">Search</button>
  </form>
  <ul class="mb-0">
    <li v-for="m in results" :key="m.id">{{ m.firstName }} {{ m.lastName }} ({{ m.specialty }})</li>
  </ul>
</template>
  • 第 16 行:[route.query] 包含 URL 的参数([?q=...]);
  • 第 18 行:如果 URL 发生变化(点击“上一页”按钮),输入框随之变化;
  • 第 20 行:结果取决于 URL,而不是输入框;
  • 第 27 行:搜索会改变 URL;显示内容随之更新。你可以为该搜索加书签、重新加载它,或者后退。

Image

4.2. 示例 14:导航限制

有些页面要求用户已登录,另一些页面则要求具备特定角色。本示例在没有服务器的情况下模拟登录:

// =========================================================================
// 14-guards/src/session.ts - 一个模拟的会话(没有服务器)
// -------------------------------------------------------------------------
// 已登录的用户,保存在声明于模块级别的 ref 中:所有
// 导入该模块的文件共用同一个。(示例 15 会用 Pinia 更好地做同样的事;
// 示例 18 则使用真实的服务器。)
// =========================================================================

import { ref } from 'vue';

export type Role = 'ADMIN' | 'DOCTOR' | 'USER';

export interface User {
  login: string;
  role: Role;
}

export const user = ref<User | null>(null);

// 三个“硬编码”的账户(密码 = 登录名)
const ACCOUNTS: Record<string, Role> = { admin: 'ADMIN', pelissier: 'DOCTOR', martin: 'USER' };

export function logIn(login: string, password: string): boolean {
  const role = ACCOUNTS[login];
  if (role === undefined || password !== login) {
    return false;
  }
  user.value = { login, role };
  return true;
}

export function logOut(): void {
  user.value = null;
}
  • 第 18 行:一个声明在 [ref] 模块级别的变量:所有导入 [session.ts] 的文件共用同一个。

路由及其守卫:

// =========================================================================
// 14-guards/src/router.ts - 受保护的路由
// -------------------------------------------------------------------------
// meta:附加在路由上的自由信息。这里:
//   - meta.requiresLogin:该页面要求已登录;
//   - meta.roles        :授权的角色(缺省 = 所有角色)。
//
// router.beforeEach(...):一个导航守卫,在每次页面切换之前
// 执行。它返回:
//   - true                :导航继续;
//   - 另一个地址          :重定向;
// 它相当于 NestJS 守卫(JwtAuthGuard、
// RolesGuard)在客户端的对应物——但有一个根本的区别:客户端守卫
// 只是一种便利。客户端代码掌握在用户手中,用户
// 可以随意修改它。数据真正的保护仍然来自
// 服务器(见黑盒一章)。
// =========================================================================

import { createRouter, createWebHashHistory } from 'vue-router';
import { user, type Role } from './session';
import Home from './views/Home.vue';
import Login from './views/Login.vue';
import Schedule from './views/Schedule.vue';

// 我们向 TypeScript 声明所使用的 meta 属性
declare module 'vue-router' {
  interface RouteMeta {
    requiresLogin?: boolean;
    roles?: Role[];
  }
}

export const router = createRouter({
  history: createWebHashHistory(),
  routes: [
    { path: '/', component: Home },
    { path: '/login', component: Login },
    { path: '/schedule', component: Schedule, meta: { requiresLogin: true } },
    {
      path: '/administration',
      // 懒加载:该组件的代码只在首次访问此页面时才下载
      // (Vite 会把它做成单独的文件)
      component: () => import('./views/Administration.vue'),
      meta: { requiresLogin: true, roles: ['ADMIN'] },
    },
  ],
});

router.beforeEach((to) => {
  if (to.meta.requiresLogin && user.value === null) {
    // 未登录:转到登录页面,并记住我们原本想去的地方
    return { path: '/login', query: { redirect: to.fullPath } };
  }
  if (to.meta.roles && user.value && !to.meta.roles.includes(user.value.role)) {
    // 已登录,但角色不符:返回主页,并附上原因
    return { path: '/', query: { denied: to.fullPath } };
  }
  return true;
});
  • 第 26–31 行:我们在 [TypeScript] 中声明将存放在路由的 [meta] 字段中的属性。[meta] 接受任意数据;声明这些属性后,使用它们时无需类型转换;
  • 第 38 行:该页面要求用户已登录;
  • 第 43 行:延迟加载:该组件的代码只在首次访问此页面时才下载。[Vite] 把它存放在单独的文件中。这样,应用在启动时只加载它需要的内容;
  • 第 49–59 行:一个 导航守卫,在每一次页面切换之前执行。它返回 [true] 表示允许访问,或返回另一个要重定向到的地址:
    • 未登录:重定向到 [/login],并把请求的页面保存在 [redirect] 参数中;
    • 已登录但角色不符:返回主页,并附上拒绝访问的原因。

登录页面会把用户重定向到他原本想去的地方:

<!--
  14-guards/src/views/Login.vue
  After logging in, the user is sent back to the page they wanted to
  open (parameter ?redirect=... set by the guard), or to the home page.
-->
<script setup lang="ts">
import { ref } from 'vue';
import { useRoute, useRouter } from 'vue-router';
import { logIn } from '../session';

const route = useRoute();
const router = useRouter();
const login = ref('');
const password = ref('');
const error = ref(false);

function submit(): void {
  error.value = !logIn(login.value.trim(), password.value);
  if (!error.value) {
    const redirect = route.query.redirect;
    // 只接受内部路径:它以 / 开头,但不以 // 开头
    // (//site.com/... 指向另一个站点)——不会重定向到其他站点
    const internal = typeof redirect === 'string' && redirect.startsWith('/') && !redirect.startsWith('//');
    router.push(internal ? redirect : '/');
  }
}
</script>

<template>
  <p v-if="route.query.redirect" class="alert alert-warning">Log in to open {{ route.query.redirect }}.</p>
  <form class="d-flex flex-wrap gap-2" @submit.prevent="submit">
    <input v-model="login" class="form-control w-auto" placeholder="login" autocomplete="username">
    <input v-model="password" type="password" class="form-control w-auto" placeholder="password" autocomplete="current-password">
    <button class="btn btn-primary">Log in</button>
  </form>
  <p v-if="error" class="text-danger mt-2 mb-0">Incorrect login or password.</p>
</template>
  • 第 23 行:只接受内部路径:它以 [/] 开头,但不以 [//] 开头([//site.com/...] 指向另一个站点)。如果重定向到 URL 中收到的完整 URL,恶意链接就能让用户在登录之后立即被送到一个仿冒我们的其他站点(这种漏洞称为 [open redirect])。

其他文件都非常短:

<script setup lang="ts">
import { RouterLink, RouterView, useRouter } from 'vue-router';
import { logOut, user } from './session';

const router = useRouter();

function onLogOut(): void {
  logOut();
  router.push('/');
}
</script>

<template>
  <div class="container py-4" style="max-width: 720px">
    <h1 class="h3 mb-3">Example 14 - navigation guards</h1>
    <nav class="d-flex gap-3 align-items-center mb-3">
      <RouterLink to="/">Home</RouterLink>
      <RouterLink to="/schedule">Schedule (logged in)</RouterLink>
      <RouterLink to="/administration">Administration (ADMIN)</RouterLink>
      <span class="ms-auto">
        <template v-if="user">
          {{ user.login }} <span class="badge text-bg-primary">{{ user.role }}</span>
          <button class="btn btn-sm btn-link" @click="onLogOut">log out</button>
        </template>
        <RouterLink v-else to="/login">log in</RouterLink>
      </span>
    </nav>
    <div class="card p-3"><RouterView /></div>
  </div>
</template>
<script setup lang="ts">
import { useRoute } from 'vue-router';
const route = useRoute();
</script>

<template>
  <!-- ?denied=...:当角色不符时由守卫设置 -->
  <p v-if="route.query.denied" class="alert alert-danger">Your role does not allow you to open {{ route.query.denied }}.</p>
  <p class="mb-0">Public page. Try the two other links, logged in or not (admin, pelissier, martin - password = login).</p>
</template>

在未登录时点击“Administration (ADMIN)”,会进入登录页面:

Image

使用账户 [martin] (角色 [USER])登录后,守卫拒绝访问管理页面:

Image

一个根本性的提醒:导航守卫只是一种 便利手段 (避免显示不必要的页面)。客户端代码掌握在用户手中;他们可以在自己的浏览器中读取和修改它。真正的数据保护来自 服务器,它在每次请求时都会验证用户的身份和角色。我们将在 [RdvMedecins] 服务器上看到这一点。