Skip to content

6. 第 5 章 - [RdvMedecins] 应用的 [React] 客户端

本章逐个文件详细介绍本文档附带的 [rdvmedecins-react-client] 文件夹的内容,采用本课程一贯的格式:逐行编号的源代码,后面是“我们来解读这段代码:”一节。项目中的每个文件夹也都包含自己的 [README.md]。

6.1. 架构概览

与原文档一样,客户端遵循分层架构,我们在这里称之为 V-Services(视图-服务):

Image

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

与原文档一样,组件绝不直接与服务器通信:这一职责专属于服务层(这里是 Hook useAppointmentService() 和上下文 AuthContext)。这是一条设计原则,同样适用于 AngularJS 1.x 以及 [Angular] 和 [React]——它没有改变。

6.2. 项目结构树

Image

Image

这种划分直接遵循原文档的流程(登录、选择医生/日期、显示日程表、预约),只是在这里组织为 [React] 函数组件,而不是 AngularJS 1.x 的独立控制器/视图,或 [Angular] 的独立组件。与本课程 [Angular] 的目录结构相比,有两处结构上的差异:

  • 根组件由 三个 文件(App.tsx、App.css、README.md)组成,而不是五个(app.ts、app.html、app.css、app.config.ts、app.routes.ts):[JSX] 把类和模板合并在一起,并且 [React] 没有与 app.config.ts 对应的应用配置文件(见下文的“应用配置”);
  • 出现了一个 `core/context/` 文件夹,它在 [Angular] 变体中是没有的:它包含自定义 Hook 和 [React] [Context] 文件 ,它们充当 [SettingsService]、[AuthService]、[LanguageService] 等可注入服务(属于 [Angular] 变体)——这一机制(Hook + [Context])已在上一章中连同一个通用示例一起介绍过(见上一章的“共享逻辑”)。

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

6.3. 项目配置文件

Image

6.3.1. package.json

{
  "name": "rdvmedecins-react-client",
  "version": "0.0.0",
  "private": true,
  "type": "module",
  "scripts": {
    "dev": "vite",
    "start": "vite",
    "build": "tsc -b && vite build",
    "preview": "vite preview"
  },
  "dependencies": {
    "i18next": "^25.0.0",
    "i18next-http-backend": "^3.0.0",
    "react": "^19.1.0",
    "react-dom": "^19.1.0",
    "react-i18next": "^15.0.0",
    "bootstrap": "^5.3.3"
  },
  "devDependencies": {
    "@types/react": "^19.1.0",
    "@types/react-dom": "^19.1.0",
    "@vitejs/plugin-react": "^5.0.0",
    "typescript": "~5.9.0",
    "vite": "^6.4.0"
  }
}

我们来解读这段代码:

  • 第 5 行:"type": "module", ——告诉 Node,该项目原生使用 ECMAScript 模块(import/export),无需任何预先转换——[Angular] CLI 项目也在其自己的工具集中隐式地定义了这一设置;
  • 第 6–11 行:"scripts": { … } ——可用的 [npm run <name>] 命令。[start] (与 `dev` 相同)启动 [Vite] 开发服务器,每当源文件被修改时自动重新加载([Vite] 把这种机制称为热模块替换,Hot Module Replacement)——这是本文档全程使用的命令,使用 4200 端口(见下文的 [vite.config.ts] ),与本课程的 [Angular] 变体端口相同;
  • 第 12–19 行:"dependencies": { … } ——在浏览器中运行应用所需的包:[react]/[react-dom]([React] 的核心及其与浏览器 DOM 的集成)、[Bootstrap] (仅样式表),以及——本章新增的——[i18next]/[i18next-http-backend]/[react-i18next],即用于界面 FR/EN 翻译的第三方库(见下文的 i18n.ts 和 core/context/language.context.tsx)。与本课程的 [Angular] 变体不同,这里没有与 [@angular/router] 对应的包(没有 路由器;见上一章),也没有 RxJS([fetch] 直接返回 Promise;见上一章);
  • 第 20–26 行:"devDependencies": { … } ——仅在开发期间需要的包,绝不会包含在交付给浏览器的最终包中:TypeScript 和 [React] 的类型([@types/react]、[@types/react-dom]——[React] 本身是用 JavaScript 而不是 TypeScript 编写的,不同于 [Angular])、[@vitejs/plugin-react] (把 [JSX] 转换为 JavaScript,并在开发期间提供 Fast Refresh)、TypeScript,以及 [Vite] 本身。

与 [NestJS] 服务器([commonjs] 模块,见第 3 章)不同,这个项目运行在原生的 ECMAScript 模块(import/export)上——与本课程的 [Angular] 变体完全一样(tsconfig.json 中的 “module”: “preserve”,见下文)。

6.3.2. vite.config.ts

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

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

我们来解读这段代码:

  • 第 5 行:plugins: [react()], ——启用 [JSX]/[TSX] 的转换和热重载——相当于 [React] 方面,@angular/build:dev-server 在后台为 [Angular] 所做的事情(见本课程 [Angular] 变体的 angular.json);
  • 第 6–8 行:server: { port: 4200, }, ——把开发服务器的端口设为 4200,与 [ng serve] 在 [Angular] 方面相同——这纯粹是出于教学考虑,使本课程的两个变体可以互换,而无需改变您的工作流程。

这个文件在原 AngularJS 1.x 项目中没有对应物(当时的构建工具——Grunt、Gulp——是单独配置的);在本课程的 [Angular] 方面,起这个作用的是 [angular.json] ;在 [NestJS] 方面(第 3 章),则是 [nest-cli.json]。

6.3.3. tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "preserve",
    "jsx": "react-jsx",
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true,
    "skipLibCheck": true,
    "moduleResolution": "bundler",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true
  },
  "include": ["src"]
}

我们来解读这段代码:

  • 第 5 行:"jsx": "react-jsx", ——告诉 TypeScript 编译器如何转换 [JSX];[react-jsx] 是现代的设置(自 React 17 起),它消除了在每个使用 [import React from 'react'] 的 .tsx 文件中编写 [JSX] 的必要——相比最早的 [React] 项目,这是一点小小的简化;
  • 第 6 行:"strict": true, ——与本课程 [tsconfig.json] 中 [Angular] 变体的配置一样,启用了 TypeScript 的完整严格模式:每个变量都必须具有可确定的类型,每个 null 或 undefined 值都必须被显式处理;
  • 第 7–8 行:"noUnusedLocals": true, "noUnusedParameters": true, ——在编译期间标记任何已声明但从未使用的变量或参数——本课程的 [Angular] 变体没有显式启用这一设置([Angular] 编译器通过 strictTemplates 有自己不同的检查);
  • 第 14 行:"noEmit": true ——这里使用 TypeScript 仅用于类型检查([npm run build] 首先运行 `tsc -b`,如果存在类型错误它就会失败):真正生成浏览器所执行的 JavaScript 的是 [Vite] (通过 esbuild),而不是 TypeScript 编译器本身——这与 [Angular](ngc)有显著区别,后者自己生成最终的 JavaScript。

本课程的 [Angular] 变体把 [tsconfig.json] (公共基础)和 [tsconfig.app.json] (通过项目引用机制)分开,而这个较小的 [React] 项目只有一个文件——因为无论如何,模板的类型检查([Angular] 和 strictTemplates)在这里都没有对应物:检查 [JSX] 的是 TypeScript 编译器本身,就像检查任何其他 .tsx 文件一样。

6.4. 启动应用

Image

6.4.1. index.html

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <link rel="icon" type="image/x-icon" href="/favicon.ico" />
    <title>RdvMedecins - React client</title>
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="/src/main.tsx"></script>
  </body>
</html>

我们来解读这段代码:

  • 第 2 行:<html lang="en"> ——与 [Angular] 中一样,由于这个页面(HTML)是静态的(在 [React] 应用甚至还没有启动之前就已被浏览器加载),它无法立即反映用户之后所做的语言选择;
  • 第 10 行:<div id="root"></div> ——这个页面最初包含的唯一元素,[React] 在启动后会完全填充它(见下文的 [main.tsx] )——它完全等价于 [Angular] 方面的 <app-root></app-root>,以及原文档(AngularJS 1.x,2014)中 <html> 标签上的 [ng-app="rdvmedecinsApp"] 。
  • 第 11 行:<script type="module" src="/src/main.tsx"></script> ——与本课程 [Angular] 变体相比的第一个显著区别:直接引用 main.tsx 的是 index.html (这是 [Vite] 特有的约定),而不是反过来(由 [Angular] 构建过程把预编译的 JavaScript 包注入页面)。在开发期间,[Vite] 会即时转换并提供这个 .tsx 文件;在生产环境(npm run build)中,它当然是事先编译好的。

与 [Angular] 一样,整个应用只有一个入口点:这正是单页 Web 应用(SPA)的定义,原文档中已有描述。

6.4.2. src/main.tsx

import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import { SettingsProvider } from './app/core/context/settings.context';
import { AuthProvider } from './app/core/context/auth.context';
import { LanguageProvider } from './app/core/context/language.context';
import { App } from './app/App';
import 'bootstrap/dist/css/bootstrap.min.css';
import './index.css';
import './i18n';

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <SettingsProvider>
      <AuthProvider>
        <LanguageProvider>
          <App />
        </LanguageProvider>
      </AuthProvider>
    </SettingsProvider>
  </StrictMode>,
);

我们来解读这段代码:

  • 第 11 行:createRoot(document.getElementById('root')!).render(…) ——直接对应 [Angular] 方面的 bootstrapApplication(App, appConfig):在 index.html 的 #root 元素中启动应用。感叹号(!)告诉 TypeScript 我们确信该元素存在(它在 [index.html] 的第 10 行定义);
  • 第 13–19 行:<SettingsProvider><AuthProvider><LanguageProvider><App /></LanguageProvider></AuthProvider></SettingsProvider> ——来自 core/context/ 的三个 Provider(见下文)包裹根组件 [App]:这使得 useSettings()、useAuth() 和 useLanguage() 可以在任何后代组件中使用——相当于 [app.config.ts] 在 [Angular] 方面的三个 provideXxx()(providers: [...]),只是这里表示为组件的嵌套,而不是列表;
  • 第 7 行:import 'bootstrap/dist/css/bootstrap.min.css'; ——[Vite] 允许直接从 TypeScript 文件导入样式表;而在 [Angular] 中,起这个作用的是 angular.json(styles 数组:[...])——结果相同,机制不同;
  • 第 9 行:import './i18n'; ——仅为其副作用而导入(初始化 [i18next];见下文的 i18n.ts):这个导入中的任何内容都没有被使用,但必须先执行它,[useTranslation()] 才能在组件中工作。

<StrictMode> 是 [React] 特有的组件,仅影响开发环境(在生产环境中没有效果):它通过把某些渲染运行两次,帮助检测某些写得不好的副作用——在 [Angular] 中没有直接对应物,那里是由编译器在编译时检测这类错误。

6.4.3. src/i18n.ts

import i18n from 'i18next';
import { initReactI18next } from 'react-i18next';
import HttpBackend from 'i18next-http-backend';

i18n
  .use(HttpBackend)
  .use(initReactI18next)
  .init({
    lng: navigator.language?.toLowerCase().startsWith('fr') ? 'fr' : 'en',
    fallbackLng: 'en',
    interpolation: {
      escapeValue: false,
    },
    backend: {
      loadPath: '/i18n/{{lng}}.json',
    },
  });

export default i18n;

我们来解读这段代码:

  • 第 6 行:.use(HttpBackend) ——通过 HTTP GET 请求加载每个字典,URL 由 [backend.loadPath](第 15 行)构成:[/i18n/fr.json] 或 [/i18n/en.json],与 [TranslateHttpLoader] 在 [Angular] 方面构成的 URL 完全相同(prefix: '/i18n/',suffix: '.json'),因此 [public/i18n/fr.json] 和 [public/i18n/en.json] (见下文)可以原样复用,无需任何修改;
  • 第 7 行:.use(initReactI18next) ——把 [i18next] 接入 [React]:提供 features/ 中每个组件使用的 useTranslation() Hook,以及 React 的 Hook [Context] (库内部使用,这里看不到),语言变化时它会触发整个界面的完全重新渲染——相当于 [Angular] 方面由 [TranslatePipe] 装饰器与 [provideTranslateService(...)] 结合起来所完成的功能;
  • 第 9 行:lng: navigator.language?.toLowerCase().startsWith('fr') ? 'fr' : 'en', ——启动语言(浏览器设置为法语时为法语,否则为英语;第 10 行有 fallbackLng: 'en');Hook [useLanguage()] (见下文的 core/context/language.context.tsx)会立即用 localStorage 中存储的选择(如果有的话)替换它——与 [app.config.ts] 在 [Angular] 方面的 lang: 'en' 完全一样;
  • 第 11–13 行:interpolation: { escapeValue: false, }, ——[React] 本身已经对 HTML 进行了转义(防范 XSS 漏洞):无需再让 [i18next] 再转义一次。

在原文档(2014)中,AngularJS 1.x 客户端依靠 angular-translate 库满足同样的需求——它在 AngularJS 1.x 生态中是 [@ngx-translate/core] (本课程 [Angular] 变体使用的库)的前身,在这里则是 [i18next] 的前身。这两个现代库([ngx-translate] 在 [Angular] 方面,[i18next] 在 [React] 方面)都通过简单的 HTTP GET 请求加载 JSON 字典,采用相同的“每种语言一个文件,每个界面一个分区”的模式。

6.4.4. src/index.css

1
2
3
4
5
6
7
body {
  background-color: #f5f7fa;
}

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

我们来解读这段代码:

  • 第 1 行:body { background-color: #f5f7fa; } ——原样复制自 [Angular] 方面的 src/styles.css:一种很浅的灰色,而不是默认的纯白色,使 [Bootstrap] 卡片(白色背景,.card)与页面背景略有区分;
  • 第 5–7 行:.free-slot:hover ——应用于日程表中表示可预约时间段的行(见 Schedule.tsx,稍后讨论的 className={scheduleSlot.appointment === null ? 'free-slot' : undefined}):悬停时背景会略微变绿。手形光标(如 [Angular] 中所示的 cursor: pointer)直接应用于“预约”按钮本身(一个真正的 <button>),而不是整个表格行。

这个文件包含全局样式,与每个组件自己的 .css 文件(login.css、schedule.css……)中定义的“局部”样式相对,后者只应用于 该特定组件的 [JSX] ——原则与 [Angular] (每个组件各有 CSS 文件)相同。App.css 是根组件的样式表,保持为空:[Bootstrap] 和 index.css 已足以满足本文档实现的一切需求。

6.5. core/models 层

Image

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

export interface ServerResponse<T> {
  status: number;
  data: T | null;
}

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

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;
  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] 变体中同名文件的:描述与服务器交换的数据的 TypeScript 接口不依赖于任何界面库,例如 [React] 或 [Angular]——这是“纯”TypeScript,与 [ServerResponse]<T> 类以及 [TypeORM] 实体在 [NestJS] 服务器(第 3 章)中逐项对应;
  • [Client] 在这里——与在 [Angular] 方面和原文档中一样——指的是医疗诊所的患者——不要与“HTTP 客户端”混淆;
  • Role / LoginResult ——是同名服务器类型(src/entities/user.entity.ts、auth/login-result.model.ts,第 3 章)的忠实副本。

在 AngularJS 1.x(2014)中,纯 JavaScript 无法以这种方式描述期望的数据格式。而使用 TypeScript——[Angular] 和 [React]都使用它——字段名中的拼写错误在程序运行之前,即在编译时就会被标出。

6.6. core/context 层

Image

这个文件夹在本课程的 [Angular] 变体中没有对应物(见上一章的“共享逻辑”):它汇集了三个 [React] [Context],它们在这里承担 [SettingsService]、[AuthService]以及 [LanguageService] 的一部分在 [Angular] 方面所扮演的可注入服务的角色。

6.6.1. src/app/core/context/settings.context.tsx

import { createContext, useContext, useState, type ReactNode } from 'react';

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

const SettingsContext = createContext<SettingsContextValue | null>(null);

export function SettingsProvider({ children }: { children: ReactNode }) {
  const [apiBaseUrl, setApiBaseUrl] = useState('http://localhost:8080');
  return (
    <SettingsContext.Provider value={{ apiBaseUrl, setApiBaseUrl }}>
      {children}
    </SettingsContext.Provider>
  );
}

export function useSettings(): SettingsContextValue {
  const context = useContext(SettingsContext);
  if (context === null) {
    throw new Error('useSettings() must be called under a <SettingsProvider>');
  }
  return context;
}

我们来解读这段代码:

  • 第 11 行:const [apiBaseUrl, setApiBaseUrl] = useState('http://localhost:8080'); ——替代 [readonly apiBaseUrl = signal('http://localhost:8080');],与 [SettingsService] 在 [Angular] 方面完全一致:相同的默认值,相同的修改能力,可从原文档主视图中的“服务器 URL”字段修改;
  • 第 12–16 行:<SettingsContext.Provider value={{ apiBaseUrl, setApiBaseUrl }}>{children}</SettingsContext.Provider> ——向所有后代发布(值,设置函数)这一对,正是 [providedIn: 'root'] 在 [Angular] 方面所起的作用;
  • 第 19–25 行:export function useSettings(): SettingsContextValue { ——组件调用的 Hook(const settings = useSettings();),直接对应 inject(SettingsService)。

6.6.2. src/app/core/context/auth.context.tsx

移植自 [AuthService]:管理用户的连接,调用 [POST /login],存储收到的 JWT 令牌(以及随之而来的身份/角色),并使用 [localStorage] 确保它在页面重新加载后依然保留。这是应用中仅有的 、与 [useAppointmentService()] (见下文)一起通过 HTTP 与服务器通信的地方。

import { createContext, useContext, useMemo, useState, type ReactNode } from 'react';
import type { LoginResult, ServerResponse, Role } from '../models/appointment.models';
import { useSettings } from './settings.context';

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;
  }
}

interface AuthContextValue {
  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;
}

const AuthContext = createContext<AuthContextValue | null>(null);

export function AuthProvider({ children }: { children: ReactNode }) {
  const { apiBaseUrl } = useSettings();
  const [session, setSession] = useState<StoredSession | null>(readStoredSession);

  async function logIn(login: string, password: string): Promise<LoginResult> {
    const httpResponse = await fetch(`${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;
    setSession(result);
    localStorage.setItem(STORAGE_KEY, JSON.stringify(result));
    return result;
  }

  function logOut(): void {
    setSession(null);
    localStorage.removeItem(STORAGE_KEY);
  }

  const value = useMemo<AuthContextValue>(
    () => ({
      isLoggedIn: session !== null,
      login: session?.login ?? null,
      name: session?.name ?? null,
      role: session?.role ?? null,
      isAdmin: session?.role === 'ADMIN',
      accessToken: session?.accessToken ?? null,
      logIn,
      logOut,
    }),
    [session, apiBaseUrl],
  );

  return <AuthContext.Provider value={value}>{children}</AuthContext.Provider>;
}

export function useAuth(): AuthContextValue {
  const context = useContext(AuthContext);
  if (context === null) {
    throw new Error('useAuth() must be called under an <AuthProvider>');
  }
  return context;
}

我们来解读这段代码:

  • 第 14–21 行:function readStoredSession(): StoredSession | null { ——由 try/catch 块保护,与 [Angular] 方面完全一样:[localStorage] 可能不可用(限制非常严格的隐私浏览模式),或者包含已损坏的值——在这种情况下,我们直接认为没有会话;
  • 第 38 行:const [session, setSession] = useState<StoredSession | null>(readStoredSession); ——[useState(function)] 只在第一次渲染时执行该函数一次(而不是每次渲染都执行):这恰好是 [signal(readStoredSession())] 中的初始化器在 [Angular] 方面所起的作用。如果用户在登录后重新加载页面,他们仍保持登录状态;
  • 第 40–54 行:async function logIn(login: string, password: string): Promise<LoginResult> { ——等价于 [POST /login,JSON 请求体 { login, password }]; 与 [AuthService.logIn()] 在 [Angular] 方面不同(后者返回 Observable,并在单独的 tap() 操作符中保存会话),[fetch]/async-await 版本自然地自上而下串联各个步骤,无需专门的操作符;
  • 第 56–59 行:function logOut(): void { ——纯本地操作(不调用服务器):在本次移植中,JWT 令牌不会在服务器端被“撤销”;它在 JWT_EXPIRES_IN 之后自行过期(见服务器的 .env,第 3 章);
  • 第 61–73 行:const value = useMemo<AuthContextValue>(() => ({ … }), [session, apiBaseUrl]); ——[useMemo]() 可避免在 [AuthProvider] 渲染时,在 [session] 和 [apiBaseUrl] 都没有变化的情况下每次都重新创建新的 `value` 对象:没有它,任何使用 [useAuth()] 的组件在每次 [AuthProvider] 渲染时都会被不必要地重新绘制——这是一个性能问题,在 [Angular] 方面没有直接的对应物,因为那里的 `computed()` 本来就只重新计算真正依赖于已修改信号的内容。

6.6.3. src/app/core/context/language.context.tsx

移植了 [LanguageService] 的一部分:在 [useTranslation()] Hook(由 [react-i18next] 提供)之上集中处理界面语言(法语/英语)的切换。

// src/app/core/context/language.context.tsx

import { createContext, useContext, useEffect, type ReactNode } from 'react';
import { useTranslation } from 'react-i18next';

const STORAGE_KEY = 'rdvmedecins.language';

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

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

const LanguageContext = createContext<LanguageContextValue | null>(null);

export function LanguageProvider({ children }: { children: ReactNode }) {
  const { i18n } = useTranslation();

  useEffect(() => {
    const savedLanguage = localStorage.getItem(STORAGE_KEY) as Language | null;
    if (savedLanguage && savedLanguage !== i18n.language) {
      i18n.changeLanguage(savedLanguage);
      document.documentElement.lang = savedLanguage;
    }
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, []);

  function changeLanguage(language: Language): void {
    localStorage.setItem(STORAGE_KEY, language);
    i18n.changeLanguage(language);
    document.documentElement.lang = language;
  }

  const value: LanguageContextValue = {
    currentLanguage: i18n.language as Language,
    changeLanguage,
  };

  return <LanguageContext.Provider value={value}>{children}</LanguageContext.Provider>;
}

export function useLanguage(): LanguageContextValue {
  const context = useContext(LanguageContext);
  if (context === null) {
    throw new Error('useLanguage() must be called under a <LanguageProvider>');
  }
  return context;
}

我们来解读这段代码:

  • 第 18 行:const { i18n } = useTranslation(); ——[react-i18next] 已经通过这个 Hook 公开了 i18n 实例(及其当前语言 i18n.language):无需像 [SettingsContext]/[AuthContext] 那样再为它创建单独的状态;这与 [Angular] 中的概念相同,在那里 LanguageService 只是把 this.translate.currentLang 换个名字重新发布;
  • 第 20–27 行:useEffect(() => { … }, []); ——空的依赖数组([])表示“仅在组件挂载时执行一次这个副作用(effect)”——直接对应 [LanguageService] 在 [Angular] 方面的 constructor():如果用户在之前的访问中已经选择过语言,就会恢复该语言;否则使用 [i18n.ts] 中设置的默认语言(英语,法语浏览器则为法语);
  • 第 29–33 行:function changeLanguage(language: Language): void { ——由导航栏上的 FR/EN 两个按钮调用(见下文的 [App.tsx] );[i18n.changeLanguage(...)] (如有必要)加载相应的 [public/i18n/<language>.json] 文件,然后切换当前语言——与 [translate.use(language)] 在 [Angular] 方面(是一个 Observable,见上一章)不同,这里代码选择不等待 Promise(它很快就会完成,因为文件在第一次加载后就被缓存了);
  • 第 32 行:document.documentElement.lang = language; ——更新页面的 <html lang="..."> 属性(对无障碍访问很有用),这两个库自身都不处理它,因为 [index.html] 是在应用启动之前就已加载的静态页面——需求完全相同,解决办法也与 [Angular] 相同。

相当于原 AngularJS 1.x 客户端中的“FR / EN”按钮,当时它依赖 [angular-translate] 库——它在 AngularJS 1.x 生态中是 [ngx-translate]([Angular])以及后来的 [i18next] ([React])的前身。

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

Image

[i18next-http-backend] (在 i18n.ts 中配置,见上文)每当语言变化(或首次使用)时,就通过 [HTTP GET /i18n/<language>.json] 请求加载这两个文件之一。[react-i18next] 随后 通过 [useTranslation() (function t(...))] Hook 解析每个键("LOGIN.TITLE"、"SCHEDULE.FREE"……),该 Hook 用于 features/ 目录中的所有组件(见本章后文)。

6.7.1. public/i18n/fr.json

{
  "APP": {
    "TITLE": "RdvMedecins - portage NestJS / React",
    "SERVER_URL_LABEL": "URL du serveur",
    "LOGOUT": "Se déconnecter"
  },
  "LOGIN": {
    "TITLE": "Connexion",
    "LOGIN_LABEL": "Login",
    "...": "..."
  },
  "DOCTOR_DAY_PICKER": { "...": "..." },
  "SCHEDULE": { "...": "..." },
  "BOOKING_DIALOG": { "...": "..." }
}

我们来解读这段代码:

  • 这个文件 原样 取自本课程的 [Angular] 变体(相同的键,相同的文本),只有一处例外:第 3 行,["TITLE"],现在指的是 [React] 而不是 [Angular]——这是两个客户端之间唯一真正影响显示给用户的文本的差异;
  • 一个嵌套的 JSON 对象,每个组件一个分区(APP、LOGIN、DOCTOR_DAY_PICKER、SCHEDULE、BOOKING_DIALOG);[i18next] 把它展平为扁平的字典,其中每个完整的键("LOGIN.TITLE")由路径用点号连接而成——与 [TranslateService] 在 [Angular] 中的做法完全一样。

6.7.2. public/i18n/en.json

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

我们来解读这段代码:

  • 第 3 行:"TITLE": "RdvMedecins - NestJS / React port", ——只有副标题发生变化:“[RdvMedecins]”在两种语言中都保持不变,它是应用的专有名称。

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

6.8. core/interceptors 层

Image

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

[React] 只是一个界面库,没有内置的 HTTP 拦截器概念,不像 [HttpClient]/withInterceptors([...])在 [Angular] 方面那样。这个文件把同一概念重新实现为 Hook ,它封装了 [fetch]:这是 AngularJS 1.x 的 $http 拦截器的现代等价物,原文档(“示例 6”一章)已经讨论过它。

import { useAuth } from '../context/auth.context';

export function useAuthFetch() {
  const auth = useAuth();

  return async function authFetch(input: RequestInfo | URL, init: RequestInit = {}): Promise<Response> {
    const headers = new Headers(init.headers);
    if (auth.accessToken) {
      headers.set('Authorization', `Bearer ${auth.accessToken}`);
    }
    const response = await fetch(input, { ...init, headers });
    if (response.status === 401) {
      auth.logOut();
    }
    return response;
  };
}

我们来解读这段代码:

  • 第 3 行:export function useAuthFetch() { ——不同于 [authInterceptor] 在 [Angular] 方面的做法(它是一个一次性注册在 [app.config.ts] 中的函数,然后自动应用于对 [HttpClient] 的每一次调用),[useAuthFetch()] 是一个 Hook ,每个调用者(这里是 useAppointmentService(),见下文)都必须显式调用它,并用它代替 fetch()——这是两个库在机制上的差异,而不是最终行为上的差异;
  • 第 6–10 行:if (auth.accessToken) { headers.set('Authorization', …); } ——直接对应 [request.clone({ setHeaders: { Authorization: … } })] 在 [Angular] 方面的做法。与 [HttpClient] 请求(不可变)不同,[fetch] 的选项只是一个 JavaScript 对象:无需创建它的“克隆”副本;只需在调用之前构造 [headers] 对象即可;
  • 第 12–14 行:if (response.status === 401) { auth.logOut(); } ——原理与 [Angular] 方面相同(catchError + HttpErrorResponse.status === 401):会话期间出现 401 意味着令牌已不再有效,因此客户端被平稳地登出;这里,[fetch] 不会把 HTTP 状态当作错误使其 Promise 被拒绝(不同于 Observable [HttpClient])——这就是为什么这个测试直接针对 [response.status],而无需 try/catch 块;
  • 第 15 行:return response; ——响应(可能是 401)仍然原样返回给调用者,由调用者负责处理(见下文的 useAppointmentService()、extract<T>())——拦截器不能向调用它的代码隐藏错误。

我们本可以手动把 [Authorization: Bearer ...] 添加到 [useAppointmentService()] 的每个方法中。共享的 Hook 避免了这种重复,带来与 [Angular] 拦截器相同的好处:“如何对请求进行身份验证?”这个问题只在一个地方回答。

6.9. core/services 层

Image

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

移植自 [AppointmentService]:应用中(与 [core/context/auth.context.tsx] 一起,后者负责连接本身)唯一通过 HTTP 与 [NestJS] 服务器通信的部分。它直接对应原文档“示例 6:HTTP 服务”一章中介绍的 [dao] 服务(该服务使用 AngularJS 的 $http 服务)。

import { useCallback } from 'react';
import { useAuthFetch } from '../interceptors/auth.interceptor';
import { useSettings } from '../context/settings.context';
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 answered with the error status ${envelope.status}`);
  }
  return envelope.data as T;
}

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

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

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

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

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

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

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

我们来解读这段代码:

  • 第 6 行:async function extract<T>(httpResponse: Response): Promise<T> { ——我们不在每个公开函数中重复检查“如果 status !== 0,则为错误”,而是在这里集中只做一次——这恰好是 [AppointmentService.extract()] 在 [Angular] 方面的作用,只是它在 Hook 之外声明(一个普通函数,因此不需要在每次渲染时重新创建);
  • 第 14 行:export function useAppointmentService() { ——一个 自定义 Hook ,其读取和使用方式与 [inject(AppointmentService)] 在 [Angular] 方面完全一样:在组件顶部调用一次,然后使用它返回的函数;
  • 第 18–21 行:const getAllDoctors = useCallback(async () => { … }, [authFetch, apiBaseUrl]); ——[useCallback]() 在多次渲染之间缓存这个函数,只要 [authFetch] 和 [[apiBaseUrl]] 不变:这里需要这种优化,因为每当使用该 Hook 的组件(App.tsx)渲染时都会调用它——没有它,每次渲染都会重新创建一个新的函数 [getAllDoctors] ,从而不必要地再次触发某些副作用(useEffect(…, [api]),见下文的 App.tsx);这个技术细节在 [Angular] 方面没有对应物,那里 [AppointmentService] 在整个应用中只存在一份(providedIn: 'root');
  • 每个函数都恰好对应 [NestJS] 控制器(第 3 章)中的十一个路由之一——事实上,两边出现的是相同的名称(getAllDoctors、addAppointment、deleteAppointment……),这便于比较服务器端和客户端,就像 [Angular] 那样。

与 [AuthService.logIn()] (上一章)不同,这个 Hook 中的方法在调用之后都不需要存储任何东西:如何处理结果(setDoctors(...)、setSchedule(...)……)由调用它的组件(App.tsx)决定——职责分离与 [Angular] 方面相同,在那里 [AppointmentService] 对屏幕上显示的状态一无所知。

6.10. features 层:四个组件

Image

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

移植自 [login.component.ts/.html]:登录界面,等价于原 AngularJS 1.x 客户端中的视图 [login.html] 。

import { useState, type FormEvent } from 'react';
import { useTranslation } from 'react-i18next';
import { useAuth } from '../../core/context/auth.context';
import './login.css';

export function Login() {
  const { t } = useTranslation();
  const auth = useAuth();

  const [login, setLogin] = useState('');
  const [password, setPassword] = useState('');
  const [submitting, setSubmitting] = useState(false);
  const [error, setError] = useState<string | null>(null);

  async function onSubmit(event?: FormEvent): Promise<void> {
    event?.preventDefault();
    if (login.trim() === '' || password === '') {
      return;
    }
    setError(null);
    setSubmitting(true);
    try {
      await auth.logIn(login, password);
      setSubmitting(false);
    } catch {
      setSubmitting(false);
      setError('LOGIN.ERROR');
    }
  }

  return (
    <div className="row justify-content-center">
      <div className="col-sm-8 col-md-6 col-lg-4">
        <form className="card p-4" onSubmit={onSubmit}>
          <h5 className="card-title mb-3">{t('LOGIN.TITLE')}</h5>
          {error && (
            <div className="alert alert-danger py-2" role="alert">
              {t(error)}
            </div>
          )}
          <div className="mb-3">
            <label className="form-label" htmlFor="input-login">
              {t('LOGIN.LOGIN_LABEL')}
            </label>
            <input id="input-login" type="text" className="form-control"
              value={login} onChange={(e) => setLogin(e.target.value)} />
          </div>
          <div className="mb-3">
            <label className="form-label" htmlFor="input-password">
              {t('LOGIN.PASSWORD_LABEL')}
            </label>
            <input id="input-password" type="password" className="form-control"
              value={password} onChange={(e) => setPassword(e.target.value)} />
          </div>
          <button type="submit" className="btn btn-primary w-100" disabled={submitting}>
            {submitting ? t('LOGIN.SUBMITTING') : t('LOGIN.SUBMIT')}
          </button>
        </form>
      </div>
    </div>
  );
}

我们来解读这段代码:

  • 第 6 行:export function Login() { ——独立组件 [Angular] 在其装饰器 [@Component] 中声明它所使用的管道(imports: [TranslatePipe]);而 [React] 组件没有需要声明的对应内容:[useTranslation()](第 7 行)只需像任何其他函数一样被导入和调用;
  • 第 10–13 行:const [login, setLogin] = useState(''); … ——纯粹局限于表单的状态(用户当前正在输入的内容),等价于 [signal()] 或 [Angular] 组件的局部变量;
  • 第 15–16 行:async function onSubmit(event?: FormEvent): Promise<void> { event?.preventDefault(); ——有意的差异:与本课程的 [Angular] 变体相比,该组件不是分别监听(keyup.enter)每个字段,而是使用真正的 <form> 元素(第 34 行)及其原生的 [onSubmit] 事件——这样,按 Enter 键和点击“登录”按钮(type="submit")都会触发 [onSubmit()],无需任何额外代码;[event?.preventDefault()] 可阻止浏览器的默认行为(重新加载页面),那会违背单页应用的基本原则;
  • 第 23–24 行:await auth.logIn(login, password); setSubmitting(false); ——这里无需再做任何处理:[AuthContext] 已经存储了会话(状态 + localStorage)——是 App.tsx 在调用 useAuth().isLoggedIn,它会据此停止显示 <Login />;
  • 第 24–27 行:catch { … setError('LOGIN.ERROR'); } ——无效的用户名/密码对会导致 [logIn()] 以 JavaScript 异常失败(由 [auth.context.tsx] 抛出,见上文):向用户显示“LOGIN.ERROR”,不尝试区分用户名不存在还是密码错误——做法与 [Angular] 完全相同。存储翻译键而不是已经解析好的文本,与 [Angular] 中有同样的优点:如果用户在显示此消息时切换语言,它会自动翻译自身(第 38 行的 t(error),每次渲染时重新求值)。

这个组件把 [Angular] 拆分为两个文件(login.component.ts 放逻辑,login.component.html 放模板)的内容合并在单个 .tsx 文件中:Login() 函数返回的 [JSX] 就是模板,并与驱动它的 TypeScript 代码结合在一起。因此,不像本课程 [Angular] 变体的相应章节那样,这里没有需要单独解读的 .html 文件。

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

移植自 [doctor-day-picker.component.ts/.html]:允许选择医生和日期,然后请求查看其日程的组件。在概念上等价于原 AngularJS 1.x 客户端的示例 7 至 10。

import { useState, type ChangeEvent } from 'react';
import { useTranslation } from 'react-i18next';
import type { Doctor } from '../../core/models/appointment.models';
import './doctor-day-picker.css';

interface DoctorDayPickerProps {
  doctors: Doctor[];
  onSearch: (criteria: { doctorId: number; day: string }) => void;
}

export function DoctorDayPicker({ doctors, onSearch }: DoctorDayPickerProps) {
  const { t } = useTranslation();
  const [selectedDoctorId, setSelectedDoctorId] = useState<number | null>(null);
  const [selectedDay, setSelectedDay] = useState<string>(
    new Date().toISOString().slice(0, 10),
  );

  function onDoctorChange(event: ChangeEvent<HTMLSelectElement>): void {
    const value = event.target.value;
    setSelectedDoctorId(value === '' ? null : Number(value));
  }

  function onSearchClick(): void {
    if (selectedDoctorId === null) {
      return;
    }
    onSearch({ doctorId: selectedDoctorId, day: selectedDay });
  }

  return (
    <div className="card p-3 mb-3">
      <div className="row g-2 align-items-end">
        <div className="col-sm-5">
          <label className="form-label" htmlFor="select-doctor">
            {t('DOCTOR_DAY_PICKER.DOCTOR_LABEL')}
          </label>
          <select id="select-doctor" className="form-select" onChange={onDoctorChange}>
            <option value="">{t('DOCTOR_DAY_PICKER.CHOOSE_DOCTOR')}</option>
            {doctors.map((doctor) => (
              <option key={doctor.id} value={doctor.id}>
                {doctor.title} {doctor.firstName} {doctor.lastName}
              </option>
            ))}
          </select>
        </div>
        <div className="col-sm-4">
          <input id="input-day" type="date" className="form-control"
            value={selectedDay} onChange={(e) => setSelectedDay(e.target.value)} />
        </div>
        <div className="col-sm-3">
          <button type="button" className="btn btn-primary w-100"
            disabled={selectedDoctorId === null} onClick={onSearchClick}>
            {t('DOCTOR_DAY_PICKER.VIEW_SCHEDULE')}
          </button>
        </div>
      </div>
    </div>
  );
}

我们来解读这段代码:

  • 第 11 行:export function DoctorDayPicker({ doctors, onSearch }: DoctorDayPickerProps) { ——[input.required<Doctor[]>()] ([Angular])在这里直接变成 `props` 对象的一个字段 (`doctors`);`output<...>()` 变成 包含回调函数的 prop ,由父组件提供 `[(onSearch)]`——`[App.tsx]` 会调用它,就像订阅 `[Angular]` 模板的 `search` 事件一样;
  • 第 39–43 行:{doctors.map((doctor) => ( <option key={doctor.id} …>…</option> ))} ——带有 [key={doctor.id}] 的 .map(...),是 [React] 中对应 [@for (doctor of doctors(); track doctor.id)] 在 [Angular] 方面的写法:两种情况下,都由一个稳定的标识符指明,在重新绘制时如何识别已显示过的医生;
  • 第 37 行:onChange={onDoctorChange} ——不同于 [Login.tsx] 的“login”字段(它在每次按键时都使用 [onChange] ),<select> 只在选择真正发生变化时才通知——与 [change] 这个 HTML 事件相同,[(change)="onDoctorChange($event)] 在 [Angular] 方面已经使用的就是它。

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

移植自 [schedule.component.ts/.html]:显示某位医生在给定日期的日程。等价于原 AngularJS 1.x 客户端的示例 8 和 9。自加入身份验证以来,该组件还接受 [canEdit]:设为 false(角色 USER)时,“预约”/“取消”按钮会消失——日程仍可查看,但处于只读模式。

import { useTranslation } from 'react-i18next';
import type { DoctorDaySchedule, ScheduleSlot, SlotJson, AppointmentJson } from '../../core/models/appointment.models';
import './schedule.css';

interface ScheduleProps {
  schedule: DoctorDaySchedule | null;
  canEdit: boolean;
  onBook: (slot: SlotJson) => void;
  onCancel: (appointment: AppointmentJson) => void;
}

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

export function Schedule({ schedule, canEdit, onBook, onCancel }: ScheduleProps) {
  const { t } = useTranslation();

  function onSlotClick(scheduleSlot: ScheduleSlot): void {
    if (!canEdit) {
      return;
    }
    if (scheduleSlot.appointment === null) {
      onBook(scheduleSlot.slot);
    } else {
      onCancel(scheduleSlot.appointment);
    }
  }

  if (schedule === null) {
    return <p className="text-muted">{t('SCHEDULE.EMPTY_STATE')}</p>;
  }

  return (
    <div className="card p-3">
      <h5>
        {t('SCHEDULE.TITLE_PREFIX')} {schedule.day} - {schedule.doctor.title} {schedule.doctor.firstName} {schedule.doctor.lastName}
      </h5>
      <table className="table table-hover align-middle">
        <thead>
          <tr><th>{t('SCHEDULE.COLUMN_SLOT')}</th><th>{t('SCHEDULE.COLUMN_STATUS')}</th><th></th></tr>
        </thead>
        <tbody>
          {schedule.slots.map((scheduleSlot) => (
            <tr key={scheduleSlot.slot.id}
              className={scheduleSlot.appointment === null ? 'free-slot' : undefined}>
              <td>
                {formatTime(scheduleSlot.slot.startHour, scheduleSlot.slot.startMinute)} -{' '}
                {formatTime(scheduleSlot.slot.endHour, scheduleSlot.slot.endMinute)}
              </td>
              <td>
                {scheduleSlot.appointment === null ? (
                  <span className="badge text-bg-success">{t('SCHEDULE.FREE')}</span>
                ) : (
                  <span className="badge text-bg-secondary">
                    {scheduleSlot.appointment.client?.title} {scheduleSlot.appointment.client?.firstName} {scheduleSlot.appointment.client?.lastName}
                  </span>
                )}
              </td>
              <td>
                {canEdit && (
                  <button type="button" className={'btn btn-sm ' +
                    (scheduleSlot.appointment === null ? 'btn-outline-success' : 'btn-outline-danger')}
                    onClick={() => onSlotClick(scheduleSlot)}>
                    {scheduleSlot.appointment === null ? t('SCHEDULE.BOOK') : t('SCHEDULE.CANCEL_APPOINTMENT')}
                  </button>
                )}
              </td>
            </tr>
          ))}
        </tbody>
      </table>
    </div>
  );
}

我们来解读这段代码:

  • 第 30–32 行:if (schedule === null) { return <p …>{t('SCHEDULE.EMPTY_STATE')}</p>; } ——一个 提前返回 取代了 [@if (schedule(); as currentSchedule) { … } @else { … }] 在 [Angular] 方面的写法:[React] 组件函数可以在其函数体的任何位置返回任何 [JSX] ,包括在末尾之前——这里,只要还没有执行搜索(或日程为空),函数在显示空状态消息之后就会停止,甚至不会构造数组;
  • 第 7 行:canEdit: boolean; ——身份验证引入的新特性,与 [Angular] 方面类似:[App.tsx] 向它传入 [auth.isAdmin](见下文)。设为 false(角色 USER)时,“预约”/“取消”按钮在 DOM 中根本不存在(见第 61 行,[{canEdit && (…)}])——它们不只是变灰或被禁用,而是完全不存在;
  • 第 52–58 行:{scheduleSlot.appointment === null ? ( <span …>Free</span> ) : ( <span …>{patient name}</span> )} ——三元运算符取代了 [@if (…) { … } @else { … }] 在 [Angular] 方面的写法:根据时间段的状态,显示绿色的 [Bootstrap] 徽章(“空闲”)或灰色徽章(患者姓名);
  • 第 61 行:{canEdit && (…)} ——&& 运算符仅在第一个操作数为真时才显示第二个操作数(否则什么都不显示)——这是 [JSX] 中条件渲染最简短的形式,这里用它而不是三元运算符,是因为否则没有任何内容要显示;
  • 第 65 行:{scheduleSlot.appointment === null ? t('SCHEDULE.BOOK') : t('SCHEDULE.CANCEL_APPOINTMENT')} ——与 [Angular] 方面一样(在那里管道可用于任何模板表达式),t(...) 是标准的 JavaScript 函数:可以直接在三元运算符中使用,无需任何特殊语法。

这个组件自己不发出任何 HTTP 调用:它显示通过 props 收到的数据,并通过 [onBook/onCancel] 把用户的意图通知给其父组件(App.tsx)——职责分离与 [Angular] 方面完全相同(通过 output() 实现预约/取消)。

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

移植自 [booking-dialog.component.ts/.html]:(模态)窗口,用于选择一位患者来预约一个可用的时间段。等价于原 AngularJS 1.x 客户端的示例 9。

import { useState, type ChangeEvent } from 'react';
import { useTranslation } from 'react-i18next';
import type { Client, SlotJson } from '../../core/models/appointment.models';
import './booking-dialog.css';

interface BookingDialogProps {
  open: boolean;
  slot: SlotJson | null;
  clients: Client[];
  onConfirm: (choice: { clientId: number }) => void;
  onClose: () => void;
}

export function BookingDialog({ open, slot, clients, onConfirm, onClose }: BookingDialogProps) {
  const { t } = useTranslation();
  const [selectedClientId, setSelectedClientId] = useState<number | null>(null);

  if (!open) {
    return null;
  }

  function onClientChange(event: ChangeEvent<HTMLSelectElement>): void {
    const value = event.target.value;
    setSelectedClientId(value === '' ? null : Number(value));
  }

  function onConfirmClick(): void {
    if (selectedClientId === null) {
      return;
    }
    onConfirm({ clientId: selectedClientId });
    setSelectedClientId(null);
  }

  return (
    <>
      <div className="modal-backdrop fade show"></div>
      <div className="modal fade show d-block" tabIndex={-1} role="dialog" aria-modal="true">
        <div className="modal-dialog modal-dialog-centered">
          <div className="modal-content">
            <div className="modal-header">
              <h5 className="modal-title">{t('BOOKING_DIALOG.TITLE')}</h5>
              <button type="button" className="btn-close"
                aria-label={t('BOOKING_DIALOG.CLOSE_ARIA')} onClick={onClose}></button>
            </div>
            <div className="modal-body">
              {slot && (
                <p>
                  {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>
              )}
              <select id="select-client" className="form-select" onChange={onClientChange}>
                <option value="">{t('BOOKING_DIALOG.CHOOSE_PATIENT')}</option>
                {clients.map((client) => (
                  <option key={client.id} value={client.id}>
                    {client.title} {client.firstName} {client.lastName}
                  </option>
                ))}
              </select>
            </div>
            <div className="modal-footer">
              <button type="button" className="btn btn-secondary" onClick={onClose}>
                {t('BOOKING_DIALOG.CANCEL')}
              </button>
              <button type="button" className="btn btn-primary"
                disabled={selectedClientId === null} onClick={onConfirmClick}>
                {t('BOOKING_DIALOG.CONFIRM')}
              </button>
            </div>
          </div>
        </div>
      </div>
    </>
  );
}

我们来解读这段代码:

  • 第 18–20 行:if (!open) { return null; } ——[React] 组件可以返回 null 以完全不显示任何内容:这恰好等价于 [@if (open()) { … }] 在 [Angular] 方面的写法(只要 `open` 为 false,DOM 中甚至不会加载任何内容),也等价于 AngularJS 1.x 中的 [ngIf/ngShow];
  • 第 37 行:<div className="modal-backdrop fade show"></div> ——使页面其余部分变暗的半透明背景——这里是硬编码的,而 [Bootstrap] 通常在显示模态框时通过 JavaScript 自行插入它;
  • 第 38 行:<div className="modal fade show d-block" …> ——d-block 代替了通常由 [Bootstrap] 的 JavaScript 完成的作用(打开时添加 [display:block] )——在这里,起这个作用的直接就是第 18 行的条件渲染([if (!open) return null;]);
  • 第 44 行:aria-label={t('BOOKING_DIALOG.CLOSE_ARIA')} ——不同于 [attr.aria-label="'BOOKING_DIALOG.CLOSE_ARIA' | translate"] 在 [Angular] 方面的写法(一种有别于 {{ }} 插值的属性绑定),[JSX] 不区分 HTML 属性和元素的内容:{expression} 在两处的用法完全相同。

与 [Angular] 方面一样,这个组件使用模态框的真正类,但其可见性由 [React] 控制(基于 [open] 属性的条件渲染),而不是由 [Bootstrap] 的 JavaScript 控制([bootstrap.bundle.js, new bootstrap.Modal(...)])——以防止 [Bootstrap] 和 [React] 各自独立地管理同一条信息(模态框是否打开?),这是一个常见的微妙缺陷来源。原文档(2014)使用了 angular-ui-bootstrap 库中的组件(一个“交钥匙”式的 AngularJS 1.x 模态框),它已经是按照这同一原则设计的。

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

Image

这个组件承担着原 AngularJS 1.x 应用的“主控制器”,以及 [Angular] 方面 App 组件所扮演的角色:它维护应用的全局状态,并响应 features/ 组件的事件,在适当的时候调用 [useAppointmentService()] 。自从加入身份验证以来,它承担了第二个角色:表示层上的“守门人”,决定是显示登录界面还是应用的其余部分。[React] 组件把 [Angular] 拆分为三个文件([app.ts, app.html, app.css])的内容合并在单个 .tsx 文件中:App() 返回的 [JSX] 就是模板([App.css] 在下面导入,仅作为副作用)。

6.11.1. src/app/App.tsx

import { useEffect, useRef, useState } from 'react';
import { useTranslation } from 'react-i18next';
import { useAuth } from './core/context/auth.context';
import { useSettings } from './core/context/settings.context';
import { useLanguage } from './core/context/language.context';
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';
import { Schedule } from './features/schedule/Schedule';
import { BookingDialog } from './features/booking-dialog/BookingDialog';
import { Login } from './features/login/Login';
import './App.css';

export function App() {
  const { t } = useTranslation();
  const auth = useAuth();
  const settings = useSettings();
  const language = useLanguage();
  const api = useAppointmentService();

  const [doctors, setDoctors] = useState<Doctor[]>([]);
  const [clients, setClients] = useState<Client[]>([]);
  const [schedule, setSchedule] = useState<DoctorDaySchedule | null>(null);
  const [error, setError] = useState<string | null>(null);
  const [slotBeingBooked, setSlotBeingBooked] = useState<SlotJson | null>(null);

  const lastDoctorId = useRef<number | null>(null);
  const lastDay = useRef<string | null>(null);

  useEffect(() => {
    if (auth.isLoggedIn) {
      loadInitialLists();
    }
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [auth.isLoggedIn]);

  function loadInitialLists(): void {
    api.getAllDoctors().then(setDoctors)
      .catch((err: unknown) => setError(String((err as Error).message ?? err)));
    api.getAllClients().then(setClients)
      .catch((err: unknown) => setError(String((err as Error).message ?? err)));
  }

  function onLogout(): void {
    auth.logOut();
    setDoctors([]); setClients([]); setSchedule(null);
    setError(null); setSlotBeingBooked(null);
    lastDoctorId.current = null; lastDay.current = null;
  }

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

  function onBookingRequest(slot: SlotJson): void {
    setSlotBeingBooked(slot);
  }

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

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

  function loadSchedule(): void {
    if (lastDoctorId.current === null || lastDay.current === null) {
      return;
    }
    api.getDoctorScheduleOfDay(lastDoctorId.current, lastDay.current).then(setSchedule)
      .catch((err: unknown) => setError(String((err as Error).message ?? err)));
  }

  return (
    <div className="container py-4">
      <nav className="navbar navbar-expand-sm navbar-dark bg-primary rounded mb-4 px-3">
        <span className="navbar-brand mb-0">{t('APP.TITLE')}</span>
        <div className="d-flex align-items-center gap-2">
          <div className="btn-group btn-group-sm" role="group" aria-label="FR / EN">
            <button type="button" onClick={() => language.changeLanguage('fr')}
              className={'btn ' + (language.currentLanguage === 'fr' ? 'btn-light' : 'btn-outline-light')}>FR</button>
            <button type="button" onClick={() => language.changeLanguage('en')}
              className={'btn ' + (language.currentLanguage === 'en' ? 'btn-light' : 'btn-outline-light')}>EN</button>
          </div>
          {auth.isLoggedIn && (
            <>
              <span className="badge text-bg-light text-primary">{auth.role}</span>
              <span className="text-white">{auth.name}</span>
              <button type="button" className="btn btn-sm btn-outline-light" onClick={onLogout}>
                {t('APP.LOGOUT')}
              </button>
            </>
          )}
        </div>
      </nav>

      <div className="row g-2 align-items-center mb-4">
        <div className="col-auto">
          <label className="form-label mb-0" htmlFor="input-server-url">{t('APP.SERVER_URL_LABEL')}</label>
        </div>
        <div className="col-sm-4">
          <input id="input-server-url" type="text" className="form-control form-control-sm"
            defaultValue={settings.apiBaseUrl} onChange={(e) => settings.setApiBaseUrl(e.target.value)} />
        </div>
      </div>

      {error && <div className="alert alert-danger" role="alert">{error}</div>}

      {!auth.isLoggedIn ? (
        <Login />
      ) : (
        <>
          <DoctorDayPicker doctors={doctors} onSearch={onSearchSchedule} />
          <Schedule schedule={schedule} canEdit={auth.isAdmin}
            onBook={onBookingRequest} onCancel={onCancelAppointment} />
          <BookingDialog open={slotBeingBooked !== null} slot={slotBeingBooked}
            clients={clients} onConfirm={onConfirmBooking} onClose={() => setSlotBeingBooked(null)} />
        </>
      )}
    </div>
  );
}

我们来解读这段代码:

  • 第 27–28 行:const lastDoctorId = useRef<number | null>(null); const lastDay = useRef<string | null>(null); ——我们存储最近一次搜索(医生 + 日期),以便在预约或取消之后刷新日程表。使用的是 [useRef](),而不是 [useState]():这两个值从不直接用于显示(不同于“schedule”或“error”),因此它们变化时无需重新绘制组件——这与在 [Angular] 方面把 [lastDoctorId/lastDay] 保留为简单的私有字段而不是信号的理由完全相同;修改 [useRef]() 的值(.current = …)不会重新绘制组件,这不同于 [setXxx()] 来自 [useState]() 的调用;
  • 第 30–35 行:useEffect(() => { if (auth.isLoggedIn) { loadInitialLists(); } }, [auth.isLoggedIn]); ——每当 [auth.isLoggedIn] 变化时就重新执行其函数体——直接对应 [effect(() => { if (this.auth.isLoggedIn()) { … } })] 在 [Angular] 方面的写法。它在组件挂载时也会运行一次:如果会话已存储在 [localStorage] 中(页面重新加载),列表会在启动时立即加载,而无需等待登录;
  • 第 89–94 行:<div className="btn-group btn-group-sm" …> …FR…EN… </div> ——语言选择器始终可见(包括在登录界面上);而角色徽章、姓名和登出按钮则仅在 [auth.isLoggedIn] 时才显示(第 95–103 行,[{auth.isLoggedIn && (…)})]——与 [Angular] 和 [(@if (auth.isLoggedIn()) { … })] 两侧的逻辑完全相同;
  • 第 119–130 行:{!auth.isLoggedIn ? ( <Login /> ): ( <>…</> )} ——只要 [useAuth().isLoggedIn] 等于 false,该组件就只显示 <Login />;由于现在所有服务器路由都受 [JwtAuthGuard] 保护(第 3 章),在登录之前加载医生/客户(患者)/日程表无论如何都没有意义(还会导致 401 错误)——理由与 [Angular] 完全相同;
  • 第 123–127 行:<DoctorDayPicker doctors={doctors} onSearch={onSearchSchedule} /> … ——features/ 中的三个“业务逻辑”组件在这里组装,每个都接收自己的 props(数据 + 回调函数)——完全对应 [app.html] 模板在 [Angular] 方面的写法,在那里同样的三个组件以 [doctors]="doctors()"([search)="onSearchSchedule($event)"]……的形式出现。

状态([useState/useRef])、副作用([useEffect])和事件处理函数(各个 onXxx 函数):这恰好是上一章已经介绍过的四个组成部分,在这里应用于整个根组件——这个文件中没有引入任何新东西,只是把它们组装了起来。

6.12. 应用使用分步指南

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

6.12.1. 1. 登录界面

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

Image

登录界面

尝试使用无效的用户名/密码组合时,会显示由 [Login.tsx] 存储的错误消息:

Image

登录错误

始终可见的 FR/EN 选择器也会把这个界面翻译成法语(存储的错误消息也会被重新翻译,无需额外代码;见上文的 [Login.tsx] ):

Image

法语的登录界面

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

使用 admin/admin 登录后,[App.tsx] 不再显示 <Login />,并加载医生/客户(患者)([loadInitialLists()],由第 30 行的 [useEffect(…, [auth.isLoggedIn])] 触发):

Image

以 ADMIN 登录后的主页

Image

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

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

Image

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

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

Image

预约窗口(Bootstrap 模态框)

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

Image

预约后的日程表

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

Image

取消后的日程表

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

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

Image

以 USER 登录后的主页

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

Image

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

6.13. 仍不在范围内或推迟的内容

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

还有两处差异,是本次 [React] 移植特有的,值得在此一提:

  • 单元测试(本项目和本课程的 [Angular] 项目中都没有)在 [React] 中会采用不同的方法:不是使用 TestBed([Angular] 特有),而是 [React] 生态通常依赖 [React Testing Library]——本文档未予介绍;
  • 模板的类型检查([Angular] strictTemplates,见上一章)在 [React] 方面没有需要单独配置的对应物:检查 [JSX] 的是 TypeScript 编译器本身,就像检查任何其他 .tsx 文件一样——这简化了配置,代价是理论上模板语言与类型系统之间的集成稍浅一些(实际上,在本项目中没有可观察到的差异)。