Skip to content

11. 案例研究:RdvMedecins 应用程序的 Ionic 客户端

11.1. 问题

[RdvMedecins] 应用程序允许用户在诊所预约医生。[NestJS] 课程把它写成了一个 HTML 应用程序,由服务器生成页面;[Vue.js]、[Angular] 和 [React] 课程为它编写了 Web 客户端,它们利用“RdvMedecins 服务器,一个黑盒”一章中描述的服务器 JSON 数据,在浏览器中生成相同的页面;[Flutter] 课程则开发了一个移动客户端。在这里,我们开发的是 [Ionic] 客户端:一个移动应用([Android]),使用 [Angular] 和 [Capacitor] 构建,同时无需任何修改,它也是一个 Web 应用。

该客户端必须提供其他客户端所提供的一切:

  • 一个受验证码(CAPTCHA)保护的登录界面,并可创建患者账户;
  • 医生某一天的日程,可预约(患者选择窗口)和取消;
  • 对于管理员,管理医生和客户(列表、添加、编辑、删除);
  • 对于患者,一个个人仪表板(显示即将到来的预约,可取消)以及账户管理;
  • 两种语言:法语和英语;
  • 与 Web 客户端相同的地址([/schedule?doctorId=1&day=...])。在手机上,这些地址不可见,但它们组织着应用;在 Web 上,用户可以重新加载它们、将其加入书签,并使用浏览器的后退/前进按钮在应用中导航。

移动应用有它自己的要求:狭窄的屏幕(没有五列的表格)、会遮住半个屏幕的键盘、返回按钮、密码管理器,以及并非来自由服务器提供的网页的 HTTP 请求(令牌 Cookie 应该存放在哪里?)。

这是一个把各个示例分别介绍过的内容整合起来的机会:组件和信号、表单、路由器和守卫、共享状态、翻译,以及与服务器的通信。

11.2. 安装与运行

必须已安装并运行 JSON 服务器(参见“RdvMedecins 服务器:一个黑盒”一章)。不需要 CAPTCHA 测试模式:你可以在服务器的 [.env] 文件中将 [CAPTCHA_TEST] 字段留空。

在 [rdvmedecins_ionic] 文件夹下打开的控制台窗口中:

npm install
npm start
  • 第 1 行:下载项目的软件包([node_modules] 文件夹),由 [package.json] 描述;
  • 第 2 行:启动 [ng serve],即 [Angular] 的开发服务器,地址为 http://localhost:8100。它把 /api 请求转发给 JSON 服务器(文件 [proxy.conf.json],与示例 22 至 25 相同)。在 [Chrome] 中打开这个 URL,最好使用开发者工具(F12)的“移动设备”模式(Ctrl+Shift+M),按手机的尺寸查看。

与示例中一样,对源文件的任何修改都会立即在浏览器中被编译并重新加载。

要在 [Android] 上试用(需要 [Android] SDK 和 [Android Studio];参见“搭建开发环境”一章):

1
2
3
4
npx cap add android
npx ng build
npx cap sync android
npx cap run android
  • 第 1 行:仅需执行一次:创建 [Android Studio] 项目(文件夹 [android/])。使用较新版本 [Android Studio] 中的 JDK([Java] 25),然后我们把项目升级到 [Gradle] 9.1(文件 [android/gradle/wrapper/gradle-wrapper.properties],参见示例 01);
  • 第 2 行:把 Web 应用编译到 [dist/rdvmedecins_ionic/browser/];
  • 第 3 行:把它复制到 [Android] 项目中;
  • 第 4 行:在模拟器或通过 USB 连接的手机上运行(该命令会提示你选择其中之一)。模拟器通过地址 [10.0.2.2:8080] 连接到服务器(参见示例 22);对于真机,请在编译时指定电脑在 Wi-Fi 网络中的地址:[npx ng build --define "SERVER='http://192.168.1.20:8080'"] (参见 [config.ts])。“部署”一章详细介绍了这些步骤。

演示账户列在登录界面上(密码 = 登录名)。

11.3. 使用应用程序

本节中的截图来自一部分辨率为 1082 × 2342 像素(412 × 892 点)的手机。它们由程序 [captures/captures.mjs] (参见示例 01)生成,该程序以这个分辨率驱动一个 [Chromium] 浏览器,并针对每一组屏幕运行 [captures/scenarios/] 文件夹中的一个场景。

11.3.1. 登录界面

登录界面;密码错误:消息显示在屏幕底部,并显示一张新图片(每张图片只使用一次):

11.3.2. 管理员和医生所看到的日程

以 [admin] 身份登录后,你会进入日程。☰ 按钮会打开菜单:管理员可访问的屏幕,以及顶部显示的当前登录者:

选择一位医生和一个日期(在日历中选择日期),然后点击“查看日程”。URL 会变为 [/schedule?doctorId=1&day=2026-10-13]。点击“预约”会打开预约窗口;URL 会变为 [/schedule?doctorId=1&day=2026-10-13&book=2]:

预约已保存;“取消”会提示确认:

医生直接进入他或她自己的每日日程:

Image

11.3.3. 患者的仪表板

患者([martin])进入“我的空间”。在日历中,他在其他患者的时间段旁看到“已预约”,并为自己预约,而无需选择具体的患者:

他的预约显示在他的姓名下;“预约”按钮不再可用(只允许有一个即将到来的预约)。在另一位医生的日程中,如果他的预约没有出现,会有一条消息解释他为何无法预约。他的空间显示这个预约:

“管理我的账户”:任何修改都需要当前密码;错误来自服务器端:

Image

患者的菜单中没有“医生”一项。在 Web 上,如果他们自己输入地址 /doctors,路由器的守卫会显示 403 错误页面(参见 [app.routes.ts])。

11.3.4. 管理医生和客户

医生列表;一个填写不正确的条目:

添加成功;一个同名者;删除有预约的医生被拒绝:

11.3.5. 创建账户

在登录界面上,输入验证码,然后点击“创建患者账户”。表单被服务器拒绝;账户创建后,你会回到登录界面,登录信息已预先填好:

11.3.6. 法语界面,大屏幕

顶部栏中的 FR / EN 菜单会在本地重新渲染屏幕,无需向服务器发出任何请求,日期也包括在内(“mardi 13 octobre 2026”)。在宽屏幕(Web、平板)上,菜单会一直显示在左侧:

Image

Image

11.3.7. 会话过期

如果令牌过期(或 Cookie 被删除),下一个请求会收到 401 响应;应用程序会重定向到登录界面并显示一条消息:

Image

11.4. 客户端架构

rdvmedecins_ionic/
├── package.json             the packages, the scripts
├── angular.json             the Angular project configuration
├── tsconfig.json            the TypeScript configuration
├── proxy.conf.json          the development server (/api relay)
├── capacitor.config.ts      the Capacitor configuration (Android)
├── android/                 the Android Studio project (after npx cap add android)
├── captures/                the making of the screenshots (Playwright)
├── public/
│   └── i18n/                the dictionaries fr.json, en.json
└── src/
    ├── index.html           the page that hosts the application
    ├── main.ts              the startup
    ├── styles.scss          the common styles
    └── app/
        ├── app.ts           the root component
        ├── back-button.ts   Android's Back button
        ├── app.routes.ts    the screens, their addresses, their access rights
        ├── config.ts        the address of the server
        ├── formatting.ts    the formatting of times and days
        ├── api/             the API access layer
        ├── i18n/            the languages
        ├── state/           session, messages, cache (signal-based services)
        ├── components/      the layout and the reusable components
        └── pages/           the screens

这是 [Flutter] 客户端的逐文件结构,文件名采用 [Angular] 的风格(小写,单词之间用连字符分隔):

  • 数据层([api/]):唯一了解 [Angular] 的 HTTP 客户端、URL 和 JSON 格式的一层;
  • 状态层([state/]):基于信号的服务,通过依赖注入提供给整个应用程序,由各屏幕读取;
  • 界面层([pages/]、[components/]):显示状态并传递用户操作的组件。

下表将 [Flutter] 客户端与本客户端进行比较:

概念
Flutter 客户端
Ionic 客户端
屏幕
控件(widget)
Angular 和 Ionic 组件
屏幕外围的元素
[layout.dart],[ShellRoute] 的控件
[layout.ts],包裹 [ion-router-outlet]
菜单
[NavigationDrawer] / [NavigationRail]
[ion-menu] 位于 [ion-split-pane] 中
地址
[go_router]
Angular 路由器
访问权限
路由器的 [redirect] 函数
一个守卫:[CanActivateFn]
令牌 Cookie
一个管理 Cookie 的 HTTP 客户端
浏览器(Web),[CapacitorHttp] (Android)
会话过期(401)
分配给 [ApiClient] 的一个函数
一个拦截器,[HttpInterceptorFn]
共享状态
[ChangeNotifier] ([provider])
信号服务([inject()])
异步数据
[FutureBuilder]
[resource()]
已读取的数据
[Cache] (几行代码)
[Cache] (几行代码)
存储的语言
[shared_preferences]
[@capacitor/preferences]
表单被拒绝
错误显示在字段下方
相同

下面列出了该客户端的所有文件。它们都有大量注释;这些注释是课程材料的一部分。

11.5. 项目配置

该项目的创建方式与示例相同(参见示例 01):[ng new],然后添加 [Ionic] 和 [Capacitor] 软件包。文件 [angular.json] 和 [tsconfig.json] 是由 [ng new] 生成的;它们与示例中的完全相同,只有两处例外:在 [angular.json] 中,是开发服务器端口(8100)和转发文件([proxyConfig]);在 [tsconfig.json] 中,是严格检查([strict]、[strictTemplates])。

11.5.1. package.json

{
  "name": "rdvmedecins-ionic",
  "version": "0.0.0",
  "scripts": {
    "ng": "ng",
    "start": "ng serve",
    "build": "ng build",
    "watch": "ng build --watch --configuration development",
    "android": "ng build && cap sync android && cap run android",
    "captures": "node captures/captures.mjs"
  },
  "private": true,
  "packageManager": "npm@10.9.4",
  "dependencies": {
    "@angular/common": "^22.2.0",
    "@angular/compiler": "^22.2.0",
    "@angular/core": "^22.2.0",
    "@angular/forms": "^22.2.0",
    "@angular/platform-browser": "^22.2.0",
    "@angular/router": "^22.2.0",
    "@capacitor/android": "^8.5.2",
    "@capacitor/app": "^8.1.2",
    "@capacitor/core": "^8.5.2",
    "@capacitor/preferences": "^8.0.1",
    "@ionic/angular": "^9.0.6",
    "ionicons": "^8.1.0",
    "rxjs": "~7.8.0",
    "tslib": "^2.3.0"
  },
  "devDependencies": {
    "@angular/build": "^22.2.1",
    "@angular/cli": "^22.2.1",
    "@angular/compiler-cli": "^22.2.0",
    "@capacitor/cli": "^8.5.2",
    "playwright": "^1.56.1",
    "prettier": "^3.8.1",
    "typescript": "~6.0.2"
  }
}
  • 第 4–11 行:脚本:[npm start] 启动开发服务器,[npm run build] 编译应用程序,[npm run android] 编译应用、将其复制到 [Android] 项目并在手机上运行;[npm run captures] 生成截图;
  • 第 14–29 行:应用程序的软件包:[Angular] (不含 [@angular/animations] 或 [zone.js]:该应用程序是“无 Zone”的,参见示例 01)、[Capacitor] (其核心、[Android] 平台、提供返回按钮访问能力的 [App] 插件,以及存储语言的 [Preferences] 插件)、[Ionic] 及其图标;[rxjs] 是 HTTP 客户端所用的 [Observable] 库;
  • 第 30–38 行:开发工具:[Angular] 编译器、[ng] 命令、[cap] 命令(来自 [Capacitor])、用于截图的 [Playwright] 、用于代码格式化的 [Prettier] ,以及 [TypeScript]。

除了示例中的软件包之外,没有任何额外的软件包:没有翻译库、状态管理库或表单库。应用程序所需的一切都在 [Angular] 和 [Ionic] 中,以及这里编写的少量文件中。

11.5.2. proxy.conf.json

1
2
3
4
5
6
7
8
{
  "/api": {
    "target": "http://localhost:8080",
    "secure": false,
    "changeOrigin": false,
    "logLevel": "warn"
  }
}

即示例 22 中的那个:在 Web 开发中,[ng serve] 把 /api 请求转发给 JSON 服务器。对浏览器、应用程序和 API 而言,源是相同的(http://localhost:8100):无需 CORS 授权,令牌 Cookie 也会被传递。

11.5.3. capacitor.config.ts

// =========================================================================
// capacitor.config.ts - Capacitor 的配置
// -------------------------------------------------------------------------
// Capacitor 把 Web 应用程序(ng build 生成的文件夹)
// 变成 Android 应用程序:它把应用包装在一个 Android Studio 项目
// (android/ 文件夹)中,由“WebView”显示它,WebView 是手机上
// Chrome 浏览器的引擎。命令(参见“部署”一章):
//     npx cap add android       (只需一次:创建 android/ 文件夹)
//     ng build                  (构建 Web 应用程序)
//     npx cap sync android      (把它复制到 Android 项目中)
//     npx cap run android       (在模拟器或手机上运行)
// =========================================================================

import type { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  // 应用在手机(以及 Play Store)上的唯一标识符
  appId: 'fr.stahe.rdvmedecins',
  // 显示在图标下方的名称
  appName: 'RdvMedecins',
  // 已编译 Web 应用所在的文件夹(ng build)
  webDir: 'dist/rdvmedecins_ionic/browser',
  server: {
    // 允许向开发用 JSON 服务器发送未加密的 HTTP 请求 (http://10.0.2.2:8080)
    // (生产环境中应移除:使用 HTTPS)
    cleartext: true,
  },
  plugins: {
    // CapacitorHttp:应用程序的 HTTP 请求不再由
    // WebView 发出,而是由 Android 的原生代码发出。后果(参见
    // api/http-client.ts):没有 CORS 检查(JSON 服务器无需
    // 允许任何内容),并且 Cookie(身份验证令牌的那个)由
    // Android 保存并自动发回
    CapacitorHttp: {
      enabled: true,
    },
  },
};

export default config;

[Capacitor] 的配置(参见示例 01):

  • 第 18 行:应用程序在手机上(以及在 [Play Store] 上)的应用 ID:与 [Flutter] 应用的相同。因此,这两个应用不能同时安装在同一部手机上;要比较它们,必须修改其中一个;
  • 第 22 行:编译后的 Web 应用程序所在的文件夹,[npx cap sync] 会把它复制到 [Android] 项目中;
  • 第 26 行:默认情况下,[Android] 会拒绝未加密的 HTTP 请求;这里允许它们,以便连接开发服务器([http://10.0.2.2:8080])。在生产环境中,服务器必须设置为 HTTPS;
  • 第 34–36 行:[CapacitorHttp] 插件(示例 22):在手机上,HTTP 请求不再由 [WebView] 发出,而是由 [Android] 的原生代码发出。因此服务器无需遵循任何 CORS 规则,Cookie 由 [Android] 自身保存并发回。这使得 [Ionic] 客户端不再需要“管理 Cookie”的 HTTP 客户端——而 [Flutter] 客户端则需要。

11.6. 启动应用程序

11.6.1. src/app/config.ts

// =========================================================================
// src/app/config.ts - JSON 服务器在哪里?
// -------------------------------------------------------------------------
// 对于由服务器自身提供服务的 Web 应用程序,这个问题并不存在:
// 请求发往与页面相同的源
// (相对地址,/api/...)。但移动应用没有
// 可用的源(在 Android 上,页面由 Capacitor 从
// https://localhost 提供):必须给它服务器的完整地址。
//   - Android 模拟器把运行它的电脑看作
//     地址 10.0.2.2(对它来说,localhost 就是模拟器自己);
//   - 真机与电脑连接到同一个 Wi-Fi 网络时,必须
//     使用电脑在该网络中的地址(192.168.1.20……):
//     在构建应用程序时提供它:
//         ng build --define "SERVER='http://192.168.1.20:8080'"
//   - 在 Web 开发(ng serve)中,Angular 的开发
//     服务器会把 /api 请求转发给 JSON 服务器(文件
//     proxy.conf.json):使用相对地址就够了。
// =========================================================================

import { Capacitor } from '@capacitor/core';

// 构建(ng build、ng serve)时由 --define "SERVER='...'" 给出的值。
// 该选项会在编译后的代码中把单词
// SERVER 替换为给定的值。没有它,SERVER 就不存在:typeof
// 让我们可以在不引发错误的情况下检查它
declare const SERVER: string | undefined;
const forcedServer = typeof SERVER === 'string' ? SERVER : '';

export const config = {
  // Capacitor.isNativePlatform():在 Android(或 iOS)应用中为 true,
  // 在浏览器中为 false;Capacitor.getPlatform():'android'、'ios' 或 'web'
  serverUrl:
    forcedServer !== ''
      ? forcedServer
      : !Capacitor.isNativePlatform()
        ? '' // Web:同源,使用相对地址
        : Capacitor.getPlatform() === 'android'
          ? 'http://10.0.2.2:8080'
          : 'http://localhost:8080',
};

服务器地址,取决于平台(参见示例 22):

  • 第 26 行:[declare const SERVER] 向 [TypeScript] 编译器声明一个编译器在其他任何地方都看不到的常量;它由编译命令提供([ng build --define "SERVER='...'"])。选项 [--define] 会在编译后的代码中把单词 [SERVER] 替换为给定的值:地址被写入构建好的应用程序中,就像 [--dart-define] 在 [Flutter] 中那样;
  • 第 27 行:如果没有这个选项,[SERVER] 就不存在,试图读取它会导致运行时错误;[typeof] 是唯一接受未知名称的运算符(此时它返回“undefined”);
  • 第 32–39 行:否则,使用相对 Web 地址(开发服务器,以及生产环境中的 JSON 服务器本身,既提供页面又提供 API),在 [10.0.2.2] 上用于 [Android] (从模拟器看到的电脑),其他情况使用 [localhost]。[Capacitor.isNativePlatform()] 表示应用程序是否运行在 [Capacitor] 的原生环境中(而不是在浏览器中),而 [Capacitor.getPlatform()] 则指明具体是哪个系统。

11.6.2. src/main.ts

// =========================================================================
// src/main.ts - 应用的入口点
// -------------------------------------------------------------------------
// Angular 应用程序从 bootstrapApplication 开始:Angular 创建
// 根组件(App),并把它插入 index.html 页面的 <app-root> 标签中。
// 第二个参数给出整个应用程序的“提供者”:
// Ionic、路由器、HTTP 客户端及其拦截器、屏幕标题,
// 以及语言的加载。
// 各个服务(会话、消息、缓存、翻译、API)无需在这里
// 声明:providedIn: 'root' 会把它们提供给整个应用程序。
// =========================================================================

import { provideHttpClient, withInterceptors } from '@angular/common/http';
import { inject, provideAppInitializer } from '@angular/core';
import { bootstrapApplication } from '@angular/platform-browser';
import { provideRouter, TitleStrategy, withComponentInputBinding } from '@angular/router';
import { provideIonicAngular } from '@ionic/angular';
import { apiInterceptor } from './app/api/http-client';
import { App } from './app/app';
import { routes } from './app/app.routes';
import { PageTitle } from './app/components/page-title';
import { Translations } from './app/i18n/translations';

bootstrapApplication(App, {
  providers: [
    // Ionic:'md' 模式(Material Design)= Android 的外观,即使在
    // 电脑的浏览器中也是如此
    provideIonicAngular({ mode: 'md' }),
    // 路由器:路由列表(app.routes.ts);
    // withComponentInputBinding:路由的参数(:id、?day=...、
    // data)会传给屏幕组件的输入
    provideRouter(routes, withComponentInputBinding()),
    // Angular 的 HTTP 客户端,它的每个请求都会经过我们的拦截器
    provideHttpClient(withInterceptors([apiInterceptor])),
    // 我们的屏幕标题是翻译键(参见 page-title.ts)
    { provide: TitleStrategy, useClass: PageTitle },
    // 在第一个屏幕之前:语言(已保存的,或设备的)
    // 及其字典。Angular 会等待所返回的 Promise 结束
    provideAppInitializer(() => inject(Translations).start()),
  ],
}).catch((err) => console.error(err));

启动。这里只有提供者:共享对象(会话、消息、缓存、翻译和 API 访问层)都是 [providedIn: 'root'] 服务,由 [Angular] 在首次注入时创建(参见示例 14)。

  • 第 28 行:[Ionic],使用 [md] 模式([Android] 的外观);
  • 第 32 行:路由器;[withComponentInputBinding()] 把地址参数([?day=...]、[:id])和路由数据([data])提供给屏幕组件的输入(参见示例 17)。这样,各屏幕就不必自己读取地址;
  • 第 34 行:HTTP 客户端及其拦截器(参见 [api/http-client.ts]);
  • 第 36 行:路由器的“标题策略”被我们的策略取代,后者会翻译标题(参见 [components/page-title.ts]);
  • 第 39 行:[provideAppInitializer]:在显示第一个屏幕之前执行的函数;如果它返回 [Promise],[Angular] 会等待它完成。源语言字典在这里加载:第一个屏幕直接以正确的语言显示(这相当于 [await translations.start()] 在 [runApp] 之前、[Flutter] 客户端中的位置)。

11.6.3. src/app/app.ts

// =========================================================================
// src/app/app.ts - 应用的根组件
// -------------------------------------------------------------------------
// 它显示布局(其中包含各屏幕的位置),并通过两种机制
// 把应用程序的各个服务连接起来:
//   1. 会话变化(登录、注销、会话过期):为
//      上一个用户读取的数据已毫无价值(缓存会被
//      清除),并且路由器守卫会针对
//      当前屏幕重新评估:正是它们在登录后
//      离开登录界面,或在注销后把用户送回登录界面;
//   2. “闪现”消息:在每次导航结束时,上一个屏幕
//      的消息消失,留给下一个
//      屏幕的消息出现(参见 state/messages.ts)。
// 会话过期(401 响应)由拦截器处理
// (api/http-client.ts):它清除会话,其余由机制 1 完成。
// 它还接通了 Android 的返回按钮(参见 back-button.ts)。
// =========================================================================

import { Component, computed, effect, inject, untracked } from '@angular/core';
import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
import { NavigationEnd, Router } from '@angular/router';
import { IonApp, NavController } from '@ionic/angular';
import { filter } from 'rxjs';
import { handleBackButton } from './back-button';
import { Layout } from './components/layout';
import { Cache } from './state/cache';
import { Messages } from './state/messages';
import { Session } from './state/session';

@Component({
  selector: 'app-root',
  imports: [IonApp, Layout],
  template: `
    <ion-app>
      <app-layout />
    </ion-app>
  `,
})
export class App {
  private readonly session = inject(Session);
  private readonly cache = inject(Cache);
  private readonly messages = inject(Messages);
  private readonly router = inject(Router);
  private readonly navigation = inject(NavController);
  // 已登录用户的角色(null:无人)。新的姓名
  // (账户更新)不会改变这个信号:只有登录
  // 和注销才会改变它
  private readonly role = computed(() => this.session.user()?.role ?? null);
  private url = '';

  constructor() {
    // Android 的返回按钮
    handleBackButton();
    // 1a. 会话变化:缓存被清除
    effect(() => {
      this.session.user();
      untracked(() => this.cache.clear());
    });
    // 1b. 登录、注销:针对当前地址重新评估守卫。
    // navigateRoot:显示的屏幕将替换 Ionic 屏幕的整个栈
    // (上一个用户的屏幕会消失);
    // onSameUrlNavigation: 'reload':即使导航到当前地址,
    // 导航也会发生(守卫也会运行)
    effect(() => {
      this.role();
      untracked(() => {
        // 不在第一次导航之前:它会负责处理
        if (!this.router.navigated) return;
        void this.navigation.navigateRoot(this.router.url, { onSameUrlNavigation: 'reload', replaceUrl: true });
      });
    });
    // 2. 每次导航完成时(地址已变化):新页面
    this.router.events
      .pipe(
        filter((e) => e instanceof NavigationEnd),
        takeUntilDestroyed(),
      )
      .subscribe((e) => {
        if (e.urlAfterRedirects !== this.url) {
          this.url = e.urlAfterRedirects;
          this.messages.newPage();
        }
      });
  }
}

根组件:它显示布局,并把应用程序的各个服务连接起来,就像 [main.dart] 所做的那样:

  • 第 34–36 行:[ion-app],整个 [Ionic] 应用程序的容器,以及布局(参见 [components/layout.ts]),其中包含各屏幕的位置;
  • 第 48 行:已登录用户的角色,由会话计算得出。计算信号([computed])只有在其值发生变化时才通知读取者:更改用户的姓名(“管理我的账户”)会改变用户,但不会改变其角色;
  • 第 53 行:[Android] 的返回按钮,由 [back-button.ts] 中的函数关联(见下文);
  • 第 55–58 行:1a. 每当用户变化时,缓存都会被清除:为上一个用户读取的数据与下一个用户无关(患者不应看到管理员查看过的日程)。当副作用所读取的信号发生变化时,副作用([effect])会重新执行:此处为 [this.session.user()]。[untracked]:随后发生的事情不是该副作用的依赖项;
  • 第 64–71 行:1b. 每次登录或注销时,系统都会“导航”回当前地址,从而重新执行路由器的守卫(参见 [app.routes.ts]):正是守卫在登录成功后离开登录界面,或在注销或会话过期后返回登录界面。这就是 [refreshListenable] (来自 [go_router])的手工实现。[navigateRoot] (来自 [NavController] ,属于 [Ionic]):显示的屏幕会替换 [Ionic] 的整个屏幕栈;上一个用户的屏幕会被销毁。[onSameUrlNavigation: 'reload']:没有这个选项,路由器会忽略对当前地址的导航;
  • 第 68 行:启动时,副作用在第一次导航之前运行,而第一次导航无论如何都会执行检查:因此不采取任何操作;
  • 第 73–83 行:2. 闪现消息。路由器在一个 [Observable] ([router.events])中发布其事件;只保留导航结束事件([filter]),并且如果地址已发生变化,系统就会切换到“新页面”:上一个屏幕的消息消失,为本屏幕发布的消息出现(参见 [messages.ts])。关闭预约窗口的返回按钮会改变 URL:它也会清除消息。[takeUntilDestroyed()]:订阅随组件结束(此处是随应用程序结束)。

11.6.4. src/app/back-button.ts

// =========================================================================
// src/app/back-button.ts - Android 的返回按钮
// -------------------------------------------------------------------------
// 在手机上,Capacitor 会收到返回按钮的按下事件。如果它没有
// 针对该事件的监听器,它只会在
// WebView 的历史中后退,然后关闭应用程序:Ionic 对此一无所知
// (已打开的对话框不会关闭,抽屉菜单也不会)。
// @capacitor/app 插件让我们可以订阅它:只要有
// 一个监听器,Capacitor 就会把按键转发给 Ionic,Ionic 会调用
// 优先级最高的处理程序:
//   - 100:已打开的对话框(alert、ion-modal……)关闭;
//   -  99:已打开的抽屉菜单关闭;
//   -   1:(我们的)返回上一个屏幕;如果没有上一个屏幕,
//          就退出应用程序。
// 在浏览器中没有返回按钮:我们什么也不做。
// =========================================================================

import { inject } from '@angular/core';
import { NavController, Platform } from '@ionic/angular';
import { App as CapacitorApp } from '@capacitor/app';
import { Capacitor } from '@capacitor/core';

// 在根组件的构造函数中调用(注入上下文)
export function handleBackButton(): void {
  if (!Capacitor.isNativePlatform()) return;
  const navigation = inject(NavController);
  // 一个(空的)监听器:Capacitor 现在会把按键转发给 Ionic
  void CapacitorApp.addListener('backButton', () => {});
  inject(Platform).backButton.subscribeWithPriority(1, async () => {
    // pop():回到 Ionic 栈中的上一个屏幕;false:栈中
    // 只有当前显示的屏幕,后面没有可返回的了
    if (!(await navigation.pop())) {
      await CapacitorApp.exitApp();
    }
  });
}

与示例中的文件相同(参见示例 01,“Android 返回按钮”)。在这里,它依次为手机的返回按钮分配如下功能:关闭已打开的窗口(预约窗口、确认请求、医生列表、日历),关闭抽屉菜单,返回上一个屏幕,最后在第一个屏幕上退出应用。

11.6.5. src/styles.scss

// =========================================================================
// src/styles.scss - 整个应用的样式
// -------------------------------------------------------------------------
// Ionic 的样式表:没有它们,它的组件就没有
// 应有的外观。core.css 是必需的;其余的是工具类
// (边距、对齐、类 ion-padding、ion-text-center……)。
// =========================================================================

@use '@ionic/angular/css/core.css';
@use '@ionic/angular/css/normalize.css';
@use '@ionic/angular/css/structure.css';
@use '@ionic/angular/css/typography.css';
@use '@ionic/angular/css/padding.css';
@use '@ionic/angular/css/float-elements.css';
@use '@ionic/angular/css/text-alignment.css';
@use '@ionic/angular/css/text-transformation.css';
@use '@ionic/angular/css/flex-utils.css';
@use '@ionic/angular/css/display.css';

// 应用程序的主色调(按钮、顶部栏):靛蓝色,
// 与课程示例中一样。Ionic 会从 --ion-color-primary 派生出
// 更浅(tint)和更深(shade)的变体
:root {
  --ion-color-primary: #3f51b5;
  --ion-color-primary-rgb: 63, 81, 181;
  --ion-color-primary-contrast: #ffffff;
  --ion-color-primary-contrast-rgb: 255, 255, 255;
  --ion-color-primary-shade: #37479f;
  --ion-color-primary-tint: #5262bc;
}

// -------------------------------------------------------------------------
// RdvMedecins 各屏幕共用的样式
// -------------------------------------------------------------------------

// 屏幕的标题
h1 {
  font-size: 26px;
  font-weight: 400;
  margin: 8px 0 12px;
}

// 一个分区的标题(“用户账户”)
h3 {
  font-size: 15px;
  font-weight: 500;
  margin: 16px 0 12px;
}

// 帮助文本,灰色
.help,
.intro {
  font-size: 14px;
  color: var(--ion-color-medium-shade);
}

// 每个下拉列表下方留一点空白
ion-select {
  margin-bottom: 12px;
}

// 表单的按钮,并排显示(如果放不下,
// 则上下排列)
.buttons {
  display: flex;
  flex-wrap: wrap;
  gap: 8px;
  margin-top: 12px;
}

// 登录界面的演示账户
.demo {
  margin-top: 16px;
  font-size: 13px;
  color: var(--ion-color-medium-shade);

  code {
    font-family: 'Roboto Mono', monospace;
    font-size: 12px;
  }
}

// 确认框(AlertController,参见 confirmation.ts):稍宽一些,
// 其“Yes”按钮为红色
ion-alert.confirmation {
  --min-width: 310px;
  --max-width: 340px;
}

ion-alert.confirmation button.danger-button {
  background: #d32f2f;
  color: white;
  border-radius: 20px;
  padding: 0 16px;
}

// 一个窗口(ion-modal),大小与其内容相同,位于屏幕中央,
// 而不是占满整个屏幕(这是手机上的默认行为)
ion-modal.dialog {
  --width: calc(100% - 48px);
  --max-width: 420px;
  --height: fit-content;
  --border-radius: 16px;
}

所有屏幕共用的样式:

  • 第 9–18 行:[Ionic] 的样式表(参见示例 01);
  • 第 23–30 行:主色调靛蓝色及其变体;
  • 第 37–60 行:标题、帮助文本,以及下拉列表下方的间距;
  • 第 64–69 行:表单按钮,并排显示,如果放不下则上下排列([Wrap] 来自 [Flutter],在 CSS 中为:[flex-wrap: wrap]);
  • 第 72–81 行:登录界面上的演示账户,小号字体;用户名使用等宽字体;
  • 第 85–95 行:确认框,比 [Ionic] 默认的稍宽(“No, go back”和“Yes, confirm”可以排在一行),以及它的红色按钮。由 [AlertController] 创建的对话框会被添加到页面末尾,位于任何组件之外:只有全局样式表才能影响它们;
  • 第 99–104 行:类为 [ion-modal] 窗口的 [dialog] 会采用其内容的大小并在屏幕上居中。在手机上,[Ionic] 窗口默认占满整个屏幕;因此预约窗口和日历窗口类似于 [Material] 对话框。[fit-content]:内容的高度。

11.7. API 访问层

11.7.1. src/app/api/api-client.ts

// =========================================================================
// src/app/api/api-client.ts - 所有对 API 的请求都经过这里
// -------------------------------------------------------------------------
// 取自示例的 API 层(示例 24):只有一个方法 request(),
// 它构建完整地址(config.serverUrl + /api + url),
// 以 JSON 发送请求体,并返回响应的 Promise。
//
// Angular 的 HTTP 客户端(HttpClient)让每个请求都经过应用程序的
// 拦截器(http-client.ts),拦截器把任何错误
// 转换为 ApiError,并在唯一的一处处理 401 响应
// (会话过期)。
// 有些请求自己处理 401(登录、GET
// /api/auth/me……):它们是“公开”的;这一点通过请求的上下文(HttpContext)
// 告知拦截器。
// =========================================================================

import { HttpClient, HttpContext, HttpContextToken } from '@angular/common/http';
import { inject, Injectable } from '@angular/core';
import { firstValueFrom } from 'rxjs';
import { config } from '../config';

// 附加在请求上、由拦截器读取的一条信息。其
// 默认值(false):受保护的请求
export const PUBLIC = new HttpContextToken<boolean>(() => false);

export type Method = 'GET' | 'POST' | 'PUT' | 'DELETE';

@Injectable({ providedIn: 'root' })
export class ApiClient {
  private readonly http = inject(HttpClient);

  // isPublic:对于自己处理 401 的路由为 true。
  // 失败时,Promise 以 ApiError 被拒绝
  request<T>(method: Method, url: string, body?: unknown, isPublic = false): Promise<T> {
    // http.request 返回一个 Observable;firstValueFrom 把它转换为
    // Promise(请求在此刻发送)。请求体对象会
    // 以 JSON 发送(content-type: application/json 头),JSON 响应会
    // 被解码(如果响应体为空则为 null)
    return firstValueFrom(
      this.http.request<T>(method, `${config.serverUrl}/api${url}`, {
        body,
        context: new HttpContext().set(PUBLIC, isPublic),
      }),
    );
  }
}

所有请求都经过 [request] 方法(参见示例 24):

  • 第 24 行:一个“上下文令牌”——附加在请求上、拦截器可以读取的信息。其默认值由函数提供:[false],即受保护的请求;
  • 第 34 行:一个泛型方法:[request<Person[]>(...)] 返回 [Promise<Person[]>]。[isPublic = false]:一个带默认值的可选参数;
  • 第 39–44 行:[http.request] 返回一个 [Observable] (示例 22),只有在订阅它时才会发送请求;[firstValueFrom] 订阅它,并返回一个包含其初始值(即响应)的 [Promise] 。请求体是一个 [JavaScript] 对象:HTTP 客户端会将其作为 JSON 发送,并带上相应的 [Content-Type] 头;响应的 JSON 会被解码(按 UTF-8:重音字符保持完好)。请求上下文携带“公开”信息。

[Flutter] 客户端在这里处理错误和 401 状态码;[Ionic] 客户端则把它们委托给拦截器。

11.7.2. src/app/api/http-client.ts

// =========================================================================
// src/app/api/http-client.ts - HTTP 请求的拦截器
// -------------------------------------------------------------------------
// 拦截器是一个函数,Angular HTTP 客户端的每个请求
// 都要经过它(它在 main.ts 中声明:
// provideHttpClient(withInterceptors([apiInterceptor])))。它接收
// 请求和负责发送请求的“next”处理程序;它可以修改前者,
// 并转换响应。我们的拦截器处理错误:
//   - 任何错误都会变成 ApiError(参见 api-error.ts);
//   - 受保护请求上的 401 响应(会话过期)在这里
//     一次性处理:用户被遗忘,缓存被
//     清除,并准备好登录界面的消息。会话变化时重新评估的
//     路由器守卫(参见 app.ts)随后会
//     把用户送回登录界面。
//
// 那么 JWT 令牌的 Cookie 呢?服务器把它放在一个 Cookie
// (httpOnly)中。应用程序的代码无需做任何事:
//   - 在 Web 上,由浏览器保存 Cookie 并将其发回;
//   - 在 Android 上,CapacitorHttp 插件(已在
//     capacitor.config.ts 中启用)让请求经过 Android 的原生代码,
//     原生代码同样会保存 Cookie 并将其发回(并且
//     在应用程序停止后再重新启动时仍保留它们)。
// =========================================================================

import { HttpErrorResponse, HttpInterceptorFn } from '@angular/common/http';
import { inject } from '@angular/core';
import { catchError, throwError } from 'rxjs';
import { Cache } from '../state/cache';
import { Messages } from '../state/messages';
import { Session } from '../state/session';
import { PUBLIC } from './api-client';
import { ApiError } from './api-error';

export const apiInterceptor: HttpInterceptorFn = (request, next) => {
  // inject():只能在这里,即函数的开头使用(之后,在
  // catchError 中,我们已不在“注入上下文”中)
  const session = inject(Session);
  const cache = inject(Cache);
  const messages = inject(Messages);
  const isPublic = request.context.get(PUBLIC);

  // next(request):发送请求;pipe(catchError(...)):如果失败
  // 该怎么办(成功的响应原样通过)
  return next(request).pipe(
    catchError((e: unknown) => {
      // 并非来自 HTTP 客户端的错误:属于异常情况,让它通过
      if (!(e instanceof HttpErrorResponse)) return throwError(() => e);
      const error = ApiError.fromResponse(e);
      if (error.statusCode === 401 && !isPublic) {
        session.forget();
        cache.clear();
        messages.flash({ success: false, key: 'ERRORS.SESSION_EXPIRED' });
        // 等待响应的屏幕也会显示这条消息
        return throwError(() => new ApiError(401, 'ERRORS.SESSION_EXPIRED'));
      }
      return throwError(() => error);
    }),
  );
};

请求拦截器:它在唯一的一处处理所有错误,尤其是 401 响应。

  • 第 34 行:拦截器是一个简单的函数([HttpInterceptorFn]),在 [main.ts] 中声明:它接收请求和函数 [next](用于转发请求,发往服务器,或者在有多个拦截器时发往下一个拦截器),并返回响应的 [Observable];
  • 第 37–39 行:拦截器所需的服务。[inject()] 只允许在函数开头、即 [Angular] 调用它的“注入上下文”中使用:之后,在 [catchError] 中,这个上下文已不复存在;
  • 第 40 行:该请求是否公开?(参见 [api-client.ts]);
  • 第 44–58 行:[next(request)] 发送请求;[pipe(catchError(...))] 处理响应的 [Observable]:成功的响应原样通过;错误则由给定的函数处理,该函数返回一个新的 [Observable] (此处仍然是一个错误:[throwError]);
  • 第 47 行:并非源自 HTTP 响应的错误属于客户端异常:原样向上传递;
  • 第 48 行:任何错误响应都会变成一个 [ApiError](参见 [api-error.ts]);
  • 第 49–55 行:受保护请求上的 401 表示会话已过期:用户被遗忘,缓存被清除,并准备好下一个屏幕的消息。然而,屏幕切换由路由器的守卫处理,它们会在会话变化时重新评估(参见 [app.ts])。仍然会返回一个错误(正在等待响应的屏幕需要知道响应没有到达),其键为 [ERRORS.SESSION_EXPIRED]:如果该屏幕显示这个错误,那就是同一条消息。

令牌 Cookie 呢?客户端无需编写任何代码:在 Web 上,由浏览器保存并发回;在 [Android] 上,[CapacitorHttp] 让请求经过原生代码,原生代码同样会保存并重新发送它,并在应用停止后再重新启动时保留它(参见示例 23)。这是与 [Flutter] 客户端相比的主要简化之处,后者必须自己读取 [Set-Cookie] 头并写入 [Cookie] 头。

11.7.3. src/app/api/api-error.ts

// =========================================================================
// src/app/api/api-error.ts - 所有 API 错误共用的一个类
// -------------------------------------------------------------------------
// RdvMedecins 服务器的所有错误响应都具有相同的结构:
//   { "statusCode": 409, "key": "ERRORS.LOGIN_TAKEN", "params": {...}, "fields": {...} }
// 但是,请求也可能以其他方式失败:根本没有响应
// (网络中断、服务器已停止、地址错误),或者响应并非来自
// 我们的服务器(代理的错误页面)。我们把
// 所有这些都转换为同一个类 ApiError,它携带服务器
// 发送的翻译键(以及参数和每个
// 字段的错误,如果有的话)。
// =========================================================================

import { HttpErrorResponse } from '@angular/common/http';

// 一个对象 { name: text }
export type Texts = Record<string, string>;

// “extends Error”:一个完整的 JavaScript 错误(throw、catch,并且
// Angular 资源的 error() 属性会原样保留它)
export class ApiError extends Error {
  constructor(
    readonly statusCode: number, // 0:服务器没有响应
    readonly key: string, // 例如 'ERRORS.LOGIN_TAKEN'
    readonly params: Texts = {},
    readonly fields: Texts = {},
  ) {
    super(`${statusCode} ${key}`);
    this.name = 'ApiError';
  }

  // Angular HTTP 客户端的错误响应 -> 一个 ApiError
  static fromResponse(response: HttpErrorResponse): ApiError {
    // 状态码 0:无响应(网络中断、服务器已停止、地址错误)
    if (response.status === 0) {
      return new ApiError(0, 'ERRORS.SERVER_UNREACHABLE');
    }
    // error:响应的请求体,如果是 JSON 则已解码
    const body: unknown = response.error;
    if (isObject(body) && typeof body['key'] === 'string') {
      return new ApiError(response.status, body['key'], texts(body['params']), texts(body['fields']));
    }
    // 没有键:由代理或网络代替服务器作出了响应
    return new ApiError(
      response.status,
      response.status >= 500 ? 'ERRORS.SERVER_UNREACHABLE' : 'ERRORS.SERVER_ERROR',
    );
  }
}

function isObject(value: unknown): value is Record<string, unknown> {
  return typeof value === 'object' && value !== null && !Array.isArray(value);
}

// 一个 JSON 对象 { "name": "ERRORS..." } -> Texts(否则为空)
function texts(json: unknown): Texts {
  if (!isObject(json)) return {};
  return Object.fromEntries(Object.entries(json).map(([key, value]) => [key, String(value)]));
}

即示例 24 中的那个:任何失败的请求最终都会得到一个 [ApiError],其中包含消息的翻译键、参数以及每个字段的错误。

  • 第 21 行:[extends Error]:一个完整的 [JavaScript] 错误。这对 [Angular] 的资源([resource()],稍后讨论)很重要:它们的 [error()] 信号会原样保留 [Error] ,但会“包装”任何其他被拒绝的值;
  • 第 22–27 行:以 [readonly] 为前缀的构造函数参数会成为对象的属性:这是 [TypeScript] 的一种简写写法;
  • 第 35–37 行:当没有收到任何响应时(网络中断、服务器宕机、地址错误),[status] 为 0;
  • 第 39–42 行:[response.error]:错误响应的请求体,如果是 JSON,则已由 HTTP 客户端解码。它的类型是 [unknown]:在使用之前会先验证其格式([isObject],文本类型的键 [key]);
  • 第 44–47 行:没有键:是代理或网络代替服务器作出了响应;
  • 第 51 行:[value is Record<string, unknown>]:一个“类型守卫”函数:当它返回 [true] 时,[TypeScript] 在后面的代码中就知道该值是一个对象;
  • 第 56–59 行:把 JSON 对象([params]、[fields])转换为文本对象。

11.7.4. src/app/api/types.ts

// =========================================================================
// src/app/api/types.ts - 与服务器交换的 JSON 对象
// -------------------------------------------------------------------------
// 把“服务器,一个黑盒”一章中描述的 API 翻译成
// TypeScript 类型。它们只是描述:
// 它们在编译时消失,在执行期间不检查任何内容。
// 它们让编译器检查代码
// 只使用存在的字段,且类型正确。
// =========================================================================

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

// POST /api/auth/login, GET /api/auth/me, PUT /api/my-account
export interface User {
  login: string;
  name: string; // 显示名称:"Marie PELISSIER"
  role: Role;
}

// GET /api/captcha
export interface Captcha {
  id: string;
  svg: string; // 图片,SVG 格式(文本)
}

// 称谓、名、姓
export interface Identity {
  title: string;
  firstName: string;
  lastName: string;
}

// "Mme Alice DURAND"
export function label(i: Identity): string {
  return `${i.title} ${i.firstName} ${i.lastName}`;
}

// 一位医生或一位客户:GET /api/doctors, GET /api/clients/:id...
export interface Person extends Identity {
  id: number;
  version: number; // 乐观锁:更新时需要一并发回
  login?: string; // 仅 ADMIN 可见
}

// 一个时间段
export interface Slot {
  id: number;
  startHour: number;
  startMinute: number;
  endHour: number;
  endMinute: number;
}

// 日程的一行,带有已登录用户的权限
export interface ScheduleSlot extends Slot {
  free: boolean;
  patient: Identity | null; // null:空闲,或被其他患者占用
  mine: boolean; // 已登录患者的预约
  bookable: boolean;
  appointmentId: number | null; // 如果用户可以取消,则设置
}

// GET /api/schedule?doctorId=...&day=...
export interface Schedule {
  doctor: Person;
  day: string; // "yyyy-MM-dd"
  slots: ScheduleSlot[];
  info: string | null; // 翻译键(已有预约的患者)
}

// GET /api/my-area 的一个预约
export interface Appointment {
  id: number;
  day: string;
  slot: Slot;
  doctor: Person;
}

// GET /api/my-area
export interface MyArea {
  patient: Identity;
  appointments: Appointment[];
}

// GET /api/my-account
export interface MyAccount extends Identity {
  login: string;
  version: number;
}

API 的 JSON 对象,以 [TypeScript] 类型描述(参见示例 24)。它们只是描述:在编译时消失,在运行时不做任何检查(相比之下,[Flutter] 客户端通过 [Dart] 3 的过滤来验证每个响应的格式)。它们让编译器和编辑器能够验证代码只使用存在的字段,且类型正确。

  • 第 11 行:一个“文本联合”类型:角色只能是这三个字符串之一,编译器会对此进行验证([u.role === 'ADMNI'] 会是编译错误);
  • 第 34–36 行:一个函数,因为接口不能包含代码:“Mme Alice DURAND”;
  • 第 39–43 行:一位医生或一位客户:一个 [Identity],外加一个标识符、一个版本(乐观锁:修改时会随之发回)和一个登录名,只有 ADMIN 才会收到登录名(因此带有问号:可选字段);
  • 第 55–61 行:日程中的一个条目,显示由服务器计算出的已登录用户的权限:[patient] 只显示给有权查看的人,[bookable] 表示用户是否可以预约;[appointmentId] 只提供给可以取消的人;
  • 第 86–89 行:已登录患者的账户:其身份、登录名和版本。

11.7.5. src/app/api/rdvmedecins-api.ts

// =========================================================================
// src/app/api/rdvmedecins-api.ts - API 的每个路由对应一个方法
// -------------------------------------------------------------------------
// 客户端的“数据访问层”:各屏幕调用这些
// 带类型的方法,而对 URL、HTTP 客户端或 JSON 一无所知。
// 如果 API 发生变化,只有这个文件需要修改。
// 每个方法返回一个 Promise;失败时,它以 ApiError 被拒绝
// (参见 http-client.ts)。
// 发送的数据(表单)是普通的 Data 对象:
// 它们的键是服务器所期望的字段名——也是
// 服务器返回的错误所用的字段名(ApiError.fields)。
// =========================================================================

import { inject, Injectable } from '@angular/core';
import { ApiClient } from './api-client';
import { Schedule, Captcha, MyAccount, MyArea, Person, User } from './types';

// /api/doctors 或 /api/clients:两者的处理方式相同
export type PersonType = 'doctors' | 'clients';

export type Data = Record<string, unknown>;

@Injectable({ providedIn: 'root' })
export class RdvMedecinsApi {
  private readonly client = inject(ApiClient);

  private get<T>(url: string, isPublic = false): Promise<T> {
    return this.client.request<T>('GET', url, undefined, isPublic);
  }

  private post<T>(url: string, body: unknown, isPublic = false): Promise<T> {
    return this.client.request<T>('POST', url, body, isPublic);
  }

  // —— 登录(公开路由)
  captcha(): Promise<Captcha> {
    return this.get('/captcha', true);
  }

  me(): Promise<User> {
    return this.get('/auth/me', true);
  }

  logIn(login: string, password: string, captchaId: string, captcha: string): Promise<User> {
    return this.post('/auth/login', { login, password, captchaId, captcha }, true);
  }

  async logOut(): Promise<void> {
    await this.post('/auth/logout', {}, true);
  }

  // —— 创建账户(公开)
  async registrationAccess(captchaId: string, captcha: string): Promise<void> {
    await this.post('/register/access', { captchaId, captcha }, true);
  }

  async registrationAccessStatus(): Promise<boolean> {
    const response = await this.get<{ valid?: boolean }>('/register/access', true);
    return response?.valid === true;
  }

  async register(data: Data): Promise<string> {
    const response = await this.post<{ login: string }>('/register', data, true);
    return response.login;
  }

  // —— 日程和预约
  // doctorId 为 undefined:对于已登录的医生,是他或她自己的日程
  schedule(doctorId: number | undefined, day: string): Promise<Schedule> {
    // URLSearchParams:"day=2026-10-05&doctorId=1",特殊字符会被编码
    const params = new URLSearchParams({ day });
    if (doctorId !== undefined) params.set('doctorId', String(doctorId));
    return this.get(`/schedule?${params}`);
  }

  async book(day: string, slotId: number, clientId: number | undefined): Promise<void> {
    // clientId: undefined 会从发送的 JSON 中消失
    await this.post('/appointments', { day, slotId, clientId });
  }

  async cancelAppointment(appointmentId: number): Promise<void> {
    await this.client.request('DELETE', `/appointments/${appointmentId}`);
  }

  // —— 医生和客户
  list(type: PersonType): Promise<Person[]> {
    return this.get(`/${type}`);
  }

  read(type: PersonType, id: number): Promise<Person> {
    return this.get(`/${type}/${id}`);
  }

  add(type: PersonType, data: Data): Promise<Person> {
    return this.post(`/${type}`, data);
  }

  edit(type: PersonType, id: number, data: Data): Promise<Person> {
    return this.client.request('PUT', `/${type}/${id}`, data);
  }

  async remove(type: PersonType, id: number): Promise<void> {
    await this.client.request('DELETE', `/${type}/${id}`);
  }

  // —— 患者空间
  myArea(): Promise<MyArea> {
    return this.get('/my-area');
  }

  myAccount(): Promise<MyAccount> {
    return this.get('/my-account');
  }

  editMyAccount(data: Data): Promise<User> {
    return this.client.request('PUT', '/my-account', data);
  }

  async deleteMyAccount(currentPassword: string): Promise<void> {
    await this.client.request('DELETE', '/my-account', { currentPassword });
  }
}

每个 API 路由对应一个方法:这是示例 24 中的类,经过了扩展。

  • 第 19 行:[/api/doctors] 和 [/api/clients] 的处理方式相同:类型(两个字符串的联合)同时也是路由名称;
  • 第 21 行:表单数据:键为字符串、值可以是任意类型的对象;
  • 第 23–25 行:一个提供给整个应用程序的服务,通过注入接收 [ApiClient] ;
  • 第 35–50 行:登录的公开路由:401 在这里有其特定含义(“无人登录”、“密码错误”),并不表示会话已过期;
  • 第 48–50 行:一个不返回任何内容的 [async] 方法([Promise<void>]):我们不关心服务器的响应;只有成功与否才重要;
  • 第 57–60 行:账户创建令牌是否有效?[response?.valid]:如果响应为空,运算符 [?.] 会返回 [undefined] ,而不是触发错误;
  • 第 69–74 行:地址参数,由 [URLSearchParams] 构造(它会对参数编码)。已登录的医生请求日程时不带 [doctorId]:服务器返回该医生自己的日程;
  • 第 78 行:同样,[clientId] 只有在已知时才发送(患者为自己预约):[JSON.stringify] 会省略值为 [undefined] 的属性;
  • 第 86–104 行:涉及医生或客户的五个操作:[/api/${type}];
  • 第 107–121 行:患者空间。删除账户时会发送一个带请求体的 [DELETE] 请求(当前密码):HTTP 和 [http.request] 都允许这样做。

11.8. 语言

11.8.1. src/app/i18n/translations.ts

// =========================================================================
// src/app/i18n/translations.ts - 字典和当前语言
// -------------------------------------------------------------------------
// 取自示例 21。这些字典(public/i18n/fr.json、en.json)
// 就是 Vue.js、Angular、React 和 Flutter 客户端所用的:键相同,
// 约定相同({{param}},复数 _one / _other)。服务器只
// 发回键("ERRORS.LOGIN_TAKEN"):键在这里
// 变成用户所选语言的文本。
//   - t('KEY', { param: value }):当前语言的文本;
//   - changeLanguage('fr')       :加载另一个字典,并
//                                  在设备上记住这个选择。
// 语言和字典是信号:t() 会读取它们,因此任何
// 显示 t('...') 的模板都会在语言变化时更新。
// =========================================================================

import { Injectable, signal } from '@angular/core';
import { Preferences } from '@capacitor/preferences';

export const languages = ['fr', 'en'] as const;
export type Language = (typeof languages)[number]; // 'fr' | 'en'

// 字典:存放在嵌套分区中的文本
interface Dictionary {
  [key: string]: string | Dictionary;
}

const LANGUAGE_KEY = 'rdvmedecins.language';

@Injectable({ providedIn: 'root' })
export class Translations {
  private readonly _language = signal<Language>('en');
  private readonly dictionary = signal<Dictionary>({});
  readonly language = this._language.asReadonly();

  // 起始语言:设备上记住的那个,否则是手机的语言
  // (如果已知),否则是英语。只调用一次,
  // 在显示第一个屏幕之前(provideAppInitializer,main.ts)
  async start(): Promise<void> {
    // Preferences:设备上的键/值存储(在 Web 上是
    // 浏览器的 localStorage)
    const { value: stored } = await Preferences.get({ key: LANGUAGE_KEY });
    const device = navigator.language.slice(0, 2); // “en-US” -> “en”
    await this.changeLanguage(stored ?? device);
  }

  async changeLanguage(requested: string): Promise<void> {
    const language: Language = languages.find((l) => l === requested) ?? 'en';
    // fetch:public/ 文件夹中的文件随应用程序一起发布
    // (在 Android 上也是如此:相对地址不会经过 CapacitorHttp)
    const response = await fetch(`i18n/${language}.json`);
    this.dictionary.set((await response.json()) as Dictionary);
    this._language.set(language);
    await Preferences.set({ key: LANGUAGE_KEY, value: language });
  }

  // "AREA.HELLO" -> dictionary['AREA']['HELLO'];如果缺失则为 undefined
  private find(key: string): string | undefined {
    let node: string | Dictionary | undefined = this.dictionary();
    for (const part of key.split('.')) {
      node = typeof node === 'object' ? node[part] : undefined;
    }
    return typeof node === 'string' ? node : undefined;
  }

  // 一个箭头函数:可以原样传给组件
  // (readonly t = inject(Translations).t),它保留自己的“this”
  readonly t = (key: string, params: Record<string, unknown> = {}): string => {
    let text: string | undefined;
    const count = params['count'];
    if (typeof count === 'number') {
      // Intl.PluralRules:根据语言的规则得出的复数形式
      // ('zero'、'one'、'other'……);在法语中 0 是 'one'
      const form = new Intl.PluralRules(this._language()).select(count);
      text = this.find(`${key}_${count === 0 ? 'zero' : form}`) ?? this.find(`${key}_${form}`);
    }
    text ??= this.find(key);
    // 未知的键原样显示:缺失的内容一眼就能看出
    if (text === undefined) return key;
    // {{name}} -> 参数 name 的值
    return text.replace(/\{\{(\w+)\}\}/g, (whole, name: string) => (name in params ? String(params[name]) : whole));
  };
}

示例 21 中的 [Translations] 类,现在是一个提供给整个应用程序的服务,并且经过了简化:字典的名称仍然相同([public/i18n/fr.json])。

  • 第 19 行:[as const]:数组是固定的,其类型恰好是 [readonly ['fr', 'en']];第 20 行推断出类型 [Language],即 ['fr' | 'en']:向数组中添加一种语言,也就把它添加到了类型中;
  • 第 23–25 行:字典:组织成嵌套分区的文本(递归类型);
  • 第 31–33 行:语言和字典是信号。任何读取 [t(...)] 的内容(模板、计算信号、副作用)也会读取这些信号,因此在语言变化时会自动更新:这相当于 [notifyListeners()] 在 [Flutter] 的 [ChangeNotifier] 中的作用,而无需编写任何代码。[asReadonly()]:应用程序的其余部分可以读取语言,但只有这个服务可以更改它;
  • 第 38–44 行:默认语言:上一次会话中选择的语言,否则是手机的语言(如果应用支持),否则是英语。[Preferences] ([Capacitor] 的插件,参见示例 20)在设备上存储键值对;在浏览器中,它使用 [localStorage]。[navigator.language]:系统语言(“en-US”);
  • 第 46–54 行:切换语言:字典由 [fetch] 从随应用程序一起打包的文件中读取([public/] 文件夹,由 [ng build] 原样复制)。在 [Android] 上,相对 URL([i18n/fr.json])不会被 [CapacitorHttp] 重定向:它由应用程序自身提供。未知的语言会变成英语;
  • 第 57–63 行:“AREA.HELLO” → [dictionary['AREA']['HELLO']],逐个分区地处理;
  • 第 67–81 行:键的翻译,包括复数([_zero]、[_one]、[_other])和参数([{{name}}]),遵循 [i18next] 的约定,这些约定与其他客户端的字典所用的相同。[Intl.PluralRules] 了解每种语言的复数规则(在法语中,0 和 1 是单数)。[t] 是一个箭头函数,而不是方法:把它复制到组件中时([this] ,[readonly t = inject(Translations).t]),它仍保留其 this,所有屏幕都是这样做的。

11.8.2. 字典

这些字典就是 [Flutter] 客户端的字典,原封不动(它们本身取自 [React] 客户端,并补充了几个移动应用特有的键:“我的账户”菜单、“选择日期”等)。法语字典的开头,[public/i18n/fr.json]:

{
  "APP": {
    "TITLE": "RdvMedecins",
    "LOGOUT": "Se déconnecter",
    "MENU_SCHEDULE": "Agenda",
    "MENU_DOCTORS": "Médecins",
    "MENU_PATIENTS": "Clients",
    "MENU_MY_AREA": "Mon espace",
    "LOADING": "Chargement...",
    "LANGUAGE": "Langue",
    "MENU_ACCOUNT": "Mon compte",
    "CONNECTED_AS": "Connecté : {{name}}",
    "RETRY": "Réessayer"
  },
  "LOGIN": {
    "TITLE": "Connexion",
    "LOGIN_LABEL": "Login",
    "PASSWORD_LABEL": "Mot de passe",
    "SUBMIT": "Se connecter",
    "ERROR": "Login ou mot de passe incorrect.",
    "DEMO_ACCOUNTS": "Comptes de démonstration (mot de passe = login) :",
    "DEMO_ADMIN": "rôle ADMIN : rendez-vous + gestion des médecins et des clients",
    "DEMO_DOCTOR": "rôle DOCTOR : prise et annulation de rendez-vous",
    "DEMO_USER": "rôle USER (patients) : réservation pour eux-mêmes, gestion de leur compte",
    "CREATE_ACCOUNT": "Créer un compte client",
    "CREATE_ACCOUNT_HELP": "Pour créer un compte, recopiez d'abord les caractères de l'image."
  },
  "DOCTOR_DAY_PICKER": {
    "DOCTOR_LABEL": "Médecin",
    "CHOOSE_DOCTOR": "-- choisir un médecin --",
    "DAY_LABEL": "Jour",
    "VIEW_SCHEDULE": "Voir l'agenda",

每种语言一个文件,各文件中的键相同;每个屏幕一组键;键 [ERRORS.*] 是服务器返回的那些键。

11.9. 共享状态

三个信号服务,提供给整个应用程序([providedIn: 'root']),与示例 20 中的那个类似。

11.9.1. src/app/state/session.ts

// =========================================================================
// src/app/state/session.ts - 谁已登录?
// -------------------------------------------------------------------------
// 已登录的用户(或 null),存放在一个提供给整个应用程序的
// 信号服务中(providedIn: 'root',参见示例 20):各屏幕
// 和路由器守卫都可以读取,它变化时守卫会重新评估
// (参见 app.ts)。
//
// JWT 令牌本身不在这里:它在 Cookie 中(在 Web 上由
// 浏览器管理,在手机上由 Android 的原生代码管理)。会话
// 只保存用户的描述({ login, name, role })。
//
// 应用程序启动时,会话为空:check() 只向服务器询问
// 一次,谁已登录(GET /api/auth/me)。
// =========================================================================

import { inject, Injectable, signal } from '@angular/core';
import { RdvMedecinsApi } from '../api/rdvmedecins-api';
import { User } from '../api/types';

@Injectable({ providedIn: 'root' })
export class Session {
  private readonly api = inject(RdvMedecinsApi);
  private readonly _user = signal<User | null>(null);
  // 信号的“只读”版本,供应用程序的其余部分使用
  readonly user = this._user.asReadonly();
  // 主动注销(按钮、删除账户)之后为 true;会话过期
  // 之后为 false。守卫会考虑它(参见 app.routes.ts)
  private _voluntaryExit = false;
  // “谁已登录?”这个问题是否已经向服务器询问过?
  private checking?: Promise<void>;

  get voluntaryExit(): boolean {
    return this._voluntaryExit;
  }

  // 只在第一次向服务器询问(Promise 会被保留)
  check(): Promise<void> {
    this.checking ??= this.api.me().then(
      (u) => this.change(u),
      () => this.change(null), // 401:无人登录;或服务器无法访问
    );
    return this.checking;
  }

  async logIn(login: string, password: string, captchaId: string, captcha: string): Promise<void> {
    this.change(await this.api.logIn(login, password, captchaId, captcha));
  }

  // 用户更改了姓名或登录名(PUT /api/my-account)
  update(u: User): void {
    this.change(u);
  }

  async logOut(): Promise<void> {
    try {
      await this.api.logOut();
    } finally {
      this.forget(true);
    }
  }

  // 不向服务器询问任何内容:会话过期、账户已删除
  forget(voluntary = false): void {
    this.change(null, voluntary);
  }

  // 信号变化:所有读取它的内容(布局、守卫……)都会收到通知
  private change(u: User | null, voluntary = false): void {
    this._voluntaryExit = voluntary;
    this._user.set(u);
  }
}

// 由用户推断出的内容(null:无人登录)
export const isAdmin = (u: User | null): boolean => u?.role === 'ADMIN';
export const isPatient = (u: User | null): boolean => u?.role === 'USER';
// ADMIN 和 DOCTOR:为任何患者预约和取消预约
export const isManager = (u: User | null): boolean => u?.role === 'ADMIN' || u?.role === 'DOCTOR';
// 每个角色在登录后立即进入的主页
export const homePage = (u: User | null): string => (isPatient(u) ? '/my-area' : '/schedule');

谁已登录?会话保存的是用户的描述(登录名、姓名、角色),而不是令牌,令牌保留在用户的 Cookie 中。

  • 第 24–26 行:用户,存放在一个私有的可修改信号([_user])中,以及供应用程序其余部分使用的只读版本。布局(显示用户的姓名)、[app.ts] (它清除缓存并重新评估守卫)以及各屏幕都会读取这个信息;
  • 第 38–44 行:向服务器发送的“谁已登录?”这个问题([GET /api/auth/me])只在启动时询问一次:[??=] 仅当 [checking] 为 [undefined] 时才对 [Promise] 赋值。后续调用返回同一个 [Promise],它已经完成:路由器守卫可以在每次导航前毫无代价地调用 [check()] 。启动时,如果 Cookie 中的令牌仍然有效,用户就保持登录状态。[then(success, failure)]:401(无人登录)或服务器无法访问,两者都会得到一个空会话;
  • 第 46–48 行:登录:如果服务器拒绝,[api.logIn] 会以 [Promise] 拒绝,并带有 [ApiError],[await] 会重新抛出它,而 [change] 不会被调用;
  • 第 55–61 行:注销——即使服务器没有响应,用户也会被遗忘([finally]);
  • 第 69–72 行:所有变更都经由此处。[_voluntaryExit] 用于区分主动注销和会话过期(参见 [app.routes.ts]);它在更改信号之前设置,因为守卫会读取它;
  • 第 76–81 行:关于用户的推断信息,以函数形式给出([Flutter] 客户端使用的是 [Dart] 的扩展)。[u?.role]:如果无人登录([undefined] ),则为 [null],无需事先测试。

11.9.2. src/app/state/messages.ts

// =========================================================================
// src/app/state/messages.ts - 向用户显示的消息
// -------------------------------------------------------------------------
// 与其他 RdvMedecins 客户端的呈现方式相同:
//   - 成功消息显示在屏幕顶部(绿色横幅);
//   - 错误消息显示在底部(粉色横幅),始终可见。
// 消息是一个翻译键(及其参数):因此,如果用户切换语言,
// 它会自行重新翻译。
//
// “闪现”消息:以屏幕切换结束的操作(预约、添加医生……)
// 通过 flash() 留下它的消息;该消息会在
// 下一个屏幕上显示,然后在之后的
// 导航时消失。由 app.ts 在每次导航结束时
// 调用 newPage()。
// =========================================================================

import { effect, inject, Injectable, Resource, signal, untracked } from '@angular/core';
import { ApiError, Texts } from '../api/api-error';

export interface Message {
  key: string;
  params: Texts;
}

@Injectable({ providedIn: 'root' })
export class Messages {
  readonly success = signal<Message | null>(null);
  readonly error = signal<Message | null>(null);
  // 要在下一个屏幕上显示的消息
  private pendingSuccess: Message | null = null;
  private pendingError: Message | null = null;

  showSuccess(key: string, params: Texts = {}): void {
    this.success.set({ key, params });
    this.error.set(null);
  }

  showError(key: string, params: Texts = {}): void {
    this.error.set({ key, params });
    this.success.set(null);
  }

  // 一个 ApiError -> 屏幕的消息;任何其他错误都是
  // 客户端的异常,会被放行
  showApiError(e: unknown): void {
    if (!(e instanceof ApiError)) throw e;
    this.showError(e.key, e.params);
  }

  clear(): void {
    this.success.set(null);
    this.error.set(null);
  }

  // 用于下一个屏幕
  flash({ success = true, key, params = {} }: { success?: boolean; key: string; params?: Texts }): void {
    if (success) {
      this.pendingSuccess = { key, params };
    } else {
      this.pendingError = { key, params };
    }
  }

  // 新屏幕:上一个屏幕的消息消失,闪现
  // 消息出现
  newPage(): void {
    this.success.set(this.pendingSuccess);
    this.error.set(this.pendingError);
    this.pendingSuccess = null;
    this.pendingError = null;
  }
}

// 要在屏幕的构造函数中调用:读取这些资源(Angular resource)失败时
// 会在屏幕底部显示其消息
export function reportErrors(...resources: Resource<unknown>[]): void {
  const messages = inject(Messages);
  for (const resource of resources) {
    // 一个副作用:每当它所读取的信号发生变化时(这里是资源的错误),就会
    // 重新运行的函数
    effect(() => {
      const error = resource.error();
      // untracked:后面的内容不能成为该副作用的依赖项
      if (error) untracked(() => messages.showApiError(error));
    });
  }
}

应用程序消息:屏幕顶部的成功消息,底部的错误消息(参见 [layout.html])。

  • 第 20–23 行:一条消息由一个翻译代码(KEY)及其参数组成。它只在显示时才被翻译;切换语言会重新翻译已显示的消息;
  • 第 27–28 行:显示的成功消息和错误消息:由布局读取的两个信号;
  • 第 45–48 行:[ApiError] 成为屏幕的错误消息。任何其他异常都是客户端问题:会被重新抛出,以便在开发期间出现在控制台中,而不是被隐藏;
  • 第 56–62 行:用于下一个屏幕的消息:以屏幕切换结束的操作(预约、添加等)把它的消息放在这里。参数是一个“解包”的对象:[flash({ success: false, key: '...' })],带有默认值;这相当于 [Dart] 中的命名参数;
  • 第 66–71 行:每次地址变化时调用(参见 [app.ts]):上一个屏幕的消息消失,闪现消息出现;
  • 第 76–87 行:一个要在屏幕构造函数中调用的函数:如果读取其资源失败([resource()],参见 [schedule.ts]),其消息会显示在屏幕底部。对于每个资源,都有一个副作用读取其 [error()] 信号:每出现一个新错误,它就会重新执行。副作用只能在注入上下文中创建,例如 [inject()]:因此要求在构造函数中(或初始化字段时)调用该函数。

11.9.3. src/app/state/cache.ts

// =========================================================================
// src/app/state/cache.ts - 已从服务器读取的数据
// -------------------------------------------------------------------------
// 医生列表几乎不会变化:无需在每次访问日程时都重新读取。
// 缓存以键('doctors'、'schedule/1/2026-10-05'……)
// 保存每次读取的 Promise:
//
//     cache.read('doctors', () => api.list('doctors'))
//
// 返回已保存的 Promise,或者启动读取并保存它。
// 发生变更后,相关的键会失效(它们将在
// 下一次请求时被重新读取):cache.invalidate('schedule')。
// 失败的读取不会被保存:下一次会重试。
// 每次失效都会让 version 信号递增:仍然存活的屏幕
// (即使隐藏在 Ionic 栈中另一个屏幕之下)因此可以
// 重新读取其数据(参见下面的 reloadAfterInvalidation)。
// 这几行代码实现了 React 客户端中
// TanStack Query 库的功能。
// =========================================================================

import { effect, inject, Injectable, signal, untracked, WritableResource } from '@angular/core';

@Injectable({ providedIn: 'root' })
export class Cache {
  private readonly promises = new Map<string, Promise<unknown>>();
  private readonly _version = signal(0);
  readonly version = this._version.asReadonly();

  read<T>(key: string, load: () => Promise<T>): Promise<T> {
    let promise = this.promises.get(key) as Promise<T> | undefined;
    if (promise === undefined) {
      promise = load();
      this.promises.set(key, promise);
      // 失败时,这个 Promise 会被遗忘(下一次请求会重试)
      promise.catch(() => this.promises.delete(key));
    }
    return promise;
  }

  // 忘记所有以 prefix 开头的键,并通知各屏幕
  invalidate(prefix: string): void {
    for (const key of [...this.promises.keys()]) {
      if (key.startsWith(prefix)) this.promises.delete(key);
    }
    this._version.update((v) => v + 1);
  }

  // 用户变化:所有内容都被遗忘,且不通知(上一个用户的屏幕
  // 即将消失,它们不能读取任何内容)
  clear(): void {
    this.promises.clear();
  }
}

// 要在屏幕的构造函数中调用:每次缓存失效之后,其资源都会被重新
// 读取(reload)。reload() 在重新读取期间保留当前
// 值:屏幕不会“闪烁”
export function reloadAfterInvalidation(...resources: WritableResource<unknown>[]): void {
  const cache = inject(Cache);
  const start = cache.version();
  effect(() => {
    // 该副作用在创建时会运行一次:我们等待真正的
    // 失效
    if (cache.version() === start) return;
    untracked(() => resources.forEach((r) => r.reload()));
  });
}

已从服务器读取的数据:用几行代码实现了 [TanStack Query] 在 [React] 客户端中的功能,以及 [Cache] 在 [Flutter] 客户端中的功能。

  • 第 25 行:缓存存储的是 [Promise],而不是实际的值:两个屏幕在数据传输途中请求同样的数据时,会收到同一个 [Promise],而且只会发送一次请求;
  • 第 29–38 行:一个泛型方法:[read<Person[]>(...)] 返回 [Promise<Person[]>] (类型 [T] 由函数 [load] 推断)。失败的读取会被忽略([catch]):下一次请求会重试;
  • 第 41–46 行:修改之后,受影响的键会被丢弃,并且 [version] 信号会递增:读取这个信号的屏幕会收到通知;
  • 第 50–52 行:当用户变化时,所有内容都会被清除而不通知任何人:上一个用户的屏幕将会消失;它们没有什么需要重新读取的;
  • 第 58–67 行:一个要在屏幕构造函数中调用的函数:每次缓存失效后,其资源都会被重新读取。该副作用读取 [cache.version()]:每次失效时它都会重新执行并重新读取资源([reload()])。[Ionic] 的屏幕 仍然处于活动状态,隐藏在显示的屏幕之下(返回按钮的栈):发生更改后,当你返回它们时,它们已经是最新的了。[reload()] 在重新读取期间保留当前值:屏幕不会“闪烁”。

11.10. 格式化

11.10.1. src/app/formatting.ts

// =========================================================================
// src/app/formatting.ts - 时间和日期的显示
// -------------------------------------------------------------------------
// 服务器发送的是原始数据(startHour: 8, startMinute: 0;day:
// "2026-10-05");与语言相关的格式化是客户端的
// 职责(参见示例 09)。我们在这里使用 JavaScript 的 Intl API,
// 它了解所有语言的规则。
// =========================================================================

import { Slot } from './api/types';

const two = (n: number): string => n.toString().padStart(2, '0');

// "8:05" 而不是 "8:5"
export const time = (h: number, m: number): string => `${h}:${two(m)}`;

// "8:00 - 8:20"
export const timeRange = (s: Slot): string => `${time(s.startHour, s.startMinute)} - ${time(s.endHour, s.endMinute)}`;

// 一个日期 -> "yyyy-MM-dd"(API 的格式),采用设备的时区
export const toDay = (d: Date): string => `${d.getFullYear()}-${two(d.getMonth() + 1)}-${two(d.getDate())}`;

export const today = (): string => toDay(new Date());

// "2026-10-05" -> 本地时间 2026 年 10 月 5 日 0:00(new Date("2026-10-05")
// 会得到世界时的 0:00:在另一个大陆上则是前一天晚上)
export function toDate(day: string): Date {
  const [y, m, d] = day.split('-').map(Number);
  return new Date(y, m - 1, d);
}

// 如果 day 是存在的日期且采用 yyyy-MM-dd 格式,则为 true
export function isValidDate(day: string): boolean {
  if (!/^\d{4}-\d{2}-\d{2}$/.test(day)) return false;
  return toDay(toDate(day)) === day; // 2026-02-30 -> 2026-03-02:被拒绝
}

// "lundi 5 octobre 2026" / "Monday, October 5, 2026"
export function longDay(day: string, language: string): string {
  return new Intl.DateTimeFormat(language, { weekday: 'long', day: 'numeric', month: 'long', year: 'numeric' }).format(
    toDate(day),
  );
}

对服务器的原始数据进行格式化(参见示例 09):

  • 第 21 行:API 格式的日期(“2026-10-05”),采用设备的时区。[getMonth()] 的月份从 0 开始计数;
  • 第 27–30 行:反过来:“2026-10-05” → 10 月 5 日本地时间 0:00。[new Date('2026-10-05')] 表示协调世界时(UTC)的午夜,即在格林尼治以西则是前一天晚上;
  • 第 33–36 行:地址中的日期是否有效?[new Date(2026, 1, 30)] 会得到 3 月 2 日:我们验证返回的是否为同一个字符串;
  • 第 39–43 行:根据语言显示“Monday, October 5, 2026”:[Intl.DateTimeFormat]——[JavaScript] 的格式化变体——支持所有语言。[Flutter] 客户端为此需要软件包 [intl]。

11.11. 路由器

11.11.1. src/app/app.routes.ts

// =========================================================================
// src/app/app.routes.ts - 应用程序的屏幕及其访问权限
// -------------------------------------------------------------------------
// 与其他客户端相同的地址(/login、/schedule、/doctors、
// /my-area……)。在 Web 上,它们显示在地址栏中;
// 在手机上,它们不可见,但同样会组织应用程序
// (以及返回按钮的屏幕栈)。
//
// 守卫:守卫函数(一个 CanActivateFn)在每次导航到
// 每个屏幕之前被调用。它是异步的:第一次
// (应用程序启动、Web 上按 F5)时,它会等待服务器对
// “谁已登录?”这个问题的回答(session.check())。然后
// 它检查所请求屏幕的权限(accessOf),并在
// 需要时重定向。runGuardsAndResolvers: 'always':当我们“再次导航”到
// 当前地址时,守卫也会
// 重新评估,app.ts 在会话变化(登录、注销、过期)时就会这样做。
// 提醒:这些检查只是一种便利(不显示无用的
// 屏幕)。数据保护由服务器保证,它在每个请求中
// 都会重新检查令牌和角色。
// =========================================================================

import { inject } from '@angular/core';
import { CanActivateFn, CanMatchFn, Router, Routes } from '@angular/router';
import { RdvMedecinsApi, PersonType } from './api/rdvmedecins-api';
import { Role } from './api/types';
import { Messages } from './state/messages';
import { homePage, Session } from './state/session';
import { keys } from './pages/persons-config';

// 屏幕的访问权限:公开(无需登录),或仅限于
// 某些角色(未指定 roles:所有已登录的角色)
interface Access {
  public: boolean;
  roles?: Role[];
}

export function accessOf(path: string): Access {
  if (path === '/login' || path === '/register') return { public: true };
  if (path.startsWith('/doctors') || path.startsWith('/clients')) return { public: false, roles: ['ADMIN'] };
  if (path === '/my-area' || path === '/my-account') return { public: false, roles: ['USER'] };
  if (path === '/schedule' || path === '/forbidden' || path === '/') return { public: false };
  return { public: true }; // 未知地址:404 页面,对所有人开放
}

// 只有内部路径("/doctors"):绝不能是 "//other-site.com"
export function internalPath(r: string | undefined): string | undefined {
  return r !== undefined && r.startsWith('/') && !r.startsWith('//') ? r : undefined;
}

// "3" -> 3;""、"abc"、"-2"、缺失(undefined)-> undefined
export function positiveInteger(value: string | undefined): number | undefined {
  if (value === undefined || !/^\d+$/.test(value)) return undefined;
  const n = Number(value);
  return n > 0 ? n : undefined;
}

// 所有屏幕的守卫
export const guard: CanActivateFn = async (_route, state) => {
  // 先 inject():在 await 之后,我们已不在注入上下文中
  const session = inject(Session);
  const router = inject(Router);
  await session.check();
  const user = session.user();
  // state.url:所请求的地址,包括参数("/schedule?doctorId=1...")
  const url = router.parseUrl(state.url);
  const path = state.url.split(/[?#]/)[0];
  const access = accessOf(path);
  if (access.public) {
    // 已登录:登录界面不再有意义。正是在这里
    // 离开它,就在登录之后:会话已变化,守卫
    // 被重新评估。我们前往登录前所请求的屏幕
    // (?redirect=...),否则前往该角色的主页
    if (path === '/login' && user !== null) {
      return router.parseUrl(internalPath(url.queryParams['redirect']) ?? homePage(user));
    }
    return true;
  }
  if (user === null) {
    // 主动注销:直接前往登录界面
    if (session.voluntaryExit) return router.parseUrl('/login');
    // 会话过期、未登录就打开了地址:所请求的
    // 屏幕会被记住,以便登录后返回
    return router.createUrlTree(['/login'], { queryParams: { redirect: state.url } });
  }
  if (path === '/') return router.parseUrl(homePage(user));
  if (access.roles !== undefined && !access.roles.includes(user.role)) return router.parseUrl('/forbidden');
  // true:导航继续;UrlTree:被重定向
  return true;
};

// 一个专属于 /register 的守卫:没有通行证(在
// 登录界面上解决验证码),就返回登录界面
const registrationGuard: CanActivateFn = async () => {
  const api = inject(RdvMedecinsApi);
  const messages = inject(Messages);
  const router = inject(Router);
  const valid = await api.registrationAccessStatus().catch(() => false);
  if (valid) return true;
  messages.flash({ success: false, key: 'ERRORS.CAPTCHA_BEFORE_ACCOUNT' });
  return router.parseUrl('/login');
};

// /doctors/abc/edit:这条路由不“匹配”(canMatch);
// 路由器会依次尝试后面的路由,直到 404 页面(**)
const validId: CanMatchFn = (_route, segments) => positiveInteger(segments[1]?.path) !== undefined;

// 医生或客户的三个管理屏幕(ADMIN);
// data:固定值,传递给组件的输入(type)
function personRoutes(type: PersonType): Routes {
  const c = keys(type);
  const list = () => import('./pages/persons').then((m) => m.PersonsPage);
  const form = () => import('./pages/person-form').then((m) => m.PersonFormPage);
  return [
    { path: type, title: c.title, data: { type }, loadComponent: list },
    { path: `${type}/add`, title: c.add, data: { type }, loadComponent: form },
    {
      path: `${type}/:id/edit`,
      title: c.edit,
      data: { type },
      canMatch: [validId],
      loadComponent: form,
    },
  ];
}

// 各个屏幕,不含它们的守卫;title:一个翻译键(参见
// components/page-title.ts);loadComponent:屏幕的代码只在
// 首次访问时加载(一个单独的 JavaScript 文件)
const screens: Routes = [
  // "/":总是被守卫重定向(该角色的主页,或登录)
  { path: '', pathMatch: 'full', children: [] },
  {
    path: 'login',
    title: 'LOGIN.TITLE',
    loadComponent: () => import('./pages/login').then((m) => m.LoginPage),
  },
  {
    path: 'schedule',
    title: 'SCHEDULE.PAGE_TITLE',
    loadComponent: () => import('./pages/schedule').then((m) => m.SchedulePage),
  },
  ...personRoutes('doctors'),
  ...personRoutes('clients'),
  {
    path: 'register',
    title: 'REGISTRATION.TITLE',
    canActivate: [registrationGuard],
    loadComponent: () => import('./pages/register').then((m) => m.RegisterPage),
  },
  {
    path: 'my-area',
    title: 'AREA.TITLE',
    loadComponent: () => import('./pages/patient-area').then((m) => m.PatientAreaPage),
  },
  {
    path: 'my-account',
    title: 'MY_ACCOUNT.TITLE',
    loadComponent: () => import('./pages/my-account').then((m) => m.MyAccountPage),
  },
  {
    path: 'forbidden',
    title: 'ERROR_PAGE.TITLE',
    data: { code: 403 },
    loadComponent: () => import('./pages/error-page').then((m) => m.ErrorPage),
  },
  // 没有任何路由描述的地址:404 页面
  {
    path: '**',
    title: 'ERROR_PAGE.TITLE',
    data: { code: 404 },
    loadComponent: () => import('./pages/error-page').then((m) => m.ErrorPage),
  },
];

// 每个屏幕都会接收公共守卫(在它自己的守卫之前)
export const routes: Routes = screens.map((r) => ({
  ...r,
  canActivate: [guard, ...(r.canActivate ?? [])],
  runGuardsAndResolvers: 'always',
}));

应用程序的屏幕、它们的地址及其访问权限(参见示例 17 和 18)。

  • 第 32–35 行:屏幕的访问权限:公开,或仅限于某些角色(如果缺少 [roles] :则所有角色均可);
  • 第 37–43 行:每个地址的权限,集中在一处;
  • 第 46–48 行:只有当地址 [?redirect=] 是内部路径时才会跟随:在 Web 上,通过电子邮件发送的 [/login?redirect=//pirate-site.com] 地址不应在用户登录后把他带到别的地方;
  • 第 51–55 行:URL 的参数是文本字符串,任何人都可以输入(在 Web 上):“abc”或“-2”会变成 [undefined];
  • 第 58–89 行:这个守卫,在导航到任何屏幕之前执行(参见第 176–180 行):
  • 第 62 行:第一次时,系统会等待服务器对“谁已连接?”这个问题的响应;此后,这个调用不再有开销。守卫可以是异步的([async]):路由器会等待它的响应;
  • 第 65–67 行:[state.url]:请求的地址,包括参数;[router.parseUrl]:对其的拆解(其路径、其参数 [queryParams]);
  • 第 68–77 行:公开屏幕对所有人开放;但是,已登录的用户在登录界面上无事可做:他们会前往登录前所请求的屏幕,或其角色的主屏幕。应用程序就是这样在登录成功后离开登录界面的:登录界面本身无需导航。返回 [UrlTree] (解析后的地址)的守卫会重定向导航;
  • 第 78–84 行:无人登录:前往登录界面。会话过期后,或者直接打开了受保护的地址(在 Web 上),所请求的屏幕([?redirect=])会被保留,以便登录后返回;而主动注销后则不会保留。[createUrlTree] 通过对参数编码来构造地址;
  • 第 85–88 行:[/] 导向该角色的主页;如果角色权限不足,则导向 403 页面;否则,[true]:导航继续;
  • 第 93–101 行:一个特定于某个路径的守卫:创建账户需要通行证,服务器在输入验证码后签发它([POST /api/register/access],参见登录界面)。没有通行证,用户会被带回登录界面并显示一条消息;
  • 第 105 行:[CanMatchFn] 守卫不检查你是否有权进入某个屏幕,而是检查该路由是否匹配地址:[/doctors/abc/edit] 不匹配路由 [doctors/:id/edit];路由器会依次尝试后面的路由,直到到达 404 页面;
  • 第 109–124 行:一个为医生或客户生成三条路由的函数:[/doctors], [/doctors/add], [/doctors/:id/edit]。[:id]:路径参数,传递给组件的 [id] 输入;[data: { type }]:固定值,传递给它的 [type] 输入。[title]:屏幕标题(一个翻译键;参见 [page-title.ts]);
  • 第 111–112 行:[loadComponent]:屏幕的代码只在首次访问时加载。[import()] 按需加载模块;因此 [ng build] 把每个屏幕存放在单独的 [JavaScript] 文件中,应用程序启动得更快;
  • 第 131 行:[/]:一条没有屏幕的路由([children: []]),总是被守卫重定向;
  • 第 132–136 行:[/login?login=jbernard] (创建账户之后)会预先填写登录字段:参数 [login] 被赋给登录界面上同名的输入字段;
  • 第 137–141 行:同样,日程的三个参数([doctorId]、[day]、[book])被赋给屏幕的字段:整个屏幕的布局都包含在地址中(参见 [schedule.ts]);
  • 第 160–172 行:403 页面,以及对于任何没有被路由描述的地址(“通配符”路径,两个星号),404 页面:同一个屏幕,使用不同的代码([data]);
  • 第 176–180 行:每条路由在其自己的守卫之前先接收公共守卫。[runGuardsAndResolvers: 'always']:守卫在每次导航时都会执行,即使导航到当前地址也是如此(默认情况下,只有当路径或其参数变化时才执行)。这使得 [app.ts] 能够在会话变化时重新评估它们。

这些检查只是一种便利:它们防止显示不必要的屏幕。数据保护由服务器保证,它在每个请求中都会重新验证令牌和角色。

11.12. 组件

11.12.1. src/app/components/layout.ts

// =========================================================================
// src/app/components/layout.ts - 所有屏幕共用的布局
// -------------------------------------------------------------------------
// 根组件中唯一的组件(参见 app.ts);它包裹着
// 各屏幕的位置(<ion-router-outlet>):
//   - 顶部栏:标题、语言(FR / EN)、注销;
//   - 侧边菜单(“抽屉”,<ion-menu>),由 ☰ 按钮打开:用户的
//     角色所允许的屏幕。“医生”和“患者”
//     只对 ADMIN 显示:这只是显示上的便利,真正的
//     保护由服务器提供;
//   - 顶部的成功消息;
//   - 当前屏幕(<ion-router-outlet>);
//   - 底部的错误区域。
// 在大屏幕(Web、平板)上,菜单永久显示
// 在左侧:这是 <ion-split-pane> 的工作。
// =========================================================================

import { Component, computed, inject, signal } from '@angular/core';
import { toSignal } from '@angular/core/rxjs-interop';
import { NavigationEnd, Router, RouterLink } from '@angular/router';
import {
  IonButton, IonButtons, IonChip, IonContent, IonFooter, IonHeader, IonIcon, IonItem, IonLabel, IonList,
  IonMenu, IonMenuButton, IonMenuToggle, IonPopover, IonRouterLink, IonRouterOutlet, IonSplitPane, IonTitle,
  IonToolbar,
} from '@ionic/angular';
import { addIcons } from 'ionicons';
import {
  calendar, checkmarkCircle, close, alertCircle, home, logOutOutline, medkit, people, personCircle,
} from 'ionicons/icons';
import { filter, map } from 'rxjs';
import { User } from '../api/types';
import { Messages } from '../state/messages';
import { isAdmin, isPatient, Session } from '../state/session';
import { Language, languages, Translations } from '../i18n/translations';

// 菜单项:路径、标签的键、图标
interface MenuEntry {
  path: string;
  key: string;
  icon: string;
}

export function menuEntries(u: User | null): MenuEntry[] {
  if (u === null) return [];
  return [
    ...(isPatient(u) ? [{ path: '/my-area', key: 'APP.MENU_MY_AREA', icon: 'home' }] : []),
    { path: '/schedule', key: 'APP.MENU_SCHEDULE', icon: 'calendar' },
    ...(isAdmin(u)
      ? [
          { path: '/doctors', key: 'APP.MENU_DOCTORS', icon: 'medkit' },
          { path: '/clients', key: 'APP.MENU_PATIENTS', icon: 'people' },
        ]
      : []),
    ...(isPatient(u) ? [{ path: '/my-account', key: 'APP.MENU_ACCOUNT', icon: 'person-circle' }] : []),
  ];
}

@Component({
  selector: 'app-layout',
  imports: [
    RouterLink, IonRouterLink, IonSplitPane, IonMenu, IonMenuToggle, IonMenuButton, IonHeader, IonToolbar, IonTitle,
    IonButtons, IonButton, IonIcon, IonContent, IonList, IonItem, IonLabel, IonChip, IonPopover, IonRouterOutlet,
    IonFooter,
  ],
  templateUrl: './layout.html',
  styleUrl: './layout.scss',
})
export class Layout {
  private readonly session = inject(Session);
  private readonly translations = inject(Translations);
  readonly messages = inject(Messages);
  readonly t = this.translations.t;
  readonly language = this.translations.language;
  readonly languages = languages;
  readonly user = this.session.user;
  readonly entries = computed(() => menuEntries(this.user()));

  // 当前地址,不含其参数:由路由器的事件构建的
  // 信号(toSignal:Observable -> 信号)
  private readonly path = toSignal(
    inject(Router).events.pipe(
      filter((e) => e instanceof NavigationEnd),
      map((e) => e.urlAfterRedirects.split('?')[0]),
    ),
    { initialValue: '' },
  );
  // 语言菜单:是否打开,以及在哪个元素下方
  readonly languagesOpen = signal(false);
  languagesEvent?: Event;

  constructor() {
    addIcons({ calendar, checkmarkCircle, close, alertCircle, home, logOutOutline, medkit, people, personCircle });
  }

  // 当前屏幕的菜单项
  isActive(e: MenuEntry): boolean {
    return this.path().startsWith(e.path);
  }

  // 语言按钮:语言菜单在它下方打开
  openLanguages(event: Event): void {
    this.languagesEvent = event;
    this.languagesOpen.set(true);
  }

  // FR / EN:不向服务器发送请求,屏幕当场重新翻译
  changeLanguage(l: Language): void {
    void this.translations.changeLanguage(l);
  }

  // 会话被清除;重新评估的路由器守卫会显示
  // 登录界面。catch:即使服务器没有响应
  logOut(): void {
    this.session.logOut().catch(() => undefined);
  }
}

包裹所有屏幕的组件:顶部栏、菜单和消息。它对应 [ShellRoute] 控件在 [Flutter] 客户端中的角色。

  • 第 37–41 行:菜单项:一个接口;
  • 第 43–56 行:用户的角色所允许的菜单项。[...(condition ? [entries] : [])]:展开运算符向数组中插入零个、一个或多个项目(相当于 [if] 在 [Dart] 列表中的作用);
  • 第 69–76 行:各个服务,以及模板所显示的内容:语言、用户、菜单项(一个计算值:它随用户而变化);
  • 第 80–86 行:当前地址,用于标记活动的菜单项。[toSignal] 把 [Observable] (路由器事件,已精简为仅用于导航)转换为模板可读取的信号;必须为它提供一个初始值;
  • 第 88–89 行:语言菜单:打开或关闭,以及打开它的事件(按下按钮);
  • 第 92 行:模板所用的图标,使用 [ionicons] 注册;
  • 第 107–109 行:切换语言:不向服务器发送任何请求;字典改变,所有显示翻译的内容都会更新;
  • 第 113–115 行:注销:会话被清除,重新评估的守卫(参见 [app.ts])会显示登录界面。[catch]:即使服务器没有响应,用户也被视为已注销。

11.12.2. src/app/components/layout.html

<!-- ======================================================================
     layout.html - the layout common to all the screens
     ====================================================================== -->

<!-- ion-split-pane: beyond 800 pixels wide (when), the menu is
     permanently displayed to the left of the content; below, it is a drawer.
     contentId: the identifier of the main content. disabled: no menu
     for a visitor who is not logged in -->
<ion-split-pane contentId="main" when="(min-width: 800px)" [disabled]="!user()">
  <ion-menu contentId="main" [disabled]="!user()">
    <ion-content>
      @if (user(); as u) {
        <!-- 菜单的头部:谁已登录 -->
        <div class="who">
          <div class="name">{{ u.name }}</div>
          <ion-chip [outline]="true">{{ u.role }}</ion-chip>
        </div>
        <ion-list lines="none">
          @for (e of entries(); track e.path) {
            <!-- ion-menu-toggle: touching the entry closes the drawer;
                 routerDirection="root": the chosen screen replaces the whole
                 stack of screens (no going back to the previous screen) -->
            <ion-menu-toggle [autoHide]="false">
              <ion-item
                [button]="true"
                [detail]="false"
                [routerLink]="e.path"
                routerDirection="root"
                [class.active]="isActive(e)"
              >
                <ion-icon slot="start" [name]="e.icon" />
                <ion-label>{{ t(e.key) }}</ion-label>
              </ion-item>
            </ion-menu-toggle>
          }
        </ion-list>
      }
    </ion-content>
  </ion-menu>

  <!-- the main content: an Ionic "page" (class ion-page: in a column,
       over the full height) -->
  <div class="ion-page" id="main">
    <ion-header>
      <ion-toolbar color="primary">
        <!-- ion-menu-button: the ☰ button, which opens the drawer. It hides
             itself when the menu is disabled or permanently displayed -->
        <ion-buttons slot="start">
          <ion-menu-button />
        </ion-buttons>
        <ion-title>{{ t('APP.TITLE') }}</ion-title>
        <ion-buttons slot="end">
          <!-- 语言按钮会打开下面声明的 popover -->
          <ion-button id="language-button" [title]="t('APP.LANGUAGE')" (click)="openLanguages($event)">
            <strong>{{ language().toUpperCase() }}</strong>
          </ion-button>
          @if (user()) {
            <ion-button [title]="t('APP.LOGOUT')" (click)="logOut()">
              <ion-icon slot="icon-only" name="log-out-outline" />
            </ion-button>
          }
        </ion-buttons>
      </ion-toolbar>
    </ion-header>

    <!-- ion-popover: a small window, opened (isOpen) under the element
         touched (event); dismissOnSelect: it closes when a choice is made;
         didDismiss: it has closed (choice, or press beside it) -->
    <ion-popover
      [isOpen]="languagesOpen()"
      [event]="languagesEvent"
      [dismissOnSelect]="true"
      (didDismiss)="languagesOpen.set(false)"
    >
      <ng-template>
        <ion-list lines="none">
          @for (l of languages; track l) {
            <ion-item [button]="true" [detail]="false" (click)="changeLanguage(l)">
              <ion-label>{{ l.toUpperCase() }}</ion-label>
            </ion-item>
          }
        </ion-list>
      </ng-template>
    </ion-popover>

    <!-- 顶部的成功消息 -->
    @if (messages.success(); as success) {
      <ion-item class="message success" lines="none">
        <ion-icon slot="start" name="checkmark-circle" />
        <ion-label class="ion-text-wrap">{{ t(success.key, success.params) }}</ion-label>
        <ion-button slot="end" fill="clear" color="dark" (click)="messages.clear()">
          <ion-icon slot="icon-only" name="close" />
        </ion-button>
      </ion-item>
    }

    <!-- 当前屏幕 -->
    <div class="screen">
      <ion-router-outlet />
    </div>

    <!-- the error area, at the bottom: always visible, even if the screen scrolls.
         ion-footer: above the phone's navigation bar -->
    @if (messages.error(); as error) {
      <ion-footer>
        <ion-item class="message error" lines="none">
          <ion-icon slot="start" name="alert-circle" />
          <ion-label class="ion-text-wrap">{{ t(error.key, error.params) }}</ion-label>
          <ion-button slot="end" fill="clear" color="dark" (click)="messages.clear()">
            <ion-icon slot="icon-only" name="close" />
          </ion-button>
        </ion-item>
      </ion-footer>
    }
  </div>
</ion-split-pane>
  • 第 9 行:[ion-split-pane]:在大屏幕上(此处指宽度超过 800 像素:[when],一个 CSS“媒体查询”),菜单会永久显示在内容的左侧;在小屏幕上,它是一个由 ☰ 按钮打开的抽屉。[Flutter] 的布局——在这里由 [Ionic] 自己完成——需要在 [NavigationDrawer] 和 [NavigationRail] 之间做出选择。[contentId]:主要内容的标识符(第 43 行)。未登录的访客没有菜单([disabled]);
  • 第 10–39 行:[ion-menu]:菜单;顶部为已登录用户显示姓名和角色,放在一个“标签”中([ion-chip]);
  • 第 23–34 行:一个菜单项。[ion-menu-toggle] 在点按该项时关闭抽屉([autoHide] 设为 [false]:当菜单永久显示时,该项保持可见)。[routerLink]:屏幕地址(参见示例 17);[routerDirection="root"]:所选屏幕会替换 [Ionic] 的整个屏幕栈:返回按钮不会返回上一个屏幕(就像 [context.go] 和 [go_router] 中那样)。[class.active]:在当前屏幕的菜单项上设置 CSS 类 [active] ;
  • 第 43 行:主要内容:[Ionic] 的一个“页面”(类 [ion-page]:按列排列,占满整个高度);
  • 第 44–64 行:顶部栏:☰ 按钮([ion-menu-button],当菜单被禁用或永久显示时会自动隐藏)、标题、语言按钮(其文本为“FR”或“EN”)以及注销按钮(仅对已登录用户显示);
  • 第 69–84 行:[ion-popover]:一个小窗口,在被点按的元素([isOpen])下方打开([event]),在选择后关闭([dismissOnSelect]);[didDismiss]:它已经关闭,原因是进行了选择,或点按了旁边的区域。其内容位于 [ng-template] 中:只有在打开时才会构建;
  • 第 87–95 行:顶部的成功消息(如果有的话)。[@if (messages.success(); as success)]:条件及其存放在模板变量中的值;
  • 第 98–100 行:屏幕的位置,[ion-router-outlet] (参见示例 17):路由器在那里显示当前地址对应的屏幕。标有 [Ionic] 的屏幕负责管理屏幕之间的过渡,并把之前的屏幕隐藏着保留在内存中:返回按钮会回到它们,而无需重新创建;
  • 第 104–114 行:底部的错误区域:[ion-footer],即使屏幕滚动它也保持可见,并位于手机导航栏之上。

11.12.3. src/app/components/layout.scss

// =========================================================================
// layout.scss - 布局的样式
// =========================================================================

// 菜单的头部。在手机上,抽屉会延伸到 Android 的
// 状态栏(时间、电量)之下:其高度会加在顶部
.who {
  padding: calc(16px + var(--ion-safe-area-top, 0px)) 16px 8px 20px;

  .name {
    font-size: 18px;
    font-weight: 500;
  }
}

// 当前屏幕的菜单项:位于彩色圆角背景上
ion-item.active {
  --background: rgba(var(--ion-color-primary-rgb), 0.14);
  --border-radius: 28px;
  margin: 0 8px;
  font-weight: 500;
}

ion-menu-toggle ion-item {
  margin: 0 8px;
}

// 在大屏幕上:永久显示的菜单的宽度
ion-split-pane {
  --side-width: 230px;
  --side-min-width: 230px;
  --side-max-width: 230px;
}

// 各屏幕的位置:占满所有剩余高度。<ion-router-outlet>
// 被设为“absolute”:它填满这个“relative”容器
.screen {
  position: relative;
  flex: 1;
}

// 消息横幅
.message {
  font-size: 17px;
}

.success {
  --background: #e8f5e9;
  --color: #1b5e20;

  ion-icon[slot='start'] {
    color: #388e3c;
  }
}

.error {
  --background: #f8d7da;
  --color: #b71c1c;

  ion-icon[slot='start'] {
    color: #c62828;
  }
}

布局的样式。它们只作用于 [layout.html] 中的元素:[Angular] 会“封装”组件的样式。

  • 第 7–8 行:菜单头部(用户的姓名和角色)。在手机上,应用占据整个屏幕,包括 [Android] 显示时间和电量的顶部栏(状态栏):[Ionic] 的工具栏([ion-toolbar])会自动调整其位置,但这个简单的 [div] 不会。[--ion-safe-area-top] 这个 CSS 变量由 [Ionic] 提供,指明了这个栏的高度(在浏览器中为 0):它会被加到上边距上。没有它,姓名就会与时间重叠;
  • 第 17–22 行:活动菜单项,位于彩色圆角背景上,就像 [Material] 3 的菜单那样。[rgba(var(--ion-color-primary-rgb), 0.14)]:主色,几乎透明;
  • 第 29–33 行:永久显示的菜单的宽度(否则为 270 像素);
  • 第 37–40 行:[ion-router-outlet] 被设为“absolute”(它填满其父元素):它被放在一个占据所有剩余高度的容器中([flex: 1]),位于各条消息之间;
  • 第 47–63 行:消息横幅:成功为绿色,错误为粉色,以及其他客户端的颜色。

11.12.4. src/app/components/page-title.ts

// =========================================================================
// src/app/components/page-title.ts - 屏幕标题,已翻译
// -------------------------------------------------------------------------
// 在 Web 上:标签页的标题;在 Android 上:最近使用的应用列表中
// 的应用程序名称。"Schedule - RdvMedecins"
//
// Angular 的路由器可以为每个屏幕指定标题:路由的
// title 属性(参见 app.routes.ts)。每次导航之后,它都会
// 调用“标题策略”(TitleStrategy)。我们用这个策略
// 替换 Angular 自带的(参见 main.ts):我们的标题是翻译
// 键,并且标题也必须在语言变化时随之变化。
// =========================================================================

import { effect, inject, Injectable, signal } from '@angular/core';
import { Title } from '@angular/platform-browser';
import { RouterStateSnapshot, TitleStrategy } from '@angular/router';
import { Translations } from '../i18n/translations';

@Injectable()
export class PageTitle extends TitleStrategy {
  private readonly title = inject(Title);
  private readonly t = inject(Translations).t;
  // 当前屏幕的标题键
  private readonly key = signal<string | undefined>(undefined);

  constructor() {
    super();
    // 当键变化(导航)或语言变化时重新运行
    // (t 读取字典,它是一个信号)
    effect(() => {
      const key = this.key();
      const application = this.t('APP.TITLE');
      this.title.setTitle(key ? `${this.t(key)} - ${application}` : application);
    });
  }

  // 由路由器在每次导航之后调用;buildTitle:所显示路由的
  // title 属性
  override updateTitle(state: RouterStateSnapshot): void {
    this.key.set(this.buildTitle(state));
  }
}

屏幕标题,已翻译:文档标题,即 Web 上的标签页标题。[Angular] 路由器知道如何为每个屏幕指定标题:其路由的 [title] 属性(参见 [app.routes.ts]);每次导航之后,它都会调用“标题策略”([TitleStrategy]),而 [main.ts] 用这里的策略替换了它。

  • 第 19 行:[@Injectable()] 不带 [providedIn]:该服务由 [main.ts] 提供,而不是由 [Angular] 自带的提供;
  • 第 30–34 行:一个副作用,在标题键变化(导航事件)或语言变化时重新执行([t] 读取字典,它是一个信号)。[Title]:[Angular] 中负责写入页面标题的服务;
  • 第 39–41 行:在每次导航之后由路由器调用;[buildTitle] 读取所显示路由的 [title] 属性并设置标题。

[Flutter] 客户端用一个 [PageTitle] 控件包裹每个屏幕;而在这里,标题与路由一起声明。

11.12.5. src/app/components/form-submission.ts

// =========================================================================
// src/app/components/form-submission.ts - 向服务器发送表单
// -------------------------------------------------------------------------
// 应用程序的所有表单都遵循与示例 25 相同的模式:
// 手机上不检查任何规则(规则只存在于
// 唯一的一处,即服务器),而在被拒绝时:
//   - 每个字段的错误(ApiError.fields)显示在该字段下方;
//   - 通用消息(ApiError.key)显示在屏幕底部。
// 这个类把这些步骤归并在一起。它不是服务:屏幕
// 为每个表单创建一个实例(new),带有自己的信号:
//
//     readonly submission = new FormSubmission(inject(Messages));
//     if (await this.submission.submit(() => api.register(form))) { ... }
//     <app-input-field ... [error]="submission.errors()['lastName']" />
// =========================================================================

import { signal } from '@angular/core';
import { ApiError, Texts } from '../api/api-error';
import { Messages } from '../state/messages';

export class FormSubmission {
  // 每个字段的错误:一个翻译键
  readonly errors = signal<Texts>({});
  // 错误消息的参数({{min}}……),由服务器发回
  readonly params = signal<Texts>({});
  readonly inProgress = signal(false);

  constructor(private readonly messages: Messages) {}

  // 执行提交;成功则返回 true。出现 ApiError 时,会显示
  // 错误并返回 false
  async submit(action: () => Promise<unknown>): Promise<boolean> {
    if (this.inProgress()) return false; // 不允许重复提交
    this.errors.set({});
    this.params.set({});
    this.inProgress.set(true);
    try {
      await action();
      return true;
    } catch (e) {
      // 任何其他错误都是异常:showApiError 会再次抛出它
      this.messages.showApiError(e);
      const error = e as ApiError;
      this.errors.set(error.fields);
      this.params.set(error.params);
      return false;
    } finally {
      this.inProgress.set(false);
    }
  }

  // 用户修改了一个字段:其错误消失
  clearError(field: string): void {
    if (field in this.errors()) {
      // 一个不含该字段的新对象:信号的值发生变化
      const { [field]: _removed, ...others } = this.errors();
      this.errors.set(others);
    }
  }
}

向服务器提交表单:示例 23 的 [Command] ,并增加了字段错误(示例 25)。它不是服务:每个表单都创建自己的实例([new]),带有自己的信号。

  • 第 23–26 行:每个字段的错误(一个翻译键)、消息参数,以及正在进行的提交(按钮变为禁用)。三个信号,由模板读取;
  • 第 28 行:[private readonly messages]:一个变成属性的构造函数参数(参见 [api-error.ts]);
  • 第 32–50 行:提交:不允许重复提交;如果出现 [ApiError],则显示屏幕底部的通用消息和每个字段的错误。[finally] 在所有情况下都会运行,即使在 [return] 之后也是如此;
  • 第 53–59 行:用户修正某个字段;错误消失。会创建一个不含该字段的新对象([const { [field]: _removed, ...others } = ...]:一个解构赋值,其余部分 [others] 包含除该字段之外的所有字段):信号只有在其值变化时才通知它的监听者,而修改对象本身并不会改变它的值。

11.12.6. src/app/components/input-field.ts

// =========================================================================
// src/app/components/input-field.ts - 一个完整的表单字段
// -------------------------------------------------------------------------
// 标签 + 字段 + 帮助消息或错误消息。应用程序的所有
// 表单都使用它:
//
//   <app-input-field label="PERSONS.LASTNAME_LABEL" [maxLength]="20"
//       [value]="form().lastName" (valueChange)="update('lastName', $event)"
//       [error]="submission.errors()['lastName']" />
//
// 它是一个受控组件(参见示例 11):值属于父表单,由父表单提供
// (value 输入),并在每次按键时接收
// (valueChange 输出)。label、help 和 error 是
// 翻译键;params 是它们消息的参数({{min}}……)。
// =========================================================================

import { Component, inject, input, output } from '@angular/core';
import { InputCustomEvent, IonInput } from '@ionic/angular';
import type { AutocompleteTypes } from '@ionic/core';
import { Texts } from '../api/api-error';
import { Translations } from '../i18n/translations';

@Component({
  selector: 'app-input-field',
  imports: [IonInput],
  templateUrl: './input-field.html',
  styles: `
    :host {
      display: block;
      margin-bottom: 8px;
    }
  `,
})
export class InputField {
  readonly t = inject(Translations).t;

  // input.required:必填输入(如果父组件忘记提供,会出现编译错误)
  readonly label = input.required<string>();
  readonly value = input.required<string>();
  readonly error = input<string>();
  readonly help = input<string>();
  readonly params = input<Texts>({});
  readonly secret = input(false); // 密码:字符被隐藏
  readonly maxLength = input<number>();
  // 供手机的密码管理器使用('username'、'current-password'……)
  readonly autocomplete = input<AutocompleteTypes>('off');

  readonly valueChange = output<string>();

  // ionInput:每次按键时(ionChange:只在字段失去焦点时)
  change(event: InputCustomEvent): void {
    this.valueChange.emit(event.detail.value ?? '');
  }
}

一个完整的表单字段:标签、字段、帮助文本或错误消息。所有表单都使用它。

  • 第 38–46 行:输入(参见示例 10)。标签、帮助文本和错误消息都是翻译键。[input.required]:必填输入;如果父组件省略它,会导致编译错误。[AutocompleteTypes]:由 [Ionic] 提供的类型,表示 HTML 的 [autocomplete] 属性的允许取值;
  • 第 48 行:输出(参见示例 11):每次按键后的新值。这是一个受控组件:值属于父组件,由父组件提供([value])并接收([valueChange])。当父组件自己修改它时(验证码在失败后被清空),字段会随之更新:无需编写任何代码,这与 [didUpdateWidget] 在 [Flutter] 客户端中的情况不同;
  • 第 51–53 行:[ionInput]:来自 [ion-input] 的每次按键事件([ionChange] 只在字段失去焦点时发生);[detail.value] 可能是 [null] 或 [undefined]:这种情况下会发送空字符串。

11.12.7. src/app/components/input-field.html

<!-- ======================================================================
     input-field.html - the template of a form field
     ====================================================================== -->

<!-- fill="outline": a framed field; labelPlacement="floating": the
     label is in the empty field, and "floats" on the frame as soon as it has
     the focus or a value;
     helperText / errorText: the messages under the field. errorText is only
     displayed (in red, instead of the help) if the field has the
     classes ion-invalid AND ion-touched -->
<ion-input
  [label]="t(label())"
  fill="outline"
  labelPlacement="floating"
  [type]="secret() ? 'password' : 'text'"
  [value]="value()"
  [maxlength]="maxLength()"
  [autocomplete]="autocomplete()"
  [autocorrect]="secret() ? 'off' : 'on'"
  [helperText]="help() ? t(help()!, params()) : undefined"
  [errorText]="error() ? t(error()!, params()) : undefined"
  [class.ion-invalid]="!!error()"
  [class.ion-touched]="!!error()"
  (ionInput)="change($event)"
/>
  • 第 13–14 行:带边框的字段([fill="outline"]),其标签位于空字段中,一旦字段获得焦点或有了值,标签就会“浮”到边框上;
  • 第 15 行:密码会被隐藏;
  • 第 17–19 行:[maxlength] 限制输入;[autocomplete] 告诉手机的密码管理器该字段包含什么(用户名、密码或新密码);拼写检查器不检查密码;
  • 第 20–23 行:帮助和错误消息显示在字段下方。[ion-input] 只有当字段具有 CSS 类 [ion-invalid]和 [ion-touched]时,才会显示错误(红色,取代帮助文本):这些类在出现错误时设置。这些类通常由 [Angular] 表单设置(示例 08);而这里,由服务器决定有效性。示例 07 和 11 不建议的做法(手动设置这些类)在这里行得通:[Ionic] 确实会在下一次按键时移除它们,但那次按键同时也会清除错误([clearError]),而该错误本来就不应再显示;
  • 第 24 行:每次按键都会调用 [change]。

11.12.8. src/app/components/person-fields.ts

// =========================================================================
// src/app/components/person-fields.ts - 称谓、名、姓
// -------------------------------------------------------------------------
// 身份字段,为三个表单所共用:ADMIN 的医生/客户表单、
// “创建患者账户”和“管理我的账户”。父组件
// 向它传入值和错误,并接收每次变更:
//     <app-person-fields [values]="form()" [errors]="submission.errors()"
//         (fieldChange)="update($event.field, $event.value)" />
// =========================================================================

import { Component, inject, input, output } from '@angular/core';
import { IonSelect, IonSelectOption, SelectCustomEvent } from '@ionic/angular';
import { Texts } from '../api/api-error';
import { Data } from '../api/rdvmedecins-api';
import { Translations } from '../i18n/translations';
import { InputField } from './input-field';

export const titles = ['Mr', 'Mme', 'Melle'];

export interface FieldChange {
  field: string;
  value: string;
}

@Component({
  selector: 'app-person-fields',
  imports: [IonSelect, IonSelectOption, InputField],
  templateUrl: './person-fields.html',
})
export class PersonFields {
  readonly t = inject(Translations).t;
  readonly titles = titles;

  readonly values = input.required<Data>();
  readonly errors = input.required<Texts>();
  readonly fieldChange = output<FieldChange>();

  // 字段的值,作为文本
  value(field: string): string {
    return String(this.values()[field] ?? '');
  }

  update(field: string, value: string): void {
    this.fieldChange.emit({ field, value });
  }

  chooseTitle(event: SelectCustomEvent<string>): void {
    this.update('title', event.detail.value);
  }
}

身份字段(称谓、名、姓),为 ADMIN 表单、账户创建表单和“管理我的账户”表单所共用。

  • 第 34–36 行:父组件传入值和错误,并接收任何字段的同一个输出:字段名及其新值;
  • 第 39–41 行:字段的值,作为文本(表单值的类型为 [unknown]);
  • 第 47–49 行:从列表中选择的称谓;[SelectCustomEvent<string>]:[ion-select] 的事件,其值为文本。

11.12.9. src/app/components/person-fields.html

<!-- ======================================================================
     person-fields.html - title, first name, last name
     ====================================================================== -->

<!-- ion-select: a drop-down list, with label and error message;
     interface="popover": the list opens under the field -->
<ion-select
  [label]="t('PERSONS.TITLE_LABEL')"
  fill="outline"
  labelPlacement="floating"
  interface="popover"
  [value]="value('title')"
  [errorText]="errors()['title'] ? t(errors()['title']) : undefined"
  [class.ion-invalid]="!!errors()['title']"
  [class.ion-touched]="!!errors()['title']"
  (ionChange)="chooseTitle($event)"
>
  @for (title of titles; track title) {
    <ion-select-option [value]="title">{{ title }}</ion-select-option>
  }
</ion-select>

<app-input-field
  label="PERSONS.FIRSTNAME_LABEL"
  [maxLength]="20"
  [value]="value('firstName')"
  (valueChange)="update('firstName', $event)"
  [error]="errors()['firstName']"
/>
<app-input-field
  label="PERSONS.LASTNAME_LABEL"
  [maxLength]="20"
  [value]="value('lastName')"
  (valueChange)="update('lastName', $event)"
  [error]="errors()['lastName']"
/>
  • 第 7–21 行:称谓,位于下拉列表中([ion-select],参见示例 05),带有标签和错误消息,就像输入字段一样;[interface="popover"]:列表在字段下方打开(默认在对话框中打开);
  • 第 23–36 行:名和姓:两个输入字段。错误消息显示在服务器所期望的字段名下([errors()['firstName']])。

11.12.10. src/app/components/captcha-field.ts

// =========================================================================
// src/app/components/captcha-field.ts - 验证码图片和输入字段
// -------------------------------------------------------------------------
// 一个显示组件:图片(svg)、“另一张图片”按钮
// (reload 输出),以及由父表单控制的字段
// (value、valueChange)。图片及其标识符由登录页面向
// 服务器请求,因为登录页面需要它们来发送答案。
// =========================================================================

import { Component, computed, inject, input, output } from '@angular/core';
import { IonButton, IonIcon } from '@ionic/angular';
import { addIcons } from 'ionicons';
import { refresh } from 'ionicons/icons';
import { Translations } from '../i18n/translations';
import { InputField } from './input-field';

@Component({
  selector: 'app-captcha-field',
  imports: [IonButton, IonIcon, InputField],
  templateUrl: './captcha-field.html',
  styles: `
    .label {
      font-size: 13px;
      color: var(--ion-color-step-700, #444);
    }
    .row {
      display: flex;
      align-items: center;
      gap: 8px;
    }
    .image {
      width: 160px;
      height: 54px;
      background: #f5f7fa;
      border: 1px solid #d0d0d0;
      border-radius: 6px;
      object-fit: contain;
    }
  `,
})
export class CaptchaField {
  readonly t = inject(Translations).t;

  readonly svg = input<string>();
  readonly value = input.required<string>();
  readonly error = input<string>();
  readonly valueChange = output<string>();
  readonly reload = output<void>();

  // SVG 图片(文本)-> 一个 <img> 标签可以
  // 显示的“data:”地址。图片不能运行任何脚本:这是安全的
  readonly source = computed(() => {
    const svg = this.svg();
    return svg ? `data:image/svg+xml;charset=utf-8,${encodeURIComponent(svg)}` : undefined;
  });

  constructor() {
    addIcons({ refresh });
  }
}

验证码图片、“另一张图片”按钮和输入字段。该组件不调用服务器:由登录界面请求图片,因为发送响应时需要用到图片的标识符。

  • 第 21–39 行:组件的样式,直接写在组件内部([styles]):它们很短;
  • 第 48 行:一个空输出([output<void>()]):“用户想要另一张图片”;
  • 第 52–55 行:SVG 图片以文本形式接收(示例 22)。它被转换为“data:”URL(文件内容直接编码在 URL 中),这样 [img] 标签就可以显示它。这是安全的:图片不能执行任何脚本,而通过 [innerHTML] 插入页面的 SVG 则可以([Angular] 会拒绝它,除非明确授权)。

11.12.11. src/app/components/captcha-field.html

<!-- ======================================================================
     captcha-field.html - the captcha image and the input field
     ====================================================================== -->

<div class="label">{{ t('CAPTCHA.LABEL') }}</div>
<div class="row">
  @if (source(); as source) {
    <!-- alt:屏幕阅读器代替图片朗读的内容 -->
    <img class="image" [src]="source" [alt]="t('CAPTCHA.IMAGE_ALT')" />
  } @else {
    <div class="image"></div>
  }
  <ion-button fill="clear" (click)="reload.emit()">
    <ion-icon slot="start" name="refresh" />
    {{ t('CAPTCHA.NEW_IMAGE') }}
  </ion-button>
</div>
<app-input-field
  label="CAPTCHA.LABEL"
  help="CAPTCHA.HELP"
  [maxLength]="10"
  [value]="value()"
  (valueChange)="valueChange.emit($event)"
  [error]="error()"
/>
  • 第 9 行:[alt]:屏幕阅读器([TalkBack] ,来自 [Android])代替图片朗读的内容;
  • 第 13–16 行:“另一张图片”触发输出 [reload];
  • 第 18–25 行:字段,同样由父组件控制:组件传递该值及其任何更改。

11.12.12. src/app/components/confirmation.ts

// =========================================================================
// src/app/components/confirmation.ts - “确定吗?”
// -------------------------------------------------------------------------
// 取自示例 16。一个服务,它会打开一个 Ionic 对话框
// (AlertController)。消息是一个翻译键:
//     if (await this.confirmation.ask('SCHEDULE.CANCEL_CONFIRM')) { ... }
// 用“No, go back”而不是“Cancel”:有时问题是“取消这个
// 预约吗?”,此时用“Cancel”按钮会有歧义。
// 新的提问会清除上一个操作的消息。
// =========================================================================

import { inject, Injectable } from '@angular/core';
import { AlertController } from '@ionic/angular';
import { Messages } from '../state/messages';
import { Translations } from '../i18n/translations';

@Injectable({ providedIn: 'root' })
export class Confirmation {
  private readonly alerts = inject(AlertController);
  private readonly messages = inject(Messages);
  private readonly t = inject(Translations).t;

  async ask(key: string): Promise<boolean> {
    this.messages.clear();
    const alert = await this.alerts.create({
      // 对话框的 CSS 类:其宽度(参见 styles.scss)
      cssClass: 'confirmation',
      header: this.t('CONFIRMATION.TITLE'),
      message: this.t(key),
      buttons: [
        // 角色 'cancel':No 按钮;点按对话框外部或手机的
        // 返回按钮会得到角色 'backdrop':只有 'confirm' 表示同意
        { text: this.t('CONFIRMATION.NO'), role: 'cancel' },
        // cssClass:红色按钮(参见 styles.scss)
        { text: this.t('CONFIRMATION.YES'), role: 'confirm', cssClass: 'danger-button' },
      ],
    });
    await alert.present();
    // onDidDismiss:一个 Promise,在关闭时完成,其结果为按钮的角色
    const { role } = await alert.onDidDismiss();
    return role === 'confirm';
  }
}

示例 16 中的确认窗口,用法为:[if (await this.confirmation.ask('SCHEDULE.CANCEL_CONFIRM')) ...]。它是一个服务,因为它自身没有任何要显示的内容:创建对话框的是 [Ionic] 的 [AlertController] 。

  • 第 24 行:新的提问会清除上一个操作的消息;
  • 第 27 行:对话框的 CSS 类:其宽度(参见 [styles.scss]);
  • 第 33–35 行:按钮。点按对话框外部或按手机的返回按钮,会以 [backdrop] 角色关闭对话框(参见示例 16):只有“Yes, confirm”([confirm])才表示确认;
  • 第 38–41 行:[present()] 显示对话框;[onDidDismiss()] 返回一个 [Promise],在关闭时完成,其结果为被点按按钮的角色。

11.12.13. src/app/components/booking-dialog.ts

// =========================================================================
// src/app/components/booking-dialog.ts - 预约时间段的
// 对话框内容
// -------------------------------------------------------------------------
// 对话框本身是日程屏幕的一个 <ion-modal>,在其地址要求时
// 打开(/schedule?...&book=7,参见
// pages/schedule.ts):因此地址描述了整个屏幕,包括对话框。
// 这个组件只是它的内容。
//
// 它不与服务器通信:它发出
//   - confirm,带上所选患者(对于为自己
//     预约的患者则为 undefined);
//   - close。
// 由日程屏幕决定如何处理它们。
// =========================================================================

import { Component, inject, input, output, signal } from '@angular/core';
import { IonButton, IonSelect, IonSelectOption, SelectCustomEvent } from '@ionic/angular';
import { label, Person } from '../api/types';
import { Translations } from '../i18n/translations';

@Component({
  selector: 'app-booking-dialog',
  imports: [IonButton, IonSelect, IonSelectOption],
  templateUrl: './booking-dialog.html',
  styles: `
    :host {
      display: block;
      padding: 20px;
    }
    h2 {
      margin-top: 0;
      font-size: 22px;
      font-weight: 400;
    }
    .buttons {
      display: flex;
      justify-content: flex-end;
      flex-wrap: wrap;
      gap: 8px;
      margin-top: 20px;
    }
  `,
})
export class BookingDialog {
  readonly t = inject(Translations).t;
  readonly label = label;

  readonly timeRange = input.required<string>(); // "8:00 - 8:20"
  // ADMIN / DOCTOR:供选择的患者
  readonly clients = input<Person[]>([]);
  // USER:患者就是用户本人
  readonly patient = input<string>();
  readonly submitting = input(false);
  readonly confirm = output<number | undefined>();
  readonly close = output<void>();

  // 从列表中选择的患者
  readonly clientId = signal<number | undefined>(undefined);

  choose(event: SelectCustomEvent<number>): void {
    this.clientId.set(event.detail.value);
  }
}

预约窗口的内容。窗口本身是日程屏幕中的一个 [ion-modal] ,当地址要求时打开([&book=7],参见 [schedule.html])。

  • 第 49–56 行:该组件不与服务器通信:它接收要显示的内容,并发出两种响应——一种用于确认(带上所选患者),一种用于关闭窗口。当患者为自己预约时,它接收到的是患者自己的姓名([patient]),而没有列表;
  • 第 59 行:从列表中选择的患者:窗口的状态。

11.12.14. src/app/components/booking-dialog.html

<!-- ======================================================================
     booking-dialog.html - the content of the booking dialog
     ====================================================================== -->

<h2>{{ t('BOOKING_DIALOG.TITLE') }}</h2>
<p>{{ t('BOOKING_DIALOG.SLOT', { time: timeRange() }) }}</p>

<!-- a patient books for themselves: no list (and the server
     would ignore any clientId anyway) -->
@if (patient(); as patient) {
  <p>{{ t('BOOKING_DIALOG.PATIENT_LABEL') }}: <strong>{{ patient }}</strong></p>
} @else {
  <!-- placeholder:在尚未选择患者时显示的文本 -->
  <ion-select
    [label]="t('BOOKING_DIALOG.PATIENT_LABEL')"
    fill="outline"
    labelPlacement="stacked"
    interface="popover"
    [placeholder]="t('BOOKING_DIALOG.CHOOSE_PATIENT')"
    [value]="clientId()"
    (ionChange)="choose($event)"
  >
    @for (c of clients(); track c.id) {
      <ion-select-option [value]="c.id">{{ label(c) }}</ion-select-option>
    }
  </ion-select>
}

<div class="buttons">
  <ion-button fill="clear" (click)="close.emit()">{{ t('BOOKING_DIALOG.CANCEL') }}</ion-button>
  <ion-button [disabled]="submitting()" (click)="confirm.emit(clientId())">
    {{ t('BOOKING_DIALOG.CONFIRM') }}
  </ion-button>
</div>
  • 第 10–11 行:患者为自己预约:显示其姓名,没有列表;
  • 第 14–26 行:ADMIN 或医生从下拉列表中选择患者;[placeholder]:在尚未选择患者时显示的文本;
  • 第 29–34 行:按钮,右对齐;提交期间“确认”被禁用。

11.13. 各个屏幕

每个屏幕都是一个组件,由路由器按需加载(参见 [app.routes.ts]),其模板以 [ion-content] 开头:这是位于顶部栏和布局的错误区域之间的滚动区域。

11.13.1. src/app/pages/login.ts

// =========================================================================
// src/app/pages/login.ts - 登录界面(/login)
// -------------------------------------------------------------------------
// 与其他客户端相同的界面:登录名、密码、验证码,以及
// 第二个按钮“创建患者账户”,它在打开账户创建界面之前
// 会检查同一个验证码。
//
// /login?login=jbernard:登录字段已预先填好(就在
// 创建账户之后)。
// 登录成功后,这个界面不会自己导航:会话
// 发生变化,路由器守卫被重新评估(参见 app.ts),
// 由守卫离开登录界面(前往 ?redirect=... 或
// 该角色的主页,参见 app.routes.ts)。
// =========================================================================

import { Component, inject, input, linkedSignal, signal } from '@angular/core';
import { Router } from '@angular/router';
import { IonButton, IonContent, ViewWillEnter } from '@ionic/angular';
import { RdvMedecinsApi } from '../api/rdvmedecins-api';
import { Captcha } from '../api/types';
import { CaptchaField } from '../components/captcha-field';
import { InputField } from '../components/input-field';
import { FormSubmission } from '../components/form-submission';
import { Messages } from '../state/messages';
import { Session } from '../state/session';
import { Translations } from '../i18n/translations';

// 演示账户
const demoAccounts = [
  { accounts: 'admin', key: 'LOGIN.DEMO_ADMIN' },
  { accounts: 'pelissier, tatou, dupont', key: 'LOGIN.DEMO_DOCTOR' },
  { accounts: 'martin, durand, bistrou, german', key: 'LOGIN.DEMO_USER' },
];

@Component({
  selector: 'app-login',
  imports: [IonContent, IonButton, InputField, CaptchaField],
  templateUrl: './login.html',
})
export class LoginPage implements ViewWillEnter {
  private readonly api = inject(RdvMedecinsApi);
  private readonly session = inject(Session);
  private readonly router = inject(Router);
  private readonly messages = inject(Messages);
  readonly t = inject(Translations).t;
  readonly submission = new FormSubmission(this.messages);
  readonly demoAccounts = demoAccounts;

  // 地址中的登录名(?login=...),由路由器提供
  // (withComponentInputBinding,参见 main.ts)
  readonly login = input<string>();
  // 表单:与 login 输入相关联的信号。它以该输入的值开始(最多 30
  // 个字符),之后可以修改,并且如果
  // 地址变化,则从它重新开始
  readonly form = linkedSignal(() => ({ login: (this.login() ?? '').slice(0, 30), password: '', captcha: '' }));
  readonly captcha = signal<Captcha | null>(null);

  // ionViewWillEnter:Ionic 在屏幕即将显示的每一次
  // 都会调用它(第一次,以及返回该屏幕时)
  ionViewWillEnter(): void {
    void this.reloadCaptcha();
  }

  // 一张新图片:每次尝试之后都需要,因为一张图片只
  // 使用一次(服务器一检查完就会忘记它)
  async reloadCaptcha(): Promise<void> {
    try {
      this.captcha.set(await this.api.captcha());
    } catch {
      this.captcha.set(null); // 服务器无法访问:登录将失败并显示清晰的消息
    }
  }

  update(field: 'login' | 'password' | 'captcha', value: string): void {
    // 一个新对象:信号的值发生变化
    this.form.update((f) => ({ ...f, [field]: value }));
    this.submission.clearError(field);
  }

  // 两个按钮共用这一顺序:提交,然后在失败时
  // 显示错误消息并获取新图片
  private async attempt(action: () => Promise<void>): Promise<void> {
    this.messages.clear();
    const succeeded = await this.submission.submit(action);
    if (!succeeded) {
      this.form.update((f) => ({ ...f, captcha: '' }));
      await this.reloadCaptcha();
    }
  }

  // 成功时,这里无需再做任何事:由守卫切换屏幕
  logIn(): Promise<void> {
    const f = this.form();
    return this.attempt(() => this.session.logIn(f.login.trim(), f.password, this.captcha()?.id ?? '', f.captcha));
  }

  createAccount(): Promise<void> {
    return this.attempt(async () => {
      await this.api.registrationAccess(this.captcha()?.id ?? '', this.form().captcha);
      await this.router.navigateByUrl('/register');
    });
  }
}

登录界面。

  • 第 29–33 行:演示账户,显示在表单下方;
  • 第 41–47 行:各个服务(通过 [inject()] 获得)、表单提交以及演示账户;
  • 第 51 行:地址中的登录名([/login?login=jbernard],创建账户之后),由路由器赋给这个输入;
  • 第 55 行:输入:放在 [linkedSignal] 中的一个对象(字段名 → 值):这是一个可修改的值,但与一个计算相关联。它以计算出的值开始(地址中的登录名,最多 30 个字符);之后可以修改,而当 [login] 输入变化时,计算会重新开始。在字段初始化期间无法读取输入(它还没有收到它的值):[linkedSignal] 解决了这个问题;
  • 第 56 行:收到的验证码(其 ID 和图片);
  • 第 60–62 行:[ionViewWillEnter]:一个方法,[Ionic] 在屏幕即将显示的每一次都会调用它;包括第一次以及返回到该屏幕时(保存在内存中的屏幕不会被重新创建)。这里会请求一张新图片:上一次访问时的那张可能已经被使用过了;
  • 第 66–72 行:打开屏幕时、应请求时,以及每次尝试之后(一张图片只使用一次)都会获取新图片;
  • 第 74–78 行:字段被修改:创建一个新对象([{ ...f, [field]: value }]:一个副本,其中一个字段发生了变化),并且字段错误消失。参数 [field] 只接受输入中的三个名称:拼写错误会导致编译错误;
  • 第 82–89 行:两个按钮都遵循这一顺序:提交,然后如果不成功,则清空验证码并显示新图片;
  • 第 92–95 行:登录。如果成功,屏幕不做任何其他事情:会话发生变化,守卫被重新评估,由守卫离开登录界面(参见 [app.routes.ts]);
  • 第 97–102 行:“创建患者账户”:服务器验证验证码并签发一个令牌(一个 Cookie);随后打开账户创建界面。

11.13.2. src/app/pages/login.html

<!-- ======================================================================
     login.html - the login screen
     ====================================================================== -->

<ion-content class="ion-padding">
  <h1>{{ t('LOGIN.TITLE') }}</h1>

  <!-- autocomplete: the phone's password manager can
       fill in the form -->
  <app-input-field
    label="LOGIN.LOGIN_LABEL"
    autocomplete="username"
    [value]="form().login"
    (valueChange)="update('login', $event)"
    [error]="submission.errors()['login']"
  />
  <app-input-field
    label="LOGIN.PASSWORD_LABEL"
    autocomplete="current-password"
    [secret]="true"
    [value]="form().password"
    (valueChange)="update('password', $event)"
    [error]="submission.errors()['password']"
  />
  <app-captcha-field
    [svg]="captcha()?.svg"
    [value]="form().captcha"
    (valueChange)="update('captcha', $event)"
    (reload)="reloadCaptcha()"
    [error]="submission.errors()['captcha']"
  />

  <!-- expand="block":占满整个宽度 -->
  <ion-button expand="block" shape="round" [disabled]="submission.inProgress()" (click)="logIn()">
    {{ t('LOGIN.SUBMIT') }}
  </ion-button>
  <ion-button expand="block" shape="round" fill="outline" [disabled]="submission.inProgress()" (click)="createAccount()">
    {{ t('LOGIN.CREATE_ACCOUNT') }}
  </ion-button>
  <p class="ion-text-center help">{{ t('LOGIN.CREATE_ACCOUNT_HELP') }}</p>

  <!-- 演示账户 -->
  <div class="demo">
    <div>{{ t('LOGIN.DEMO_ACCOUNTS') }}</div>
    @for (d of demoAccounts; track d.key) {
      <div>• <code>{{ d.accounts }}</code> - {{ t(d.key) }}</div>
    }
  </div>
</ion-content>
  • 第 10–24 行:用户名和密码。[autocomplete]:手机的密码管理器会自动填写它们,并在登录后提示保存该账户;
  • 第 25–31 行:验证码;其图片在屏幕显示后由服务器发送:在此之前,[captcha()?.svg] 等于 [undefined] ;
  • 第 34–39 行:两个按钮,占满整个宽度([expand="block"]),提交期间被禁用;
  • 第 43–48 行:演示账户:对数组 [@for] (参见示例 03)进行的循环 [login.ts];[track d.key]:用于标识每个元素。

11.13.3. src/app/pages/schedule.ts

// =========================================================================
// src/app/pages/schedule.ts - 日程屏幕(/schedule)
// -------------------------------------------------------------------------
// 三个部分,与其他客户端相同:
//   1. 选择医生和日期;
//   2. 该医生当天的日程;
//   3. 预约时间段的对话框(一个 <ion-modal>)。
//
// 屏幕的全部状态都在其地址中:
//     /schedule?doctorId=1&day=2026-10-05              日程
//     /schedule?doctorId=1&day=2026-10-05&book=7       + 预约对话框
// 路由器把这三个参数传给组件的输入
// (withComponentInputBinding);屏幕由它们推导出要显示的内容(计算
// 信号),而用户的操作会改变地址。
// 因此在 Web 上,可以重新加载页面、将其加入书签、
// 使用后退/前进;在手机上,返回按钮会关闭
// 预约对话框。
//
// 每个人能看到什么、能做什么,由服务器决定(每个时间段的
// patient、mine、bookable、appointmentId 字段):屏幕只是
// 显示它。患者甚至不会收到其他患者的姓名。
// =========================================================================

import { Location } from '@angular/common';
import { Component, computed, effect, inject, input, linkedSignal, resource, signal } from '@angular/core';
import { Router } from '@angular/router';
import {
  DatetimeCustomEvent, IonButton, IonCard, IonCardContent, IonCardHeader, IonCardSubtitle, IonCardTitle, IonContent,
  IonDatetime, IonIcon, IonItem, IonLabel, IonList, IonModal, IonSelect, IonSelectOption, IonSpinner,
  SelectCustomEvent,
} from '@ionic/angular';
import { addIcons } from 'ionicons';
import { calendarOutline } from 'ionicons/icons';
import { ApiError } from '../api/api-error';
import { RdvMedecinsApi } from '../api/rdvmedecins-api';
import { ScheduleSlot, label } from '../api/types';
import { positiveInteger } from '../app.routes';
import { Confirmation } from '../components/confirmation';
import { BookingDialog } from '../components/booking-dialog';
import { Cache, reloadAfterInvalidation } from '../state/cache';
import { Messages, reportErrors } from '../state/messages';
import { isManager, isPatient, Session } from '../state/session';
import { today, isValidDate, timeRange, longDay } from '../formatting';
import { Translations } from '../i18n/translations';

// 日程的地址(不带预约对话框,或带上它)
export function scheduleUrl(doctorId: number | undefined, day: string, book?: number): string {
  const params = new URLSearchParams({ doctorId: String(doctorId ?? ''), day });
  if (book !== undefined) params.set('book', String(book));
  return `/schedule?${params}`;
}

@Component({
  selector: 'app-schedule',
  imports: [
    IonContent, IonCard, IonCardContent, IonCardHeader, IonCardTitle, IonCardSubtitle, IonSelect, IonSelectOption,
    IonItem, IonLabel, IonIcon, IonButton, IonList, IonSpinner, IonModal, IonDatetime, BookingDialog,
  ],
  templateUrl: './schedule.html',
  styleUrl: './schedule.scss',
})
export class SchedulePage {
  private readonly api = inject(RdvMedecinsApi);
  private readonly cache = inject(Cache);
  private readonly messages = inject(Messages);
  private readonly router = inject(Router);
  private readonly location = inject(Location);
  private readonly confirmation = inject(Confirmation);
  private readonly translations = inject(Translations);
  readonly t = this.translations.t;
  readonly user = inject(Session).user;
  readonly timeRange = timeRange;
  readonly label = label;

  // 地址的参数,保持原样(文本,可能无效)
  readonly doctorId = input<string>();
  readonly day = input<string>();
  readonly book = input<string>();

  // 由它们推导出的内容:计算信号(computed),在
  // 地址变化时重新计算
  readonly urlDoctorId = computed(() => positiveInteger(this.doctorId()));
  private readonly bookId = computed(() => positiveInteger(this.book()));
  // 日期:如果地址中的有效则用它,否则用今天
  readonly invalidDay = computed(() => {
    const day = this.day();
    return day !== undefined && !isValidDate(day);
  });
  readonly shownDay = computed(() => (this.invalidDay() ? today() : (this.day() ?? today())));

  // —— 数据
  // resource:由信号描述的异步读取。每当 params 变化时,
  // 就会再次调用 loader;params 为 undefined:没有什么可读取的
  readonly doctors = resource({
    loader: () => this.cache.read('doctors', () => this.api.list('doctors')),
  });
  // 患者:只对有权读取他们的人读取(预约对话框)
  readonly clients = resource({
    params: () => (isManager(this.user()) ? true : undefined),
    loader: () => this.cache.read('clients', () => this.api.list('clients')),
  });
  // 地址中没有医生时,DOCTOR 会看到他或她自己的日程(服务器
  // 通过令牌找到它);其他人什么也看不到
  readonly schedule = resource({
    params: () => {
      const id = this.urlDoctorId();
      if (this.invalidDay() || (id === undefined && this.user()?.role !== 'DOCTOR')) return undefined;
      return { id, day: this.shownDay() };
    },
    loader: ({ params: { id, day } }) => this.cache.read(`schedule/${id}/${day}`, () => this.api.schedule(id, day)),
  });

  // 收到的日程(undefined:尚未到达、失败,或没有日程)
  readonly s = computed(() => (this.schedule.hasValue() ? this.schedule.value() : undefined));
  // 显示的医生:地址中的那个,或收到的日程中的那个(DOCTOR)
  readonly shownDoctorId = computed(() => this.urlDoctorId() ?? this.s()?.doctor.id);
  // 预约对话框所打开的时间段(&book=7),
  // 仅当该用户可以预约它时才有效
  readonly toBook = computed(() => this.s()?.slots.find((c) => c.id === this.bookId() && c.bookable));
  // 已有即将到来的预约的患者:为什么没有
  // “预约”按钮;在包含该预约的日程中无用
  readonly info = computed(() => {
    const s = this.s();
    return s?.info && !s.slots.some((c) => c.mine) ? s.info : undefined;
  });
  // USER:患者的姓名,显示在预约对话框中
  readonly patient = computed(() => {
    const u = this.user();
    return isPatient(u) ? u?.name : undefined;
  });

  // —— 1. 选择医生和日期
  // 一个小表单,其状态只在提交之前使用。linkedSignal:
  // 它以地址中的值开始,并在地址变化时回到这些值
  readonly doctorChoice = linkedSignal(() => this.shownDoctorId());
  readonly dayChoice = linkedSignal(() => this.shownDay());
  readonly calendarOpen = signal(false);
  // 日历的语言(ion-datetime):'fr-FR' 或 'en-US'
  readonly locale = computed(() => (this.translations.language() === 'fr' ? 'fr-FR' : 'en-US'));
  // 所选医生必须在列表中(否则为无)
  readonly knownId = computed(() => {
    const id = this.doctorChoice();
    const list = this.doctors.hasValue() ? this.doctors.value() : [];
    return list.some((d) => d.id === id) ? id : undefined;
  });

  readonly submitting = signal(false);
  // 如果对话框是由本屏幕的“预约”按钮打开的,则为 true
  private openedHere = false;

  constructor() {
    addIcons({ calendarOutline });
    // 失效的数据(预约、取消):它们会被重新读取
    reloadAfterInvalidation(this.doctors, this.clients, this.schedule);
    // 读取失败:其消息显示在屏幕底部
    reportErrors(this.doctors, this.clients, this.schedule);
    // 地址中的日期无效:显示一条消息,在当前导航结束之后才显示
    // (setTimeout),因为导航会清除
    // 上一个屏幕的消息(参见 app.ts)
    effect(() => {
      if (this.invalidDay()) setTimeout(() => this.messages.showError('ERRORS.INVALID_DATE'));
    });
  }

  longDay(day: string): string {
    return longDay(day, this.translations.language());
  }

  chooseDoctor(event: SelectCustomEvent<number>): void {
    this.doctorChoice.set(event.detail.value);
  }

  // 日历:"2026-10-05"(或 "2026-10-05T00:00:00")-> "2026-10-05"
  chooseDay(event: DatetimeCustomEvent): void {
    const value = event.detail.value;
    if (typeof value === 'string') this.dayChoice.set(value.slice(0, 10));
    this.calendarOpen.set(false);
  }

  // “查看日程”会改变地址;路由器会复用这个组件
  // (同一条路由):只有它的输入变化,其他一切都会重新计算
  view(): void {
    void this.router.navigateByUrl(scheduleUrl(this.knownId(), this.dayChoice()));
  }

  // “预约”会改变地址(&book=...):对话框随之打开
  openBooking(c: ScheduleSlot): void {
    this.openedHere = true;
    void this.router.navigateByUrl(scheduleUrl(this.shownDoctorId(), this.shownDay(), c.id));
  }

  // 关闭对话框:返回上一个地址
  closeBooking(): void {
    // 地址中已经没有 &book= 了(浏览器的后退按钮):无需任何操作
    if (this.bookId() === undefined) return;
    if (this.openedHere) {
      // 就像返回按钮:带 &book= 的地址从历史中移除
      this.openedHere = false;
      this.location.back();
    } else {
      // 屏幕是直接在这个地址上打开的:用新地址替换它
      void this.router.navigateByUrl(scheduleUrl(this.shownDoctorId(), this.shownDay()), { replaceUrl: true });
    }
  }

  // 以服务器为准:每个操作之后,都会重新读取日程
  // (以及显示其预约的患者空间)。失效会
  // 通知所有存活的日程屏幕,包括这一个
  private reload(): void {
    this.cache.invalidate('my-area');
    this.cache.invalidate('schedule');
  }

  async confirmBooking(slot: ScheduleSlot, clientId: number | undefined): Promise<void> {
    const manager = isManager(this.user());
    this.submitting.set(true);
    try {
      await this.api.book(this.shownDay(), slot.id, manager ? clientId : undefined);
      this.messages.flash({ key: 'SCHEDULE.BOOKED' });
    } catch (e) {
      if (!(e instanceof ApiError)) throw e;
      if (e.key === 'ERRORS.CHOOSE_PATIENT') {
        // 没有选择患者:对话框保持打开
        this.messages.showError(e.key);
        return; // (finally 无论如何都会运行)
      }
      // 时间段在此期间被占用、患者已有预约……:消息
      // 将显示在日程上,对话框已关闭
      this.messages.flash({ success: false, key: e.key, params: e.params });
    } finally {
      this.submitting.set(false);
    }
    this.closeBooking();
    this.reload();
  }

  async cancel(c: ScheduleSlot): Promise<void> {
    if (c.appointmentId === null || !(await this.confirmation.ask('SCHEDULE.CANCEL_CONFIRM'))) return;
    try {
      await this.api.cancelAppointment(c.appointmentId);
      this.messages.showSuccess('SCHEDULE.CANCELLED');
    } catch (e) {
      this.messages.showApiError(e);
    }
    this.reload();
  }

  goToMyArea(): void {
    void this.router.navigateByUrl('/my-area');
  }
}

功能最丰富的屏幕:选择医生和日期、日程以及预约窗口。

  • 第 47–51 行:日程的地址。屏幕的全部状态都包含在它的地址中;用户的操作会改变地址,屏幕再据此决定显示什么;
  • 第 76–78 行:地址的三个参数,由路由器提供给各输入。它们是原样的文本字符串:可能缺失或无效;
  • 第 82–89 行:由它们派生的内容:计算信号,在地址变化时重新计算。如果地址中的日期有效则使用它;否则使用今天;
  • 第 94–96 行:[resource()]:由信号描述的异步读取(它相当于 [FutureBuilder] 在 [Flutter] 中的作用,但更好)。它的函数 [loader] 返回一个 [Promise];资源公开信号:[value()]、[isLoading()]、[error()]、[status()]……医生从缓存中读取:整个会话期间只读一次;
  • 第 98–101 行:[params]:资源所依赖的一个计算。每当它的值变化时,就会以这个新值调用 [loader] ;如果它等于 [undefined],则没有什么可读取的。这里:只有在用户有权查看患者时才读取患者(用于预约窗口);
  • 第 104–111 行:日程;其参数是医生和预约日期。“查看日程”会改变地址;路由器会以新的输入复用该屏幕(同一条路由);[params] 发生变化,日程就会被重新读取,无需再写任何其他代码([Flutter] 客户端则需要 [didUpdateWidget])。如果地址中没有医生,已登录的医生会看到他或她自己的日程(服务器通过令牌取得);其他人则什么也看不到;
  • 第 114 行:收到的日程。先用 [hasValue()] :从失败的资源读取 [value()] 会导致错误;
  • 第 119 行:预约窗口的时间段是地址中指定的那个([&book=7]),且仅当该用户可以预约它时才有效(期间已被占用的时间段、手工构造的地址:都不会有预约窗口);
  • 第 122–125 行:对于已有即将到来的预约的患者,服务器会在所有日程中附带发送这条消息([info]);但在包含该预约的日程中(一个 [mine] 时间段),它在预约后是不必要的——甚至会产生误导:患者看到自己的预约列在自己的姓名下,并带有“取消”按钮。因此,它只在其他日程中显示。[some]:如果数组中至少有一个元素满足条件,则为 true;
  • 第 135–136 行:选择医生和日期:一个小表单,其状态以地址中的值开始,并在地址变化时(浏览器的后退按钮)回到这些值:两个 [linkedSignal]。[Flutter] 客户端通过重新创建控件来实现这一点(其键随地址而变化);
  • 第 139 行:日历的语言,采用 [ion-datetime] 所期望的格式;
  • 第 141–145 行:所选医生必须在列表中(否则为无,并且“查看日程”被禁用);
  • 第 154–156 行:失效的数据(预约、取消):三个资源会被重新读取;如果读取操作失败,屏幕底部会出现一条消息(参见 [cache.ts] 和 [messages.ts]);
  • 第 160–162 行:地址中的日期无效:显示一条消息。它在当前导航结束之后才显示([setTimeout]:即整个当前代码块及其后续代码执行完毕之后);否则,切换到“新页面”(参见 [app.ts])会立刻把它清除;
  • 第 174–178 行:在日历中选择的日期;[ion-datetime] 返回 ISO 格式的日期(“2026-10-05”,有时后面跟着时间);
  • 第 182–184 行:“查看日程”会改变地址;
  • 第 187–190 行:“预约”同样会改变地址([&book=...]):浏览历史中会增加一个新条目;预约窗口因为地址要求而打开。[openedHere] 记录是该屏幕打开了它;
  • 第 193–204 行:关闭窗口:返回上一个地址。如果是该屏幕打开了它,我们就在历史中后退([location.back()]),就像手机上的返回按钮或浏览器中的后退按钮一样。如果该屏幕是直接在这个地址上打开的(在 Web 上),它的后面没有任何历史:我们就用日程的地址替换当前地址([replaceUrl])。如果地址中不再包含 [&book=] (你刚刚后退了),则无需任何操作;
  • 第 209–212 行:预约或取消之后,以服务器的数据为准:日程(以及患者空间)会失效;缓存通知日程屏幕,它们随即重新加载;
  • 第 214–235 行:预约。如果没有选择患者,窗口保持打开,并显示消息。任何其他操作都会关闭窗口,而消息(成功或错误——例如时间段在此期间被占用……)是一条弹出消息,在地址恢复为日程地址时显示;
  • 第 237–246 行:确认后取消。

11.13.4. src/app/pages/schedule.html

<!-- ======================================================================
     schedule.html - the schedule screen
     ====================================================================== -->

<ion-content class="ion-padding">
  <!-- 1. 选择医生和日期 -->
  <ion-card class="picker">
    <ion-card-content>
      <ion-select
        [label]="t('DOCTOR_DAY_PICKER.DOCTOR_LABEL')"
        fill="outline"
        labelPlacement="stacked"
        interface="popover"
        [placeholder]="t('DOCTOR_DAY_PICKER.CHOOSE_DOCTOR')"
        [value]="knownId()"
        (ionChange)="chooseDoctor($event)"
      >
        @if (doctors.hasValue()) {
          @for (d of doctors.value(); track d.id) {
            <ion-select-option [value]="d.id">{{ label(d) }}</ion-select-option>
          }
        }
      </ion-select>
      <!-- 日期:点按即可打开日历的一行 -->
      <ion-item class="day" [button]="true" [detail]="false" lines="full" (click)="calendarOpen.set(true)">
        <ion-label>
          <p>{{ t('DOCTOR_DAY_PICKER.DAY_LABEL') }}</p>
          <h3>{{ longDay(dayChoice()) }}</h3>
        </ion-label>
        <ion-icon slot="end" name="calendar-outline" [attr.aria-label]="t('DOCTOR_DAY_PICKER.CHOOSE_DAY')" />
      </ion-item>
      <ion-button expand="block" shape="round" [disabled]="knownId() === undefined" (click)="view()">
        {{ t('DOCTOR_DAY_PICKER.VIEW_SCHEDULE') }}
      </ion-button>
    </ion-card-content>
  </ion-card>

  <!-- the calendar, in a dialog; locale: the language of the names of the
       days and months; showDefaultButtons: the Cancel / OK buttons -->
  <ion-modal class="dialog" [isOpen]="calendarOpen()" (didDismiss)="calendarOpen.set(false)">
    <ng-template>
      <ion-datetime
        presentation="date"
        [value]="dayChoice()"
        [locale]="locale()"
        [firstDayOfWeek]="1"
        min="2020-01-01"
        max="2035-12-31"
        [showDefaultButtons]="true"
        [cancelText]="t('BOOKING_DIALOG.CANCEL')"
        doneText="OK"
        (ionChange)="chooseDay($event)"
      />
    </ng-template>
  </ion-modal>

  <!-- 已有即将到来的预约的患者:为什么没有“预约”按钮 -->
  @if (info(); as info) {
    <ion-card class="info">
      <ion-item lines="none" color="none">
        <ion-label class="ion-text-wrap">{{ t(info) }}</ion-label>
        <ion-button slot="end" fill="clear" (click)="goToMyArea()">{{ t('APP.MENU_MY_AREA') }}</ion-button>
      </ion-item>
    </ion-card>
  }

  <!-- 2. 日程 -->
  @if (s(); as s) {
    <ion-card class="schedule">
      <ion-card-header>
        <ion-card-title>{{ t('SCHEDULE.TITLE_PREFIX') }} {{ longDay(s.day) }}</ion-card-title>
        <ion-card-subtitle>{{ label(s.doctor) }}</ion-card-subtitle>
      </ion-card-header>
      @if (s.slots.length === 0) {
        <ion-card-content>{{ t('SCHEDULE.NO_SLOTS') }}</ion-card-content>
      }
      <ion-list lines="full">
        @for (c of s.slots; track c.id) {
          <!-- 可预约的时间段略带颜色 -->
          <ion-item [class.bookable]="c.bookable">
            <div slot="start" class="time-range">{{ timeRange(c) }}</div>
            <ion-label>
              @if (c.free) {
                <span class="tag free">{{ t('SCHEDULE.FREE') }}</span>
              } @else if (c.patient) {
                <span class="tag" [class.mine]="c.mine">{{ label(c.patient) }}</span>
              } @else {
                <span class="tag">{{ t('SCHEDULE.BOOKED_BY_OTHER') }}</span>
              }
            </ion-label>
            <!-- 由服务器允许的按钮(bookable、appointmentId) -->
            @if (c.bookable) {
              <ion-button slot="end" fill="outline" shape="round" (click)="openBooking(c)">
                {{ t('SCHEDULE.BOOK') }}
              </ion-button>
            } @else if (c.appointmentId !== null) {
              <ion-button slot="end" fill="outline" shape="round" color="danger" (click)="cancel(c)">
                {{ t('SCHEDULE.CANCEL_APPOINTMENT') }}
              </ion-button>
            }
          </ion-item>
        }
      </ion-list>
    </ion-card>
  } @else if (schedule.isLoading()) {
    <div class="ion-text-center ion-padding"><ion-spinner /></div>
  } @else if (schedule.status() === 'idle') {
    <p class="empty">{{ t('SCHEDULE.EMPTY_STATE') }}</p>
  }

  <!-- 3. the booking dialog, open only if the address contains
       &book=...; it closes (Back button, press beside it...):
       didDismiss -->
  <ion-modal class="dialog" [isOpen]="toBook() !== undefined" (didDismiss)="closeBooking()">
    <ng-template>
      @if (toBook(); as slot) {
        <app-booking-dialog
          [timeRange]="timeRange(slot)"
          [clients]="clients.hasValue() ? clients.value() : []"
          [patient]="patient()"
          [submitting]="submitting()"
          (confirm)="confirmBooking(slot, $event)"
          (close)="closeBooking()"
        />
      }
    </ng-template>
  </ion-modal>
</ion-content>
  • 第 9–23 行:医生列表;[labelPlacement="stacked"]:标签保持在字段上方,这样在尚未选择医生时,文本“-- choose a doctor --”([placeholder])是可见的。各选项要等待列表:[@if (doctors.hasValue())];
  • 第 25–31 行:日期显示为一个字段(标签在上方,日期完整拼写,并带有日历图标),位于一个 [ion-item] 中,点按它即可打开日历;
  • 第 32–34 行:“查看日程”,在选择已知医生之前被禁用;
  • 第 40–55 行:日历 [ion-datetime],位于由信号 [ion-modal] 打开的窗口中[calendarOpen]。[presentation="date"]:仅日期,不含时间;[locale]:日期和月份名称的语言;[firstDayOfWeek]:每周从星期一开始;[showDefaultButtons]:“取消”/“OK”按钮。“OK”会带着所选日期发出 [ionChange] ,然后关闭窗口;[didDismiss]:窗口已关闭(OK、取消、点按按钮之外、返回按钮);
  • 第 58–65 行:已有即将到来的预约的患者:为什么没有“预约”按钮(参见上面的 [info]);
  • 第 68–104 行:日程。每个时间段一行:时间、一个标签(空闲、患者的姓名,或对其他患者显示“已预约”),以及由服务器启用的按钮([bookable]、[appointmentId])。[@else if]:是 [@if] 的后续分支;
  • 第 105–109 行:预约日程正在加载:一个旋转的圆圈([ion-spinner]);没有可显示的日程(资源处于非活动状态,[idle]):提示选择医生和日期;
  • 第 114–127 行:预约窗口,仅当地址对应一个可预约的时间段时才打开([isOpen])。它也可以自行关闭:手机的返回按钮,或点按它旁边;[didDismiss] 随后调用 [closeBooking],由它校正地址。其内容是一个 [ng-template]:只在打开时创建,关闭时销毁(所选的患者会被遗忘)。

[Flutter] 客户端自己绘制预约窗口(一个 [Stack]、灰色背景、一张卡片);[ion-modal] 则提供所有这些,以及打开动画和对返回按钮的处理。

11.13.5. src/app/pages/schedule.scss

// =========================================================================
// schedule.scss - 日程屏幕的样式
// =========================================================================

ion-card {
  margin: 0 0 12px;
}

// 日期:外观类似输入字段的一行
ion-item.day {
  --padding-start: 0;
  --inner-padding-end: 0;
  margin-bottom: 12px;

  p {
    font-size: 13px;
  }

  h3 {
    font-size: 16px;
  }
}

// 面向患者的信息
ion-card.info {
  --background: #e1f5fe;
}

ion-card.schedule ion-card-title {
  font-size: 19px;
}

// 可预约的时间段:淡绿色背景
ion-item.bookable {
  --background: #e8f5e9;
}

.time-range {
  width: 96px;
  font-size: 14px;
  font-weight: 500;
}

// 一个彩色标签(其他客户端的“徽章”);默认为灰色
.tag {
  display: inline-block;
  padding: 3px 8px;
  border-radius: 6px;
  color: white;
  background: #757575;
  font-size: 13px;
  font-weight: bold;
  white-space: normal;

  &.free {
    background: #388e3c;
  }

  &.mine {
    background: var(--ion-color-primary);
  }
}

.empty {
  padding: 0 16px;
  color: var(--ion-color-medium-shade);
}

屏幕样式:日期视图、患者信息(淡蓝色背景)、可预约的时间段(淡绿色背景)、日程,以及彩色标签(第 45–62 行:默认为灰色,空闲时间段为绿色,已登录患者的预约为靛蓝色)。

11.13.6. src/app/pages/persons-config.ts

// =========================================================================
// src/app/pages/persons-config.ts - 医生还是客户?
// -------------------------------------------------------------------------
// 医生和客户的管理屏幕是相同的:相同的
// 列表,相同的表单。它们只写一次(persons.ts、
// person-form.ts);只有 API 的地址和
// 标签的键不同,在这里描述。路由器把类型传给每个屏幕。
// =========================================================================

import { PersonType } from '../api/rdvmedecins-api';
import { Person } from '../api/types';

export interface PersonKeys {
  title: string; // "Doctors"
  add: string; // "Add a doctor"
  edit: string; // "Edit a doctor"
  empty: string; // "No doctor."
  confirmDelete: string;
  added: string; // "Doctor {{name}} has been added (login: {{login}})."
  edited: string;
  deleted: string;
  notFound: string; // 该记录在此期间已被删除
}

// Record<PersonType, ...>:每种类型恰好有一个属性的对象
// (编译器会检查有没有遗漏)
const allKeys: Record<PersonType, PersonKeys> = {
  doctors: {
    title: 'DOCTORS.TITLE',
    add: 'DOCTORS.ADD',
    edit: 'DOCTORS.EDIT',
    empty: 'DOCTORS.EMPTY',
    confirmDelete: 'DOCTORS.DELETE_CONFIRM',
    added: 'DOCTORS.ADDED',
    edited: 'DOCTORS.UPDATED',
    deleted: 'DOCTORS.DELETED',
    notFound: 'ERRORS.DOCTOR_NOT_FOUND',
  },
  clients: {
    title: 'CLIENTS.TITLE',
    add: 'CLIENTS.ADD',
    edit: 'CLIENTS.EDIT',
    empty: 'CLIENTS.EMPTY',
    confirmDelete: 'CLIENTS.DELETE_CONFIRM',
    added: 'CLIENTS.ADDED',
    edited: 'CLIENTS.UPDATED',
    deleted: 'CLIENTS.DELETED',
    notFound: 'ERRORS.PATIENT_NOT_FOUND',
  },
};

export const keys = (type: PersonType): PersonKeys => allKeys[type];

// “已添加/已编辑/已删除”消息的 {{name}} 和 {{login}}
export const messageParams = (p: Person): Record<string, string> => ({
  name: `${p.firstName} ${p.lastName}`,
  login: p.login ?? '',
});

医生和客户的屏幕是相同的;只有标签键不同,在这里描述。

  • 第 13–23 行:“人员”类型的键,由一个接口描述;
  • 第 27–50 行:[Record<PersonType, PersonKeys>]:每种人员类型恰好有一个属性的对象。只要没有定义其键,向 [PersonType] 中添加一个值就会在这里导致编译错误;
  • 第 55–58 行:“已添加”、“已修改”和“已删除”消息的参数。

11.13.7. src/app/pages/persons.ts

// =========================================================================
// src/app/pages/persons.ts - 医生或客户的列表(ADMIN)
// -------------------------------------------------------------------------
// 两者共用一个屏幕:类型(医生或客户)作为
// 输入传入(路由的 data 属性,参见 app.routes.ts);各自特有的
// 标签位于 persons-config.ts 中。
// 在手机上,五列的表格放不下:每个人一个列表
// 行(姓名、登录名),带有两个按钮;圆形的
// “+”按钮(<ion-fab>)用于添加一个人。
// =========================================================================

import { Component, computed, inject, input, resource } from '@angular/core';
import { Router } from '@angular/router';
import {
  IonButton, IonCard, IonContent, IonFab, IonIcon, IonItem, IonLabel, IonSpinner,
} from '@ionic/angular';
import { addIcons } from 'ionicons';
import { add, createOutline, trashOutline } from 'ionicons/icons';
import { RdvMedecinsApi, PersonType } from '../api/rdvmedecins-api';
import { label, Person } from '../api/types';
import { Confirmation } from '../components/confirmation';
import { Cache, reloadAfterInvalidation } from '../state/cache';
import { Messages, reportErrors } from '../state/messages';
import { Translations } from '../i18n/translations';
import { keys, messageParams } from './persons-config';

@Component({
  selector: 'app-persons',
  imports: [IonContent, IonCard, IonItem, IonLabel, IonButton, IonIcon, IonFab, IonSpinner],
  templateUrl: './persons.html',
  styleUrl: './persons.scss',
})
export class PersonsPage {
  private readonly api = inject(RdvMedecinsApi);
  private readonly cache = inject(Cache);
  private readonly messages = inject(Messages);
  private readonly router = inject(Router);
  private readonly confirmation = inject(Confirmation);
  readonly t = inject(Translations).t;
  readonly label = label;

  readonly type = input.required<PersonType>();
  readonly c = computed(() => keys(this.type()));

  // 列表,来自缓存;params:类型(路由器可能会
  // 为另一种类型复用该屏幕,/doctors -> /clients)
  readonly list = resource({
    params: () => this.type(),
    loader: ({ params: type }) => this.cache.read(type, () => this.api.list(type)),
  });

  constructor() {
    addIcons({ add, createOutline, trashOutline });
    reloadAfterInvalidation(this.list);
    reportErrors(this.list);
  }

  // "Mme Marie PELISSIER" -> "MP"
  initials(p: Person): string {
    return `${p.firstName.charAt(0)}${p.lastName.charAt(0)}`;
  }

  add(): void {
    void this.router.navigateByUrl(`/${this.type()}/add`);
  }

  edit(p: Person): void {
    void this.router.navigateByUrl(`/${this.type()}/${p.id}/edit`);
  }

  async remove(p: Person): Promise<void> {
    const c = this.c();
    if (!(await this.confirmation.ask(c.confirmDelete))) return;
    try {
      await this.api.remove(this.type(), p.id);
      this.messages.showSuccess(c.deleted, messageParams(p));
    } catch (e) {
      // 仍有预约的医生:409 ERRORS.DOCTOR_HAS_APPOINTMENTS
      this.messages.showApiError(e);
    }
    // 列表被重新读取(reloadAfterInvalidation)
    this.cache.invalidate(this.type());
  }
}

医生或客户列表。

  • 第 42 行:类型(医生或客户):路由的 [data] 属性,赋给这个输入;
  • 第 47–50 行:列表,来自缓存。如果路由器为另一种类型复用该屏幕,[params] 就会变化,并读取另一个列表;
  • 第 63–69 行:添加和编辑通过其地址打开表单;
  • 第 71–83 行:确认后删除。有现有预约的医生会被服务器拒绝(409 [DOCTOR_HAS_APPOINTMENTS])。无论哪种情况,列表都会失效并被重新读取。

11.13.8. src/app/pages/persons.html

<!-- ======================================================================
     persons.html - the list of the doctors or the clients
     ====================================================================== -->

<ion-content class="ion-padding">
  <h1>{{ t(c().title) }}</h1>

  @if (list.hasValue()) {
    @for (p of list.value(); track p.id) {
      <ion-card>
        <ion-item lines="none">
          <!-- 姓名首字母,位于圆圈中 -->
          <div slot="start" class="initials">{{ initials(p) }}</div>
          <ion-label>
            <h2>{{ label(p) }}</h2>
            <p class="login">{{ p.login }}</p>
          </ion-label>
          <ion-button slot="end" fill="clear" color="medium" [title]="t('PERSONS.EDIT')" (click)="edit(p)">
            <ion-icon slot="icon-only" name="create-outline" />
          </ion-button>
          <ion-button slot="end" fill="clear" color="danger" [title]="t('PERSONS.DELETE')" (click)="remove(p)">
            <ion-icon slot="icon-only" name="trash-outline" />
          </ion-button>
        </ion-item>
      </ion-card>
    } @empty {
      <p>{{ t(c().empty) }}</p>
    }
  } @else if (list.isLoading()) {
    <!-- 尚未加载(或加载失败:消息显示在屏幕底部) -->
    <div class="ion-text-center ion-padding"><ion-spinner /></div>
  }

  <!-- ion-fab: a floating button, fixed (slot="fixed") at the bottom right,
       above the scrolling list -->
  <ion-fab slot="fixed" vertical="bottom" horizontal="end">
    <ion-button shape="round" size="large" class="extended-fab" (click)="add()">
      <ion-icon slot="start" name="add" />
      {{ t(c().add) }}
    </ion-button>
  </ion-fab>
</ion-content>
  • 第 9–28 行:每人一张卡片:圆圈中的姓名首字母、姓名、登录名和两个按钮。像 Web 客户端那样的五列表格无法放在手机上。[@empty]:[@for] 在列表为空时所显示的内容;
  • 第 36–41 行:[ion-fab]:一个浮动按钮,固定在右下角([slot="fixed"]:它不随列表滚动),“+ 添加医生”。[Flutter] 的 [FloatingActionButton.extended] (一个图标加文本)在 [Ionic] 中没有现成的对应物([ion-fab-button] 是圆形的,只用于图标):这里在 [ion-fab] 中放置了一个标准的圆角按钮。

11.13.9. src/app/pages/persons.scss

// =========================================================================
// persons.scss - 医生或客户列表的样式
// =========================================================================

ion-card {
  margin: 0 0 10px;
}

// 姓名首字母,位于彩色圆圈中
.initials {
  width: 44px;
  height: 44px;
  border-radius: 50%;
  display: flex;
  align-items: center;
  justify-content: center;
  background: #dde3fb;
  color: var(--ion-color-primary);
  font-weight: 500;
}

.login {
  font-family: 'Roboto Mono', monospace;
}

// 底部留出一些空间,以免最后一行被浮动按钮遮住
ion-content {
  --padding-bottom: 96px;
}

// 一个“展开”的浮动按钮:图标加文本,位于浅色背景上
.extended-fab {
  --background: #dde3fb;
  --color: var(--ion-color-primary);
  --border-radius: 16px;
  text-transform: none;
}

圆圈中的姓名首字母、等宽字体的登录名文本、列表下方的空白(第 27–29 行:否则浮动按钮会遮住最后一张卡片),以及“展开”的浮动按钮。

11.13.10. src/app/pages/person-form.ts

// =========================================================================
// src/app/pages/person-form.ts - 创建或更新一位
// 医生或客户(ADMIN)
// -------------------------------------------------------------------------
//     /doctors/add               -> 创建(无 id)
//     /doctors/3/edit            -> 更新(id = 3)
// (/clients 下的地址同理)。
//
// 对于更新,屏幕首先读取记录;表单只有在读取记录之后才
// 显示,并以记录的值开始(一个
// linkedSignal,无需之后再复制它们)。
// 这里不检查任何规则:服务器验证一切,其错误
// 显示在字段下方(参见 components/form-submission.ts)。
// 随记录读取的版本会随更新一并发回:如果另一位
// ADMIN 在此期间修改了它,服务器会返回 409 CONCURRENT_UPDATE。
// =========================================================================

import { Component, computed, effect, inject, input, linkedSignal, resource, untracked } from '@angular/core';
import { Router } from '@angular/router';
import { IonButton, IonContent, IonSpinner } from '@ionic/angular';
import { ApiError } from '../api/api-error';
import { Data, RdvMedecinsApi, PersonType } from '../api/rdvmedecins-api';
import { positiveInteger } from '../app.routes';
import { InputField } from '../components/input-field';
import { PersonFields } from '../components/person-fields';
import { FormSubmission } from '../components/form-submission';
import { Cache } from '../state/cache';
import { Messages } from '../state/messages';
import { Translations } from '../i18n/translations';
import { keys, messageParams } from './persons-config';

const empty: Data = { title: 'Mr', firstName: '', lastName: '', login: '', password: '' };

@Component({
  selector: 'app-person-form',
  imports: [IonContent, IonButton, IonSpinner, InputField, PersonFields],
  templateUrl: './person-form.html',
})
export class PersonFormPage {
  private readonly api = inject(RdvMedecinsApi);
  private readonly cache = inject(Cache);
  private readonly messages = inject(Messages);
  private readonly router = inject(Router);
  readonly t = inject(Translations).t;
  readonly submission = new FormSubmission(this.messages);

  // 类型:路由的 data 属性;id:地址的 :id 参数
  // (创建时不存在;其有效性由路由检查)
  readonly type = input.required<PersonType>();
  readonly id = input<string>();
  readonly recordId = computed(() => positiveInteger(this.id()));
  readonly creating = computed(() => this.recordId() === undefined);
  readonly c = computed(() => keys(this.type()));

  // 更新:读取记录(包括其版本),不经缓存:它
  // 必须是最新的(否则表单会以过时的
  // 版本开始:409 CONCURRENT_UPDATE)
  readonly record = resource({
    params: () => {
      const id = this.recordId();
      return id === undefined ? undefined : { type: this.type(), id };
    },
    loader: ({ params: { type, id } }) => this.api.read(type, id),
  });

  // 起始值(所读取的记录,或空值)的可修改副本
  readonly form = linkedSignal<Data>(() => {
    if (!this.record.hasValue()) return { ...empty };
    const p = this.record.value();
    return { title: p.title, firstName: p.firstName, lastName: p.lastName, login: p.login ?? '', password: '', version: p.version };
  });

  // 创建时,或读取记录之后,才显示表单
  readonly ready = computed(() => this.creating() || this.record.hasValue());

  constructor() {
    // 记录不存在(在此期间已被删除……):返回列表
    effect(() => {
      const e = this.record.error();
      if (e instanceof ApiError) {
        untracked(() => {
          this.messages.flash({ success: false, key: e.key, params: e.params });
          void this.router.navigateByUrl(`/${this.type()}`);
        });
      }
    });
  }

  text(field: string): string {
    return String(this.form()[field] ?? '');
  }

  update(field: string, value: string): void {
    this.form.update((f) => ({ ...f, [field]: value }));
    this.submission.clearError(field);
  }

  back(): void {
    void this.router.navigateByUrl(`/${this.type()}`);
  }

  async save(): Promise<void> {
    const type = this.type();
    const c = this.c();
    const id = this.recordId();
    const succeeded = await this.submission.submit(async () => {
      const p = id === undefined
        ? await this.api.add(type, this.form())
        : await this.api.edit(type, id, this.form());
      this.messages.flash({ key: this.creating() ? c.added : c.edited, params: messageParams(p) });
    });
    const key = this.messages.error()?.key;
    if (succeeded) {
      this.cache.invalidate(type); // 列表已变化
      this.back();
    } else if (key === c.notFound) {
      // 在此期间被另一位 ADMIN 删除:返回列表
      this.messages.flash({ success: false, key });
      this.back();
    }
  }
}

添加或编辑医生或客户。

  • 第 49–53 行:类型(路由的 [data] )和标识符(地址的 [:id] 参数,添加时不存在);
  • 第 58–64 行:对于修改,记录不经缓存读取:它必须是最新的。对于添加,[params] 等于 [undefined]:没有什么可读取的;
  • 第 67–71 行:读取记录之后,输入以记录中的值(或空值)开始:又一个 [linkedSignal]。[Flutter] 客户端用两个控件来实现这一点(第二个在读取记录之后创建);
  • 第 74 行:表单只在创建时或读取记录之后才显示;
  • 第 78–86 行:找不到记录(在此期间已被删除):返回列表,并显示一条消息;
  • 第 102–121 行:保存记录:[POST] 或 [PUT],取决于是否存在 ID。成功消息是一条弹出消息:它会出现在列表上。如果某条记录在此期间被另一位 ADMIN 删除:返回列表。

11.13.11. src/app/pages/person-form.html

<!-- ======================================================================
     person-form.html - creation or update of a person
     ====================================================================== -->

<ion-content class="ion-padding">
  <h1>{{ t(creating() ? c().add : c().edit) }}</h1>

  @if (ready()) {
    <app-person-fields
      [values]="form()"
      [errors]="submission.errors()"
      (fieldChange)="update($event.field, $event.value)"
    />

    <h3>{{ t('PERSONS.ACCOUNT_SECTION') }}</h3>
    <app-input-field
      label="PERSONS.LOGIN_LABEL"
      [maxLength]="30"
      [value]="text('login')"
      (valueChange)="update('login', $event)"
      [error]="submission.errors()['login']"
      [help]="creating() ? 'PERSONS.LOGIN_HELP_CREATE' : 'PERSONS.LOGIN_HELP_EDIT'"
    />
    <!-- 从不预先填充:密码永远不会从服务器返回 -->
    <app-input-field
      label="PERSONS.PASSWORD_LABEL"
      [secret]="true"
      [maxLength]="72"
      [value]="text('password')"
      (valueChange)="update('password', $event)"
      [error]="submission.errors()['password']"
      [params]="submission.params()"
      [help]="creating() ? 'PERSONS.PASSWORD_HELP_CREATE' : 'PERSONS.PASSWORD_HELP_EDIT'"
    />

    <div class="buttons">
      <ion-button shape="round" [disabled]="submission.inProgress()" (click)="save()">
        {{ t('PERSONS.SAVE') }}
      </ion-button>
      <ion-button shape="round" fill="outline" (click)="back()">{{ t('PERSONS.BACK') }}</ion-button>
    </div>
  } @else {
    <div class="ion-text-center ion-padding"><ion-spinner /></div>
  }
</ion-content>
  • 第 9–13 行:身份字段(参见 [person-fields.ts]);
  • 第 16–34 行:用户名和密码,创建和修改时使用不同的提示(把密码字段留空则不改变密码)。密码从不预先填充:服务器从不返回它。[params]:密码错误消息的参数([{{min}}]……)。

11.13.12. src/app/pages/register.ts

// =========================================================================
// src/app/pages/register.ts - “创建患者账户”(/register)
// -------------------------------------------------------------------------
// 只有在登录界面上复制了验证码之后才会到达这里
// (“创建患者账户”按钮):服务器随后签发了
// 一个通行证(一个 Cookie),路由的守卫已对其进行检查(参见
// app.routes.ts)。字段与 ADMIN 的表单相同,但登录名
// 和密码是必填的,并带有确认。
// =========================================================================

import { Component, computed, inject, signal } from '@angular/core';
import { Router } from '@angular/router';
import { IonButton, IonContent } from '@ionic/angular';
import { Data, RdvMedecinsApi } from '../api/rdvmedecins-api';
import { InputField } from '../components/input-field';
import { PersonFields } from '../components/person-fields';
import { FormSubmission } from '../components/form-submission';
import { Messages } from '../state/messages';
import { Translations } from '../i18n/translations';

// 患者所选密码的最小长度:与服务器相同的值
// (服务器在 PASSWORD_TOO_SHORT 错误中也会发回 {min})
const minPassword = '6';

@Component({
  selector: 'app-register',
  imports: [IonContent, IonButton, InputField, PersonFields],
  templateUrl: './register.html',
})
export class RegisterPage {
  private readonly api = inject(RdvMedecinsApi);
  private readonly messages = inject(Messages);
  private readonly router = inject(Router);
  readonly t = inject(Translations).t;
  readonly submission = new FormSubmission(this.messages);

  readonly form = signal<Data>({
    title: 'Mr',
    firstName: '',
    lastName: '',
    login: '',
    password: '',
    confirmation: '',
  });

  // 帮助消息和密码错误的参数
  readonly passwordParams = computed(() => ({ min: minPassword, ...this.submission.params() }));

  text(field: string): string {
    return String(this.form()[field] ?? '');
  }

  update(field: string, value: string): void {
    this.form.update((f) => ({ ...f, [field]: value }));
    this.submission.clearError(field);
  }

  backToLogin(): void {
    void this.router.navigateByUrl('/login');
  }

  async create(): Promise<void> {
    let login = '';
    const succeeded = await this.submission.submit(async () => {
      login = await this.api.register(this.form());
    });
    if (succeeded) {
      // 返回登录界面,登录名已预先填好
      this.messages.flash({ key: 'REGISTRATION.DONE', params: { login } });
      void this.router.navigate(['/login'], { queryParams: { login } });
    } else if (this.messages.error()?.key === 'ERRORS.CAPTCHA_BEFORE_ACCOUNT') {
      // 通行证已过期(15 分钟):返回验证码
      this.messages.flash({ success: false, key: 'ERRORS.CAPTCHA_BEFORE_ACCOUNT' });
      this.backToLogin();
    }
  }
}

创建患者账户,需持有登录界面签发的通行证才能访问(参见 [app.routes.ts] 中的 [registrationGuard])。

  • 第 23 行:密码的最小长度;用于帮助消息:与服务器相同的值(服务器在错误 [PASSWORD_TOO_SHORT] 中也会返回它);
  • 第 47 行:帮助消息和密码错误的参数([{{min}}]):如果有服务器的参数,则以服务器的为准;
  • 第 62–76 行:创建。成功:返回登录界面,并预先填好用户名([/login?login=...]:由 [queryParams] 构造该参数),同时显示一条弹出消息。因通行证已过期(15 分钟)而失败:返回验证码界面。其他任何错误都继续显示在字段下方。

11.13.13. src/app/pages/register.html

<!-- ======================================================================
     register.html - "Create a patient account"
     ====================================================================== -->

<ion-content class="ion-padding">
  <h1>{{ t('REGISTRATION.TITLE') }}</h1>
  <p class="intro">{{ t('REGISTRATION.INTRO') }}</p>

  <app-person-fields
    [values]="form()"
    [errors]="submission.errors()"
    (fieldChange)="update($event.field, $event.value)"
  />

  <h3>{{ t('PERSONS.ACCOUNT_SECTION') }}</h3>
  <app-input-field
    label="PERSONS.LOGIN_LABEL"
    autocomplete="username"
    [maxLength]="30"
    [value]="text('login')"
    (valueChange)="update('login', $event)"
    [error]="submission.errors()['login']"
    help="REGISTRATION.LOGIN_HELP"
  />
  <app-input-field
    label="PERSONS.PASSWORD_LABEL"
    autocomplete="new-password"
    [secret]="true"
    [maxLength]="72"
    [value]="text('password')"
    (valueChange)="update('password', $event)"
    [error]="submission.errors()['password']"
    [params]="passwordParams()"
    help="REGISTRATION.PASSWORD_HELP"
  />
  <app-input-field
    label="ACCOUNT.CONFIRMATION_LABEL"
    autocomplete="new-password"
    [secret]="true"
    [maxLength]="72"
    [value]="text('confirmation')"
    (valueChange)="update('confirmation', $event)"
    [error]="submission.errors()['confirmation']"
  />

  <div class="buttons">
    <ion-button shape="round" [disabled]="submission.inProgress()" (click)="create()">
      {{ t('REGISTRATION.SUBMIT') }}
    </ion-button>
    <ion-button shape="round" fill="outline" (click)="backToLogin()">
      {{ t('REGISTRATION.BACK_TO_LOGIN') }}
    </ion-button>
  </div>
</ion-content>
  • 第 16–44 行:一个新账户:[autocomplete="new-password"] 会提示密码管理器建议一个强密码并保存它。

11.13.14. src/app/pages/patient-area.ts

// =========================================================================
// src/app/pages/patient-area.ts - “我的空间”(/my-area,USER 角色)
// -------------------------------------------------------------------------
// 患者在登录后立即看到的主屏幕:
//   - 两个选项:[管理我的账户]和[查看日程];
//   - 他或她即将到来的预约(如果有的话),以及取消它的方式。
// =========================================================================

import { Component, inject, resource } from '@angular/core';
import { Router } from '@angular/router';
import {
  IonButton, IonCard, IonCardContent, IonCardHeader, IonCardTitle, IonContent, IonIcon, IonItem, IonLabel,
  IonSpinner,
} from '@ionic/angular';
import { addIcons } from 'ionicons';
import { calendar, personCircle } from 'ionicons/icons';
import { RdvMedecinsApi } from '../api/rdvmedecins-api';
import { label, Appointment } from '../api/types';
import { Confirmation } from '../components/confirmation';
import { Cache, reloadAfterInvalidation } from '../state/cache';
import { Messages, reportErrors } from '../state/messages';
import { timeRange, longDay } from '../formatting';
import { Translations } from '../i18n/translations';
import { scheduleUrl } from './schedule';

@Component({
  selector: 'app-patient-area',
  imports: [
    IonContent, IonCard, IonCardHeader, IonCardTitle, IonCardContent, IonItem, IonLabel, IonIcon, IonButton,
    IonSpinner,
  ],
  templateUrl: './patient-area.html',
  styleUrl: './patient-area.scss',
})
export class PatientAreaPage {
  private readonly api = inject(RdvMedecinsApi);
  private readonly cache = inject(Cache);
  private readonly messages = inject(Messages);
  private readonly router = inject(Router);
  private readonly confirmation = inject(Confirmation);
  private readonly translations = inject(Translations);
  readonly t = this.translations.t;
  readonly label = label;
  readonly timeRange = timeRange;

  readonly area = resource({
    loader: () => this.cache.read('my-area', () => this.api.myArea()),
  });

  constructor() {
    addIcons({ calendar, personCircle });
    reloadAfterInvalidation(this.area);
    reportErrors(this.area);
  }

  // "Monday, October 5, 2026, 8:00 - 8:20"
  when(a: Appointment): string {
    return `${longDay(a.day, this.translations.language())}, ${timeRange(a.slot)}`;
  }

  goTo(url: string): void {
    void this.router.navigateByUrl(url);
  }

  // 医生当天的日程:患者在其中看到自己的姓名
  seeInSchedule(a: Appointment): void {
    this.goTo(scheduleUrl(a.doctor.id, a.day));
  }

  async cancel(appointmentId: number): Promise<void> {
    if (!(await this.confirmation.ask('SCHEDULE.CANCEL_CONFIRM'))) return;
    try {
      await this.api.cancelAppointment(appointmentId);
      this.messages.showSuccess('SCHEDULE.CANCELLED');
    } catch (e) {
      this.messages.showApiError(e);
    }
    // 空间和日程都已发生变化(空间被重新读取:reloadAfterInvalidation)
    this.cache.invalidate('my-area');
    this.cache.invalidate('schedule');
  }
}

患者空间:两个选项及其即将到来的预约。

  • 第 46–48 行:患者的仪表板,来自缓存;
  • 第 57–59 行:“Tuesday, October 13, 2026, 8:00–8:20”;
  • 第 66–68 行:医生当天的日程:患者在其中看到自己的姓名;
  • 第 70–81 行:取消患者的预约:空间和日程都已发生变化。

11.13.15. src/app/pages/patient-area.html

<!-- ======================================================================
     patient-area.html - "My area"
     ====================================================================== -->

<ion-content class="ion-padding">
  @if (area.hasValue()) {
    @let e = area.value();
    <h1>{{ t('AREA.HELLO', { name: label(e.patient) }) }}</h1>

    <!-- two option "cards", touched to open a screen;
         detail: the > chevron on the right -->
    <ion-card>
      <ion-item [button]="true" [detail]="true" lines="none" (click)="goTo('/my-account')">
        <ion-icon slot="start" name="person-circle" color="primary" />
        <ion-label class="ion-text-wrap">
          <h2>{{ t('AREA.MANAGE_ACCOUNT') }}</h2>
          <p>{{ t('AREA.MANAGE_ACCOUNT_HELP') }}</p>
        </ion-label>
      </ion-item>
    </ion-card>
    <ion-card>
      <ion-item [button]="true" [detail]="true" lines="none" (click)="goTo('/schedule')">
        <ion-icon slot="start" name="calendar" color="primary" />
        <ion-label class="ion-text-wrap">
          <h2>{{ t('AREA.VIEW_SCHEDULE') }}</h2>
          <p>{{ t('AREA.VIEW_SCHEDULE_HELP') }}</p>
        </ion-label>
      </ion-item>
    </ion-card>

    <ion-card>
      <ion-card-header>
        <ion-card-title>{{ t('AREA.MY_APPOINTMENT') }}</ion-card-title>
      </ion-card-header>
      <ion-card-content>
        <!-- normally only one (rule "one upcoming appointment at a time"),
             but the screen can display several -->
        @for (a of e.appointments; track a.id) {
          <div class="when">{{ when(a) }}</div>
          <div>{{ label(a.doctor) }}</div>
          <div class="buttons">
            <ion-button fill="clear" (click)="seeInSchedule(a)">{{ t('AREA.SEE_IN_SCHEDULE') }}</ion-button>
            <ion-button fill="outline" shape="round" color="danger" (click)="cancel(a.id)">
              {{ t('AREA.CANCEL_APPOINTMENT') }}
            </ion-button>
          </div>
        } @empty {
          <p class="none">{{ t('AREA.NO_APPOINTMENT') }}</p>
        }
      </ion-card-content>
    </ion-card>
  } @else if (area.isLoading()) {
    <div class="ion-text-center ion-padding"><ion-spinner /></div>
  }
</ion-content>
  • 第 7 行:[@let]:一个模板变量,用于避免重复 [area.value()];
  • 第 12–29 行:两个选项:点按即可打开屏幕的卡片。[ion-item] 和 [button] 会响应触摸;[detail] 会在右侧添加 > 箭头;
  • 第 38–49 行:预约,以及两个按钮:查看医生当天的日程、取消;或者,如果没有预约([@empty]),则显示一条消息。

11.13.16. src/app/pages/patient-area.scss

// =========================================================================
// patient-area.scss - “我的空间”的样式
// =========================================================================

ion-card {
  margin: 0 0 12px;
}

// 选项的图标,更大
ion-item ion-icon[slot='start'] {
  font-size: 32px;
}

ion-item h2 {
  font-weight: 500;
}

ion-card-title {
  font-size: 19px;
}

.when {
  font-weight: 600;
  color: var(--ion-text-color, #000);
}

.none {
  color: var(--ion-color-medium);
}

卡片没有侧边距(屏幕本身已有边距)、选项使用更大的图标,以及预约日期加粗。

11.13.17. src/app/pages/my-account.ts

// =========================================================================
// src/app/pages/my-account.ts - “管理我的账户”(/my-account,USER 角色)
// -------------------------------------------------------------------------
// 两个独立的表单:
//   1. 更新(身份、登录名、可选的新密码);
//   2. 删除账户——同时也会取消其预约。
// 两者都需要当前密码(由服务器检查)。
// 两个表单,因此有两个 FormSubmission(两套错误)。与
// 人员表单一样,更新表单只有在读取账户之后
// 才显示,并以其值开始。
// =========================================================================

import { Component, inject, linkedSignal, resource, signal } from '@angular/core';
import { Router } from '@angular/router';
import { IonButton, IonCard, IonCardContent, IonContent, IonSpinner } from '@ionic/angular';
import { Data, RdvMedecinsApi } from '../api/rdvmedecins-api';
import { InputField } from '../components/input-field';
import { PersonFields } from '../components/person-fields';
import { Confirmation } from '../components/confirmation';
import { FormSubmission } from '../components/form-submission';
import { Cache } from '../state/cache';
import { Messages, reportErrors } from '../state/messages';
import { Session } from '../state/session';
import { Translations } from '../i18n/translations';

@Component({
  selector: 'app-my-account',
  imports: [IonContent, IonCard, IonCardContent, IonButton, IonSpinner, InputField, PersonFields],
  templateUrl: './my-account.html',
  styleUrl: './my-account.scss',
})
export class MyAccountPage {
  private readonly api = inject(RdvMedecinsApi);
  private readonly session = inject(Session);
  private readonly cache = inject(Cache);
  private readonly messages = inject(Messages);
  private readonly router = inject(Router);
  private readonly confirmation = inject(Confirmation);
  readonly t = inject(Translations).t;

  // —— 1. 更新
  // 每次访问都重新读取,不使用缓存:其版本必须是最新的
  readonly account = resource({ loader: () => this.api.myAccount() });
  readonly editing = new FormSubmission(this.messages);
  readonly form = linkedSignal<Data>(() => {
    if (!this.account.hasValue()) return {};
    const a = this.account.value();
    return {
      title: a.title,
      firstName: a.firstName,
      lastName: a.lastName,
      login: a.login,
      password: '',
      confirmation: '',
      currentPassword: '',
      version: a.version,
    };
  });

  // —— 2. 删除
  readonly deletion = new FormSubmission(this.messages);
  readonly deletePassword = signal('');

  constructor() {
    reportErrors(this.account);
  }

  text(field: string): string {
    return String(this.form()[field] ?? '');
  }

  update(field: string, value: string): void {
    this.form.update((f) => ({ ...f, [field]: value }));
    this.editing.clearError(field);
  }

  back(): void {
    void this.router.navigateByUrl('/my-area');
  }

  async save(): Promise<void> {
    const succeeded = await this.editing.submit(async () => {
      // 服务器签发了新令牌(姓名、登录名):顶部栏必须随之更新
      this.session.update(await this.api.editMyAccount(this.form()));
      this.messages.flash({ key: 'MY_ACCOUNT.UPDATED' });
    });
    if (succeeded) {
      this.cache.invalidate('my-area');
      this.back();
    } else {
      // 被拒绝的提交之后,字段中绝不能留下密码;
      // 该值的修改不经过 update(),以免清除
      // 服务器刚刚附加在其上的错误
      this.form.update((f) => ({ ...f, currentPassword: '' }));
    }
  }

  changeDeletePassword(value: string): void {
    this.deletePassword.set(value);
    this.deletion.clearError('currentPassword');
  }

  async deleteAccount(): Promise<void> {
    if (!(await this.confirmation.ask('MY_ACCOUNT.DELETE_CONFIRM'))) return;
    const succeeded = await this.deletion.submit(() => this.api.deleteMyAccount(this.deletePassword()));
    if (succeeded) {
      // 先显示消息:它将显示在登录界面上,会话一旦为空,
      // 守卫就会把我们带到那里
      this.messages.flash({ key: 'MY_ACCOUNT.DELETED' });
      this.session.forget(true); // 服务器已删除令牌 Cookie
    }
  }
}

“管理我的账户”:两个独立的表单,各自拥有自己的 [FormSubmission]。

  • 第 43 行:账户,每次访问都重新读取,不使用缓存(其版本必须是最新的);
  • 第 45–58 行:读取账户之后,数据输入以账户的值开始;
  • 第 81–96 行:编辑。服务器返回带有更新信息的用户(以及其 Cookie 中的新令牌):会话随之更新,菜单中显示的姓名也相应更新。登录尝试失败后,当前密码会从字段中清除,但不会清除服务器刚刚附加在其上的错误消息;
  • 第 103–112 行:确认后删除账户。首先是消息(一条弹出消息);然后清除会话,守卫显示登录界面,并附带该消息。

11.13.18. src/app/pages/my-account.html

<!-- ======================================================================
     my-account.html - "Manage my account"
     ====================================================================== -->

<ion-content class="ion-padding">
  <!-- 1. 更新 -->
  <ion-card>
    <ion-card-content>
      <h1>{{ t('MY_ACCOUNT.TITLE') }}</h1>
      @if (account.hasValue()) {
        <app-person-fields
          [values]="form()"
          [errors]="editing.errors()"
          (fieldChange)="update($event.field, $event.value)"
        />
        <h3>{{ t('PERSONS.ACCOUNT_SECTION') }}</h3>
        <app-input-field
          label="PERSONS.LOGIN_LABEL"
          autocomplete="username"
          [maxLength]="30"
          [value]="text('login')"
          (valueChange)="update('login', $event)"
          [error]="editing.errors()['login']"
        />
        <app-input-field
          label="MY_ACCOUNT.NEW_PASSWORD_LABEL"
          autocomplete="new-password"
          [secret]="true"
          [maxLength]="72"
          [value]="text('password')"
          (valueChange)="update('password', $event)"
          [error]="editing.errors()['password']"
          [params]="editing.params()"
          help="PERSONS.PASSWORD_HELP_EDIT"
        />
        <app-input-field
          label="ACCOUNT.CONFIRMATION_LABEL"
          autocomplete="new-password"
          [secret]="true"
          [maxLength]="72"
          [value]="text('confirmation')"
          (valueChange)="update('confirmation', $event)"
          [error]="editing.errors()['confirmation']"
        />
        <app-input-field
          label="MY_ACCOUNT.CURRENT_PASSWORD_LABEL"
          autocomplete="current-password"
          [secret]="true"
          [maxLength]="72"
          [value]="text('currentPassword')"
          (valueChange)="update('currentPassword', $event)"
          [error]="editing.errors()['currentPassword']"
          help="MY_ACCOUNT.CURRENT_PASSWORD_HELP"
        />
        <div class="buttons">
          <ion-button shape="round" [disabled]="editing.inProgress()" (click)="save()">
            {{ t('PERSONS.SAVE') }}
          </ion-button>
          <ion-button shape="round" fill="outline" (click)="back()">{{ t('MY_ACCOUNT.BACK') }}</ion-button>
        </div>
      } @else {
        <div class="ion-text-center ion-padding"><ion-spinner /></div>
      }
    </ion-card-content>
  </ion-card>

  <!-- 2. 删除:只有一个字段的表单 -->
  <ion-card class="danger">
    <ion-card-content>
      <h1>{{ t('MY_ACCOUNT.DELETE_TITLE') }}</h1>
      <p class="help">{{ t('MY_ACCOUNT.DELETE_HELP') }}</p>
      <app-input-field
        label="MY_ACCOUNT.CURRENT_PASSWORD_LABEL"
        autocomplete="current-password"
        [secret]="true"
        [maxLength]="72"
        [value]="deletePassword()"
        (valueChange)="changeDeletePassword($event)"
        [error]="deletion.errors()['currentPassword']"
      />
      <ion-button shape="round" color="danger" [disabled]="deletion.inProgress()" (click)="deleteAccount()">
        {{ t('MY_ACCOUNT.DELETE_SUBMIT') }}
      </ion-button>
    </ion-card-content>
  </ion-card>
</ion-content>
  • 第 7–65 行:编辑,位于一张卡片中;表单只在读取账户之后才出现;
  • 第 68–85 行:删除,位于带红色边框的卡片中:一个单字段表单。

11.13.19. src/app/pages/my-account.scss

// =========================================================================
// my-account.scss - “管理我的账户”的样式
// =========================================================================

ion-card {
  margin: 0 0 12px;
}

ion-card-content {
  color: var(--ion-text-color, #000);

  // 标题,与其他地方一样(Ionic 在卡片中给它们设置了其他边距)
  h1 {
    font-size: 26px;
    margin: 8px 0 16px;
  }

  h3 {
    font-size: 15px;
    font-weight: 500;
    margin: 16px 0 12px;
  }
}

// 删除卡片:红色边框,红色标题
ion-card.danger {
  border: 1px solid #e57373;

  h1 {
    color: #d32f2f;
  }
}

卡片中的标题([Ionic] 在 [ion-card-content] 中为它们设置了不同的大小和边距),以及删除所用的红色边框。

11.13.20. src/app/pages/error-page.ts

// =========================================================================
// src/app/pages/error-page.ts - 错误屏幕:404(未知地址)
// 或 403(角色不足,参见 app.routes.ts)
// -------------------------------------------------------------------------
// 代码(403 或 404)由路由的 data 属性给出。
// =========================================================================

import { Component, inject, input } from '@angular/core';
import { Router } from '@angular/router';
import { IonButton, IonContent } from '@ionic/angular';
import { Translations } from '../i18n/translations';

@Component({
  selector: 'app-error-page',
  imports: [IonContent, IonButton],
  templateUrl: './error-page.html',
  styles: `
    .error {
      color: #d32f2f;
    }
  `,
})
export class ErrorPage {
  private readonly router = inject(Router);
  readonly t = inject(Translations).t;
  readonly code = input(404);

  // "/":由守卫重定向到该角色的主页(或登录)
  home(): void {
    void this.router.navigateByUrl('/');
  }
}
1
2
3
4
5
6
7
8
9
<!-- ======================================================================
     error-page.html - the error screen (403, 404)
     ====================================================================== -->

<ion-content class="ion-padding">
  <h1 class="error">{{ t('ERROR_PAGE.TITLE') }} {{ code() }}</h1>
  <p>{{ t(code() === 403 ? 'ERRORS.FORBIDDEN' : 'ERRORS.NOT_FOUND') }}</p>
  <ion-button shape="round" (click)="home()">{{ t('ERROR_PAGE.BACK') }}</ion-button>
</ion-content>

错误页面:404(未知地址)或 403(权限不足)。该代码是路由的 [data] 属性,赋给入口 [code]([error-page.ts] 的第 26 行)。“返回首页”指向 [/],守卫会将其重定向到该角色的主页。

11.14. Flutter 与 Ionic:比较

两个客户端做的事情完全相同,架构也相同,文件一一对应。以下几点差异值得注意:

  • 令牌 Cookie:[Flutter] 客户端必须在手机上自己管理它(一个读取 [Set-Cookie] 并写入 [Cookie] 的 HTTP 客户端);[Ionic] 客户端则依赖 Web 浏览器,以及手机上 [Android] 的原生代码([CapacitorHttp]);
  • 状态与更新:[ChangeNotifier] 信号来自 [Flutter] ,它们通知自己的监听者([notifyListeners()]),然后控件自行重建;[Angular] 的信号知道是谁在读取它们,只更新依赖它们的部分。计算信号([computed])、链接信号([linkedSignal])和资源([resource])取代了[initState]、[didUpdateWidget]、和[FutureBuilder]中的很大一部分;
  • 地址:在两者中,整个屏幕状态都包含在地址里;[Angular] 路由器把它直接传给组件的输入([withComponentInputBinding]);
  • 预制组件:[Ionic] 在大屏幕上提供常驻菜单([ion-split-pane])、窗口([ion-modal]、[ion-popover]、[AlertController])和日历([ion-datetime]);[Flutter] 提供它自己的那一套([NavigationRail]、[showDatePicker]……),但与地址关联的预约窗口是在那里手工绘制的;
  • Web:[Ionic] 客户端本身就是一个 Web 应用(基于 HTML,几百 KB);而为 Web 编译的 [Flutter] 客户端在画布上绘制每个像素,并且首先要下载它的渲染引擎(几 MB)。相反,在手机上,[Flutter] 应用被编译为机器码,而 [Ionic] 应用则运行在 [WebView],即浏览器引擎之中。