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] 文件夹下打开的控制台窗口中:
- 第 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];参见“搭建开发环境”一章):
| 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]:
预约已保存;“取消”会提示确认:
医生直接进入他或她自己的每日日程:

11.3.3. 患者的仪表板
患者([martin])进入“我的空间”。在日历中,他在其他患者的时间段旁看到“已预约”,并为自己预约,而无需选择具体的患者:
他的预约显示在他的姓名下;“预约”按钮不再可用(只允许有一个即将到来的预约)。在另一位医生的日程中,如果他的预约没有出现,会有一条消息解释他为何无法预约。他的空间显示这个预约:
“管理我的账户”:任何修改都需要当前密码;错误来自服务器端:

患者的菜单中没有“医生”一项。在 Web 上,如果他们自己输入地址 /doctors,路由器的守卫会显示 403 错误页面(参见 [app.routes.ts])。
11.3.4. 管理医生和客户
医生列表;一个填写不正确的条目:
添加成功;一个同名者;删除有预约的医生被拒绝:
11.3.5. 创建账户
在登录界面上,输入验证码,然后点击“创建患者账户”。表单被服务器拒绝;账户创建后,你会回到登录界面,登录信息已预先填好:
11.3.6. 法语界面,大屏幕
顶部栏中的 FR / EN 菜单会在本地重新渲染屏幕,无需向服务器发出任何请求,日期也包括在内(“mardi 13 octobre 2026”)。在宽屏幕(Web、平板)上,菜单会一直显示在左侧:


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

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
| {
"/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()]:订阅随组件结束(此处是随应用程序结束)。
| // =========================================================================
// 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. 格式化
| // =========================================================================
// 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] 控件包裹每个屏幕;而在这里,标题与路由一起声明。
| // =========================================================================
// 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] 包含除该字段之外的所有字段):信号只有在其值变化时才通知它的监听者,而修改对象本身并不会改变它的值。
| // =========================================================================
// 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]:这种情况下会发送空字符串。
| <!-- ======================================================================
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('/');
}
}
|
| <!-- ======================================================================
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],即浏览器引擎之中。