Skip to content

6. 第 5 章 - [RdvMedecins] 应用程序的 [Vue.js] 客户端

本章逐个文件详述本文档附带的 [rdvmedecins-vuejs-client] 文件夹的内容,采用本课程通篇使用的格式:先给出逐行编号的源代码,然后是标题为“我们来解读这段代码:”的部分。每个项目文件夹还包含其自己的 [README.md]。

6.1. 架构概览

与原始文档一样,也与本课程的 [Angular] 和 [React] 变体一样,客户端采用分层架构,我们在这里称之为 V-Services (视图-服务)。

值得注意的是术语上的一处差异:在 AngularJS 1.x 中,视图(HTML 模板)和控制器(关联的 JavaScript 类)是两个不同的实体,通过 $scope 连接。在 [Vue.js] 中,它们合并为单个实体,即 [.vue] 组件(参见上一章)——与 [Angular] 和 [React] 中完全一样,尽管形式不同(是一个包含三个块的文件,而不是一个类或一个函数)——因此,在下文中,凡是原始文档区分视图和控制器的地方,我们都简单地称为“组件”。

与原始文档一样,组件绝不直接通过 HTTP 通信:这个角色专属于服务层(在这里是组合式函数 [useAppointmentService()] 和组合式函数 [useAuth()])。这是一条设计原则,同样适用于 AngularJS 1.x、[Angular]、[React]、或 [Vue.js]——它没有改变。

6.2. 项目结构

这一结构直接遵循原始文档的流程(登录、选择医生/日期、查看日程表、预约),只是在这里组织成 [Vue.js] 组件,而不是 AngularJS 1.x 的独立控制器/视图、独立组件([Angular])或函数组件([React])。与本课程中的另外两个变体相比:

  • 根组件只需一个文件(App.vue,外加 README.md),而不是三个文件([Angular]:app.ts/app.html/app.css),在 [React] 一侧也是三个文件(App.tsx/App.css/README.md):[<template>] 和 [<script setup>] 在同一个文件中合并了 [JSX] 此前在 [React] 一侧已经合并的内容——并且 App.vue 与 App.tsx 一样,没有相当于 app.config.ts 的应用程序配置文件;
  • 出现了 `core/composables/` 文件夹,取代 [React] 一侧的 `core/context/` (后者在 [Angular] 一侧本身并不存在):它包含充当可注入服务的组合式函数([SettingsService]、[AuthService]、[LanguageService]),对应于 [Angular] 变体——这一机制(组合式函数 + [provide]/[inject])已在上一章连同一个通用示例一起介绍(参见上一章“共享逻辑”)。

[Bootstrap] 5 用于所有视图(在 main.ts 中导入;见下文)——它是原始文档已使用的 Bootstrap 3 的直接演进,与本课程的 [Angular] 和 [React] 变体保持一致。

6.3. 项目配置文件

6.3.1. package.json

{
  "name": "rdvmedecins-vue-client",
  "version": "0.0.0",
  "scripts": {
    "dev": "vite",
    "start": "vite",
    "build": "vue-tsc -b && vite build",
    "preview": "vite preview"
  },
  "private": true,
  "packageManager": "npm@10.9.7",
  "dependencies": {
    "vue": "^3.5.0",
    "vue-i18n": "^11.0.0",
    "bootstrap": "^5.3.3"
  },
  "devDependencies": {
    "@vitejs/plugin-vue": "^5.2.0",
    "prettier": "^3.8.1",
    "typescript": "~5.8.0",
    "vite": "^6.0.0",
    "vue-tsc": "^2.2.0"
  }
}

我们来解读这段代码:

  • 第 5–8 行:["scripts": { … }] ——可用的 [npm run <name>] 命令。[start] (同 dev)启动 [Vite] 开发服务器,每当源文件被修改时自动重新加载,端口为 4200(见下文的 vite.config.ts)——与本课程的 [Angular] 和 [React] 变体端口相同;
  • 第 7 行:["build": "vue-tsc -b && vite build",] ——与 [React] ([tsc -b && vite build])的显著区别:[vue-tsc] 用一个变体取代标准的 TypeScript 编译器,该变体还能检查 [<template>] 内部的类型(例如,作用于不存在的属性的 [v-model] ,或与 [:doctors] 不匹配 [defineProps]所期望类型的情形)——很像 [Angular] 通过其 strictTemplates 选项所做的那样,而 [React] 只是像对待其他任何 TypeScript 一样检查 [JSX] ;
  • 第 12–16 行:["dependencies": { … }] ——在浏览器中运行所需的包:[vue] (框架的核心)、[vue-i18n] (FR/EN 翻译;见下文)、[bootstrap] (仅样式表)。与本课程的 [Angular] 和 [React] 变体不同,这里既没有单独对应于 [@angular/router]/[react-i18next] 的包(vue-i18n 直接内嵌其引擎;见 i18n.ts),也没有 RxJS;
  • 第 17–23 行:["devDependencies": { … }] ——仅在开发期间需要的包:[@vitejs/plugin-vue] (将 [.vue] 文件转换为 JavaScript,以及热重载)、TypeScript、[vue-tsc] (见上文),以及 [Vite] 本身。与 [React] ([@types/react]、[@types/react-dom])不同,[Vue.js] 不需要单独的类型包:该库本身就是用 TypeScript 编写的。

与 [NestJS] 服务器([commonjs] 模块,参见第 3 章)不同,这个项目以原生 ECMAScript 模块(import/export)运行——与本课程的 [Angular] 和 [React] 变体完全一样。

6.3.2. vite.config.ts

1
2
3
4
5
6
7
8
9
import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';

export default defineConfig({
  plugins: [vue()],
  server: {
    port: 4200,
  },
});

我们来解读这段代码:

  • 第 5 行:[plugins: [vue()],] ——启用对 [.vue] 文件的转换(拆分三个块,根据渲染模式编译 [<template>] )和热重载——对 [Vue.js] 而言,相当于 [@vitejs/plugin-react]() 在 [JSX] 方面于 [React] 一侧所做的事情(参见上一章),也相当于 [@angular/build:dev-server] 在幕后为 [Angular] 所做的事情;
  • 第 6–8 行:[server: { port: 4200, },] ——把开发服务器的端口设为 4200,与 [ng serve] 在 [Angular] 一侧的端口相同,也与本课程中的 [React] 客户端相同——这纯粹是出于教学考虑的选择,使本课程的三个变体可以互换,而无需改变你的工作流程。

这个文件在原始的 AngularJS 1.x 项目中没有对应物;在本课程的 [Angular] 一侧,起这个作用的是 [angular.json] ;在 [NestJS] 一侧(第 3 章),则是 [nest-cli.json]。

6.3.3. tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",
    "useDefineForClassFields": true,
    "lib": ["ES2022", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "skipLibCheck": true,

    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "isolatedModules": true,
    "moduleDetection": "force",
    "noEmit": true,

    "strict": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true
  },
  "include": ["src"]
}

我们来解读这段代码:

  • 第 15 行:["strict": true,] ——与本课程 [tsconfig.json] 中的 [Angular] 和 [React] 变体一样,TypeScript 的完整严格模式处于启用状态:每个变量都必须有可确定的类型,每个 null 或 undefined 值都必须被显式处理;
  • 第 18–19 行:["noUnusedLocals": true, "noUnusedParameters": true,] ——在编译期间标记任何已声明但从未使用的变量或参数——与 [React] 的设置相同;
  • 第 13 行:["noEmit": true] ——这里使用 TypeScript 只是为了类型检查([npm run build] 首先运行 [vue-tsc -b],如果出现类型错误,它就会失败,包括在 [<template>] 中;参见上文的 package.json):真正生成浏览器所执行的 JavaScript 的是 [Vite] (通过 esbuild)。

与 [tsconfig.json] 文件(由 [React] 项目生成,其中有 [jsx: ‘react-jsx’])不同,这个文件不包含任何特定于框架的设置:[vue-tsc] (而不是标准的 TypeScript 编译器)会预先确定如何解析 [.vue] 文件——这是与此配置文件分开的机制,不同于 [React],后者对 [JSX] 的支持直接在这里配置。

6.4. 启动应用程序

6.4.1. index.html

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>RdvMedecins - Vue.js client</title>
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <link rel="icon" type="image/x-icon" href="/favicon.ico">
</head>
<body>
  <div id="app"></div>
  <script type="module" src="/src/main.ts"></script>
</body>
</html>

我们来解读这段代码:

  • 第 2 行:[<html lang="en">] ——与 [Angular] 和 [React] 一样,由于这个 HTML 页面是静态的(在 [Vue.js] 应用程序启动之前由浏览器加载),它无法立即反映用户之后所做的语言选择;
  • 第 10 行:[<div id="app"></div>] ——这个页面最初包含的唯一元素,一旦挂载,[Vue.js] 就会将其完全填充(见下文的 main.ts)——完全相当于 [Angular] 一侧的 <app-root></app-root>、[React] 一侧的 <div id="root"></div>,以及原始文档(AngularJS 1.x,2014 年)中 <html> 标签上的 [ng-app="rdvmedecinsApp"] ;只有标识符不同([Vue.js] 的惯例:"app");
  • 第 11 行:[<script type="module" src="/src/main.ts"></script>] ——与 [React] 一样,是 index.html 直接引用 main.ts(这是 [Vite] 特有的约定),而不是反过来。在开发环境中,[Vite] 会即时转换并提供这个文件;在生产环境中([npm run build]),它当然是事先编译好的。

与另外两个变体一样,整个应用程序只有一个入口点:这正是单页 Web 应用程序(SPA)的定义,原始文档中已经描述过。

6.4.2. src/main.ts

import { createApp } from 'vue';

import 'bootstrap/dist/css/bootstrap.min.css';
import './index.css';

import { i18n } from './i18n';
import { createSettingsStore, SettingsKey } from './app/core/composables/settings.composable';
import { createAuthStore, AuthKey } from './app/core/composables/auth.composable';
import { createLanguageStore, LanguageKey } from './app/core/composables/language.composable';
import App from './app/App.vue';

const app = createApp(App);

app.use(i18n);

const settingsStore = createSettingsStore();
app.provide(SettingsKey, settingsStore);

const authStore = createAuthStore(settingsStore);
app.provide(AuthKey, authStore);

const languageStore = createLanguageStore();
app.provide(LanguageKey, languageStore);

const container = document.getElementById('app');
if (!container) {
  throw new Error('Element #app not found in index.html');
}

app.mount(container);

我们来解读这段代码:

  • 第 12 行:[const app = createApp(App);] ——直接相当于 [bootstrapApplication(App, appConfig)] 在 [Angular] 一侧的写法,以及 [createRoot(...).render(...)] 在 [React] 一侧的写法:[createApp(...)] 创建一个应用实例(但尚未挂载它;见第 30 行);
  • 第 14 行:[app.use(i18n);] ——安装 [vue-i18n] 插件:从此以后,任何组件的 [useI18n()] 都可以在 [<script setup>] 中使用;
  • 第 16–23 行:[const settingsStore = createSettingsStore(); app.provide(SettingsKey, settingsStore); …] ——来自 core/composables/(见下文)的三个 [createXxxStore()] + [app.provide(...)] 组合,使 [useSettings()]、[useAuth()]和 [useLanguage()] 可以在任何后代组件中使用——相当于 [provideXxx()] 的三个调用,来自 [app.config.ts] ,位于 [Angular] ([providers: [...]])一侧,但这里表现为一个函数调用的序列,而不是提供者数组,也不是像 [React] 一侧那样,围绕根组件对 [Provider] 组件进行嵌套——这里不需要视觉上的嵌套,不同于 [React] (可与本课程 React 客户端的 main.tsx 对比:<SettingsProvider><AuthProvider>...);
  • 第 16、19 行:[const settingsStore = … const authStore = createAuthStore(settingsStore);] ——调用的顺序很重要:[createAuthStore(...)] 要求 [settingsStore] 已经存在(以读取 [apiBaseUrl])——因此它是作为参数直接传入的,而不是通过 [Vue.js] 注入:在这个阶段,还不存在任何组件,所以 [inject()] 帮不上忙;
  • 第 22 行:[const languageStore = createLanguageStore();] ——在 [app.use(i18n)] (第 14 行)之后调用:这个组合式函数要求 [vue-i18n] 插件已经安装;
  • 第 30 行:[app.mount(container);] ——真正把应用程序挂载到 index.html 的 #app 元素中——与 [createApp(App)](第 12 行)分开,恰恰是为了在应用程序显示之前,留出时间让中间几行(app.use、app.provide)对其进行配置。

与本课程的 [Angular] 和 [React] 客户端一样(单页,没有路由表),这个 [Vue.js] 客户端不使用任何路由器:App.vue 根据 [useAuth().isLoggedIn]显示登录界面或应用程序的其余部分——一个简单的 [v-if] 就足够了;路由器([vue-router] 或其他)对单页应用不会增加任何价值。

6.4.3. src/i18n.ts

import { createI18n } from 'vue-i18n';

export type Language = 'fr' | 'en';

const loadedDictionaries = new Set<Language>();

export const i18n = createI18n({
  legacy: false,
  locale: navigator.language.toLowerCase().startsWith('fr') ? 'fr' : 'en',
  fallbackLocale: 'en',
  messages: {},
});

export async function loadDictionary(language: Language): Promise<void> {
  if (loadedDictionaries.has(language)) {
    return;
  }
  const httpResponse = await fetch(`/i18n/${language}.json`);
  const dictionary = (await httpResponse.json()) as Record<string, unknown>;
  i18n.global.setLocaleMessage(language, dictionary);
  loadedDictionaries.add(language);
}

我们来解读这段代码:

  • 第 8 行:[legacy: false,] ——启用 [vue-i18n] 的“组合式 API”模式:在组件中使用 [useI18n()] (就像 [useTranslation()] 在 [React] 一侧那样),而不是 [this.$t](旧模式,面向 [Vue.js] 2 的选项式 API);
  • 第 9–11 行:[locale: navigator.language.toLowerCase().startsWith('fr') ? 'fr' : 'en', fallbackLocale: 'en', messages: {},] ——启动语言(如果浏览器语言以 'fr' 开头则为法语,否则为英语)、当前字典中缺少某个键时的回退语言(英语),以及启动时为空的字典——[language.composable.ts] (见下文)会立即用 localStorage 中存储的选择(如果有的话)替换 [locale] ;
  • 第 14–22 行:[export async function loadDictionary(language: Language): Promise<void> { …] ——不同于 [i18next-http-backend] (React)或 [TranslateHttpLoader] (Angular),[vue-i18n] 原生并不提供“加载器”:它只是等待通过 [setLocaleMessage(...)] 提供已加载好的字典。因此,这个函数手动重建了 [HttpBackend] 在 [React] 一侧自动完成的工作:它使用 [fetch] 获取文件 [/i18n/<language>.json](与本课程另外两个变体使用完全相同的 URL),然后把其内容保存到 [vue-i18n];
  • 第 15–17 行:[if (loadedDictionaries.has(language)) { return; }] ——防止重新下载会话期间已经遇到过的语言——与 [i18next-http-backend] 在 [React] 一侧的内部缓存是同一种优化。

6.4.4. src/index.css

body {
  background-color: #f5f7fa;
}

.free-slot {
  cursor: pointer;
}

.free-slot:hover {
  background-color: #e9f7ef;
}

我们来解读这段代码:

  • 第 1 行:[body { background-color: #f5f7fa; }] ——与另外两个变体相同:使用非常浅的灰色,而不是默认的纯白色,使 [Bootstrap] 卡片(白色背景,.card)从页面背景中略微凸显出来;
  • 第 5–11 行:[.free-slot { cursor: pointer; } .free-slot:hover { … }] ——应用于日程表中表示可预约时间段的行(见 Schedule.vue,下文的 [:class="scheduleSlot.appointment === null ? ‘free-slot’ : undefined"] ):光标在整行上呈手形,悬停时背景略微变绿——这里与本课程的 [React] 客户端不同(在那里,“pointer”光标应用于“预约”按钮本身),整行表格都是可点击的,正如原始文档中所设计的那样。

这个文件包含全局样式,与 [Vue.js] 组件可以在其自身的 [<style scoped>] 块中定义的“局部”样式相对(本项目中没有使用:[Bootstrap] 和 index.css 已足以满足本文档实现的一切需求)——原理与 [Angular] 和 [React] 相同(每个组件有单独的样式文件)。

6.5. core/models 层

6.5.1. src/app/core/models/appointment.models.ts

// 服务器所有响应共用的信封(参见 NestJS 端的 ServerResponse<T>)
export interface ServerResponse<T> {
  status: number; // 0 = 成功,其他值 = 失败(参见服务器端的 ResponseStatus)
  data: T | null;
}

export interface Doctor {
  id: number;
  title: string;
  lastName: string;
  firstName: string;
}

// 此处的 [Client] 指医疗诊所的患者——不要与 "HTTP client" 混淆!
export interface Client {
  id: number;
  title: string;
  lastName: string;
  firstName: string;
}

export interface SlotJson {
  id: number;
  startHour: number;
  startMinute: number;
  endHour: number;
  endMinute: number;
}

export interface AppointmentJson {
  id: number;
  day: string; // 格式 "yyyy-MM-dd"
  client: Client | null;
  slot: SlotJson | null;
}

export interface ScheduleSlot {
  slot: SlotJson;
  appointment: AppointmentJson | null;
}

export interface DoctorDaySchedule {
  doctor: Doctor;
  day: string;
  slots: ScheduleSlot[];
}

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

export interface LoginResult {
  accessToken: string;
  login: string;
  name: string;
  role: Role;
}

我们来解读这段代码:

  • 这些接口本身是对本课程 [Angular] 和 [React] 变体的严格复制粘贴(只是像整个客户端一样被重写):描述与服务器交换的数据的 TypeScript 接口不依赖于任何框架——它是“纯”TypeScript,与 [ServerResponse]<T> 类和 [TypeORM] 实体完全对应,属于 [NestJS] 服务器(第 3 章);
  • [Role]/[LoginResult]——与服务器端同名类型(src/entities/user.entity.ts、auth/login-result.model.ts,第 3 章)完全相同的副本。

在 AngularJS 1.x(2014 年)中,纯 JavaScript 无法以这种方式描述所期望的数据格式。而使用 TypeScript——本课程的三个变体都使用它——字段名中的拼写错误在程序运行之前,也就是在编译时就会被标出。

6.6. core/composables 层

对于这个客户端,[Vue.js],该目录所起的作用与本课程 [React] 客户端中的 core/context/ 相同(参见上一章“共享逻辑”):它把三个组合式函数组织在一起,在这里它们充当可注入的服务(对应 [SettingsService]、[AuthService],以及 [LanguageService] 的一部分,位于 [Angular] 一侧)。

6.6.1. src/app/core/composables/settings.composable.ts

import { inject, reactive, type InjectionKey } from 'vue';

export interface SettingsStore {
  apiBaseUrl: string;
  setApiBaseUrl: (url: string) => void;
}

export const SettingsKey: InjectionKey<SettingsStore> = Symbol('SettingsStore');

export function createSettingsStore(): SettingsStore {
  const store = reactive<SettingsStore>({
    apiBaseUrl: 'http://localhost:8080',
    setApiBaseUrl(url: string) {
      store.apiBaseUrl = url;
    },
  });
  return store;
}

export function useSettings(): SettingsStore {
  const store = inject(SettingsKey);
  if (!store) {
    throw new Error('useSettings() must be called after app.provide(SettingsKey, ...) (see src/main.ts)');
  }
  return store;
}

我们来解读这段代码:

  • 第 8 行:[export const SettingsKey: InjectionKey<SettingsStore> = Symbol('SettingsStore');] ——注入键(参见上一章)——一个带类型的 [Symbol],而不是简单的字符串;
  • 第 10–18 行:[export function createSettingsStore(): SettingsStore { …] ——完全取代 [readonly apiBaseUrl = signal(‘http://localhost:8080’);] ,即 [SettingsService] 在 [Angular] 一侧的写法:默认值相同,也同样可以通过原始文档主视图上的“服务器 URL”字段来修改它;这里选择 [reactive(...)] (而不是 [ref()])是因为该存储包含多个属性(apiBaseUrl 及其更新函数)——[store.apiBaseUrl] 直接读取和写入,无需 [.value];
  • 第 20–26 行:[export function useSettings(): SettingsStore { …] ——组件调用的组合式函数([const settings = useSettings();]),直接相当于 [inject(SettingsService)] 在 [Angular] 一侧的写法,以及 [useSettings()] 在 [React] 一侧的写法。

6.6.2. src/app/core/composables/auth.composable.ts

移植自 [AuthService]:处理用户的登录,调用 [POST /login],存储收到的 JWT 令牌(以及随附的身份/角色),并通过 [localStorage] 确保它在页面重新加载后依然保留。这是应用程序中唯一使用 HTTP 与服务器通信的地方,另一处是 [core/services/appointment.service.ts] (见下文)。

import { inject, reactive, type InjectionKey } from 'vue';
import type { LoginResult, ServerResponse, Role } from '../models/appointment.models';
import type { SettingsStore } from './settings.composable';

interface StoredSession {
  accessToken: string;
  login: string;
  name: string;
  role: Role;
}

const STORAGE_KEY = 'rdvmedecins.session';

function readStoredSession(): StoredSession | null {
  try {
    const raw = localStorage.getItem(STORAGE_KEY);
    return raw ? (JSON.parse(raw) as StoredSession) : null;
  } catch {
    return null;
  }
}

export interface AuthStore {
  isLoggedIn: boolean;
  login: string | null;
  name: string | null;
  role: Role | null;
  isAdmin: boolean;
  accessToken: string | null;
  logIn: (login: string, password: string) => Promise<LoginResult>;
  logOut: () => void;
}

export const AuthKey: InjectionKey<AuthStore> = Symbol('AuthStore');

export function createAuthStore(settings: SettingsStore): AuthStore {
  const initialSession = readStoredSession();

  function applySession(session: StoredSession | null): void {
    store.isLoggedIn = session !== null;
    store.login = session?.login ?? null;
    store.name = session?.name ?? null;
    store.role = session?.role ?? null;
    store.isAdmin = session?.role === 'ADMIN';
    store.accessToken = session?.accessToken ?? null;
    if (session) {
      localStorage.setItem(STORAGE_KEY, JSON.stringify(session));
    } else {
      localStorage.removeItem(STORAGE_KEY);
    }
  }

  const store = reactive<AuthStore>({
    isLoggedIn: initialSession !== null,
    login: initialSession?.login ?? null,
    name: initialSession?.name ?? null,
    role: initialSession?.role ?? null,
    isAdmin: initialSession?.role === 'ADMIN',
    accessToken: initialSession?.accessToken ?? null,

    async logIn(login: string, password: string): Promise<LoginResult> {
      const httpResponse = await fetch(`${settings.apiBaseUrl}/login`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ login, password }),
      });
      const envelope = (await httpResponse.json()) as ServerResponse<LoginResult>;
      if (envelope.status !== 0 || envelope.data === null) {
        throw new Error('Login failed');
      }
      const result = envelope.data;
      applySession(result);
      return result;
    },

    logOut(): void {
      applySession(null);
    },
  });

  return store;
}

export function useAuth(): AuthStore {
  const store = inject(AuthKey);
  if (!store) {
    throw new Error('useAuth() must be called after app.provide(AuthKey, ...) (see src/main.ts)');
  }
  return store;
}

我们来解读这段代码:

  • 第 14–21 行:[function readStoredSession(): StoredSession | null { …] ——用 try/catch 块保护,与 [Angular] 和 [React] 中一样:[localStorage] 可能不可用(限制非常严格的隐私浏览模式),或者包含已损坏的值——这种情况下,我们直接认为没有会话;
  • 第 37 行:[const initialSession = readStoredSession();] ——只在构造存储时调用一次(在 src/main.ts 中)——所起的作用与 [useState(readStoredSession)] 在 [React] 一侧的初始化函数,或 [signal(readStoredSession())] 在 [Angular] 一侧的作用完全相同。如果用户在登录后重新加载页面,他们仍保持登录状态;
  • 第 39–51 行:[function applySession(session: StoredSession | null): void { …] ——提取出 [logIn()] 和 [logOut()] 的共同之处:一步完成更新存储的响应式属性并同步 [localStorage] ——这是一个小型内部函数,在对应的 [React] 版本中没有(由于缺少同样自然的统一写入点,它在两个函数中各重复了这一逻辑);
  • 第 53–79 行:[const store = reactive<AuthStore>({ … });] ——原理与 settings.composable.ts 相同:单个 [reactive] 对象,它的每个属性(isLoggedIn、login、accessToken……)由 [applySession()] 就地修改,而不是替换为新对象——不同于 [AuthContext] 在 [React] 一侧,那里每次变化都必须使用 [value] 通过 [useMemo]() 重建一个新对象(参见上一章),而 [Vue.js] 在这里无需这样做:只有读取了确实发生变化的属性的组件才会被自动重绘;
  • 第 61–74 行:[async logIn(login: string, password: string): Promise<LoginResult> { …] ——相当于:POST /login,JSON 请求体 { login, password };与 [React] 一侧一样(fetch/async-await),各个步骤自上而下自然地依次进行,无需专门的 RxJS 操作符(不同于 [AuthService.logIn()] 在 [Angular] 一侧,后者返回一个 Observable,并在单独的 tap() 操作符中保存会话);
  • 第 76–78 行:[logOut(): void { applySession(null); },] ——纯本地操作(不调用服务器):在本次移植中,JWT 令牌不会在服务器端被“撤销”;它会在 JWT_EXPIRES_IN 之后自行过期(参见服务器的 .env,第 3 章)。

6.6.3. src/app/core/composables/language.composable.ts

移植自 [LanguageService] 的一部分:在 [vue-i18n] 之上集中处理界面语言(法语/英语)的切换(参见上文的 i18n.ts)。

import { inject, reactive, watch, type InjectionKey } from 'vue';
import { loadDictionary, i18n, type Language } from '../../../i18n';

const STORAGE_KEY = 'rdvmedecins.language';

export interface LanguageStore {
  currentLanguage: Language;
  changeLanguage: (language: Language) => void;
}

export const LanguageKey: InjectionKey<LanguageStore> = Symbol('LanguageStore');

export function createLanguageStore(): LanguageStore {
  const store = reactive<LanguageStore>({
    currentLanguage: i18n.global.locale.value as Language,
    changeLanguage(language: Language) {
      localStorage.setItem(STORAGE_KEY, language);
      applyLanguage(language);
    },
  });

  function applyLanguage(language: Language): void {
    void loadDictionary(language).then(() => {
      i18n.global.locale.value = language;
      document.documentElement.lang = language;
    });
  }

  watch(i18n.global.locale, (newLanguage) => {
    store.currentLanguage = newLanguage as Language;
  });

  const savedLanguage = localStorage.getItem(STORAGE_KEY) as Language | null;
  if (savedLanguage && savedLanguage !== store.currentLanguage) {
    applyLanguage(savedLanguage);
  } else {
    applyLanguage(store.currentLanguage);
  }

  return store;
}

export function useLanguage(): LanguageStore {
  const store = inject(LanguageKey);
  if (!store) {
    throw new Error('useLanguage() must be called after app.provide(LanguageKey, ...) (see src/main.ts)');
  }
  return store;
}

我们来解读这段代码:

  • 第 15 行:[currentLanguage: i18n.global.locale.value as Language,] ——[vue-i18n] 已经把其当前语言暴露为响应式 [ref] ([i18n.global.locale]):[LanguageStore] 并不创建单独的状态;它只是以稳定的名称(currentLanguage)重新发布它——概念上与 [Angular] 中完全相同,在那里 [LanguageService] 只是把 [this.translate.currentLang] 以不同的名称重新发布;
  • 第 22–27 行:[function applyLanguage(language: Language): void { …] ——[loadDictionary(language)] (参见 i18n.ts)在必要时获取相应的字典,然后,一旦完成,我们就切换到 [i18n.global.locale.value]——不同于 [i18n.changeLanguage(...)] 在 [React] 一侧(它同时完成这两件事);在这里,由于 [vue-i18n] 没有内置的“加载器”(参见 i18n.ts),这个组合式函数自己编排这两个步骤;
  • 第 29–31 行:[watch(i18n.global.locale, (newLanguage) => { store.currentLanguage = newLanguage as Language; });] ——[watch(source, callback)] 每当被观察的值变化时就重新执行回调——对于单个属性,相当于 [useEffect](..., [dep]) 在 [React] 一侧,或 [effect()] 在 [Angular] 一侧。正是这一行真正实现了本文件开头提到的“重新发布”:[store.currentLanguage] 始终保持同步,与 [i18n.global.locale] 保持一致,无论后者是如何变化的;
  • 第 33–38 行:[const savedLanguage = localStorage.getItem(STORAGE_KEY) as Language | null; …] ——在最初的加载时:如果用户在之前的访问中已经选择过语言,则恢复该语言;否则,保留 i18n.ts 中设置的启动语言(英语,或法语浏览器对应的法语)——但它的字典仍然必须被加载,而 i18n.ts 自己不会加载它——这正是 [useEffect](..., []) 在 [React] 一侧 language.context.tsx 中所起的作用,它在设置期间只执行一次。

相当于原始 AngularJS 1.x 客户端中的“FR / EN”按钮,当时它依赖 [angular-translate] 库——它是 AngularJS 1.x 生态系统中 [ngx-translate]([Angular])的前身,之后有 [i18next] ([React])和 [vue-i18n] ([Vue.js])。

6.7. 翻译字典(public/i18n/)

[loadDictionary()] (参见上文的 i18n.ts)每当语言变化(或首次使用)时,都会通过 [HTTP GET /i18n/<language>.json] 请求加载这两个文件之一。[vue-i18n] 随后通过 features/ 目录中所有组件使用的 [useI18n() (function t(...))] Hook 来解析每个键("LOGIN.TITLE"、"SCHEDULE.FREE"……)(见本章后面)。

6.7.1. public/i18n/fr.json

{
  "APP": {
    "TITLE": "RdvMedecins - portage NestJS / Vue.js",
    "SERVER_URL_LABEL": "URL du serveur",
    "LOGOUT": "Se déconnecter"
  },
  "LOGIN": {
    "TITLE": "Connexion",
    "LOGIN_LABEL": "Login",
    "PASSWORD_LABEL": "Mot de passe",
    "SUBMIT": "Se connecter",
    "SUBMITTING": "Connexion...",
    "ERROR": "Login ou mot de passe incorrect.",
    "DEMO_ACCOUNTS_PREFIX": "Comptes de démonstration :",
    "DEMO_ACCOUNTS_ADMIN": "(rôle ADMIN, accès complet)",
    "DEMO_ACCOUNTS_OR": "ou",
    "DEMO_ACCOUNTS_USER": "(rôle USER, lecture seule)"
  },
  "DOCTOR_DAY_PICKER": { "...": "..." },
  "SCHEDULE": { "...": "..." },
  "BOOKING_DIALOG": { "...": "..." }
}

我们来解读这段代码:

  • 这个文件与本课程 [Angular] 和 [React] 变体的文件逐键一一对应(与 DOCTOR_DAY_PICKER/SCHEDULE/BOOKING_DIALOG 中相同的各个部分,出于篇幅原因此处不再重复;详见随附文件),只有两处例外:第 3 行([TITLE]),它现在指的是 [Vue.js] 而不是 [React];以及四个新键([DEMO_ACCOUNTS_*],第 14–17 行),由 Login.vue 显示(见下文),直接在登录界面上展示两个演示账户——这是一个小小的便利功能,本课程的另外两个版本中没有;
  • 一个嵌套的 JSON 对象,每个组件一个部分;[vue-i18n] 把它展平为扁平字典,其中每个完整的键("LOGIN.TITLE")由路径用点号连接而成——与 [i18next] 附加到 [React]、以及 [TranslateService] 附加到 [Angular] 的方式完全一样。

6.7.2. public/i18n/en.json

1
2
3
4
5
6
{
  "APP": {
    "TITLE": "RdvMedecins - NestJS / Vue.js port",
    "...": "..."
  }
}

我们来解读这段代码:

  • 第 3 行:["TITLE": "RdvMedecins - NestJS / Vue.js port",] ——只有副标题变化:“[RdvMedecins]”在两种语言中保持不变;这是应用程序的专有名称。

两个文件在结构上必须保持一致(两者的键相同):这确保每个键在两种语言中都存在。未被翻译的部分与本课程的 [Angular] 和 [React] 变体相比保持不变:[NestJS] 服务器返回的错误消息无论客户端选择哪种语言都保持英文,而医生和患者的姓名则直接来自数据库。

6.8. core/interceptors 层

6.8.1. src/app/core/interceptors/auth.interceptor.ts

[Vue.js] 和 [React] 都没有像 [Angular] 一侧的 [HttpClient]/[withInterceptors([...])] 那样内置的 HTTP 拦截器。这个文件把同样的概念重新实现为封装 [fetch] 的组合式函数:它是原始文档(“示例 6”一章)中已经遇到过的 AngularJS 1.x $http 拦截器的现代等价物。

import { useAuth } from '../composables/auth.composable';

export function useAuthFetch(): (path: string, options?: RequestInit) => Promise<Response> {
  const auth = useAuth();

  return async function authFetch(path: string, options: RequestInit = {}): Promise<Response> {
    const headers = new Headers(options.headers);
    if (auth.accessToken) {
      headers.set('Authorization', `Bearer ${auth.accessToken}`);
    }

    const response = await fetch(path, { ...options, headers });

    if (response.status === 401) {
      auth.logOut();
    }

    return response;
  };
}

我们来解读这段代码:

  • 第 3 行:[export function useAuthFetch(): (path: string, options?: RequestInit) => Promise<Response> {] ——不同于 [authInterceptor] 在 [Angular] 一侧(一个一次性注册在 [app.config.ts] 中的函数,随后会自动应用于对 [HttpClient] 的每次调用),[useAuthFetch()] 是一个组合式函数,每个调用方(这里是 [useAppointmentService()],见下文)必须显式调用它,并用它来代替 [fetch()]——与 [React] 一侧的方式相同;不同于 [React] ([useCallback](...)),这里无需存储所返回的函数:[<script setup>] 的主体对每个组件实例只执行一次,因此该函数也只构造一次;
  • 第 8–10 行:[if (auth.accessToken) { headers.set(‘Authorization’, …); }] ——直接相当于 [request.clone({ setHeaders: { Authorization: … } })] 在 [Angular] 一侧的写法。与(不可变的)[HttpClient] 请求不同,[fetch] 的选项只是一个 JavaScript 对象:无需创建它的“克隆”副本;只要在调用之前构造好 [headers] 对象即可;
  • 第 14–16 行:[if (response.status === 401) { auth.logOut(); }] ——原理与 [Angular] 中相同(catchError + HttpErrorResponse.status === 401):会话期间出现 401,意味着令牌不再有效;客户端会被平稳地断开连接;[fetch] 不会因为 HTTP 状态而把其 Promise 作为错误拒绝(不同于 Observable [HttpClient])——这就是为什么这个测试直接针对 [response.status],而不使用 try/catch 块;
  • 第 18 行:[return response;] ——响应(可能是 401)仍然原样返回给调用方,由调用方负责处理其后果(参见下文的 useAppointmentService()、extract<T>())——拦截器不应向调用代码隐瞒错误。

可以手动把 [Authorization: Bearer ...] 添加到 [useAppointmentService()] 的每个方法中。共享的组合式函数避免了这种重复,带来与 [Angular] 拦截器相同的好处:“如何对请求进行身份验证?”这个问题在单一位置得到解答。

6.9. core/services 层

6.9.1. src/app/core/services/appointment.service.ts

移植 [AppointmentService]:应用程序中唯一的部分(连同负责连接本身的 [core/composables/auth.composable.ts] ),通过 HTTP 与 [NestJS] 通信。它直接相当于原始文档“示例 6:HTTP 服务”一章中介绍的 [dao] 服务(该服务使用 AngularJS 的 $http 服务)。

import { useAuthFetch } from '../interceptors/auth.interceptor';
import { useSettings } from '../composables/settings.composable';
import type { DoctorDaySchedule, Client, Doctor, ServerResponse, AppointmentJson } from '../models/appointment.models';

async function extract<T>(httpResponse: Response): Promise<T> {
  const envelope = (await httpResponse.json()) as ServerResponse<T>;
  if (envelope.status !== 0) {
    throw new Error(`The server responded with error status ${envelope.status}`);
  }
  return envelope.data as T;
}

export function useAppointmentService() {
  const authFetch = useAuthFetch();
  const settings = useSettings();

  async function getAllDoctors(): Promise<Doctor[]> {
    const httpResponse = await authFetch(`${settings.apiBaseUrl}/getAllDoctors`);
    return extract<Doctor[]>(httpResponse);
  }

  async function getAllClients(): Promise<Client[]> {
    const httpResponse = await authFetch(`${settings.apiBaseUrl}/getAllClients`);
    return extract<Client[]>(httpResponse);
  }

  async function getDoctorScheduleOfDay(doctorId: number, day: string): Promise<DoctorDaySchedule> {
    const httpResponse = await authFetch(
      `${settings.apiBaseUrl}/getDoctorScheduleOfDay/${doctorId}/${day}`,
    );
    return extract<DoctorDaySchedule>(httpResponse);
  }

  async function addAppointment(day: string, clientId: number, slotId: number): Promise<AppointmentJson> {
    const httpResponse = await authFetch(`${settings.apiBaseUrl}/addAppointment`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ day, clientId, slotId }),
    });
    return extract<AppointmentJson>(httpResponse);
  }

  async function deleteAppointment(appointmentId: number): Promise<void> {
    const httpResponse = await authFetch(`${settings.apiBaseUrl}/deleteAppointment`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ appointmentId }),
    });
    await extract<null>(httpResponse);
  }

  return { getAllDoctors, getAllClients, getDoctorScheduleOfDay, addAppointment, deleteAppointment };
}

我们来解读这段代码:

  • 第 5 行:[async function extract<T>(httpResponse: Response): Promise<T> {] ——我们不在每个公共函数中重复“如果 status !== 0,则出错”的逻辑,而是在这里只集中处理一次——这正是 [AppointmentService.extract()] 在 [Angular] 中的作用,以及 [extract<T>()] 在 [React] 中的作用;
  • 第 13 行:[export function useAppointmentService() {]——一个组合式函数,其读取和使用方式与 [inject(AppointmentService)] 在 [Angular] 一侧完全一样:在组件的 [<script setup>] 顶部调用一次,然后使用它返回的函数;
  • 第 17–20 行:[async function getAllDoctors(): Promise<Doctor[]> { …] ——不同于 [React] ([useCallback](..., [authFetch, apiBaseUrl])),这些函数都无需在多次渲染之间缓存:[<script setup>] [Vue.js] 对每个组件实例只执行一次(参见上文的 auth.interceptor.ts)——这个技术细节在 [React] 一侧是必需的,而在这里则完全消失了;
  • 每个函数都恰好对应 [NestJS] 控制器(第 3 章)的十一个路由之一——事实上,两侧出现的名称相同(getAllDoctors、addAppointment、deleteAppointment……),这使得服务器端和客户端的比较更容易,就像 [Angular] 和 [React] 那样。

与 [AuthStore.logIn()] (上一章)不同,这个组合式函数中的方法在调用之后都无需保留任何数据:决定如何处理结果(doctors.value = result、schedule.value = result……)的是调用它的组件(App.vue)——这与 [Angular] 和 [React] 中所见的职责分离相同,在那里 [AppointmentService] 和 [useAppointmentService()] 对屏幕上显示的状态一无所知。

6.10. features 层:四个组件

6.10.1. src/app/features/login/Login.vue

移植自 [login.component.ts/.html] ([Angular])和 [Login.tsx] ([React]):登录界面,相当于原始 AngularJS 1.x 客户端的视图 [login.html] (应用程序显示的第一个视图)。这个组件对日程表或预约一无所知:它只收集一对(用户名,密码),把它转交给 [AuthStore.logIn(...)],并显示可能出现的错误。

<script setup lang="ts">
import { ref } from 'vue';
import { useI18n } from 'vue-i18n';
import { useAuth } from '../../core/composables/auth.composable';

const { t } = useI18n();
const auth = useAuth();

const login = ref('');
const password = ref('');
const submitting = ref(false);
const error = ref<string | null>(null);

async function onSubmit(): Promise<void> {
  if (login.value.trim() === '' || password.value === '') {
    return;
  }
  error.value = null;
  submitting.value = true;
  try {
    await auth.logIn(login.value, password.value);
    submitting.value = false;
  } catch {
    submitting.value = false;
    error.value = 'LOGIN.ERROR';
  }
}
</script>

<template>
  <div class="row justify-content-center">
    <div class="col-sm-8 col-md-6 col-lg-4">
      <form class="card p-4" @submit.prevent="onSubmit">
        <h5 class="card-title mb-3">{{ t('LOGIN.TITLE') }}</h5>

        <div v-if="error" class="alert alert-danger py-2" role="alert">
          {{ t(error) }}
        </div>

        <div class="mb-3">
          <label class="form-label" for="input-login">
            {{ t('LOGIN.LOGIN_LABEL') }}
          </label>
          <input id="input-login" type="text" class="form-control"
            autocomplete="username" v-model="login" />
        </div>

        <div class="mb-3">
          <label class="form-label" for="input-password">
            {{ t('LOGIN.PASSWORD_LABEL') }}
          </label>
          <input id="input-password" type="password" class="form-control"
            autocomplete="current-password" v-model="password" />
        </div>

        <button type="submit" class="btn btn-primary w-100" :disabled="submitting">
          {{ submitting ? t('LOGIN.SUBMITTING') : t('LOGIN.SUBMIT') }}
        </button>

        <p class="text-muted small mt-3 mb-0">
          {{ t('LOGIN.DEMO_ACCOUNTS_PREFIX') }} <code>admin</code> / <code>admin</code>
          {{ t('LOGIN.DEMO_ACCOUNTS_ADMIN') }} {{ t('LOGIN.DEMO_ACCOUNTS_OR') }} <code>user</code> /
          <code>user</code> {{ t('LOGIN.DEMO_ACCOUNTS_USER') }}.
        </p>
      </form>
    </div>
  </div>
</template>

我们来解读这段代码:

  • 第 6 行:[const { t } = useI18n();] ——独立的 [Angular] 组件在其装饰器 [@Component] 中声明它所用的管道([imports: [TranslatePipe]]);而 [Vue.js] 组件和 [React] 组件一样,没有任何对应的内容需要声明:[useI18n()] 只是像其他任何函数一样被导入并调用;
  • 第 9–12 行:[const login = ref(''); const password = ref(''); …] ——纯粹属于表单本地的状态(用户当前正在输入的内容)——相当于 [signal()] 本地值在 [Angular] 组件中的作用,以及 [useState()] 在 [React] 一侧的作用(这里是按值使用的 [ref] ,而不是 [value, setValue] 对);
  • 第 33 行:[@submit.prevent="onSubmit"] ——与本课程的 [Angular] 变体刻意不同:这个组件不是分别监听每个字段(keyup.enter),而是使用真正的 <form> 元素及其原生事件 [submit]——回车键和点击“登录”按钮(type="submit")都会触发 [onSubmit()];[.prevent] 修饰符会自动阻止浏览器的默认行为(重新加载页面)——相当于显式的客户端 [event?.preventDefault()],但直接在 [<template>] 中表达,而不是在 TypeScript 代码中;
  • 第 44–45 行:[autocomplete="username" v-model="login"] ——[v-model] 在单个属性中把字段与 [login] [ref] 双向关联起来(既读取又写入)——相比 [React] ([value={login} onChange={(e) => setLogin(e.target.value)}],两个独立的属性)和 [Angular] ([[(ngModel)]] 或 [[value]]+(input),视情况而定)的写法,这是一种简化;
  • 第 23–26 行:[catch { submitting.value = false; error.value = ‘LOGIN.ERROR’; }] ——无效的用户名/密码对会使 [logIn()] 因 JavaScript 异常而失败(由 auth.composable.ts 抛出,见上文):向用户显示“LOGIN.ERROR”,而不尝试区分用户名不存在和密码错误——与 [Angular] 和 [React] 的做法完全相同。存储翻译键而不是已经解析好的文本,与另外两个变体中一样有好处:如果用户在显示此消息时切换语言,它会自动翻译自己([t(error)],第 37 行,会自动重新求值)。

这个组件把 [Angular] 拆成两个文件的内容(login.component.ts 用于逻辑,login.component.html 用于模板)合并到了单个 [.vue] 文件中:[<template>] 用于模板,[<script setup>] 用于逻辑,二者在同一个文件中——就像 [Login.tsx] 在 [React] 一侧借助其函数返回的 [JSX] 已经做到的那样。

6.10.2. src/app/features/doctor-day-picker/DoctorDayPicker.vue

移植自 [doctor-day-picker.component.ts/.html] ([Angular])和 [DoctorDayPicker.tsx] ([React]):该组件可让你选择医生和日期,然后请求查看其日程。在概念上相当于原始 AngularJS 1.x 客户端的示例 7 到示例 10。

<script setup lang="ts">
import { ref } from 'vue';
import { useI18n } from 'vue-i18n';
import type { Doctor } from '../../core/models/appointment.models';

defineProps<{
  doctors: Doctor[];
}>();

const emit = defineEmits<{
  search: [criteria: { doctorId: number; day: string }];
}>();

const { t } = useI18n();

const selectedDoctorId = ref<number | null>(null);
const selectedDay = ref<string>(
  new Date().toISOString().slice(0, 10),
);

function onSearchClick(): void {
  if (selectedDoctorId.value === null) {
    return;
  }
  emit('search', { doctorId: selectedDoctorId.value, day: selectedDay.value });
}
</script>

<template>
  <div class="card p-3 mb-3">
    <div class="row g-2 align-items-end">
      <div class="col-sm-5">
        <label class="form-label" for="select-doctor">
          {{ t('DOCTOR_DAY_PICKER.DOCTOR_LABEL') }}
        </label>
        <select id="select-doctor" class="form-select" v-model="selectedDoctorId">
          <option :value="null">{{ t('DOCTOR_DAY_PICKER.CHOOSE_DOCTOR') }}</option>
          <option v-for="doctor in doctors" :key="doctor.id" :value="doctor.id">
            {{ doctor.title }} {{ doctor.firstName }} {{ doctor.lastName }}
          </option>
        </select>
      </div>

      <div class="col-sm-4">
        <label class="form-label" for="input-day">
          {{ t('DOCTOR_DAY_PICKER.DAY_LABEL') }}
        </label>
        <input id="input-day" type="date" class="form-control" v-model="selectedDay" />
      </div>

      <div class="col-sm-3">
        <button type="button" class="btn btn-primary w-100"
          :disabled="selectedDoctorId === null" @click="onSearchClick">
          {{ t('DOCTOR_DAY_PICKER.VIEW_SCHEDULE') }}
        </button>
      </div>
    </div>
  </div>
</template>

我们来解读这段代码:

  • 第 6–8 行:[defineProps<{ doctors: Doctor[]; }>();] ——[Angular] 的 [input.required<Doctor[]>()] 变成 [Vue.js] 的 prop;不同于 [React] (解构的 `props` 对象,没有单独的类型声明),[defineProps<...>()] 是在编译时被 [Vue.js] 编译器识别的函数:它在最终的 JavaScript 中甚至不再存在;
  • 第 10–12 行:[const emit = defineEmits<{ search: [criteria: { … }]; }>();] ——[output<...>()] [Angular] 在这里变成声明的事件——[App.vue] 将通过 [@search="onSearchSchedule"] 监听它(见下文),就像它订阅 [Angular] 模板的 (search) 事件一样;而在 [React] 中,它是一个简单的 prop 函数([onSearch])——[Vue.js] 在这里更显式地区分输入和输出,与 [Angular] 类似;
  • 第 21–26 行:[function onSearchClick(): void { … emit(‘search’, { … }); }] ——[emit(‘search’, ...)] 触发事件——直接相当于 [search.emit(...)] 在 [Angular] 一侧的写法,以及作为 prop 接收的函数调用([onSearch(...)])在 [React] 一侧的写法;
  • 第 36 行:[select id="select-doctor" class="form-select" v-model="selectedDoctorId"] ——在 <select> 上使用 [v-model] 可直接把所选的值与 [selectedDoctorId.value] 关联起来——相比 [React](单独的 :value 和 @change,参见上一章)以及 [Angular] ([(ngModel)] 或 [value]+(change),视情况而定)的写法,这是一种简化;
  • 第 38–40 行:[option v-for="doctor in doctors" :key="doctor.id" :value="doctor.id"] ——[v-for] + [:key] 相当于[Vue.js] 中的 [.map(...)] + [key={...}] 在 [React] 一侧(以及 [@for (doctor of doctors(); track doctor.id)] 在 [Angular] 一侧):在这三种情况下,都由一个稳定的标识符来指明,重绘时如何识别已经显示的医生。

6.10.3. src/app/features/schedule/Schedule.vue

移植自 [schedule.component.ts/.html] ([Angular])和 [Schedule.tsx] ([React]):显示某位医生在指定日期的日程。相当于原始 AngularJS 1.x 客户端的示例 8 和示例 9。由于加入了身份验证,这个组件还接收 [canEdit]:当它被设为 false(角色 USER)时,“预约”/“取消”按钮会消失——日程仍然可以查看,但处于只读模式。

<script setup lang="ts">
import { useI18n } from 'vue-i18n';
import type { DoctorDaySchedule, ScheduleSlot, SlotJson, AppointmentJson } from '../../core/models/appointment.models';

defineProps<{
  schedule: DoctorDaySchedule | null;
  canEdit: boolean;
}>();

const emit = defineEmits<{
  book: [slot: SlotJson];
  cancel: [appointment: AppointmentJson];
}>();

const { t } = useI18n();

function formatTime(h: number, m: number): string {
  return `${h}:${m.toString().padStart(2, '0')}`;
}

function onSlotClick(scheduleSlot: ScheduleSlot, canEdit: boolean): void {
  if (!canEdit) {
    return;
  }
  if (scheduleSlot.appointment === null) {
    emit('book', scheduleSlot.slot);
  } else {
    emit('cancel', scheduleSlot.appointment);
  }
}
</script>

<template>
  <p v-if="schedule === null" class="text-muted">{{ t('SCHEDULE.EMPTY_STATE') }}</p>

  <div v-else class="card p-3">
    <h5>
      {{ t('SCHEDULE.TITLE_PREFIX') }} {{ schedule.day }} - {{ schedule.doctor.title }}
      {{ schedule.doctor.firstName }} {{ schedule.doctor.lastName }}
    </h5>

    <table class="table table-hover align-middle">
      <thead>
        <tr>
          <th>{{ t('SCHEDULE.COLUMN_SLOT') }}</th>
          <th>{{ t('SCHEDULE.COLUMN_STATUS') }}</th>
          <th></th>
        </tr>
      </thead>
      <tbody>
        <tr v-for="scheduleSlot in schedule.slots" :key="scheduleSlot.slot.id"
          :class="scheduleSlot.appointment === null ? 'free-slot' : undefined">
          <td>
            {{ formatTime(scheduleSlot.slot.startHour, scheduleSlot.slot.startMinute) }} -
            {{ formatTime(scheduleSlot.slot.endHour, scheduleSlot.slot.endMinute) }}
          </td>
          <td>
            <span v-if="scheduleSlot.appointment === null" class="badge text-bg-success">
              {{ t('SCHEDULE.FREE') }}
            </span>
            <span v-else class="badge text-bg-secondary">
              {{ scheduleSlot.appointment.client?.title }} {{ scheduleSlot.appointment.client?.firstName }}
              {{ scheduleSlot.appointment.client?.lastName }}
            </span>
          </td>
          <td>
            <button v-if="canEdit" type="button"
              :class="'btn btn-sm ' + (scheduleSlot.appointment === null ? 'btn-outline-success' : 'btn-outline-danger')"
              @click="onSlotClick(scheduleSlot, canEdit)">
              {{ scheduleSlot.appointment === null ? t('SCHEDULE.BOOK') : t('SCHEDULE.CANCEL_APPOINTMENT') }}
            </button>
          </td>
        </tr>
      </tbody>
    </table>
  </div>
</template>

我们来解读这段代码:

  • 第 34、36 行:[p v-if="schedule === null" … div v-else …] ——[v-if]/[v-else] 取代了 [React] 中使用的“提前返回”([if (schedule === null) return <p>...</p>;]):只要尚未执行任何搜索(或日程为空),DOM 中就只包含空状态消息,甚至不会构造后面的表格;
  • 第 7 行:[canEdit: boolean;] ——身份验证引入的新特性,与 [Angular] 和 [React] 中类似:App.vue 向它传入 [auth.isAdmin](见下文)。当它被设为 false(角色 USER)时,“预约”/“取消”按钮在 DOM 中根本不存在(第 67 行,[v-if="canEdit"])——它不只是变灰或被禁用,而是完全缺失;
  • 第 58–64 行:[span v-if="scheduleSlot.appointment === null" … span v-else …] ——[v-if]/[v-else] 取代了 [React] 一侧使用的三元运算符——根据时间段的状态,显示绿色的 [Bootstrap] 徽章(“空闲”)或灰色徽章(患者姓名);
  • 第 67 行:[button v-if="canEdit" type="button"] ——不同于 [React] (运算符 [&&],{canEdit && (…)}),在 [v-if] 这里单独使用 [Vue.js] 就足够了:在 [Vue.js] 中没有可用于“仅在为真时显示,否则什么都不显示”的 [&&] 等价物——[v-if] 自己就能做到这一点;
  • 第 70 行:[{{ scheduleSlot.appointment === null ? t('SCHEDULE.BOOK') : t('SCHEDULE.CANCEL_APPOINTMENT') }}] ——与 [Angular] 一侧(管道可用于任何模板表达式)和 [React] 一侧一样,[t(...)] 是标准的 JavaScript 函数:可以直接用在 [{{ }}] 表达式中,无需任何特殊语法。

这个组件本身不发出任何 HTTP 调用:它显示通过 props 接收的数据,并通过 [book]/[cancel] 事件 向其父组件(App.vue)通知用户的意图——这与 [Angular] 和 [React] 之间的职责分离完全相同。

6.10.4. src/app/features/booking-dialog/BookingDialog.vue

移植自 [booking-dialog.component.ts/.html] ([Angular])和 [BookingDialog.tsx] ([React]):用于选择患者以预约可用时间段的(模态)窗口。相当于原始 AngularJS 1.x 客户端的示例 9。

<script setup lang="ts">
import { ref } from 'vue';
import { useI18n } from 'vue-i18n';
import type { Client, SlotJson } from '../../core/models/appointment.models';

defineProps<{
  open: boolean;
  slot: SlotJson | null;
  clients: Client[];
}>();

const emit = defineEmits<{
  confirm: [choice: { clientId: number }];
  close: [];
}>();

const { t } = useI18n();
const selectedClientId = ref<number | null>(null);

function onConfirmClick(): void {
  if (selectedClientId.value === null) {
    return;
  }
  emit('confirm', { clientId: selectedClientId.value });
  selectedClientId.value = null;
}

function onCloseClick(): void {
  selectedClientId.value = null;
  emit('close');
}
</script>

<template>
  <template v-if="open">
    <div class="modal-backdrop fade show"></div>

    <div class="modal fade show d-block" tabindex="-1" role="dialog" aria-modal="true">
      <div class="modal-dialog modal-dialog-centered">
        <div class="modal-content">
          <div class="modal-header">
            <h5 class="modal-title">{{ t('BOOKING_DIALOG.TITLE') }}</h5>
            <button type="button" class="btn-close"
              :aria-label="t('BOOKING_DIALOG.CLOSE_ARIA')" @click="onCloseClick"></button>
          </div>

          <div class="modal-body">
            <p v-if="slot">
              {{ t('BOOKING_DIALOG.SLOT_FROM') }} {{ slot.startHour }}:{{
                slot.startMinute.toString().padStart(2, '0')
              }}
              {{ t('BOOKING_DIALOG.SLOT_TO') }} {{ slot.endHour }}:{{
                slot.endMinute.toString().padStart(2, '0')
              }}
            </p>

            <label class="form-label" for="select-client">
              {{ t('BOOKING_DIALOG.PATIENT_LABEL') }}
            </label>
            <select id="select-client" class="form-select" v-model="selectedClientId">
              <option :value="null">{{ t('BOOKING_DIALOG.CHOOSE_PATIENT') }}</option>
              <option v-for="client in clients" :key="client.id" :value="client.id">
                {{ client.title }} {{ client.firstName }} {{ client.lastName }}
              </option>
            </select>
          </div>

          <div class="modal-footer">
            <button type="button" class="btn btn-secondary" @click="onCloseClick">
              {{ t('BOOKING_DIALOG.CANCEL') }}
            </button>
            <button type="button" class="btn btn-primary"
              :disabled="selectedClientId === null" @click="onConfirmClick">
              {{ t('BOOKING_DIALOG.CONFIRM') }}
            </button>
          </div>
        </div>
      </div>
    </div>
  </template>
</template>

我们来解读这段代码:

  • 第 35 行:[template v-if="open"] ——一个 [<template>]([Vue.js] 特有的标签,其本身不生成任何元素)承载着 [v-if]:在模态窗口打开之前,DOM 中甚至什么都不会加载——完全相当于 [if (!open) return null;] 在 [React] 一侧的写法,以及 [@if(open())] 在 [Angular] 一侧的写法;
  • 第 36 行:[div class="modal-backdrop fade show"] ——使页面其余部分变暗的半透明背景——这里与另外两个变体一样是硬编码的,而 [Bootstrap] 通常会在显示模态窗口时通过 JavaScript 自行插入它;
  • 第 38 行:[div class="modal fade show d-block"] ——[d-block] 承担了通常由 [Bootstrap] 的 JavaScript 完成的角色(在打开时添加 [display:block] )——在这里,直接履行这一角色的是第 35 行的 [v-if];
  • 第 44 行:[:aria-label="t(‘BOOKING_DIALOG.CLOSE_ARIA’)"] ——不同于 [attr.aria-label="‘BOOKING_DIALOG.CLOSE_ARIA’ | translate"] 在 [Angular] 一侧的写法(与 {{ }} 插值不同的属性绑定),而与 [JSX] 和 [React] (它们不区分属性和元素内容)颇为相似,[Vue.js] 这里使用 [:aria-label="..."]——前缀 [:] 表示属性绑定(一个 JavaScript 表达式),而不是字面字符串。

与另外两个变体一样,这个组件使用模态窗口的真实 [Bootstrap] 类,但其可见性由 [Vue.js]([v-if] 作用于 [open] 属性)控制,而不是由 [Bootstrap] 的 JavaScript([bootstrap.bundle.js, new bootstrap.Modal(...)])控制——以防止二者各自独立地管理同一条信息(模态窗口是否打开?),这是细微 bug 的常见来源。原始文档(2014 年)使用的是 angular-ui-bootstrap 库中的组件(一个“开箱即用”的模态窗口),它已经是按照同样的原则设计的。

6.11. 根 App 组件:协调者与身份验证守门人

这个组件承担着原始 AngularJS 1.x 应用程序中“主控制器”所起的作用,也相当于 [Angular] 和 [React] 两侧的 App 组件:它维护应用程序的全局状态,并响应 features/ 组件的事件,在适当的时机调用 [useAppointmentService()] 。自从加入身份验证后,它还承担了第二个角色:作为表示层上的“守门人”,决定是显示登录界面还是应用程序的其余部分。[Vue.js] 组件把 [.vue] 文件中的内容合并为单个文件,而 [Angular] 把它拆分为三个文件(app.ts、app.html、app.css)——正如 App.tsx 此前已对 [React] 所做的那样。

6.11.1. src/app/App.vue

<script setup lang="ts">
import { ref, watch } from 'vue';
import { useI18n } from 'vue-i18n';
import { useAuth } from './core/composables/auth.composable';
import { useSettings } from './core/composables/settings.composable';
import { useLanguage } from './core/composables/language.composable';
import { useAppointmentService } from './core/services/appointment.service';
import type { DoctorDaySchedule, Client, SlotJson, Doctor, AppointmentJson } from './core/models/appointment.models';
import DoctorDayPicker from './features/doctor-day-picker/DoctorDayPicker.vue';
import Schedule from './features/schedule/Schedule.vue';
import BookingDialog from './features/booking-dialog/BookingDialog.vue';
import Login from './features/login/Login.vue';

const { t } = useI18n();
const auth = useAuth();
const settings = useSettings();
const language = useLanguage();
const api = useAppointmentService();

const doctors = ref<Doctor[]>([]);
const clients = ref<Client[]>([]);
const schedule = ref<DoctorDaySchedule | null>(null);
const error = ref<string | null>(null);
const slotBeingBooked = ref<SlotJson | null>(null);
const lastDoctorId = ref<number | null>(null);
const lastDay = ref<string | null>(null);

watch(
  () => auth.isLoggedIn,
  (isLoggedIn) => {
    if (isLoggedIn) {
      loadInitialLists();
    }
  },
  { immediate: true },
);

function loadInitialLists(): void {
  api
    .getAllDoctors()
    .then((result) => (doctors.value = result))
    .catch((err: unknown) => (error.value = String((err as Error).message ?? err)));

  api
    .getAllClients()
    .then((result) => (clients.value = result))
    .catch((err: unknown) => (error.value = String((err as Error).message ?? err)));
}

function onLogout(): void {
  auth.logOut();
  doctors.value = [];
  clients.value = [];
  schedule.value = null;
  error.value = null;
  slotBeingBooked.value = null;
  lastDoctorId.value = null;
  lastDay.value = null;
}

function onSearchSchedule(criteria: { doctorId: number; day: string }): void {
  error.value = null;
  lastDoctorId.value = criteria.doctorId;
  lastDay.value = criteria.day;
  loadSchedule();
}

function onBookingRequest(slot: SlotJson): void {
  slotBeingBooked.value = slot;
}

function onConfirmBooking(choice: { clientId: number }): void {
  if (slotBeingBooked.value === null || lastDay.value === null) {
    return;
  }
  api
    .addAppointment(lastDay.value, choice.clientId, slotBeingBooked.value.id)
    .then(() => {
      slotBeingBooked.value = null;
      loadSchedule();
    })
    .catch((err: unknown) => (error.value = String((err as Error).message ?? err)));
}

function onCloseBooking(): void {
  slotBeingBooked.value = null;
}

function onCancelAppointment(appointment: AppointmentJson): void {
  api
    .deleteAppointment(appointment.id)
    .then(() => loadSchedule())
    .catch((err: unknown) => (error.value = String((err as Error).message ?? err)));
}

function loadSchedule(): void {
  if (lastDoctorId.value === null || lastDay.value === null) {
    return;
  }
  api
    .getDoctorScheduleOfDay(lastDoctorId.value, lastDay.value)
    .then((result) => (schedule.value = result))
    .catch((err: unknown) => (error.value = String((err as Error).message ?? err)));
}
</script>

<template>
  <div class="container py-4">
    <nav class="navbar navbar-expand-sm navbar-dark bg-primary rounded mb-4 px-3">
      <span class="navbar-brand mb-0">{{ t('APP.TITLE') }}</span>

      <div class="d-flex align-items-center gap-2">
        <div class="btn-group btn-group-sm" role="group" aria-label="FR / EN">
          <button type="button"
            :class="'btn ' + (language.currentLanguage === 'fr' ? 'btn-light' : 'btn-outline-light')"
            @click="language.changeLanguage('fr')">
            FR
          </button>
          <button type="button"
            :class="'btn ' + (language.currentLanguage === 'en' ? 'btn-light' : 'btn-outline-light')"
            @click="language.changeLanguage('en')">
            EN
          </button>
        </div>

        <template v-if="auth.isLoggedIn">
          <span class="badge text-bg-light text-primary">{{ auth.role }}</span>
          <span class="text-white">{{ auth.name }}</span>
          <button type="button" class="btn btn-sm btn-outline-light" @click="onLogout">
            {{ t('APP.LOGOUT') }}
          </button>
        </template>
      </div>
    </nav>

    <div class="row g-2 align-items-center mb-4">
      <div class="col-auto">
        <label class="form-label mb-0" for="input-server-url">
          {{ t('APP.SERVER_URL_LABEL') }}
        </label>
      </div>
      <div class="col-sm-4">
        <input id="input-server-url" type="text" class="form-control form-control-sm"
          v-model="settings.apiBaseUrl" />
      </div>
    </div>

    <div v-if="error" class="alert alert-danger" role="alert">
      {{ error }}
    </div>

    <Login v-if="!auth.isLoggedIn" />

    <template v-else>
      <DoctorDayPicker :doctors="doctors" @search="onSearchSchedule" />

      <Schedule
        :schedule="schedule"
        :can-edit="auth.isAdmin"
        @book="onBookingRequest"
        @cancel="onCancelAppointment"
      />

      <BookingDialog
        :open="slotBeingBooked !== null"
        :slot="slotBeingBooked"
        :clients="clients"
        @confirm="onConfirmBooking"
        @close="onCloseBooking"
      />
    </template>
  </div>
</template>

我们来解读这段代码:

  • 第 25–26 行:[const lastDoctorId = ref<number | null>(null); const lastDay = ref<string | null>(null);] ——我们保存最近一次搜索(医生 + 日期),以便在预约或取消之后刷新日程表。与 [React] (使用 [useRef](),而不是 [useState]())一样,这两个值从不直接用于显示(不同于日程表或错误页面)——但是,不同于 [React],[Vue.js] 不需要为一个能在多次渲染之间保留、且不触发重绘的变量使用特殊的 Hook([useRef]):因为 [<script setup>] 对每个组件实例只运行一次(不同于每次渲染都会重新执行的 [React] 组件函数),一个简单的 JavaScript 变量(let)同样可行;[ref()] 在这里使用,只是为了与文件其余部分保持一致;
  • 第 28–36 行:[watch(() => auth.isLoggedIn, (isLoggedIn) => { if (isLoggedIn) { loadInitialLists(); } }, { immediate: true });] ——每当 [auth.isLoggedIn] 变化时就重新执行其函数体——直接相当于 [effect(() => { if (this.auth.isLoggedIn()) { … } })] 在 [Angular] 一侧的写法,以及 [useEffect](..., [auth.isLoggedIn]) 在 [React] 一侧的写法。[{ immediate: true }] 还会使它在第一次时立即运行,而无需等待变化——这与 [useEffect]() 在 [React] 一侧的行为完全相同(后者至少总会在初始化时运行一次):如果 [localStorage] 中已存有会话(页面重新加载),则启动时列表会立即加载,而无需等待登录;
  • 第 112–133 行:[div class="btn-group btn-group-sm" … FR … EN … template v-if="auth.isLoggedIn" …] ——语言选择器始终可见(包括在登录界面上);而角色徽章 + 姓名 + 退出按钮,则仅在 [auth.isLoggedIn] 为真时才显示(第 126–132 行,[template v-if="auth.isLoggedIn"])——逻辑与 [Angular] 和 [React] 完全相同;
  • 第 152 行:[Login v-if="!auth.isLoggedIn"] ——只要 [useAuth().isLoggedIn] 为 false,这个组件就只显示 <Login />;由于现在所有服务器路由都受 [JwtAuthGuard] (第 3 章)保护,在登录之前加载医生/客户/日程表无论如何都是没有意义的(还会导致 401 错误)——理由与 [Angular] 和 [React] 完全相同;
  • 第 154–171 行:[template v-else … DoctorDayPicker … Schedule … BookingDialog …] ——features/ 中的三个“业务逻辑”组件在这里被组装起来,每个组件接收自己的 props(数据,以 [:] 为前缀)和自己的事件处理函数(以 [@] 为前缀)——完全相当于 [Angular] 一侧的 app.html 模板,在那里同样的三个组件以 [doctors]="doctors()" (search)="onSearchSchedule($event)"…… 的形式出现。

状态([ref])、副作用([watch])和事件处理函数(各个 onXxx 函数):这些正是上一章已经介绍过的同一批元素,在这里应用于整个根组件——这个文件中没有引入任何新内容;只是把它们组装了起来。

6.12. 应用程序使用分步指南

以下屏幕截图是按照与本课程 [Angular] 和 [React] 变体完全相同的操作序列,在这个 [Vue.js] 客户端上获得的:服务器 URL 保持默认值(http://localhost:8080),演示账户为 admin/admin 和 user/user。

6.12.1. 1. 登录界面

页面首次加载时,[useAuth().isLoggedIn] 为 false(localStorage 中没有会话):只显示 <Login />。

Image

登录界面

使用无效的用户名/密码组合尝试登录,会显示 Login.vue 所存储的错误消息:

Image

登录错误

仍然可见的 FR/EN 选择器也会翻译这个界面(以及所存储的错误消息,它无需额外代码即可重新翻译;参见上文的 Login.vue):

Image

法语登录界面

6.12.2. 2. 以管理员身份登录(角色 ADMIN,完全访问)

使用 admin/admin 登录后,App.vue 不再显示 <Login />,而是加载医生/客户([loadInitialLists()],由第 28 行的 [watch(() => auth.isLoggedIn, …, { immediate: true })] 触发):

Image

以 ADMIN 登录后的主页

Image

以 ADMIN 登录后的主页(法语)

在 <DoctorDayPicker /> 中选择医生和日期后,会显示带有“预约”/“取消”按钮的日程表(对于角色 ADMIN,canEdit 为 true):

Image

日程表,ADMIN 视图(“预约”/“取消”按钮可见)

点击“预约”会打开 <BookingDialog />([open] 变为 true;参见 App.vue 中的 [onBookingRequest] ):

Image

预约窗口(Bootstrap 模态窗口)

确认后([onConfirmBooking] 调用 [api.addAppointment(...)],然后 [loadSchedule()] 刷新显示),该时间段就显示为已预约:

Image

预约之后的日程表

点击“取消”([onCancelAppointment] 调用 [api.deleteAppointment(...)])会使该时间段重新变为可预约:

Image

取消之后的日程表

6.12.3. 3. 以用户身份登录(角色 USER,只读)

退出登录(onLogout)后,使用 user/user 账户登录,会显示不同的“USER”徽章:

Image

以 USER 登录后的主页

日程表仍然可以查看,但不会出现“预约”/“取消”按钮:每个时间段的操作列都是空的(参见 Schedule.vue,按钮上的 [v-if="canEdit"] )。直接向服务器发出的请求(例如,使用 Postman 并提供该用户的令牌)仍然会收到 403 Forbidden 响应——隐藏按钮只是为了显示上的便利;真正的限制由服务器端的 [RolesGuard] 强制执行(第 3 章):

Image

日程表,USER 视图(只读,没有操作按钮)

6.13. 未纳入范围或已推迟的内容

原始 AngularJS 1.x 客户端的“调试”模式(显示当前视图的原始模板)是一项被有意从本次移植中省略的功能,与本课程的 [Angular] 和 [React] 变体一样——它不会在课程的后续阶段出现(该决定的理由见第 6 章“结论”)。不过,人为网络延迟的配置在三个变体中确实都推迟到了后续阶段。

此外,这个 [Vue.js] 移植版本还有两处特有的差异,值得在这里一提:

  • 单元测试(本项目中没有,本课程的 [Angular] 和 [React] 项目中也没有)在 [Vue.js] 中会采用不同的方式:它不用 TestBed([Angular] 特有)或 [React Testing Library] ([React]),[Vue.js] 生态系统通常依赖 [Vue Test Utils]——本文档不作介绍;
  • [<template>] 的类型检查在这里有特殊地位:不同于 [React](标准的 TypeScript 编译器就足够了,因为 [JSX] 只是 JavaScript 的又一种形式),[Vue.js] 专门为此提供了 [vue-tsc] (参见 package.json,第 5 章),用来检查 [<template>] 内部的类型——就这一点而言,这种情形更接近 [Angular] 和 strictTemplates,而不是 [React],尽管它是一个单独的工具,而不是编译器本身的一个选项。