11. 案例研究:RdvMedecins 应用的 Flutter 客户端
11.1. 问题
在这里,[RdvMedecins] 应用允许用户在医生诊所预约。[NestJS] 课程把它开发为一个 HTML 应用,由服务器生成页面;[Vue.js]、[Angular] 和 [React] 为它编写了 Web 客户端,这些客户端根据“RdvMedecins 服务器,一个黑盒”一章中介绍的服务器 JSON 数据,在浏览器中生成相同的页面。这里我们描述 [Flutter] 客户端:一个移动应用([Android]),也可以编译为 Web 版本。
客户端必须提供其他客户端提供的一切:
- 一个由验证码保护的登录屏幕,并可选择创建患者账户;
- 某位医生在指定日期的日程,支持预约(患者选择窗口)和取消;
- 对于管理员,管理医生和客户(列表、添加、编辑、删除);
- 对于患者,一个个人面板(显示即将到来的预约,可以取消)以及账户管理;
- 两种语言:法语和英语;
- 与 Web 客户端相同的地址([/schedule?doctorId=1&day=...])。在手机上,它们是不可见的,但用来组织应用;在 Web 上,用户可以重新加载它们、为它们添加书签,并使用浏览器的后退/前进按钮在应用中导航。
移动应用有其自身的要求:窄屏幕(没有五列的表格)、会遮住半个屏幕的键盘、返回按钮、密码管理器,以及没有用于存储令牌 Cookie 的浏览器。
11.2. 安装与运行
必须已安装并运行 JSON 服务器(参见“RdvMedecins 服务器:黑盒”一章)。你不需要 CAPTCHA 测试模式:可以将服务器上[CAPTCHA_TEST] 字段留空,位于[.env]文件中。
在打开到[rdvmedecins_flutter]文件夹的控制台窗口中:
第一条命令会向项目添加平台专用文件夹([android/]、[web/]),与各示例中的做法一样;它不会修改任何现有文件,随项目提供的[android/app/src/main/AndroidManifest.xml]文件(示例 22 中的那个)会被保留。然后,从以下命令中选择一条:
- 第一行在[Android]模拟器上启动应用([flutter devices]命令会列出可用设备)。模拟器通过地址[10.0.2.2:8080] 连接到服务器(参见示例 22);
- 第二行在通过 USB(需在其开发者选项中启用“USB 调试”)或 Wi-Fi 连接的真机上运行应用。手机和计算机必须位于同一网络;请输入计算机在该网络中的地址(在[ipconfig] 下,于[Windows]中)。[Windows] 上的防火墙必须允许 8080 端口的传入连接;
- 第三行在[Chrome]中运行,地址为 http://localhost:5173:[Flutter] 中的 Web 开发服务器会将 /api 请求转发到 JSON 服务器(文件[web_dev_config.yaml])。
演示账号列在登录界面上(密码 = 登录名)。应用运行期间,修改代码后,在控制台按[r]键会执行“热重载”;[R] 重启应用;[q] 停止应用。
11.3. 使用应用
本节的截图来自分辨率为 1080 × 2340 像素(412 × 891 dp)的手机。
11.3.1. 登录界面
登录界面;密码错误:消息显示在屏幕底部,并显示一张新图片(每张图片只使用一次):
![]() | ![]() |
11.3.2. 管理员和医生看到的日历
以[admin]身份登录后,你会进入日历。☰ 按钮会打开菜单:管理员可访问的界面,以及顶部显示的当前登录用户:
![]() | ![]() |
选择一位医生和一个日期(在日历中选择日期),然后点击“查看日程”。URL 变为[/schedule?doctorId=1&day=2026-10-05]。点击“预约”会打开预约窗口;URL 变为[/schedule?doctorId=1&day=2026-10-05&book=3]:
![]() | ![]() |
预约已保存;“取消”会要求确认:
![]() | ![]() |
医生登录后直接进入他本人今天的日程:

11.3.3. 患者门户
患者([martin])进入“我的空间”。在日历中,其他患者的时间段旁显示“已预约”,他可以为自己预约,而无需选择具体的患者:
![]() | ![]() | ![]() |
他的预约显示在他的名下;“预约”按钮不再可用(只允许一个即将到来的预约)。在另一位医生的日历中,由于他的预约不出现在其中,会有一条消息说明他为何无法预约。他的空间(“我的空间”)会显示该预约:
![]() | ![]() | ![]() |
“管理我的账号”:任何更改都需要当前密码;错误来自服务器:

患者的菜单中没有“医生”项。在 Web 上,如果患者自己输入地址 /doctors,路由器会显示 403 错误页面(参见[router.dart])。
11.3.4. 管理医生和客户
医生列表;一条填写不正确的记录:
![]() | ![]() |
添加成功;重名;删除有预约的医生被拒绝:
![]() | ![]() | ![]() |
11.3.5. 创建账号
在登录界面输入验证码(CAPTCHA),然后点击“创建患者账号”。表单被服务器拒绝;账号创建成功后,你会返回登录界面,并且登录信息已预先填好:
![]() | ![]() |
11.3.6. 法语界面;大屏幕
顶部栏中的 FR / EN 菜单会在本地重新渲染界面,不向服务器发出任何请求。在宽屏(Web、平板)上,菜单会一直显示在左侧:
![]() | ![]() |
11.3.7. 会话过期
如果令牌过期(或 Cookie 被删除),下一次请求会收到 401 响应;应用会重定向到登录界面:

11.4. 客户端架构
这是[Flutter]指南(“App architecture”)推荐的架构,这里做了更简单的说明:
- 一个数据层([api/]):唯一了解[http]包、URL 和 JSON 的层;
- 一个状态层([state/]):提供给整个应用的[ChangeNotifier]对象([provider]),由各界面监听;
- 一个界面层([pages/]、[widgets/]):显示状态并传递用户操作的组件(Widget)。
下表对比了[NestJS]课程中的 HTML 应用、[React]客户端以及本客户端:
HTML 应用(NestJS) | React 客户端 | Flutter 客户端 |
服务器渲染每个页面([res.render]) | 组件在浏览器中渲染页面 | 组件(Widget)在手机上渲染界面 |
[views/layout.hbs] 及其局部视图 | [Layout.tsx] 和各组件 | [layout.dart] (一个[ShellRoute])和各组件(Widget) |
控制器路由 | [React Router] | [go_router] |
[JwtAuthGuard]、[RolesGuard] | 路由守卫(中间件) | 路由器的[redirect]函数 |
令牌 Cookie,由浏览器存储 | 同上 | 管理 Cookie 的 HTTP 客户端(在手机上) |
Cookie 中的闪现消息 | 名为[Zustand]的存储 | 一个[ChangeNotifier],[Messages] |
由服务器读取的字典 | [i18next] | [Translations] (示例 21) |
语言存储在 Cookie 中 | 存储在[localStorage] | 存储在[shared_preferences] |
已读取的数据 | [TanStack Query] | [Cache] (几行代码) |
表单被拒绝:服务器重新加载页面 | 400/409 响应,错误显示在字段下方 | 同上 |
下面展示客户端的全部文件。它们都带有详尽的注释;这些注释是课程的一部分。
11.5. 项目配置
11.5.1. pubspec.yaml
示例中的各个库,除了[flutter_svg]……它被保留:验证码(CAPTCHA)是一张图片(SVG)。唯一的资源是字典和用于演示账号的等宽字体。
11.5.2. analysis_options.yaml
分析器的规则,与示例中的相同:
- 第 9 行:[Flutter]团队推荐的规则;
- 第 14–15 行:更严格的类型检查:[dynamic](例如[jsonDecode]返回的值)不能在不显式转换的情况下用作[String] ([as String],或使用[Dart] 3 的模式过滤);
- 第 20–24 行:三条格式规则。
[flutter analyze]命令会将这些规则应用于整个项目;[VS Code] 则在你输入时就应用它们。
11.5.3. web_dev_config.yaml
与示例 22 中的相同:在 Web 开发中,/api 请求会被发送到 JSON 服务器。
11.6. 启动应用
11.6.1. lib/config.dart
服务器地址,取决于平台(参见示例 22):
- 第 24 行:启动时由[--dart-define=SERVER=...]提供的值。[String.fromEnvironment] 在编译时求值:该地址被嵌入到构建出的应用中;
- 第 29–35 行:否则,在 Web 上使用相对地址(开发服务器,以及生产环境中的 JSON 服务器本身,同时提供页面和 API),在[10.0.2.2] 上,[Android] (从模拟器看到的计算机)使用该地址,其他情况使用[localhost] 。[static]:类变量,而非对象变量;不使用[final],以便测试可以修改它。
11.6.2. lib/main.dart
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 | |
- 第 37–44 行:在显示任何内容之前,先准备好需要准备的东西:不带[#] 的 Web 地址(示例 17)、所有语言的星期和月份名称([intl],示例 09)、设备存储,以及初始语言的字典。[WidgetsFlutterBinding.ensureInitialized()]:这些操作需要[Flutter]引擎,因此我们在[runApp]之前启动它;
- 第 58–63 行:共享对象,只创建一次,位于根组件(Widget)的状态中。每个对象在创建时接收它所需要的对象:这就是依赖注入,只不过是手动完成的。[late]:初始化发生在第一次使用时,此时[widget] 已经存在;
- 第 70–76 行:1. 会话过期。API 访问层既不了解会话,也不了解消息;它被交付一个函数,每收到一次 401 响应就调用该函数。用户被遗忘,缓存被清空,并为下一个界面准备好消息。界面跳转本身由路由器处理,它监视会话;
- 第 79 行:每当用户变化时,缓存就会被清空:为前一位用户读取的数据对下一位用户毫无用处(患者不应看到管理员查看过的日历);
- 第 81–88 行:2. 闪现消息。路由器的[routerDelegate] 在每次传递时通知其监听者;将地址与前一个地址进行比较([_router.state]:栈顶部的界面,包括由[push]压入的界面,例如预约窗口),如果地址已改变,系统就进入“新页面”:前一个界面的消息消失,放在这个界面上的消息出现(参见[messages.dart]);
- 第 99–107 行:共享对象提供给所有界面(示例 20)。[.value]:对象已经存在;provider 不创建它(也不会销毁它);
- 第 109–118 行:应用本身,每次语言变化都会重新构建([Consumer],参见示例 20):标题([onGenerateTitle]),以及[Flutter] 自身文本(日历、工具提示)的语言。[colorSchemeSeed]:[Material] 由这一种颜色推导出整个调色板;这是[Bootstrap]的蓝色,即 Web 客户端使用的颜色。
11.7. API 访问层
11.7.1. lib/api/http_client.dart
示例 23 中的 HTTP 客户端,未做改动:在手机上,它存储收到的 Cookie([Set-Cookie]头)并将其发回([Cookie]头);在 Web 上,则交由浏览器处理。
11.7.2. lib/api/api_client.dart
示例中的[common/api.dart]文件,增加了一个新特性:401 响应。
- 第 29 行:一个在发生 401 错误时调用的函数,在启动时指定(参见[main.dart])。默认情况下它什么也不做;
- 第 34 行:[isPublic] 是一个命名可选参数(用花括号括起):[request('GET', '/captcha', isPublic: true)];
- 第 35–38 行:请求被逐步构建:方法、地址、头和 JSON 请求体;
- 第 40–45 行:发送请求。这里出现异常意味着没有收到响应(网络中断、服务器宕机、地址不正确)。[final http.Response response;]:一个[final] 变量,声明时没有赋值;[Dart] 会检查它在被读取之前恰好获得一次值;
- 第 47–54 行:错误响应会变成一个 [ApiError]。对受保护请求返回 401 意味着会话已过期:调用[onSessionExpired],然后无论如何都会抛出一个错误(等待该响应的界面必须知道响应没有到达),使用的键是[ERRORS.SESSION_EXPIRED]:如果该界面显示这个错误,则它是同一条消息;
- 第 56 行:没有响应体的响应(204)得到[null]。我们将字节解码为 UTF-8:如果没有[charset]头,[http] 包会将 [response.body] 按 Latin-1 解码,重音字符就会损坏。
11.7.3. lib/api/api_error.dart
示例 24 中的那个:任何失败的请求最终都会得到一个 [ApiError],它包含消息的翻译键、其参数以及每个字段的错误。
11.7.4. lib/api/types.dart
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 | |
API 的 JSON 对象,表示为[Dart]类(参见示例 24):
- 第 14 行:一个永远不会正常结束的函数(它会抛出异常):其返回类型为[Never]。因此它可以作为任意类型的[switch] 的最后一个分支;
- 第 24–30 行:对[Map]进行模式过滤:如果 JSON 至少包含这三个键,且值具有这些类型,则该分支适用,这些值顺带存入变量;
- 第 69–88 行:医生或客户:一个 [Identity],加上一个标识符、一个版本号 (乐观锁:修改时会将它回传),以及一个登录名,只有 ADMIN 才会收到它(因此用方括号表示可选参数);
- 第 109–114 行:日历中的一项,显示由服务器计算出的已登录用户的权限:[patient] 只显示给有权查看的人,[bookable] 表示用户是否可以预约;[appointmentId] 只提供给可以取消的人;
- 第 129–151 行:首先读取时间段本身([Slot.fromJson]),然后读取其特有字段;
- 第 209–213 行:已登录患者的账号:其身份、登录名和版本号。[super.title]:该参数原样传递给父类构造函数。
11.7.5. lib/api/rdvmedecins_api.dart
每个 API 路由对应一个方法:这是示例 24 中的[RdvMedecins]类,经过了扩充。
- 第 19 行:[/api/doctors] 和[/api/clients] 的处理方式相同:使用一个枚举,每个值的名称([PersonType.doctors.name],“doctors”)就是路由的名称;
- 第 21 行:一个类型别名:为现有类型起一个更具描述性的名称;
- 第 33–47 行:登录相关的路由,它们是公开的:401 在这里有其特定的含义(“没有人登录”“密码错误”),并不表示会话已过期;
- 第 53 行:账号创建令牌是否有效?对响应使用[switch] 表达式:[true] 仅当响应为[{"valid": true}]时;
- 第 65–67 行:地址参数,由[Uri] 构造(它会对参数编码)。['doctorId': ?doctorId?.toString()]:可选的[Map] 元素([Dart] 3.8):只有当值不为[null]时才会添加该键。已登录的医生请求日历时不带[doctorId]:服务器会返回该医生自己的日历;
- 第 71 行:类似地,只有在已知时才会发送[clientId] (患者为自己预约);
- 第 76–86 行:涉及医生或客户的五个操作:[/api/${type.name}];
- 第 89–97 行:患者的空间。删除账号时,会随[DELETE]请求发送消息体(当前密码):HTTP 允许这样做,[http]包也允许,方法是手动构造一个[http.Request] (参见[api_client.dart])。
11.8. 语言
11.8.1. lib/i18n/translations.dart
示例 21 中的[Translations]类,经过简化:字典的命名始终遵循同一规则([assets/i18n/fr.json])。
- 第 35–38 行:初始语言:上次使用时选择的语言,否则是手机的语言(如果应用支持),再否则是英语。[platformDispatcher.locale]:系统语言;
- 第 59–76 行:键的翻译,包括复数([_zero]、[_one]、[_other])和参数([{{name}}]),遵循[i18next]的约定,这些约定与其他客户端的字典所用的相同。
11.8.2. 字典
这些字典来自[React]客户端,并补充了几个移动应用特有的键(“我的账号”菜单、“选择日期”等)。法语字典的开头部分:
每种语言一个文件,每个文件中的键相同;每个界面一组键;[ERRORS.*]键是服务器返回的那些键。
11.9. 共享状态
三个[ChangeNotifier] 对象,由[main.dart]提供给整个应用。
11.9.1. lib/state/session.dart
谁已登录?会话存储的是用户的描述信息(登录名、姓名、角色),而不是令牌,令牌保留在用户的 Cookie 中。
- 第 36–38 行:“谁已登录?”这个问题只会在启动时向服务器发送一次([GET /api/auth/me]):[??=] 只有在 [_checking] 为 [null] 时才会赋值 [Future]。之后的调用返回同一个[Future],它已经完成:路由器可以在每次导航前[check()] 调用它而没有任何开销。启动时,如果存储的 Cookie 中包含仍然有效的令牌,用户就保持登录状态;
- 第 41–42 行:登录:如果服务器拒绝,[_api.logIn] 会抛出 [ApiError],而 [_change] 不会被调用;
- 第 48–52 行:登出:即使服务器没有响应,用户也会被遗忘([finally]);
- 第 61–64 行:所有变更都经由这里,并通知监听者:显示用户的界面(布局)、缓存(它会被清空)以及路由器(它会重新评估其守卫)。[_voluntaryLogout] 用于区分主动登出和会话过期(参见[router.dart]);
- 第 69–75 行:扩展为现有类型添加 getter,这里是为[User?]:[session.user.isAdmin] 在没有人登录时为[false] ,无需事先检查[null] ([this?.role])。
11.9.2. lib/state/messages.dart
应用消息:成功消息显示在屏幕顶部,错误消息显示在底部(参见[layout.dart])。
- 第 21 行:一条消息就是一个翻译键及其参数(一个 record)。它只在显示时才被翻译:切换语言会重新翻译已显示的消息;
- 第 44–46 行:[ApiError] 会成为界面的错误消息。任何其他异常都是客户端自身的问题:我们重新抛出它,使其在开发期间出现在控制台中,而不是将其隐藏;
- 第 56–60 行:给下一个界面的消息:以界面切换结束的操作(预约、添加等)把它的消息放在这里;
- 第 66–71 行:每当地址变化时调用(参见[main.dart]):前一个界面的消息消失,闪现消息出现。
11.9.3. lib/state/cache.dart
已从服务器读取的数据:用几行代码实现,相当于[React]客户端中的[TanStack Query] 。
- 第 24 行:缓存存储的是[Future],而不是实际的值:两个界面在数据还在传输途中时请求同一份数据,会收到同一个 [Future],因此只会发送一次请求;
- 第 26–33 行:一个泛型方法:[read<List<Person>>(...)] 返回一个 [Future<List<Person>>] (类型[T] 大多由函数[load]推断得出)。[putIfAbsent]:返回该键的值,如果键不存在,则返回函数的结果,并将其存储在该键下。读取失败会被忽略:下一次请求会重试;
- 第 37–39 行:修改之后,受影响的键会被丢弃,并通知各界面。日历界面监听这一点:预约之后,它会重新加载自己,即使它被隐藏在预约窗口后面;
- 第 44 行:当用户变化时,所有内容都会被清空,且不通知任何人:前一位用户的界面会消失,它们没有什么需要重新加载的。
11.10. 格式化
11.10.1. lib/formatting.dart
格式化来自服务器的原始数据(参见示例 09):
- 第 22 行:API 格式的[DateTime] (“2026-10-05”);
- 第 27–30 行:地址中的日期是否有效?[DateTime.tryParse] 会接受“2026-02-30”(即 3 月 2 日):我们验证重新格式化后得到的字符串与原字符串相同;
- 第 34 行:“Monday, October 5, 2026”或“lundi 5 octobre 2026”,取决于语言([DateFormat.yMMMMEEEEd] 源自[intl])。
11.11. 路由器
11.11.1. lib/router.dart
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 | |
应用的各个界面、它们的地址及其访问权限(参见示例 17 和 18)。
- 第 40 行:界面的访问权限:公开,或仅限某些角色([null]:所有角色);
- 第 42–47 行:每个地址的权限;只集中在一个地方:一个[switch] 字符串表达式。['/login' || '/register']:一个“或”模式;[_ when ...]:一个“任意值”模式,带有条件(一个守卫);
- 第 51 行:只有当地址[?redirect=] 是内部路径时才会跟随:在 Web 上,通过电子邮件发送的地址[/login?redirect=//pirate-site.com] 不能在用户登录后把他们带到别的网站;
- 第 54–56 行:地址的参数是字符串,任何人都可以写入(在 Web 上):“abc”或“-2”会变成[null];
- 第 61–78 行:一个局部函数,为医生或客户生成三条路由:[/doctors], [/doctors/add], [/doctors/:id/edit]。[:id]:一个路径参数,通过[state.pathParameters['id']]读取;
- 第 81 行:手机上的初始界面(在 Web 上,则是输入的地址);
- 第 84 行:路由器监视会话:每次变化(登录、登出、过期)时,它都会针对当前界面重新评估其守卫,必要时切换界面;
- 第 85–109 行:那个守卫,在每次导航之前调用:
- 第 86 行:第一次时,我们等待服务器对“谁已登录?”这个问题的响应;此后,该调用不再有任何开销;
- 第 90–98 行:公开界面对所有人开放;但是,已登录的用户没有理由停留在登录界面:他们会前往登录前请求的界面,或其角色的主页。应用就是这样在登录成功后离开登录界面的:登录界面本身不需要进行导航;
- 第 100–105 行:没有人登录:转到登录界面。会话过期后,或者直接打开了受保护的 URL(在 Web 上)时,所请求的界面([?redirect=])会被保留,以便用户登录后可以回到该界面;主动登出之后则不保留;
- 第 107–108 行:[/] 指向角色的主页;角色权限不足则指向 403 页面;
- 第 112–113 行:所有界面都显示在布局之内(顶部栏、菜单、消息);
- 第 117–121 行:[/login?login=jbernard] (创建账号之后)会预先填好登录名字段;
- 第 125–129 行:从 URL 读取的三个日历参数;整个界面的状态都存在于其中(参见[schedule.dart]);
- 第 135–142 行:某条路由专有的守卫:创建账号需要一张通行证,由服务器在验证码(CAPTCHA)输入后签发([POST /api/register/access],参见登录界面)。没有通行证,就会被重定向到登录界面并显示一条消息;
- 第 153 行:未映射到任何路由的地址:404 页面,显示在布局中。
这些防护措施只是形式上的:它们防止显示无用的界面。数据保护由服务器保证,服务器在每次请求时都会重新验证令牌和角色。
11.12. 组件(Widget)
11.12.1. lib/widgets/layout.dart
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 | |
布局,即 [ShellRoute] 的组件(Widget):包围所有界面的元素。
- 第 26 行:一个菜单项:一个 record;
- 第 28–38 行:用户角色所允许的菜单项,通过列表中的 [if] 实现(示例 03)。[...[...]]:展开运算符一次插入多个元素;
- 第 55 行:当前地址,用于标记活动的菜单项;
- 第 58 行:屏幕宽度,单位为点。超过 800 点(Web、横屏的平板)时,菜单会一直显示;
- 第 61 行:登出——会话被清除,正在监听此变化的路由器会显示登录界面。[catchError]:即使服务器没有响应,用户也被视为已登出;
- 第 63–68 行:顶部是成功消息,中间是界面([Expanded]:占据所有剩余空间),底部是错误消息;
- 第 73–89 行:顶部栏:标题、语言菜单([PopupMenuButton]:打开一个列表的按钮;这里它的图标是文本,“FR”或“EN”)、登出按钮;
- 第 93–113 行:在小屏幕上,使用一个抽屉 ([NavigationDrawer]),通过[Scaffold] 自动添加到顶部栏的 ☰ 按钮打开。点击某一项会关闭抽屉([Navigator.pop])并改变 URL;
- 第 116–129 行:在大屏幕上,使用一个[NavigationRail]:菜单排成一列,位于内容的左侧;
- 第 137–154 行:成功消息。[context.watch<Messages>()]:每当消息变化时,该组件(Widget)都会重新构建;没有消息时,它不占用任何空间([SizedBox.shrink]);
- 第 168–169 行:错误区域位于屏幕底部:[SafeArea] 使其与手机的导航栏([Android]的按钮或手势条)保持分隔。
11.12.2. lib/widgets/page_title.dart
界面标题,已翻译([Title],参见示例 02):在 Web 上是标签页标题,在[Android]上是最近使用的应用列表中的应用名称。
11.12.3. lib/widgets/form_submit.dart
向服务器提交表单:示例 23 中的[Command] ,并补充了字段错误(示例 25)。
- 第 34–50 行:提交:不允许重复提交;提交期间,[submitting] (按钮被禁用);出现 [ApiError]时,会显示屏幕底部的通用消息以及每个字段的错误。[finally] 在所有情况下都会运行,即使在[return]之后;
- 第 55–57 行:用户修正某个字段;错误随之消失。我们用副本替换[Map] ,而不是修改它:旧的可能是服务器提供的([e.fields]),而常量[Map] ([const {}])是不可更改的。
11.12.4. lib/widgets/input_field.dart
一个完整的表单字段:标签、输入框、帮助文本或错误消息。所有表单都使用它。
- 第 22–32 行:参数。标签、帮助文本和错误消息都是翻译键;
- 第 53–58 行:一个受控组件(Widget)(示例 11):值属于父组件。如果父组件自己修改了它(验证码在失败后被清空),[didUpdateWidget] 会把它复制回输入框;
- 第 75–79 行:密码会被遮盖,拼写检查器不会干扰;[autofillHints] 告诉手机的密码管理器该字段包含什么内容(用户名、密码、新密码);
- 第 80–86 行:标签、错误消息(它会取代帮助文本)以及帮助文本。[maxLength] 会限制输入,并会在字段下方显示一个计数器(“3/20”);[counterText: ''] 将其隐藏。
11.12.5. lib/widgets/person_fields.dart
身份字段(称谓、名、姓),为 ADMIN 表单、账号创建表单和“管理我的账号”表单所共用。
- 第 21 行:父组件传入值、错误以及一个用于修改任意字段的函数;
- 第 33–42 行:称谓,使用下拉列表,带有标签和错误消息,与输入字段类似。[initialValue] 只在字段创建时读取;如果值通过代码发生变化,键([ValueKey])会使它重新创建。
11.12.6. lib/widgets/captcha_field.dart
CAPTCHA 图片、“换一张图片”按钮和输入框。该组件(Widget)不调用服务器:由登录界面请求图片,因为它需要图片的标识符来发送答案。
- 第 51–53 行:SVG 图片,以文本形式接收([SvgPicture.string],示例 22)。[Semantics]:屏幕阅读器朗读的内容([TalkBack] ,来自[Android]),用来代替图片。
11.12.7. lib/widgets/confirmation.dart
示例 16 中的确认窗口,已翻译:[if (await confirm(context, 'SCHEDULE.CANCEL_CONFIRM')) ...]。焦点在“否”上([autofocus]):在 Web 上,不小心按下 Enter 键也不会删除任何东西。
11.12.8. lib/widgets/booking_dialog.dart
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 | |
时间段预约窗口。它不是由 [showDialog]打开的:它是日历界面的一部分,当地址要求时由日历界面显示它([&book=7])。
- 第 23–28 行:该组件(Widget)不与服务器通信;它接收要显示的数据,以及两个函数,分别在确认(带上所选患者)或关闭时调用;
- 第 51–54 行:[Stack] 将其子组件叠放:首先是一个[ModalBarrier]——背景变灰——它覆盖整个屏幕,并拦截发往日历的点击(点击会关闭窗口),然后是窗口本身,居中显示;
- 第 70–91 行:患者为自己预约:显示其姓名,没有列表。ADMIN 或医生则从下拉列表中选择患者;所选的患者决定窗口的状态;
- 第 95–102 行:按钮([OverflowBar]:并排显示,放不下时则上下排列);提交期间“确认”按钮被禁用。
11.13. 界面
11.13.1. lib/pages/login.dart
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 | |
登录界面。
- 第 39–43 行:状态:API 访问层和消息(只读取一次,[late]:首次使用时)、表单提交、数据输入(一个[Map]:字段名 -> 值),以及收到的 CAPTCHA;
- 第 59–66 行:新图片,在界面打开时、应请求时,以及每次尝试之后(一张图片只使用一次);
- 第 76–81 行:两个按钮都遵循这一流程:提交,然后,如果失败,则清空 CAPTCHA 并显示一张新图片;
- 第 86–93 行:登录。如果成功,界面不再做任何其他事情:会话发生变化,正在监听它的路由器会离开登录界面(参见[router.dart]);
- 第 95–97 行:“创建患者账号”:服务器验证 CAPTCHA 并签发一个令牌(一个 Cookie);随后打开账号创建界面;
- 第 105–106 行:提交状态变化时(进行中、出错),界面会重新加载;
- 第 113–129 行:[AutofillGroup] 将用户名和密码组合在一起:手机的密码管理器会一并填写它们,并在登录后提示保存该账号;
- 第 163–195 行:演示账号。[for (final (accounts, roleKey) in [...])]:对一个 record 列表的循环,循环过程中会对它们进行解构(示例 03)。
11.13.2. lib/pages/schedule.dart
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 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 | |
功能最丰富的界面:选择医生和日期、日历以及预约窗口。
- 第 40–43 行:日历的地址。界面的全部状态都包含在其地址中;用户操作会改变地址,界面再根据地址决定显示什么;
- 第 66–67 行:地址中的日期(如果有效);否则为今天;
- 第 70–87 行:界面打开时:医生(来自缓存——整个会话期间只加载一次)、患者(如果用户有权查看,用于预约窗口)以及日历。如果地址中的日期无效:会在界面构建完成之后显示一条消息([addPostFrameCallback]:在界面构建期间不修改其他状态)。最后,界面从缓存中读取;
- 第 98–100 行:“查看日程”会改变地址;路由器会用新参数复用该界面(同一路由):[didUpdateWidget] 随后重新读取日历;
- 第 103–114 行:缓存读取日程。如果地址中没有指定医生,已登录的医生会看到他自己的日程(服务器通过令牌获取);
- 第 120–122 行:预约或取消之后,服务器的数据优先:日历(以及患者的空间)被置为失效;缓存通知各日历界面,它们随即重新加载;
- 第 125–129 行:关闭窗口:返回前一个 URL。“预约”通过压栈推入了带有 [&book=] 的 URL ([context.push]):现在将其回退([context.pop]),与手机的返回按钮的效果完全相同。如果界面是直接在该地址打开的(在 Web 上),就没有可回退的内容:此时转到日历地址;
- 第 133–153 行:预约时间段。如果没有选择患者,窗口保持打开并显示消息。其他任何操作都会关闭窗口,消息(成功或错误——例如该时间段在此期间已被占用……)会作为弹出消息显示在日历上。包含窗口的日历界面消失;下面的那个界面重新出现,这得益于缓存;
- 第 156–164 行:确认之后取消;
- 第 176–184 行:界面显示日历([FutureBuilder])。预约窗口中的时间段是地址中的那个([&book=7]),仅当该时间段可由该用户预约时才显示(时间段在此期间已被占用、手动构造的地址:不显示窗口);
- 第 189 行:服务器会把这条消息([info])连同所有日历一起发送;但是在包含该患者预约的日历中(时间段 [mine]),这条消息是不必要的——在刚预约之后甚至会造成误导:患者看到自己的预约列在其名下,并带有“取消”按钮。因此,它只显示在其他日历中。[s.slots.any((c) => c.mine)]:只要至少有一个时间段满足条件,就为 true;
- 第 201–202 行:“预约”推入窗口的地址;
- 第 215–222 行:选择医生和日期。它的键包含 URL 中的医生和日期:当 URL 改变时(手机的返回按钮、浏览器的后退按钮),[Flutter] 会重新创建该组件(Widget),它会用新的值重新开始;
- 第 226–233 行:已有即将到来的预约的患者:为什么没有“预约”按钮(参见上文的[info]);
- 第 241–248 行:预约窗口,位于日历之上(在[Stack]中);
- 第 280–291 行:选择医生和日期:一个简短的表单,其状态以地址中的值开始。[late int? _doctorId = widget.doctorId;]:一个从[widget]初始化的字段,这要归功于[late]。[showDatePicker] 会以应用的语言打开来自[Material] 的日历;
- 第 319–326 行:日期显示为一个输入字段([InputDecorator]:字段的标签和边框,可包裹任何组件),点击它即可打开日历;
- 第 346–406 行:日程。每个时间段一行:时间、一个标签(自定义文本、患者姓名,或对其他患者显示“已预约”),以及由服务器启用的按钮([bookable]、[appointmentId])。
11.13.3. lib/pages/persons_config.dart
医生界面和客户界面是相同的;只有标签键不同,这里对它们作了说明。
- 第 13–22 行:一个带命名字段的 record,包含某一类人员的键;
- 第 25–37 行:对枚举的表达式:[Dart] 确保所有情况都得到处理。向[PersonType] 添加一个值会在这里引发编译错误;
- 第 51 行:“已添加”“已修改”和“已删除”消息的参数。
11.13.4. lib/pages/persons.dart
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 | |
医生或客户的列表。
- 第 54–59 行:列表,来自缓存。请注意[setState(() { ... })]中的花括号:如果写成箭头形式,[setState(() => _list = ...)],该函数就会返回被赋的值,这里是一个[Future],而[setState] 会拒绝返回[Future] 的函数(状态更新必须是同步的):[Flutter] 会以一个错误来提示这一点;
- 第 62–73 行:确认之后删除。有预约的医生会被服务器拒绝(409 [DOCTOR_HAS_APPOINTMENTS]);
- 第 84–88 行:一个[Scaffold] 嵌套在布局的 [Scaffold]之内,用于放置右下角的悬浮“+ 添加”按钮([FloatingActionButton]);
- 第 107–124 行:每个人员一个列表项([ListTile]):带姓名首字母的头像、姓名、用户名和两个按钮。像 Web 客户端那样的五列表格在手机上放不下。
11.13.5. lib/pages/person_form.dart
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 | |
添加或修改医生或客户。
- 第 54–65 行:要进行修改,需要读取该记录;不使用缓存:其版本号必须是最新的。如果找不到记录(在此期间被删除):返回列表并显示一条消息;
- 第 78–92 行:表单只有在记录读取之后才显示,并以其值开始;用户之后无需再重新输入它们;
- 第 117 行:初始值的可修改副本([...]:展开运算符,位于[Map]之中);
- 第 132–149 行:保存记录:[POST] 或[PUT],取决于是否有标识符。成功消息是一条闪现消息:它会出现在列表上。如果记录在此期间被另一位 ADMIN 删除:返回列表;
- 第 167–184 行:用户名和密码,创建和修改时使用不同的帮助消息(密码字段留空则不更改密码)。密码从不预先填入:服务器永远不会返回它。
11.13.6. lib/pages/register.dart
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 | |
创建患者账号,凭登录界面签发的通行证访问(参见 [router.dart] 中该路由的守卫)。
- 第 25 行:密码的最小长度;用于帮助消息:与服务器使用相同的值(服务器也会随错误[PASSWORD_TOO_SHORT]一起返回它);
- 第 57–69 行:创建。成功:返回登录界面,用户名已预先填好([/login?login=...]),并显示一条弹出消息。因通行证已过期(15 分钟)而失败:返回 CAPTCHA。其他任何错误都会一直显示在字段下方;
- 第 77 行:帮助消息和密码错误的参数([{{min}}]);
- 第 98–109 行:一个新账号:密码管理器可以建议一个强密码并保存它。
11.13.7. lib/pages/patient_area.dart
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 | |
患者的主界面:两个选项,以及他们即将到来的预约。
- 第 52–63 行:取消预约:该空间和各日程都发生了变化;
- 第 109–127 行:预约,以及两个按钮:查看医生当天的日程(患者在其中会看到自己的姓名)、取消;
- 第 150–166 行:一个选项:点击后打开某个界面的卡片。
11.13.8. lib/pages/my_account.dart
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 | |
“管理我的账号”:两个相互独立的表单,各自带有自己的[FormSubmit]。
- 第 38 行:账号,每次访问都重新加载,不使用缓存(其版本号必须是最新的);
- 第 100–117 行:修改。服务器返回更新后的用户(以及其 Cookie 中的新令牌):会话随之更新,菜单中显示的姓名也相应更新。被拒绝之后,字段中的当前密码会被清空;
- 第 207–216 行:确认之后删除账号。首先是消息(一条弹出消息);然后会话被清除,路由器显示登录界面,并附带该消息。
11.13.9. lib/pages/error_page.dart
错误页面:404(未知地址)或 403(角色权限不足)。“返回主页”指向[/],路由器会将其重定向到该角色的主页。






















