10. 案例研究:RdvMedecins 应用的 React 客户端
10.1. 问题
[RdvMedecins] 应用允许用户在诊所预约就诊。[NestJS] 课程把它写成了一个 HTML 应用,由服务器生成页面。在这里,我们编写 [React] 客户端应用:完全相同的页面,由浏览器根据“RdvMedecins 服务器:一个黑盒”一章中描述的服务器 JSON 数据生成。
客户端必须提供 HTML 应用提供的一切:
- 一个带验证码(CAPTCHA)保护的登录页面,并可创建患者账户;
- 某位医生某一天的日程,支持预约(带患者选择窗口)和取消;
- 对于管理员,提供医生和客户的管理(列表、添加、编辑、删除);
- 对于患者,提供个人面板(显示即将到来的预约,并可取消)和账户管理;
- 两种语言:法语和英语;
- 唯一的 URL([/schedule?doctorId=1&day=...]),可以重新加载、加入书签,并可使用浏览器的后退/前进按钮导航。
10.2. 安装与运行
必须已安装并运行 JSON 服务器(见“RdvMedecins 服务器:一个黑盒”一章)。要在浏览器中使用客户端,不需要验证码测试模式:可以让服务器 的 [CAPTCHA_TEST] 字段 在 [.env] 文件中保持为空。
在 [rdvmedecins-react] 文件夹下打开的控制台窗口中:
然后在浏览器中打开 http://localhost:5173。演示账户列在登录页面上(密码 = 登录名)。
示例同样使用 5173 端口:请先停止当前正在运行的示例([Ctrl-C])。你也可以让客户端在另一个端口上启动:[npm start -- --port 5174]。
10.3. 使用应用
10.3.1. 登录页面

密码错误:消息出现在页面底部,并显示一张新图片(每张图片只能使用一次):

10.3.2. 日程,管理员和医生所见
以 [admin] 登录后,你会进入日程页面:

选择一位医生和一个日期,然后点击“查看日程”。URL 变为 [/schedule?doctorId=1&day=2026-10-05]:

“预约”会打开预约窗口。URL 变为 [/schedule?doctorId=1&day=2026-10-05&book=3]:重新加载页面(F5)会重新打开同一个窗口。

预约已保存:

“取消”会要求确认:

医生会被直接带到他自己的当日日程:

10.3.3. 患者门户
患者([martin])进入“我的空间”:

在日程中,他在其他患者的预约时间段旁看到“已预约”:

他无需选择患者,就能为自己预约:

他的预约显示在他的姓名下;“预约”按钮不再可用(只能有一个即将到来的预约),并有一条消息解释原因:

他的面板显示如下内容:

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

如果他输入专属于管理员的地址 /doctors:

10.3.4. 管理医生和客户

填写有误的条目:

添加成功:

重名:

删除有预约的医生的请求会被拒绝:

10.3.5. 创建账户
在登录页面上,输入验证码(CAPTCHA),然后点击“创建患者账户”。表单填写有误,被服务器拒绝:

账户创建之后,返回登录页面;登录字段已预先填好:

10.3.6. 法语界面
FR / EN 按钮会当场翻译页面,无需向服务器发出任何请求;浏览器标签页的标题也会被翻译:

10.3.7. 会话过期、未知地址
如果令牌过期(或者 Cookie 被删除),下一个请求会收到 401 响应;客户端被重定向到登录页面:

一个未知的地址:

10.4. 客户端架构

下表对比了 [NestJS] 课程中的 HTML 应用与这个客户端:
HTML 应用(NestJS) | React 客户端 |
服务器生成每个页面([res.render]) | 服务器返回 JSON;[src/pages/] 中的组件生成页面 |
[views/layout.hbs] 及其局部视图 | [Layout.tsx] 以及 [src/components/] 中的组件 |
控制器的路由([@Controller('schedule')]) | 客户端路由([routes.tsx]);服务器只有 /api/... 路由 |
[JwtAuthGuard] 和 [RolesGuard] 重定向到 /login 或 403 页面 | 路由守卫;服务器仍保留自己的守卫,返回 401 或 403 |
保存在 Cookie 中的闪现消息 | 保存在 store 中的闪现消息,[useMessages] |
由服务器读取的词典,辅助函数 [{{t}}] | 客户端上的词典,[i18next];服务器只返回键 |
语言保存在 Cookie 中 | 语言保存在 [localStorage] 中 |
表单被拒绝:服务器重新加载页面 | 表单被拒绝:400/409 响应;客户端在字段下方 显示错误 |
确认窗口:一个小脚本,[public/js/app.js] | 一个 store 和一个组件,[ConfirmDialog] |
应用在没有 JavaScript 的情况下也能工作 | 应用本身就是 JavaScript |
前几课中的 [Vue.js] 和 [Angular] 客户端具有完全相同的结构:[Pinia] 中的“store”和 [Angular] 中的服务,在这里就是 [Zustand] store;“组合式函数”就是 Hook,视图就是页面。
下面列出了客户端的所有文件。它们都有大量注释;这些注释是课程的一部分。
10.4.1. 项目配置
10.4.1.1. package.json
- 第 8–10 行:[npm start] 启动开发服务器;[npm run build] 先检查类型([tsc --noEmit],见下文),然后构建生产版本;[npm run preview] 提供构建好的版本用于测试;
- 第 12–21 行:应用使用的库:[React]、[React Router]、[TanStack Query]、[Zustand]、[i18next]、[Bootstrap];
- 第 22–28 行:开发工具:[Vite] 及其用于 [React] 的插件、[TypeScript],以及 [React] 的类型。
没有表单库([React Hook Form],示例 08):与示例 25 一样,所有输入验证规则都由服务器检查,客户端只显示结果。
10.4.1.2. vite.config.ts
- 第 15 行:示例 22 中的代理:/api/... 请求会被转发给 JSON 服务器;
- 第 19 行:开发服务器;
- 第 20 行:[npm run preview] 服务器,使用相同的代理;
- 第 24–28 行:在生产环境中,库的代码存放在单独的文件中(见“部署”一章)。
10.4.1.3. tsconfig.json
- 第 8 行:JSX 被编译成对 [jsx(...)] 的调用,它们会被自动导入:无需在每个文件中写 [import React];
- 第 9 行:[TypeScript] 的严格模式;
- 第 14 行:仅用于类型的导入写作 [import type]:它在编译时消失;
- 第 15 行:只允许使用那些可以简单地擦除以得到 [JavaScript] 的 [TypeScript] 语法(不允许 [enum],也不允许参数属性):这正是不检查类型的 [Vite] 所做的事;
- 第 16 行:导入 JSON 文件(词典);
- 第 18 行:[TypeScript] 不生成任何文件:它只负责检查([tsc --noEmit]);[Vite] 才负责编译。
10.4.2. 启动应用
10.4.2.1. index.html
- 第 16 行:[React] 显示应用的元素;
- 第 18 行:没有 [JavaScript],[React] 应用就无法显示任何内容:这里对此作了说明;
- 第 19 行:应用的入口点。开发期间,[Vite] 按需编译 [main.tsx] ;在生产环境中,这一行会被编译后的文件取代(见“部署”一章)。
10.4.2.2. src/main.tsx
- 第 17–19 行:样式表,随后是 [i18next] 的配置,它在模块加载时执行一次;
- 第 23–37 行:[TanStack Query] 客户端(示例 24),带有两项设置:
- 第 24–30 行:每个失败的请求都会调用 [onError]:它的错误消息显示在错误区域中,集中在一处。自己处理错误的查询会在它的元数据中声明这一点:[meta: { errorHandled: true }];
- 第 33–34 行:默认情况下,[TanStack Query] 会对失败的请求重试三次,并在你回到标签页时重新加载数据:在这里,错误会立即显示,数据只在被请求时才改变;
- 第 42 行:路由器(在 [router.ts] 中构建)显示当前地址对应的页面。
10.4.2.3. src/router.ts
- 第 20 行:“数据”模式(示例 17)的路由器,在任何组件之外创建:因此不是组件的代码也可以使用它([router.navigate]);
- 第 23–27 行:受保护的请求收到 401 响应时该做什么(见 [api/client.ts]):忘记用户、为下一个页面准备消息、转到登录页面;
- 第 33–39 行:[router.subscribe(function)]:每当路由器的状态变化时,就会调用该函数。每次导航结束时,上一个页面的消息消失,“闪现”消息出现(见 [stores/messages.ts])。
10.4.2.4. src/styles.css
HTML 应用的样式表,几乎原样照搬。唯一需要注意的是错误区域(第 24–35 行),当页面较高时,它被定位在窗口底部。
10.4.3. API 访问层
10.4.3.1. src/api/types.ts
“RdvMedecins 服务器:一个黑盒”一章中描述的 API 的 JSON 对象,被翻译成 [TypeScript] 接口:
- 第 25–29 行:称谓、名、姓——医生、客户和患者在预约时的共同点;
- 第 32–36 行:医生或客户。[version]:服务器的 乐观锁;修改时会带回读取到的版本:如果在此期间有人修改了该记录,服务器就会拒绝([ERRORS.CONCURRENT_UPDATE]);
- 第 54–60 行:日程中的一项。服务器指明已登录用户的权限:[bookable]、[appointmentId] (如果用户可以取消,则填入该值);客户端无需重新计算它们;
- 第 67 行:一个翻译键,用于已经有预约的患者。
10.4.3.2. src/api/api-error.ts
示例 24 中的 [ApiError] 类,原样不变:任何请求错误都会变成一个 [ApiError],其中包含消息的翻译键、它的参数,以及被拒绝表单中每个字段的错误。
10.4.3.3. src/api/client.ts
示例 24 中的 [request] 函数,增加了一项新功能:处理 401 响应。
- 第 22–26 行:受保护的请求收到 401 响应时要调用的函数。这个文件没有任何依赖(既不依赖路由器,也不依赖消息):[router.ts] 在启动时把这个函数赋给它。这样避免了循环依赖(客户端导入路由器,路由器导入各路由,各路由导入各页面,各页面又导入客户端……);
- 第 31 行:有些请求自己处理 401 错误:登录(密码错误:401)、[GET /api/auth/me] (没有人登录:401)……;
- 第 45–47 行:受保护的请求收到 401:会话已过期。先报告这一情况,然后像其他任何错误一样拒绝 promise:等待响应的组件没有特定的操作需要执行。
10.4.3.4. src/api/rdvmedecins.api.ts
API 的每个路由对应一个带类型的函数:组件调用 [api.schedule(1, '2026-10-05')] ,而无需了解 URL 或 JSON 的任何信息。如果 API 发生变化,只需修改这个文件。
- 第 32–36 行:登录相关的路由,它们是公开的([request] 的最后一个参数:[true]);
- 第 39–42 行:账户创建,分两步:在登录页面解答验证码(CAPTCHA)会得到一个“通行证”(一个 Cookie),路由 [POST /api/register] 要求提供它;
- 第 46–52 行:[URLSearchParams] 生成地址参数(并对它们编码)。对于已登录的医生,没有 [doctorId]:服务器返回他自己的日程;
- 第 54 行:患者为自己预约:没有 [clientId]。[JSON.stringify] 会省略值为 [undefined] 的属性;
- 第 58–62 行:医生和客户以相同的方式处理:类型是一个参数;
- 第 28 行:空对象 [{}] 的类型,某些路由会返回它。
10.4.4. 语言
10.4.4.1. src/i18n/i18n.ts
示例 21 的配置:
- 第 22–32 行:已保存的语言,否则使用浏览器的语言。访问 [localStorage] 可能失败(严格的隐私浏览模式):[try / catch];
- 第 36–43 行:每次语言变化时,都会保存它,并更新页面的 [lang] 属性;
- 第 47 行:词典作为模块导入,属于编译后代码的一部分,无需额外的请求;
- 第 50 行:[React] 已经对它显示的一切内容做了转义:无需重复转义。
这里没有与 [Angular] 的“标题策略”对应的东西:每个页面用 [<title>] 标签声明自己的标题,[React] 19 会把它放到文档头部(见 [components/PageTitle.tsx])。
10.4.4.2. 词典
词典 [fr.json] 和 [en.json] 就是 [NestJS] 课程中 HTML 应用的词典,并补充了少量客户端专用的键([ERRORS.SERVER_UNREACHABLE]……)。它们的参数语法 [{{min}}] 与 [i18next] 的完全相同。JSON 服务器返回的是同样的键。
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 | |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 | |
10.4.5. store
10.4.5.1. src/stores/session.ts
已登录的用户,保存在 [Zustand] store 中(示例 20)。store 既可以被组件读取([useSession((s) => s.user)]),也可以 被不属于组件的代码读取:[useSession.getState()] (路由守卫)。
- 第 21 行:用户的描述([{ login, name, role }])。而 JWT 令牌则存放在 httpOnly Cookie 中:客户端永远看不到它;
- 第 31–44 行:[check()] 只询问一次服务器当前登录的是谁:promise 被保存并复用([??=]:当变量为 [null] 时赋值)。守卫在每次导航之前都会调用它:只有第一个调用才真正需要等待;
- 第 46–48 行:登录:服务器返回的用户被存入 store;
- 第 53–59 行:登出。[finally]:即使服务器没有响应,客户端也会忘记用户;
- 第 66–72 行:由用户推断出的信息:以用户为参数的普通函数。组件在从 store 读取 [user] 之后写 [isAdmin(user)] ;当用户变化时,它会被重新显示。
10.4.5.2. src/stores/messages.ts
显示给用户的消息:页面顶部的成功消息,页面底部的错误消息。
- 第 21–24 行:消息是一个翻译键及其参数,而不是纯文本:如果用户切换语言,它会自动重新翻译;
- 第 49–54 行:[ApiError] 会变成页面的错误消息。其他任何错误都是客户端的问题(编程错误):它会被重新抛出,以便出现在浏览器控制台中;
- 第 59–60 行:[flash] 为下一个页面设置一条消息。以页面切换结束的操作(添加医生,然后返回列表)会使用它:立即显示的消息会在用户导航时消失;
- 第 64–65 行:由路由器在每次导航结束时调用:待显示的消息成为该页面的消息。
10.4.5.3. src/stores/confirmation.ts
示例 16 中的确认窗口,实现为一个 store 和一个普通函数:
- 第 17 行:提出的问题(一个翻译键),或者 [null]:窗口([components/ConfirmDialog.tsx])已关闭;
- 第 22 行:用来解析当前问题的 promise 的函数。无需显示:它不是状态,而是一个模块变量;
- 第 35–43 行:[confirm] 打开窗口并返回一个 promise,由 [answer] 解析为 [true] (是)或 [false] (否)。页面只需写 [if (await confirm('SCHEDULE.CANCEL_CONFIRM')) { ... }]。与示例 16 不同,这里不需要上下文:store 在任何地方都可以访问。
10.4.6. Hook
10.4.6.1. src/hooks/useFormSubmit.ts
应用中的所有表单都遵循示例 25 所示的模式:浏览器中不检查任何验证规则,如果服务器拒绝提交,每个字段的错误就显示在该字段下方,并在页面底部显示一条总体错误消息。这个自定义 Hook(示例 15)负责处理以下事项:
- 第 24–27 行:它的状态:每个字段的错误(一个翻译键)、它们的参数,以及“提交中”(用于禁用按钮);
- 第 31–50 行:[submit(action)] 执行提交,如果成功则返回 [true] 。如果得到的是 [ApiError],就显示这些错误,并且函数返回 [false]。[useCallback]:该函数在两次显示之间保持不变;
- 第 53–59 行:用户修改某个字段:它的错误消失。如果该字段没有错误,就返回同一个对象;[React] 不会重新显示任何内容。[const { [field]: _cleared, ...rest } = e]:[rest] 是 [e] 的副本,只是没有 [field] 属性。
10.4.6.2. src/hooks/useCaptcha.ts
一个在组件显示时加载的验证码(CAPTCHA)图片,以及用来请求另一张图片的 [reload()] :每次尝试之后都必须这样做,因为服务器一旦验证了图片就会将其丢弃。
10.4.7. 格式化
10.4.7.1. src/formatting.ts
服务器发送的是原始数据([startHour: 8, startMinute: 0]; [day: "2026-10-05"]);格式化由客户端负责(示例 09)。这些都是普通函数:[React] 不需要“管道”,JSX 这样的表达式可以调用任何函数([{timeRange(c)}])。
- 第 33–39 行:[day is string]:一个 类型谓词:如果函数返回 [true],[TypeScript] 就知道 [day] 是字符串。一个“真实存在”的日期:[2026-02-30] 格式正确,但 [new Date] 会把它转换为 3 月 2 日;然后把得到的日期与原字符串进行比较;
- 第 42–47 行:用用户的语言完整拼写出的日期,使用 [Intl.DateTimeFormat]。[timeZone: 'UTC']:日期是在午夜(UTC)构造的;如果按马提尼克岛的时区(UTC-4)格式化,它仍然是前一天。
10.4.8. 路由器
10.4.8.1. src/routes.tsx
与 HTML 应用使用的地址完全相同,但它们现在是客户端的路由:
- 第 31–37 行:页面的描述:它的地址、访问权限,以及组件,组件要么立即提供([Component]),要么按需加载([load]);
- 第 39–46 行:[page()] 生成对应的路由:
- 第 43 行:通用守卫,根据页面的权限生成,之后是该页面专属的守卫。它们在页面加载之前运行(示例 18);
- 第 44 行:[lazy]:页面代码在第一次访问时加载(示例 17)。登录页面和日程页面(所有人都能看到)立即加载;ADMIN 页面和患者页面按需加载;
- 第 50–65 行:管理医生、再管理客户的三个页面,使用同一个模板。组件被包裹在一个无参数的组件中,[() => <Persons type={type} />]:这样它就能以 prop 的形式接收类型;
- 第 69–70 行:根路由。它的组件 [Layout] 在它的 [<Outlet />] 中显示当前页面;
- 第 73 行:在第一次导航期间,守卫向服务器询问当前登录的是谁时显示的内容:什么都不显示;
- 第 77 行:地址 [/] 重定向到 [/login],如果用户已登录,它的守卫本身会把用户重定向到该角色的主页;
- 第 78–79 行:[rights: { public: true }]:无需登录即可访问该页面;[rights: {}]:必须已登录,不论角色是什么;
- 第 83–87 行:创建公开账户还有第二个守卫 [registrationGuard];
- 第 88–89 行:[roles: ['USER']]:患者的页面;
- 第 90 行:403 页面;
- 第 91 行:404 页面:[*] 表示其他任何路由都不认识的地址。
提醒:如果用户重新加载 [/schedule] (F5),浏览器确实会向服务器请求 [/schedule] ,服务器此时必须返回 [index.html]:[Vite] 开发服务器就是这样做的,而在生产环境中则由 JSON 服务器来做(见“部署”一章)。
10.4.8.2. src/guards.ts
- 第 24–27 行:页面的访问权限;
- 第 29–51 行:[guard(rights)] 创建一个守卫,即路由器中间件(示例 18):
- 第 31 行:第一次(启动、F5)时,向服务器询问当前登录的是谁;之后则已有现成的响应;
- 第 36–42 行:公开页面。已登录的用户在登录页面上无需再做任何事:他们会被重定向到自己的主页;
- 第 43–46 行:没有人登录:重定向到登录页面,同时保留所请求的页面([?redirect=...]),以便登录后返回;
- 第 47–49 行:角色未获授权:显示 403 页面;
- [throw redirect(...)]:守卫“抛出”一个重定向:当前的导航被放弃,转而前往新地址;
- 第 55–61 行:页面 [/register] 专属的守卫:没有通行证(在登录页面上解答的验证码(CAPTCHA)),就带着一条消息返回登录页面。服务器无论如何都会拒绝创建账户。
这些检查只是一种便利措施:不显示无用的页面。数据保护由服务器保证,服务器在每次请求时都会重新验证令牌和角色。
10.4.9. 组件
10.4.9.1. src/components/Layout.tsx
根路由的组件,相当于 HTML 应用中的 [views/layout.hbs] :导航栏、顶部的成功消息、当前页面([<Outlet />]),以及底部的错误区域。确认窗口在整个应用中只放置在这里一次。
10.4.9.2. src/components/PageTitle.tsx
[React] 19 会在页面头部([<head>])放入由组件渲染的任何 [<title>] 元素(示例 17)。每个页面显示 [<PageTitle titleKey="SCHEDULE.PAGE_TITLE" />]:标签页显示“Schedule - RdvMedecins”,并在语言变化时重新翻译。
10.4.9.3. src/components/NavBar.tsx
- 第 17–18 行:组件从会话 store 读取用户和登出函数;用户变化时(登录、登出、会话过期)它会被重新显示;
- 第 21–24 行:登出,然后转到登录页面。即使服务器没有响应,客户端也会忘记用户(见 [stores/session.ts]):错误被忽略([catch(() => {})]);
- 第 32–37 行:菜单取决于角色;
- 第 35 行:[NavLink] (示例 17)在当前显示页面的菜单上设置来自 [active] 的 [Bootstrap] 类;
- 第 59–64 行:FR / EN 按钮。[i18n.changeLanguage(l)]:不向服务器发送任何请求;整个页面在本地重新渲染。[aria-pressed]:屏幕阅读器会把当前语言按钮读作“已按下”;
- 第 67–73 行:角色、姓名和登出按钮。
10.4.9.4. src/components/SuccessMessage.tsx 和 ErrorPanel.tsx
两个小组件,显示来自 [useMessages] store 的消息,并翻译成当前语言。[role="status"] 和 [role="alert"]:屏幕阅读器在消息出现时就会朗读它——成功消息不打扰,错误消息则立即朗读。组件可以返回 [null] (或 [false]):这时它什么都不显示。
10.4.9.5. src/components/ConfirmDialog.tsx
示例 16 中的窗口,与确认 store 相连,并为键盘操作作了补充:
- 第 26–27 行:提出的问题([null]:窗口关闭)以及回答它的函数;
- 第 33–39 行:一个依赖 [open] 的副作用:窗口打开时,保留当前拥有焦点的元素(被点击的“删除”按钮),并把焦点交给“不,返回”按钮:不小心按下回车键不会删除任何东西。关闭时执行的副作用清理会把焦点还给所保留的元素;
- 第 41–43 行:窗口已关闭:没有什么需要显示。Hook 在这个 [return] 之前调用:每次显示窗口时,它们都必须以相同的顺序被调用;
- 第 45–60 行:Esc 表示“否”。Tab 和 Shift+Tab 把焦点保持在窗口内部:Tab 从最后一个按钮移到第一个按钮,反之亦然;否则,焦点就会移到后面变灰的页面上;
- 第 63–67 行:点击变灰的背景被视为“否”。[e.target] 是被点击的元素,而 [e.currentTarget] 是 持有处理函数的元素:如果点击发生在背景本身,而不是窗口内部,两者就相等;
- 第 69–94 行:[createPortal] (示例 16)把窗口显示在 [<body>] 的末尾,即页面之外:任何页面样式都无法使它变形;
- 第 72 行:对屏幕阅读器来说,这是一个要求紧急响应的窗口;[aria-labelledby] 和 [aria-describedby] 指向它的标题和问题。
10.4.9.6. src/components/InputField.tsx
一个完整的表单字段:标签、字段、帮助消息或错误消息。应用中的所有表单都使用它。
- 第 18–32 行:它的 props;[label]、[help] 和 [error] 是翻译用的 props(键);
- 第 34–37 行:解构 props,并带有默认值([type = 'text']);
- 第 39 行:帮助消息或错误消息的标识符,由 [aria-describedby] 把它与字段关联起来;屏幕阅读器会在读字段的同时读出它;
- 第 44–46 行:一个受控字段(示例 05):它的值属于父表单,父表单通过 [onChange] 接收它。[is-invalid]:来自 [Bootstrap] 的红框;
- 第 47–51 行:服务器返回的错误,否则显示帮助文本。
10.4.9.7. src/components/PersonFields.tsx
称谓、名和姓:三种表单(ADMIN 的医生或客户表单、账户创建、账户管理)共有的字段。相当于 HTML 应用中的局部视图 [views/partials/personFields.hbs] 。
- 第 20 行:[keyof Identity]:类型 ['title' | 'firstName' | 'lastName'];编译器会拒绝任何其他字段名;
- 第 31 行:没有 [<option>] [value] 的 option 以它的文本作为值。
10.4.9.8. src/components/CaptchaField.tsx
一个展示组件:图片、“换一张图片”按钮,以及由父表单控制的字段。图片及其标识符来自页面调用的 [useCaptcha] Hook:页面需要它们来发送答案。
- 第 32 行:SVG 图片被原样插入(示例 22)。在这里是安全的:它由我们的服务器生成,不含任何用户提供的内容。[role="img"] 和 [aria-label]:对屏幕阅读器来说,这是一张带说明的图片;
- 第 35 行:[autoCapitalize="off"] 和 [spellCheck={false}]:不自动大写(手机)、不拼写检查。
10.4.9.9. src/components/BookingDialog.tsx
预约窗口。它不与服务器通信:它带着所选患者调用 [onConfirm] ,或调用 [onClose];日程页面决定如何处理它。
- 第 21–28 行:[clients]:患者列表,供 ADMIN 和医生使用;[patient]:为自己预约的患者的姓名(对于 ADMIN 和医生为 [null] );
- 第 32 行:从列表中选中的患者;
- 第 35–41 行:在页面任何位置按 Esc 都会关闭窗口。副作用订阅文档的 [keydown] 事件,并在关闭时由其清理函数取消订阅。[globalThis.KeyboardEvent]:浏览器事件,而不是同名的 [React] 事件;
- 第 43–46 行:[preventDefault()] 阻止浏览器提交表单;
- 第 71–83 行:患者为自己预约:没有列表。无论如何,服务器都会忽略任何 [clientId];
- 第 78 行:[<option>] 的值始终是字符串:它被转换成数字;
- 第 89 行:没有列表时,确认按钮获得焦点。
10.4.10. 页面
10.4.10.1. src/pages/Login.tsx
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 | |
HTML 应用的 [views/login.hbs] 页面:登录名、密码、验证码(CAPTCHA),以及第二个“创建患者账户”按钮,它会先验证同一个验证码(CAPTCHA),然后才允许开始账户创建流程。
- 第 29–32 行:页面需要的东西:登录(会话存储)、清除消息、提交表单,以及验证码(CAPTCHA)(我们的两个 Hook);
- 第 35–36 行:[/login?login=jbernard]:创建账户之后,登录名会立即预先填好。[slice(0, 30)]:我们不会取超过登录名最大长度的内容。URL 只提供字段的初始值;
- 第 38–41 行:当输入字段时,它的新值会出现,任何错误消息随之消失。[[field]: value]:属性名是计算得出的属性;
- 第 45–52 行:两个按钮遵循相同的流程:提交,然后如果失败,就清空验证码(CAPTCHA)并加载一张新图片;每张图片只使用一次;
- 第 54–63 行:登录,然后转到下一个页面:
- 第 58 行:登录之前请求的页面,由路由器缓存([/login?redirect=/doctors]);
- 第 60 行:只允许内部路径:[/doctors],而不允许 [https://malicious-site.com] 或 [//malicious-site.com] (一个“省略协议”的地址,它指向另一个站点)。否则,像 [/login?redirect=https://...] 这样的恶意链接会把刚刚登录的用户送到另一个站点:这就是所谓的“开放重定向”漏洞;
- 第 61 行:否则,转到该角色的主页。[useSession.getState()]:用户刚刚被存入 store;而组件里的变量要到下次加载页面时才会改变;
- 第 65–70 行:第二个按钮:验证码(CAPTCHA)由服务器验证,服务器会为页面 [/register] 返回一个令牌(一个 Cookie);
- 第 84–85 行:[required]:只要字段为空,浏览器就拒绝提交表单。这是在浏览器中进行的唯一验证——它只是一项便利功能。[autoFocus]:焦点在登录名字段上,如果登录名已填写,则在密码字段上(第 90 行);
- 第 97 行:[type="submit"]:在字段中按回车会触发“登录”按钮;
- 第 101 行:[type="button"]:这个按钮不提交表单,因此会忽略 [required] 字段,这些字段在这里是不必要的。
10.4.10.2. src/pages/Schedule.tsx
应用中功能最丰富的页面。与 HTML 应用一样,它的全部状态都在 URL 中:
页面跟随 URL:它读取 URL 的参数,并据此决定显示什么;用户的操作则反过来修改 URL。这样你就可以重新加载页面、把它加入书签,并使用浏览器的后退和前进按钮。
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 | |
- 第 39–42 行:URL 的一个参数是由任何人输入的字符串;只保留正整数;
- 第 45–51 行:日程的 URL,带或不带预约窗口;
- 第 66–98 行:用于选择医生和日期的表单,是同一文件中的一个组件。它的状态只在提交之前使用:它用 URL 中的值填充(第 68–69 行)。然而,[useState(value)] 只在显示时使用它的值:如果 URL 改变(使用“后退”按钮),表单会保留之前的选择。因此页面在下方给它分配了 key;
- 第 114–120 行:URL 的参数。日期:如果 URL 中的日期有效就用它,否则用今天;
- 第 124–129 行:这些列表使用 [TanStack Query] (示例 24)。键 [['doctors']] 指向缓存中的数据:另一个请求同一个键的页面无需新的请求就能得到它。[enabled]:只为有权查看的人读取患者(预约窗口中的 ADMIN 和医生);对于患者,不会发送该请求;
- 第 133–138 行:日程。它的键包含医生和日期:当 URL 变化时,键随之变化,[TanStack Query] 会自行发送新的请求。如果 URL 中没有医生,已登录的医生看到的是他自己的日程;其他人什么也看不到;
- 第 141 行:显示的医生:URL 中的那位,否则是收到的日程中的那位;
- 第 145–149 行:URL 中的日期无效:显示一条消息。这是一个副作用:我们操作的是消息 store,而不是这个组件的显示。在显示进行期间,我们从不修改另一个状态;
- 第 153 行:预约窗口打开的那个时间段([?book=7]),仅当该用户可以预约它时才会打开:手工构造的 URL 不会打开任何东西;
- 第 162–164 行:“查看日程”会改变 URL;页面随之更新;
- 第 168 行:关闭窗口会返回日程的 URL。[useCallback]:两次显示之间保持同一个函数,因为预约窗口把它用在某个副作用的依赖项中(见 [BookingDialog.tsx]):如果每次显示都是一个新函数,副作用每次都会被触发;
- 第 172–173 行:以服务器的数据为准:每次操作之后,日程(以及显示患者预约的患者空间)都会被刷新。[TanStack Query] 会立即重新读取正在显示的数据;没有显示的数据会在下次使用时重新读取;
- 第 175–200 行:预约:
- 第 181 行:ADMIN 和医生发送所选的患者;患者为自己预约;
- 第 182 行:消息会在关闭窗口的导航动作之后出现;
- 第 184–188 行:没有选择患者:窗口保持打开,并显示消息。在 [return] [try] 中:[finally] 块无论如何都会执行;
- 第 194 行:其他错误(时间段已被占用、患者已有预约等)会在窗口关闭的状态下显示在日程上;
- 第 202–213 行:确认之后取消:[await confirm(...)] 等待用户的响应(见 [stores/confirmation.ts]);
- 第 218–272 行:主要内容,在 JSX 之前计算:等待消息、日程,或选择医生的提示。标准的 [if / else] 通常比在 JSX 中层层嵌套的 [? :] 更易读;
- 第 239–245 行:时间段的状态:可预约、患者的姓名(如果是已登录的患者则为蓝色),或“已预约”:患者不会收到其他患者的姓名;服务器不会发送它们;
- 第 250–254 行:“预约”是一个链接 [<Link>]:它在 URL 中添加 [&book=...] ,从而打开预约窗口;
- 第 255 行:“取消”,如果服务器指明用户可以取消这个预约;
- 第 277 行:表单的 key 包含医生和日期。当它们变化时,key 随之变化:[React] 销毁该表单并创建一个新的,新表单从新值开始。[React] 就是这样“重置”组件的;
- 第 281–285 行:已经有即将到来的预约的患者:这解释了为什么没有“预约”按钮;
- 第 290–293 行:只有当 URL 包含 [&book=...] 时,才会出现预约窗口。
10.4.10.3. src/pages/persons.config.ts
管理医生和客户的页面是完全相同的:同样的列表,同样的表单。与 HTML 应用(抽象类 [PersonsController])一样,它们只写一次;唯一变化的是 API 的地址(类型,['doctors'] 或 ['clients'])和标签键,它们在这里描述。
- 第 14–23 行:每种类型专属的翻译键;
- 第 25 行:[Record<PersonType, PersonKeys>]:每种类型恰好有一个属性的对象;[doctors] 和 [clients]:编译器会报告缺失的元素;
- 第 49–51 行:用于“已添加 / 已修改 / 已删除”消息的参数 [{{name}}] 和 [{{login}}] 。
10.4.10.4. src/pages/Persons.tsx
医生或客户的列表。类型以 prop 的形式传入(见 [routes.tsx])。
- 第 25 行:列表。它的键是类型:医生和客户各有自己的键。医生列表与日程列表是同一份数据(键 [['doctors']]):两者都受益于缓存;
- 第 27–40 行:确认之后删除,然后重新加载列表。仍有预约的医生不能被删除:服务器返回 409 响应,并在页面底部显示一条消息;
- 第 31 行:[getState()] 提供 store 的功能,而不让页面订阅消息:消息变化时无需重新加载页面;
- 第 44–81 行:内容:“加载中……”、“没有医生”或表格;
- 第 70 行:“编辑”是指向表单页面的链接。
10.4.10.5. src/pages/PersonForm.tsx
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 | |
同一个页面既用于创建([/doctors/add])也用于编辑([/doctors/3/edit]),由两个组件组成:
- 第 46–106 行:表单本身。它只在记录读取完成之后才显示,并以记录的值开始([useState(initial)]):无需在记录到达后再在副作用中复制它们:
- 第 55–58 行:输入字段,它的错误随之消失;
- 第 60–76 行:保存操作。对于更新,[form] 包含与记录一起读取的版本号:如果另一位 ADMIN 在此期间修改了它,服务器会返回 409 [ERRORS.CONCURRENT_UPDATE];
- 第 68–70 行:如果成功,列表就发生了变化:使它失效,然后带着消息返回列表;
- 第 71–75 行:记录在此期间已被删除:返回列表。其他错误仍显示在表单上;
- 第 84 行:[noValidate]:浏览器不验证 [required] 字段;由服务器验证,而服务器的验证才算数;
- 第 91 行:密码字段从不预先填充:服务器从不返回密码;
- 第 111–159 行:页面:
- 第 112 行:路由参数 [:id],新建时它不存在;
- 第 124–130 行:为编辑而读取记录。[gcTime: 0]:访问结束后不缓存该记录;下次访问会重新读取它,使其保持最新(否则表单会以过时的版本开始)。[meta: { errorHandled: true }]:读取错误在这里处理,而不是由通用处理函数处理(见 [main.tsx]);
- 第 133–138 行:记录不存在(在此期间已被删除、地址是手工输入的……):带着一条消息返回列表;
- 第 141–143 行:[/doctors/abc/edit]:这个地址不存在;
- 第 149–156 行:新建:空表单;编辑:记录读取完成后的表单。[login: p.login ?? '']:人员的登录名只发送给 ADMIN;它在 [Person] 类型中是可选的。
10.4.10.6. src/pages/Register.tsx
创建患者账户。只有在输入登录页面上的验证码(CAPTCHA)之后,你才能进入这里:服务器已签发了通行证,守卫已验证过它。
- 第 25 行:密码的最小长度,用于帮助消息(“至少 6 个字符。”)。服务器也会在错误 [ERRORS.PASSWORD_TOO_SHORT] 中返回它;
- 第 35 行:帮助消息和密码错误的参数:如果服务器有参数,则以服务器的参数为准;
- 第 42–58 行:创建账户:
- 第 52 行:如果成功,返回登录页面,并预先填好登录名;
- 第 53–57 行:令牌已过期(15 分钟):返回登录页面,重新输入验证码(CAPTCHA)。
10.4.10.7. src/pages/PatientArea.tsx
患者的主页:两个选项,“管理我的账户”和“查看日程”,以及他即将到来的预约,他可以取消该预约。
- 第 22 行:患者的空间。[queryFn: api.myArea]:直接传入函数本身,而不把它包在箭头函数中;它没有参数;
- 第 24–38 行:确认之后取消。空间和日程都已变化:两者都被置为失效;
- 第 41–48 行:只要空间尚未读取完成,就显示“加载中……”;
- 第 55–58 行:整张 [Bootstrap] 卡片是一个链接:[<Link>] 接受任何内容;
- 第 72–86 行:即将到来的预约。通常只有一个(“一次只能有一个即将到来的预约”规则),但页面可以显示多个;
- 第 79 行:指向医生当天日程的链接,患者在那里可以看到自己的姓名。
10.4.10.8. src/pages/MyAccount.tsx
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 | |
两个相互独立的表单,因此是两个组件,各有自己的状态和 [useFormSubmit] (两组错误):
- 第 30–90 行:修改身份信息、登录名,以及(可选的)密码:
- 第 35 行:表单以账户的值(包括它的版本号)开始,密码字段为空;
- 第 47 行:服务器已签发一个新令牌,带有新的姓名和新的登录名,并重定向用户:它被存入会话 store,导航栏随之更新;
- 第 53–58 行:提交被拒绝:密码绝不能留在字段中。我们不通过 [edit()] 而直接修改该值,以免清除服务器刚刚附加到该字段上的错误;
- 第 95–130 行:删除账户,同时也会取消它的预约:
- 第 99 行:只有一个字段的表单:一个字符串;
- 第 107–111 行:账户被删除,服务器已清除令牌 Cookie:客户端忘记用户,然后转到登录页面,并带上消息;
- 第 135–149 行:页面。[gcTime: 0]:每次访问都会重新读取账户;它的版本号必须是最新的。删除操作立即显示;修改操作则在账户读取完成之后显示。
10.4.10.9. src/pages/ErrorPage.tsx
错误页面:404(未知地址)或 403(权限不足)。[code: 403 | 404]:这个属性只能取这两个值。