5. 第 4 章 - RdvMedecins 应用的 Flutter 客户端
5.1. 架构概览

该客户端与本课程的 [rdvmedecins-nestjs-server] 服务器通信——该服务器保持完全不变——使用已有文档中记录的相同 HTTP 路由(POST [/login]、GET [/getAllDoctors]、GET [/getAllClients]、GET [/getDoctorScheduleOfDay/:doctorId/:day]、POST [/addAppointment]、POST [/deleteAppointment]),使用相同的 JSON 信封 [{ status, data }] 以及相同的基于令牌的身份验证 [JWT](请求头 [Authorization: Bearer <token>])。对于这个变体,整体架构增加了第三个组成部分:根据所选的编译目标(参见第 5 章),执行客户端的不再仅仅是浏览器,而可能是直接执行编译后的 [Dart] 代码的移动操作系统或桌面操作系统——而 [NestJS] 服务器无论面对哪种目标,处理的仍然只是相同的 HTTP 请求。
5.2. 项目目录结构

| rdvmedecins_flutter_client/
├── pubspec.yaml project configuration (dependencies, assets)
├── assets/
│ └── i18n/ translation dictionaries (fr.json, en.json)
└── lib/
├── main.dart entry point (builds the services, provides them, starts the app)
├── app.dart root widget (conductor + authentication guard)
├── core/
│ ├── models/ data classes (mirror of the JSON exchanged with the server)
│ ├── services/ SettingsService, AuthService, AppointmentService
│ ├── http/ AuthHttpClient (JWT token + logout on 401)
│ └── i18n/ TranslationsService (French/English)
└── features/ one widget per feature, including the login screen
|
该目录结构与本课程中 [Vue.js] 客户端的目录结构逐个文件夹一一对应([core/models]、[core/composables] -> [core/services]、[core/interceptors] -> [core/http]、[features/] 保持不变)——这是有意为之的选择:应用的组织方式在大多数情况下并不特定于某个具体的 UI 框架。
5.3. 项目配置文件
5.3.1. pubspec.yaml
| name: rdvmedecins_flutter_client
description: >
Flutter client (mobile, desktop and web from one and the same source code)
for the RdvMedecins application - NestJS / Flutter port of this course.
publish_to: 'none'
version: 1.0.0+1
environment:
sdk: '>=3.4.0 <4.0.0'
flutter: '>=3.24.0'
dependencies:
flutter:
sdk: flutter
# http:Dart 生态官方的“低层”HTTP 客户端——严格等价于
# Vue.js 端使用的 fetch()(auth.interceptor.ts、
# appointment.service.ts)。Flutter 语言本身没有内置 fetch():由这个
# 库来取而代之。
http: ^1.2.2
# provider:向整棵 Flutter 组件(Widget)树暴露共享状态的最常用方式——
# 正是 Vue.js 端 provide()/inject() 所起的作用
# (settings.composable.ts、auth.composable.ts、
# language.composable.ts)。详见“Flutter 入门”一章
# 中的对应关系说明。
provider: ^6.1.2
# shared_preferences:持久化键/值存储,在移动端、桌面端和 Web 端
# 以相同方式可用——相当于 localStorage 的跨平台版本
# (而 localStorage 只存在于浏览器中)。
shared_preferences: ^2.3.2
# intl:日期格式化(yyyy-MM-dd,见 DoctorDayPicker)——作用与
# Vue.js/TypeScript 端的 Date.toISOString().slice(0, 10) 相同,但
# 是显式的,而不是简单的字符串截取。
intl: ^0.19.0
dev_dependencies:
flutter_test:
sdk: flutter
flutter_lints: ^4.0.0
flutter:
uses-material-design: true
# the translation dictionaries - the equivalent of public/i18n/*.json 文件,在
# Vue.js 端是由 Web 服务器提供的,而这里是嵌入到应用包中,
# 而不是由 Web 服务器提供(这一差异的原因见“移植应用”一章,
# 它恰恰涉及 3 个目标环境)。
assets:
- assets/i18n/
|
我们来逐段讲解这段代码:
- 第 9–10 行:[sdk: '>=3.4.0 <4.0.0'] / [flutter: '>=3.24.0'] ——相当于 [engines] 字段在 [package.json] [Node.js] 中的作用:本项目所需的 [Dart] 语言和 SDK [Flutter] 版本范围。
- 第 16–20、22–27、29–32、34–37 行:该客户端的四个依赖项,每个都在原位标注了其 [Vue.js] 对应项——另请参见引言中的“所用工具”一节。
- 第 42 行:[flutter_lints: ^4.0.0]——相当于 [Dart] 中的 [ESLint]:一组由 [flutter analyze] 检查的风格/质量规则,本课程先前的 Web 客户端中没有它,但它由 [flutter create] 自动生成。
- 第 51–52 行:[assets: - assets/i18n/] ——显式声明 [assets/i18n/] 中的所有内容都必须嵌入应用包中;没有这一声明,[rootBundle.loadString(...)](参见下文的 [core/i18n/translations_service.dart] )在运行时就会失败——在执行 [flutter build] 时磁盘上存在的文件不会自动包含在最终的包中,这不同于 [public/] 在 [Vite]/[Vue.js] 中的情形,后者无需事先声明就会原样提供服务。
5.4. 启动应用

5.4.1. lib/main.dart
移植自 [src/main.ts] ([Vue.js] 客户端):构建该客户端的各个服务,通过 [provider] 使它们对整个组件树可用,然后启动应用。
| // =========================================================================
// main.dart
// -------------------------------------------------------------------------
// Flutter 客户端的入口点。相当于本课程 Vue.js 客户端侧的 src/main.ts:
// 此文件显式启动应用
// (此处为 runApp(...);Vue.js 端为 createApp(...).mount(...))并
// 对其进行配置。
//
// Vue.js 通过直接在应用实例上调用 app.provide(key, value) 来配置应用,
// 而 Flutter/provider 使用
// 一个组件(Widget) MultiProvider,放在树的根部(见下方的 runApp(...)):
// 其中包含的每个 ChangeNotifierProvider/Provider 都让
// 一个实例对其包裹的整个子树可用,
// 正如 app.provide(...) 对所有后代组件所做的那样——
// 思路相同,只是表达为组件(Widget),而不是命令式的
// 方法调用,因为在 Flutter 中一切皆为组件(Widget)(包括
// 共享状态的配置)。
//
// 构造的顺序依然重要,原因与 Vue.js 端相同:
// AuthService(settings) 需要 settings 已存在
// (以读取 apiBaseUrl);AppointmentService 需要 authHttp 和 settings。
//
// 与 Vue.js 的重要区别:Vue.js 端的 createAuthStore(settings) 和
// createLanguageStore() 在构造期间,甚至在首次渲染之前,
// 就同步读取 localStorage。它们在 Flutter 中的
// 对应物(AuthService.init()、TranslationsService.init())
// 是异步的(见各自的文件):因此 main() 本身
// 必须成为 async 函数,并在调用 runApp(...) 之前等待(await)这两个
// 初始化完成——否则首个
// 显示的界面会忽略可能已存储的会话或语言,
// 持续时间就是 shared_preferences 响应所需的时间。
//
// 与本课程的 Angular、React 和 Vue.js 客户端一样(单页面,
// 无路由表),这个 Flutter 客户端只使用
// MaterialApp 提供的最小导航(对 showDialog() 至关重要,见
// features/booking_dialog/booking_dialog.dart):AppRoot(见 app.dart)
// 根据情况显示登录界面或应用的其余部分,取决于
// AuthService.isLoggedIn——一个简单的 Dart if/else 就够了,
// 对于只有一个界面的应用,路由包
// (go_router 或其他)不会带来任何好处。
// =========================================================================
import 'package:flutter/material.dart';
import 'package:provider/provider.dart';
import 'app.dart';
import 'core/http/auth_http_client.dart';
import 'core/i18n/translations_service.dart';
import 'core/services/auth_service.dart';
import 'core/services/appointment_service.dart';
import 'core/services/settings_service.dart';
Future<void> main() async {
// WidgetsFlutterBinding.ensureInitialized():只要在 runApp(...) 之前
// 调用 Flutter API(此处是 TranslationsService.init() 中的 shared_preferences 和
// rootBundle.loadString(...))就必不可少——没有
// 这一行,这些调用在启动时会失败。Vue.js 没有
// 类似的东西:浏览器始终是“就绪”的,甚至在
// src/main.ts 运行之前。
WidgetsFlutterBinding.ensureInitialized();
// 1. 首先是 SettingsService:AuthService 和 AppointmentService 都需要它
// (apiBaseUrl)。
final settings = SettingsService();
// 2. AuthService:直接在构造函数中接收 settings,如同
// Vue.js 端的 createAuthStore(settingsStore)——然后 init() 恢复
// 可能已存储的会话(关于这一步的异步性质,见上方
// 的头部注释)。
final auth = AuthService(settings);
await auth.init();
// 3. 经过身份验证的 HTTP 层,然后是业务服务——两者都
// 在此处只构建一次,而不是在某个组件(Widget)内部
// (在那里它们会在每次渲染时重建):与 Vue.js 端
// 在 app.mount(...) 之前只调用一次的
// createSettingsStore()/createAuthStore(...) 原则完全相同。
final authHttp = AuthHttpClient(auth);
final api = AppointmentService(authHttp, settings);
// 4. TranslationsService:加载启动词典
// (已存储的语言,默认为设备的语言)——与前面的步骤没有顺序
// 依赖(不同于 Vue.js 端的
// createLanguageStore(),它必须等待
// app.use(i18n):此文件自行重新实现了一切,见
// core/i18n/translations_service.dart,因此在使用之前无需
// 安装任何第三方插件)。
final translations = TranslationsService();
await translations.init();
runApp(
// MultiProvider:将多个 provider 组合成单个组件(Widget),
// 而不是手工嵌套它们(Provider(...) > Provider(...)
// > Provider(...) > ...)——可读性与 Vue.js 端的调用序列
// "app.provide(SettingsKey, ...); app.provide(AuthKey, ...);
// app.provide(LanguageKey, ...);" 相当,尽管形式
// 不同(是组件(Widget)列表,而不是语句序列)。
MultiProvider(
providers: [
// .value(...) 而不是 Provider(create: ...):这些实例
// 已经存在(在上面构建)——.value(...) 只是让它们对组件(Widget)树可用,
// 而不构建
// 新实例。具体来说,ChangeNotifierProvider 还会订阅
// notifyListeners(),并自动重绘任何
// 对该 provider 调用过 context.watch<...>() 的组件(Widget)(见
// lib/app.dart)——相当于 Vue.js 端
// reactive(...) 的“响应式”特性所起的作用。
ChangeNotifierProvider.value(value: settings),
ChangeNotifierProvider.value(value: auth),
ChangeNotifierProvider.value(value: translations),
// AppointmentService 不是 ChangeNotifier(此服务中构建之后
// 没有任何东西会随时间变化):简单的 Provider
// 就足够了,它只是让该实例可用,而没有
// 任何通知的概念。
Provider.value(value: api),
],
child: const RdvMedecinsApp(),
),
);
}
|
我们来逐段讲解这段代码:
- 第 60 行:[WidgetsFlutterBinding.ensureInitialized();] ——只要在 [runApp(...)] 之前调用 [Flutter] API,就必须有这一行(这里是 [shared_preferences] 和 [rootBundle.loadString(...)])——没有这一行,这些调用在启动时就会失败;[Vue.js] 则无需预先考虑这类问题,因为即使在 [src/main.ts] 执行之前,浏览器也始终处于“就绪”状态。
- 第 70–71 行:[final auth = AuthService(settings); await auth.init();] ——与 [createAuthStore(settingsStore)] 在 [Vue.js] 一侧的做法有重大区别,后者在构建完成后立即同步(SYNCHRONOUSLY)读取 [localStorage]:[AuthService.init()] 被明确声明为 [async],因此 [main()] 本身也必须是异步的,才能在 [runApp(...)] 之前等待(AWAIT)——否则,在等待 [shared_preferences] 响应期间,首个显示的屏幕会忽略已存储的会话。
- 第 89 行:[await translations.init();] ——与上面关于已存储语言的说明相同;与 [createLanguageStore()] 在 [Vue.js] 一侧必须等待 [app.use(i18n)] 不同,这一步不依赖前面的步骤:[TranslationsService] 自行重新实现了全部功能,无需事先安装任何第三方插件。
- 第 98–116 行:[MultiProvider(providers: [...], child: const RdvMedecinsApp())] ——以组件(WIDGET)的形式而非命令式调用,等价于 [app.provide(SettingsKey, ...); app.provide(AuthKey, ...); app.provide(LanguageKey, ...);] 这一调用序列在 [Vue.js] 一侧的写法:每个 [ChangeNotifierProvider.value(...)] 都会把一个预先构建好的实例提供给整个子树。
5.4.2. lib/app.dart
移植自 [src/app/App.vue]:应用的根组件(ROOT widget,由 [lib/main.dart] 构造)——即持有业务状态、响应来自 [lib/features/] 各组件的操作的“指挥者”,同时也是身份验证“守卫”。
| // =========================================================================
// app.dart
// -------------------------------------------------------------------------
// src/app/App.vue(本课程的 Vue.js 客户端)的移植:应用的根
// 组件(Widget)(由 lib/main.dart 构建)。与本课程另外
// 三个版本一样,它扮演
// “指挥者”的角色:持有应用状态(医生、客户、
// 显示的日程、最近搜索的医生/日期……),并响应
// lib/features/ 中“业务”组件(Widget)的操作,在适当的
// 时机通过 AppointmentService 调用 NestJS 服务器。
//
// 由于加入了身份验证,此组件(Widget)还扮演“守卫”的
// 角色:只要 AuthService.isLoggedIn 为 false,它就只显示
// LoginPage(见 lib/features/login/);服务器的所有路由都
// 受 JwtAuthGuard 保护,在登录之前加载
// 医生/客户/日程反正也没用(还会导致 401 错误)。
//
// 两个类,与此客户端中其他“有状态”文件一样:
// RdvMedecinsApp(MaterialApp——绝对的根,见 lib/main.dart)和
// AppRoot/_AppRootState(App.vue 的真正等价物,带有它的全部状态)。
// =========================================================================
import 'package:flutter/material.dart';
import 'package:provider/provider.dart';
import 'core/i18n/translations_service.dart';
import 'core/models/appointment_models.dart';
import 'core/services/auth_service.dart';
import 'core/services/appointment_service.dart';
import 'core/services/settings_service.dart';
import 'features/schedule/schedule_view.dart';
import 'features/booking_dialog/booking_dialog.dart';
import 'features/doctor_day_picker/doctor_day_picker.dart';
import 'features/login/login_page.dart';
// -------------------------------------------------------------------------
// RdvMedecinsApp:严格意义上的 Flutter 根——MaterialApp 提供
// 主题、导航(Navigator,被 showDialog() 使用,见
// features/booking_dialog/booking_dialog.dart)以及系统翻译
// (滚动、对话框……)。它大致相当于
// index.html 加上 app.mount('#app') 挂载
// 在 Vue.js 端(src/main.ts)共同完成的工作——只不过这里,
// 这个“外壳”本身就是应用 Dart 代码的一部分,而不是
// 单独的 HTML 文件。
// -------------------------------------------------------------------------
class RdvMedecinsApp extends StatelessWidget {
const RdvMedecinsApp({super.key});
@override
Widget build(BuildContext context) {
return MaterialApp(
debugShowCheckedModeBanner: false,
// 显式的 appBarTheme:默认的 Material 3 主题给
// AppBar 一个浅色背景(colorScheme.surface)——为了恢复
// Vue.js 端(见 App.vue)"navbar navbar-dark bg-primary" 的
// 白字蓝色栏,此处显式设置背景和文字,
// 而不是在下方 AppRoot 的每个
// Text() 上硬编码文字颜色(见下文的 auth.name)——这样
// 栏的外观只有唯一的事实来源。
theme: ThemeData(
colorSchemeSeed: Colors.blue,
useMaterial3: true,
appBarTheme: const AppBarTheme(
backgroundColor: Colors.blue,
foregroundColor: Colors.white,
),
),
home: const AppRoot(),
);
}
}
class AppRoot extends StatefulWidget {
const AppRoot({super.key});
@override
State<AppRoot> createState() => _AppRootState();
}
class _AppRootState extends State<AppRoot> {
// ——— 应用状态 ———————————————————
// 直接等价于 App.vue 的 ref(...),
// 这里是 _AppRootState 的简单
// 可变字段:setState(...)(见下面的方法)取代了 Vue.js 的自动响应性。
List<Doctor> _doctors = [];
List<Client> _clients = [];
DoctorDaySchedule? _schedule;
String? _error;
// 记住最近一次搜索(医生 + 日期),以便在预约或取消之后能够
// 刷新日程——与 Vue.js 端的
// lastDoctorId/lastDay 作用相同。
int? _lastDoctorId;
String? _lastDay;
// 持久保留对 AuthService 的引用,以便能够
// 在 dispose()(见下文)中干净地取消订阅——
// 选择这样做的原因见下面 initState() 的注释。
late final AuthService _auth;
@override
void initState() {
super.initState();
// context.read<AuthService>():initState() 运行时,
// 组件(Widget)已正确插入树中(不同于
// 构造函数,在构造函数中 context 还不能用于
// 依赖注入)——但这里不使用 context.watch(...):
// StatefulWidget 只应订阅 provider 一次,
// 且是显式订阅,绝不在 initState() 中使用 watch()
// (它假定存在构建上下文)。所以引用保存在
// 字段(_auth)中,由我们自己通过 addListener(...) 订阅。
_auth = context.read<AuthService>();
_auth.addListener(_onAuthChange);
// 相当于 Vue.js 端的 "watch(() => auth.isLoggedIn, ..., { immediate: true })":
// { immediate: true } 会立即触发回调,
// 无需等待第一次变化——如果已存储会话则很有用
// (见 AuthService.init(),由
// lib/main.dart 在 runApp(...) 之前 await)。Vue.js 直接提供此选项;
// Flutter 的 addListener(...) 中没有内置的等价机制,
// 所以同样的效果要手工复现:
// 在订阅之后显式调用一次,作为订阅本身
// 之外的补充。
if (_auth.isLoggedIn) {
_loadInitialLists();
}
}
@override
void dispose() {
// 在此处取消订阅至关重要:否则,_onAuthChange
// 在该组件(Widget)销毁之后仍会被调用(例如
// 在热重载或路由切换期间),并且
// 会在首次对
// 已卸载的组件(Widget)调用 setState(...) 时引发异常。Vue.js 无需考虑类似问题:watch(...) 会
// 在创建它的组件销毁时被自动“清理”。
_auth.removeListener(_onAuthChange);
super.dispose();
}
void _onAuthChange() {
if (_auth.isLoggedIn) {
_loadInitialLists();
}
}
// -----------------------------------------------------------------------
// 当变为已登录时(登录成功,或
// 从 shared_preferences 恢复了会话),医生和客户列表
// 会一次性加载完毕。
// -----------------------------------------------------------------------
void _loadInitialLists() {
final api = context.read<AppointmentService>();
api.getAllDoctors().then((result) {
if (mounted) setState(() => _doctors = result);
}).catchError((Object err) {
if (mounted) setState(() => _error = err.toString());
});
api.getAllClients().then((result) {
if (mounted) setState(() => _clients = result);
}).catchError((Object err) {
if (mounted) setState(() => _error = err.toString());
});
}
// -----------------------------------------------------------------------
// 响应“退出登录”按钮:清除会话以及显示的业务状态
// ——否则,之后登录的新用户
// 会短暂看到前一位用户的日程。
// -----------------------------------------------------------------------
Future<void> _onLogout() async {
await _auth.logOut();
setState(() {
_doctors = [];
_clients = [];
_schedule = null;
_error = null;
_lastDoctorId = null;
_lastDay = null;
});
}
// -----------------------------------------------------------------------
// 响应 DoctorDayPicker 组件(Widget)对 onSearch(...) 的调用
// -----------------------------------------------------------------------
void _onSearchSchedule(int doctorId, String day) {
setState(() {
_error = null;
_lastDoctorId = doctorId;
_lastDay = day;
});
_loadSchedule();
}
// -----------------------------------------------------------------------
// 响应 ScheduleView 组件(Widget)对 onBook(...) 的调用:此处与
// Vue.js(只是打开窗口并
// 记住 slotBeingBooked)不同,对话框
// 直接用 showDialog 打开(通过 openBookingDialog(...)),并且其结果会被
// 等待——这一结构性差异的详情见
// booking_dialog.dart 的头部注释。
// -----------------------------------------------------------------------
Future<void> _onBookingRequest(SlotJson slot) async {
final lastDay = _lastDay;
if (lastDay == null) {
return;
}
final clientId = await openBookingDialog(context: context, slot: slot, clients: _clients);
if (clientId == null) {
return; // 用户未选择患者就关闭了对话框
}
try {
await context.read<AppointmentService>().addAppointment(lastDay, clientId, slot.id);
_loadSchedule(); // 日程已刷新:该时段现在显示为已预约
} catch (err) {
if (mounted) setState(() => _error = err.toString());
}
}
// -----------------------------------------------------------------------
// 响应 ScheduleView 组件(Widget)对 onCancel(...) 的调用
// -----------------------------------------------------------------------
Future<void> _onCancelAppointment(AppointmentJson appointment) async {
try {
await context.read<AppointmentService>().deleteAppointment(appointment.id);
_loadSchedule(); // 日程已刷新:该时段重新变为空闲
} catch (err) {
if (mounted) setState(() => _error = err.toString());
}
}
void _loadSchedule() {
final doctorId = _lastDoctorId;
final day = _lastDay;
if (doctorId == null || day == null) {
return;
}
context.read<AppointmentService>().getDoctorScheduleOfDay(doctorId, day).then((result) {
if (mounted) setState(() => _schedule = result);
}).catchError((Object err) {
if (mounted) setState(() => _error = err.toString());
});
}
@override
Widget build(BuildContext context) {
// 对界面显示直接依赖的三个 provider 调用 context.watch<...>():
// 每次调用都会让此组件(Widget)订阅
// 该 provider 的后续变化——只要其中一个发出通知(notifyListeners()),build(...)
// 就会被自动再次调用。这就是此处取代
// core/services/settings_service.dart 中提到的
// Vue.js 自动响应性的机制。
final t = context.watch<TranslationsService>().t;
final language = context.watch<TranslationsService>();
final auth = context.watch<AuthService>();
final settings = context.watch<SettingsService>();
// 窄屏(竖屏手机):标题栏被精简
// (见下方的 actions:),因为空间不足,无法显示
// 宽屏上轻松容纳的所有内容。
final narrow = MediaQuery.sizeOf(context).width < 600;
return Scaffold(
appBar: AppBar(
title: Text(t('APP.TITLE')),
actions: [
// FR/EN 选择器:始终可见(包括在登录
// 界面)——对应于 App.vue 中始终
// 显示的 <div class="btn-group">。
SegmentedButton<String>(
segments: const [
ButtonSegment(value: 'fr', label: Text('FR')),
ButtonSegment(value: 'en', label: Text('EN')),
],
selected: {language.currentLanguage},
onSelectionChanged: (choice) => language.changeLanguage(choice.first),
showSelectedIcon: false,
),
const SizedBox(width: 12),
// 角色徽章 + 姓名 + 退出登录按钮则
// 只在登录之后显示(auth.isLoggedIn)——条件与
// App.vue 的 <template v-if="auth.isLoggedIn"> 相同。
if (auth.isLoggedIn) ...[
Chip(label: Text(auth.role?.asString() ?? '')),
const SizedBox(width: 8),
// 这里没有硬编码的颜色样式:此 Text() 继承
// appBarTheme 上设置的白色 foregroundColor(见上面的 RdvMedecinsApp),
// 正如 Bootstrap 端的 "navbar-dark" 默认将其全部内容
// 染成白色。
// 在窄屏上隐藏姓名:角色徽章和退出登录
// 按钮已足够,标题栏也能适应宽度。
if (!narrow) Text(auth.name ?? ''),
IconButton(
tooltip: t('APP.LOGOUT'),
icon: const Icon(Icons.logout),
onPressed: _onLogout,
),
],
const SizedBox(width: 8),
],
),
body: SafeArea(
child: SingleChildScrollView(
padding: const EdgeInsets.all(16),
child: Column(
crossAxisAlignment: CrossAxisAlignment.start,
children: [
// 服务器 URL:登录前后都有用
// ——提取到一个专用的小型私有组件(Widget) _ServerUrlField 中
// (见下方),原因在其
// 定义旁边说明。
ConstrainedBox(
constraints: const BoxConstraints(maxWidth: 320),
child: _ServerUrlField(settings: settings, label: t('APP.SERVER_URL_LABEL')),
),
const SizedBox(height: 16),
if (_error != null) ...[
Container(
width: double.infinity,
padding: const EdgeInsets.all(12),
decoration: BoxDecoration(
color: Theme.of(context).colorScheme.errorContainer,
borderRadius: BorderRadius.circular(4),
),
child: Text(
_error!,
style: TextStyle(color: Theme.of(context).colorScheme.onErrorContainer),
),
),
const SizedBox(height: 16),
],
// 未登录:只有登录界面——
// 完全等价于 Vue.js 端的
// "<Login v-if="!auth.isLoggedIn" />"。
if (!auth.isLoggedIn)
const LoginPage()
else ...[
// 组件(Widget) 1:选择医生和日期
DoctorDayPicker(doctors: _doctors, onSearch: _onSearchSchedule),
const SizedBox(height: 16),
// 组件(Widget) 2:显示日程——canEdit 对 USER 角色隐藏
// "Book"/"Cancel"
ScheduleView(
schedule: _schedule,
canEdit: auth.isAdmin,
onBook: _onBookingRequest,
onCancel: _onCancelAppointment,
),
],
],
),
),
),
);
}
}
// -------------------------------------------------------------------------
// _ServerUrlField:专用于“Server
// URL”字段的小型私有 StatefulWidget。在 Vue.js 端,此字段只占一行,直接
// 写在 App.vue 的 <template> 中(<input v-model="settings.apiBaseUrl">):
// v-model 自身在幕后处理
// 显示字段与 settings.apiBaseUrl 之间的同步。Flutter 的 TextField 没有内置双向绑定
// (参见 lib/features/login/login_page.dart):
// 它需要一个 TextEditingController,因此需要一个能创建并
// 释放它的所有者(initState/dispose)——绑定到 provider 的可编辑文本
// 在 Flutter 中不能是简单的 StatelessWidget,不像
// Vue.js 中等价的字段,后者无需单独的
// “组件”即可存在。
// -------------------------------------------------------------------------
class _ServerUrlField extends StatefulWidget {
final SettingsService settings;
final String label;
const _ServerUrlField({required this.settings, required this.label});
@override
State<_ServerUrlField> createState() => _ServerUrlFieldState();
}
class _ServerUrlFieldState extends State<_ServerUrlField> {
late final TextEditingController _controller;
@override
void initState() {
super.initState();
_controller = TextEditingController(text: widget.settings.apiBaseUrl);
}
@override
void dispose() {
_controller.dispose();
super.dispose();
}
@override
Widget build(BuildContext context) {
return TextField(
controller: _controller,
decoration: InputDecoration(labelText: widget.label, isDense: true),
// 用 onChanged 而不是 onSubmitted:每次按键都会立即
// 传给 SettingsService,与
// Vue.js 端 v-model 对每个输入字符的处理完全一样(不只是在
// 提交表单时)。
onChanged: widget.settings.setApiBaseUrl,
);
}
}
|
我们来逐段讲解这段代码:
- 第 46–71 行:[class RdvMedecinsApp extends StatelessWidget] ——严格意义上的根 [Flutter] 组件:[MaterialApp] 提供主题和导航(对 [showDialog(...)] 至关重要,参见下文的 [booking_dialog.dart] )——大致相当于 [index.html] 加上 [app.mount('#app')] 在 [Vue.js] 一侧共同完成的工作。
- 第 60–66 行:[appBarTheme: const AppBarTheme(backgroundColor: Colors.blue, foregroundColor: Colors.white)] ——复现了 ["navbar navbar-dark bg-primary"] ([Bootstrap],参见 [App.vue])的外观:默认的 [Material 3] 主题会让 [AppBar] 呈现浅色背景,因此必须显式设置,才能恢复熟悉的蓝色横幅和白色文字。
- 第 96–127 行:[initState()] ——手动(BY HAND)复现了与 [watch(() => auth.isLoggedIn, ..., { immediate: true })] 在 [Vue.js] 一侧等价的行为(参见 [App.vue]):[Flutter] 的 [addListener(...)] 没有内置 [immediate] 选项,因此必须先订阅,然后再显式检查一次当前状态——这是两个步骤,而 [Vue.js] 只需一个。
- 第 129–139 行:[dispose() { _auth.removeListener(_onAuthChange); }] ——必不可少:如果没有这一取消订阅操作,[_onAuthChange] 在组件被销毁之后仍会继续被调用,并在第一次对已拆除的组件调用 [setState(...)] 时引发异常。[Vue.js] 则无需考虑类似的问题,因为 [watch(...)] 会在创建它的组件被销毁时自动“清理”。
- 第 203–218 行:[_onBookingRequest(...)] ——这里是整个客户端中最明显的结构性差异:它不是通过存储一个布尔状态来打开“窗口”(参见 [slotBeingBooked] 在 [Vue.js] 一侧的做法),而是由该组件直接 [await] [openBookingDialog(...)] 的结果——完整的说明参见本章后面的 [booking_dialog.dart]。
- 第 253–256 行:开头的四个 [context.watch<...>()] 位于 [build(...)]的开头——只要这四个服务中的任何一个(ANY)通知发生变化([notifyListeners()]),该组件就会自动重绘,这恰恰相当于 [Vue.js] 的自动响应机制在 [auth]、[settings]和 [language] 上 [App.vue]所起的作用。
- 第 260 行和第 291 行:[MediaQuery.sizeOf(context).width < 600] ——利用屏幕(或窗口)宽度,使手机竖屏时的标题栏更为精简:隐藏用户姓名([if (!narrow) Text(...)],在组件列表中间的一个简单的 Dart [if]),而角色徽章和注销按钮仍然可见。在第 276 行,[showSelectedIcon: false] 移除了 [SegmentedButton] 为所选选项添加的对勾,它会无谓地加宽 [FR]/[EN] 选择器。如果没有这两处调整,[actions:] 元素 [AppBar] 的会超出竖屏手机的宽度。
- 第 359–409 行:[class _ServerUrlField] ——一个小型的 私有 [StatefulWidget],专用于“服务器 URL”字段。在 [Vue.js] 中,这个字段只需一行即可完成([<input v-model="settings.apiBaseUrl">]):[Flutter] 的 [TextField] 没有内置的双向绑定,因此需要一个 [TextEditingController],以及一个能够创建和释放它的所有者——与某个 provider 关联的可编辑文本在 [Flutter] 中不能简单地是一个 [StatelessWidget]。
5.5. core/models 层

5.5.1. lib/core/models/appointment_models.dart
移植自 [core/models/appointment.models.ts],而后者本身是从 [Angular] 和 [React] 客户端原样复制而来:这些类描述了与服务器交换的 JSON 数据的格式,不依赖 [Flutter]——即“纯粹的” [Dart]。
| // =========================================================================
// core/models/appointment_models.dart
// -------------------------------------------------------------------------
// core/models/appointment.models.ts(本课程的 Vue.js 客户端)的移植,该文件本身
// 原样复制自 Angular 和 React 客户端:这些 Dart 类
// 描述从 NestJS 服务器收到的 JSON 数据的形状。与对应的
// TypeScript 类一样,这些类不依赖任何 UI 框架
// (此处没有 Flutter 的 import)——这是“纯”Dart,正如
// appointment.models.ts 是“纯”TypeScript。
//
// 与 TypeScript 的结构性差异:TypeScript 的“interface”只是
// 对形状的描述,仅在编译时检查——
// 在运行时,解码后的 JSON 对象(JSON.parse)原样使用,
// 不做转换,TypeScript“信任”开发者(见
// appointment.service.ts 的 "as ServerResponse<T>")。Dart 没有这种隐式
// 结构化类型的概念:jsonDecode(...) 总是返回 dynamic
// 类型(Map<String, dynamic>、List<dynamic>……),必须
// 通过 fromJson(...) 构造函数显式转换为 Dart 类的实例
// ——下面每个类都有。这样一次性写起来更
// 冗长,但转换在运行时受到检查
// (缺少键或类型错误会立即抛出明确的
// 异常),而错误的 TypeScript 类型标注则可能不被察觉。
// =========================================================================
// -------------------------------------------------------------------------
// 所有服务器响应共有的信封(见 NestJS 端的 ServerResponse<T>,
// 以及 Vue.js 客户端的 ServerResponse<T> 接口)。
//
// Dart 同样用尖括号(<T>)实现泛型,与
// TypeScript 完全一样——很大的区别在于,这里仅用 "as T" 不
// 足以转换 [data] 字段:必须提供知道如何从原始 JSON 构建
// T 的函数(下面的 [parseData]
// 参数),因为 Dart 在运行时并不知道 T
// (类型擦除使得无法直接写 "T.fromJson(...)"
// )。
// -------------------------------------------------------------------------
class ServerResponse<T> {
final int status; // 0 = 成功,其他值 = 失败(见服务器端的 ResponseStatus)
final T? data;
ServerResponse({required this.status, required this.data});
factory ServerResponse.fromJson(
Map<String, dynamic> json,
T Function(dynamic rawData) parseData,
) {
final rawData = json['data'];
return ServerResponse<T>(
status: json['status'] as int,
data: rawData == null ? null : parseData(rawData),
);
}
}
class Doctor {
final int id;
final String title;
final String lastName;
final String firstName;
Doctor({required this.id, required this.title, required this.lastName, required this.firstName});
factory Doctor.fromJson(Map<String, dynamic> json) => Doctor(
id: json['id'] as int,
title: json['title'] as String,
lastName: json['lastName'] as String,
firstName: json['firstName'] as String,
);
}
// 此处的 [Client] 指医疗诊所的患者(业务领域的词汇,
// 沿用自原始文档)——不要与
// “HTTP 客户端”或这个 Flutter 客户端本身混淆!
class Client {
final int id;
final String title;
final String lastName;
final String firstName;
Client({required this.id, required this.title, required this.lastName, required this.firstName});
factory Client.fromJson(Map<String, dynamic> json) => Client(
id: json['id'] as int,
title: json['title'] as String,
lastName: json['lastName'] as String,
firstName: json['firstName'] as String,
);
}
// 时间段的“精简”形式,由服务器返回
// (见 NestJS 端的 getMapForSlot):只包含对显示有用的字段。
class SlotJson {
final int id;
final int startHour;
final int startMinute;
final int endHour;
final int endMinute;
SlotJson({
required this.id,
required this.startHour,
required this.startMinute,
required this.endHour,
required this.endMinute,
});
factory SlotJson.fromJson(Map<String, dynamic> json) => SlotJson(
id: json['id'] as int,
startHour: json['startHour'] as int,
startMinute: json['startMinute'] as int,
endHour: json['endHour'] as int,
endMinute: json['endMinute'] as int,
);
}
// 预约的“精简”形式(见 NestJS 端的 getMapForAppointment)
class AppointmentJson {
final int id;
final String day; // 格式 "yyyy-MM-dd"
final Client? client;
final SlotJson? slot;
AppointmentJson({required this.id, required this.day, required this.client, required this.slot});
factory AppointmentJson.fromJson(Map<String, dynamic> json) => AppointmentJson(
id: json['id'] as int,
day: json['day'] as String,
client: json['client'] == null ? null : Client.fromJson(json['client'] as Map<String, dynamic>),
slot: json['slot'] == null ? null : SlotJson.fromJson(json['slot'] as Map<String, dynamic>),
);
}
// 医生日程中的一个时间段,空闲(appointment == null)或已预约
class DoctorDaySlot {
final SlotJson slot;
final AppointmentJson? appointment;
DoctorDaySlot({required this.slot, required this.appointment});
factory DoctorDaySlot.fromJson(Map<String, dynamic> json) => DoctorDaySlot(
slot: SlotJson.fromJson(json['slot'] as Map<String, dynamic>),
appointment: json['appointment'] == null ? null : AppointmentJson.fromJson(json['appointment'] as Map<String, dynamic>),
);
}
// 医生某一天的完整日程(见 GET /getDoctorScheduleOfDay/:doctorId/:day)
class DoctorDaySchedule {
final Doctor doctor;
final String day;
final List<DoctorDaySlot> slots;
DoctorDaySchedule({required this.doctor, required this.day, required this.slots});
factory DoctorDaySchedule.fromJson(Map<String, dynamic> json) => DoctorDaySchedule(
doctor: Doctor.fromJson(json['doctor'] as Map<String, dynamic>),
day: json['day'] as String,
slots: (json['slots'] as List<dynamic>)
.map((e) => DoctorDaySlot.fromJson(e as Map<String, dynamic>))
.toList(),
);
}
// -------------------------------------------------------------------------
// 身份验证(见服务器:src/auth/,特别是 login-result.model.ts)
// -------------------------------------------------------------------------
// 应用处理的仅有两种角色——与服务器的 [Role] 类型(src/entities/user.entity.ts)完全一致。TypeScript 只需
// 字符串联合('ADMIN' | 'USER'),而 Dart 有
// 真正的枚举概念(enum):更安全(不可能
// 误创建这两个值之外的 Role),代价是通过
// 下面的 fromString(...)/asString() 与
// JSON 字符串("ADMIN"/"USER")之间进行小小的显式往返转换——
// 而 TypeScript 的 "type Role =
// 'ADMIN' | 'USER'" 完全不需要转换,对它来说 JSON 字符串本身
// 就已经是该类型的有效值。
enum Role {
admin,
user;
static Role fromString(String value) {
switch (value) {
case 'ADMIN':
return Role.admin;
case 'USER':
return Role.user;
default:
throw ArgumentError('Unknown role: $value');
}
}
String asString() => this == Role.admin ? 'ADMIN' : 'USER';
}
// POST /login 返回的数据形状(位于常规的 ServerResponse<T> 信封中)
class LoginResult {
final String accessToken;
final String login;
final String name;
final Role role;
LoginResult({required this.accessToken, required this.login, required this.name, required this.role});
factory LoginResult.fromJson(Map<String, dynamic> json) => LoginResult(
accessToken: json['accessToken'] as String,
login: json['login'] as String,
name: json['name'] as String,
role: Role.fromString(json['role'] as String),
);
}
|
我们来逐段讲解这段代码:
- 第 11–22 行:头部注释详细说明了该文件中关键的结构性差异——[interface] [TypeScript] 只在编译时(COMPILE)检查;[Dart] 则在运行时保留其类型,因此每个类都有一个显式的 [fromJson(...)] 构造函数([appointment.models.ts]中没有)。
- 第 37–53 行:[class ServerResponse<T>] 及其工厂方法 [fromJson(json, parseData)]——接收一个函数([parseData]),而不是像 [as ServerResponse<T>] 在 [TypeScript] 一侧那样依赖简单的类型断言(参见 [appointment.service.ts]):[Dart] 在运行时并不知道 [T] (类型擦除),因此它自己无法写出 [T.fromJson(...)]。
- 第 71–73 行:注释指出 [Client] 指的是医疗诊所的一位患者(PATIENT,业务领域词汇)——不要与“HTTP 客户端”混淆,也不要与这个 [Flutter] 客户端本身混淆,这一歧义在前三个 Web 变体中已经提到过。
- 第 176–192 行:[enum Role { admin, user; ... }] ——用真正的 [Dart] 枚举取代了 [TypeScript] 的字符串联合类型 [type Role = 'ADMIN' | 'USER'] ,并与 JSON 字符串进行显式的双向转换([fromString]/[asString])——这样更安全(不可能生成无效的 [Role]),代价是需要进行字符串联合类型无需执行的转换。
5.6. core/services 层

5.6.1. lib/core/services/settings_service.dart
移植自 [core/composables/settings.composable.ts]:在内存中保存 [NestJS] 服务器的 URL。
| // =========================================================================
// core/services/settings_service.dart
// -------------------------------------------------------------------------
// core/composables/settings.composable.ts(本课程的 Vue.js 客户端)的移植:一个微型
// “存储”,在内存中保存 NestJS
// 服务器的 URL。
//
// Vue.js 通过 [provide]/[inject] 这一对来暴露此共享状态:
// 一个只创建一次的 [reactive(...)] 对象,然后由
// 任何后代组件原地读取/修改。Flutter 既没有 [reactive],也没有
// [provide]/[inject]:生态中的标准等价物(也是本课程使用的)是
// ChangeNotifier——一个普通的 Dart 类,除了字段之外,
// 它还知道如何在每次变化需要触发新的显示时
// 通知其监听者,通过
// 显式调用 notifyListeners()。
//
// 与 Vue.js 的本质区别:[reactive(...)] 将对象包装在
// JavaScript 代理中,它会自动检测每次属性
// 写入(store.apiBaseUrl = ... 会自行重绘读取了
// apiBaseUrl 的组件)。而 Dart 的 ChangeNotifier 自身
// 什么也检测不到:由开发者在每次
// 修改之后调用 notifyListeners()——多一点手工的自律,换来
// 简单得多的机制(没有代理,没有“魔法”),更易于
// 理解和调试。
//
// 随后由 [provider] 包(见 pubspec.yaml 和 lib/main.dart)围绕这个 ChangeNotifier
// 扮演 Vue.js 端 app.provide(...) 的角色:
// 它让这唯一的实例对整个组件(Widget)
// 子树可用,方式是 context.watch<SettingsService>()(“读取并
// 重新订阅后续变化”,见 lib/app.dart)或 context.read<...>()
// (“读取一次,不重新订阅”)。
// =========================================================================
import 'package:flutter/foundation.dart';
class SettingsService extends ChangeNotifier {
String _apiBaseUrl = 'http://localhost:8080';
String get apiBaseUrl => _apiBaseUrl;
// 相当于 Vue.js 端的 "setApiBaseUrl(url: string)"——不同于
// store.apiBaseUrl = url(简单赋值,借助
// 响应式代理就足够了),这里在修改私有字段之后
// 必须显式通知监听者。
void setApiBaseUrl(String url) {
if (url == _apiBaseUrl) {
return; // 如果值并未真正改变,则避免无用的重绘
}
_apiBaseUrl = url;
notifyListeners();
}
}
|
我们来逐段讲解这段代码:
- 第 36–39 行:[class SettingsService extends ChangeNotifier] 带有一个私有字段([_apiBaseUrl])和一个公共访问器([get apiBaseUrl])——[ChangeNotifier] 是一个普通的 [Dart] 类,不像 [reactive(...)] 在 [Vue.js] 一侧那样使用代理:没有任何机制会自动检测属性的读取或写入。
- 第 45–51 行:[setApiBaseUrl(url)] 会在更新字段之后显式调用 [notifyListeners()]——这是 [store.apiBaseUrl = url] 在 [Vue.js] 一侧无需执行的手动步骤,因为响应式代理会自行处理。
5.6.2. lib/core/services/auth_service.dart
移植自 [core/composables/auth.composable.ts]:管理登录(POST [/login]),维护 [JWT] 令牌,并通过 [shared_preferences] 确保它在重启后仍然存在。
| // =========================================================================
// core/services/auth_service.dart
// -------------------------------------------------------------------------
// core/composables/auth.composable.ts(本课程的 Vue.js 客户端)的移植:
// 处理用户的登录,调用 POST /login,保存
// 收到的 JWT 令牌(以及随之而来的身份/角色),并借助 shared_preferences 让它
// 在应用重启后依然有效——
// 它是 localStorage 的跨平台等价物(见下文)。
//
// 与 Vue.js 端一样,这是应用中除 core/services/appointment_service.dart 之外
// 唯一与服务器进行 HTTP 通信的地方——这是对“只有一个地方进行 HTTP 通信”这一规则的
// 有意例外,它在客户端反映了服务器端早已做出的
// RdvMedecinsController(业务)与 AuthController(身份验证)
// 之间的分离。
//
// 与 Vue.js 的重要区别:readStoredSession()(Vue.js 端)
// 是同步的——localStorage.getItem(...) 立即返回其值,
// 甚至早于应用的首次渲染。而 shared_
// preferences 始终是异步的(SharedPreferences.getInstance()
// 返回一个 Future),即使在底层存储
// 实际上是几乎瞬间读完的本地文件的平台上也是如此:Dart API 不
// 区分这些情况,以保证在所有平台上的一致性(在
// Web 上,这同一调用依赖 window.localStorage,但 Dart API
// 仍保持异步,以便与其他目标保持一致)。具体
// 后果:不能再像 Vue.js 端那样,在组件(Widget)树挂载之前读取已
// 存储的会话——需要一个显式异步的 [init()],
// 由 lib/main.dart 在 runApp(...) 之前调用(并用 await 等待),
// 以避免登录界面在会话恢复之前
// “闪烁”一瞬间。
// =========================================================================
import 'dart:convert';
import 'package:flutter/foundation.dart';
import 'package:http/http.dart' as http;
import 'package:shared_preferences/shared_preferences.dart';
import '../models/appointment_models.dart';
import 'settings_service.dart';
const String _storageKey = 'rdvmedecins.session';
class AuthService extends ChangeNotifier {
// 在构造函数中接收,而不是通过 Flutter 注入获得:在这个
// 阶段(见 lib/main.dart),还没有任何组件(Widget)存在,因此像
// context.read<SettingsService>() 这样的做法是不可能的——
// 原因与 Vue.js 端(src/main.ts)createAuthStore(settings) 中记录的
// 完全相同,它同样将 settingsStore 作为函数
// 参数接收,而不是通过 inject()。
final SettingsService settings;
AuthService(this.settings);
bool isLoggedIn = false;
String? login;
String? name;
Role? role;
String? accessToken;
bool get isAdmin => role == Role.admin;
// -----------------------------------------------------------------------
// 只应调用一次,在 lib/main.dart 中,位于 runApp(...) 之前:重新读取
// 在应用上一次启动期间可能已存储的
// 会话——相当于 Vue.js 端的 readStoredSession(),但
// 是显式异步的(见本文件的头部注释),而不是
// 在存储自身的构造函数内部调用。
// -----------------------------------------------------------------------
Future<void> init() async {
try {
final prefs = await SharedPreferences.getInstance();
final raw = prefs.getString(_storageKey);
if (raw == null) {
return; // 没有已存储的会话:保持“未登录”,使用上面的默认值
}
final session = jsonDecode(raw) as Map<String, dynamic>;
_applyLocalSession(
accessToken: session['accessToken'] as String,
login: session['login'] as String,
name: session['name'] as String,
role: Role.fromString(session['role'] as String),
);
} catch (_) {
// shared_preferences 可能不可用,或包含损坏的
// 值——这种情况下,与 Vue.js 端一样(readStoredSession() 的 try/catch),
// 我们只是认为没有
// 会话,而不是让应用启动崩溃。
}
// 这里没有 notifyListeners():init() 在 lib/main.dart 的
// runApp(...) 之前被 await,因此此方法运行时还没有任何组件(Widget)在监听这个
// ChangeNotifier——通知
// 是无用的(在某些调试配置中甚至会抛出异常,因为 Flutter 的 ChangeNotifier
// 禁止在至少有一个
// 监听者之前调用 notifyListeners())。
}
// -----------------------------------------------------------------------
// 相当于:POST /login JSON 请求体 { login, password }
// -----------------------------------------------------------------------
Future<LoginResult> logIn(String login, String password) async {
final httpResponse = await http.post(
Uri.parse('${settings.apiBaseUrl}/login'),
headers: {'Content-Type': 'application/json'},
body: jsonEncode({'login': login, 'password': password}),
);
final envelope = ServerResponse<LoginResult>.fromJson(
jsonDecode(httpResponse.body) as Map<String, dynamic>,
(data) => LoginResult.fromJson(data as Map<String, dynamic>),
);
if (envelope.status != 0 || envelope.data == null) {
throw Exception('Login failed');
}
final result = envelope.data!;
await _applySessionAndPersist(result);
return result;
}
// -----------------------------------------------------------------------
// 退出登录:纯本地操作(不调用服务器——在这个移植版中 JWT 令牌不会在服务器端被
// “撤销”,它在
// JWT_EXPIRES_IN 之后自行过期,见服务器的 .env)。既由点击
// “Log out”(见 lib/app.dart)调用,也由 core/http/auth_http_client.dart
// 在受保护的请求收到 401 时调用。
// -----------------------------------------------------------------------
Future<void> logOut() async {
login = null;
name = null;
role = null;
accessToken = null;
isLoggedIn = false;
notifyListeners();
try {
final prefs = await SharedPreferences.getInstance();
await prefs.remove(_storageKey);
} catch (_) {
// 这里同样,清除存储失败不得妨碍
// 应用端的退出登录,上面已经生效。
}
}
// 更新响应式字段,但不触碰存储——由
// init() 使用(它刚刚读取了存储,无需重写)。
void _applyLocalSession({
required String accessToken,
required String login,
required String name,
required Role role,
}) {
this.accessToken = accessToken;
this.login = login;
this.name = name;
this.role = role;
isLoggedIn = true;
}
// 更新响应式字段并持久化会话——由
// 上面的 logIn() 使用。把 applySession(...) 在 Vue.js 端
// 于单个代码块中所做的事情合在一起(响应式状态 + 一并写入的 localStorage);
// 这里将这两个操作分开,因为写入
// 是异步的(await prefs.setString(...)),而字段的更新
// 必须立即同步完成
// (notifyListeners() 必须紧跟字段赋值,而不等待
// 磁盘 I/O)——颠倒顺序会不必要地延迟界面的
// 刷新。
Future<void> _applySessionAndPersist(LoginResult result) async {
_applyLocalSession(
accessToken: result.accessToken,
login: result.login,
name: result.name,
role: result.role,
);
notifyListeners();
try {
final prefs = await SharedPreferences.getInstance();
await prefs.setString(
_storageKey,
jsonEncode({
'accessToken': result.accessToken,
'login': result.login,
'name': result.name,
'role': result.role.asString(),
}),
);
} catch (_) {
// 即使持久化失败(超出配额、
// 只读存储……),会话在本次应用运行期间
// 在内存中仍然有效——只有之后的
// 应用重启才会受影响(用户将不得不重新登录)。
}
}
}
|
我们来逐段讲解这段代码:
- 第 16–29 行:头部注释详细说明了该文件中最重要的差异——[readStoredSession()] 在 [Vue.js] 一侧是同步的(SYNCHRONOUS);[shared_preferences] 无论在哪个平台上都始终(ALWAYS)是异步的,因此需要一个显式的 [async] [init()],由 [lib/main.dart] 在 [runApp(...)] 之前等待它完成。
- 第 69–95 行:[Future<void> init() async { ... }] ——读取已缓存的会话(如果有),并用 [try/catch] 加以保护——与 [try/catch] 在 [readStoredSession()] 中、位于 [Vue.js] 一侧的预防措施相同(存储不可用或值已损坏)。
- 第 100–116 行:[logIn(login, password)] ——使用 [/login] 包 [http] (相当于 [fetch])调用 POST,失败时抛出标准的 [Dart] 异常([throw Exception(...)])——该异常随后会被 [try/catch] [Dart] 捕获,就像 [throw new Error(...)] 在 [auth.composable.ts] 中被 [.catch(...)] [JavaScript] 捕获一样。
- 第 165–190 行:[_applySessionAndPersist(...)] ——先更新各字段并调用 [notifyListeners()],然后再写入 [shared_preferences]:这个顺序是有意为之的——界面必须立即刷新,而无需等待异步的磁盘写入;而 [applySession(...)] 在 [Vue.js] 一侧则是在一条同步指令中完成这两个操作。
5.6.3. lib/core/services/appointment_service.dart
移植自 [core/services/appointment.service.ts]:对服务器的五个业务逻辑调用,构建在 [core/http/auth_http_client.dart] (见下文)之上,而不是直接构建在 [http] 包之上。
| // =========================================================================
// core/services/appointment_service.dart
// -------------------------------------------------------------------------
// core/services/appointment.service.ts(本课程的 Vue.js 客户端)的移植:Flutter 客户端的
// [Services] 层——应用中唯一
// 与 NestJS 服务器进行 HTTP 通信的地方
// (登录本身除外,由 core/services/auth_service.dart 负责)。
//
// Vue.js 将此服务暴露为组合式函数(COMPOSABLE,useAppointmentService()),它本身
// 构建在另外两个组合式函数(useAuthFetch()、useSettings())之上。
// Flutter/Dart 的语言中既没有组合式函数,也没有内置的依赖注入,
// 因此此文件又变回一个普通的类,只在 lib/main.dart 中构建
// 一次,并通过构造函数传入它的两个依赖——
// 原则与 core/http/auth_http_client.dart 完全相同,
// 也是在目标语言不提供组合式函数时,移植“一组
// 依赖其他东西的函数”的最直接方式。
// =========================================================================
import 'dart:convert';
import 'package:http/http.dart' as http;
import '../http/auth_http_client.dart';
import '../models/appointment_models.dart';
import 'settings_service.dart';
class AppointmentService {
final AuthHttpClient authHttp;
final SettingsService settings;
AppointmentService(this.authHttp, this.settings);
// -----------------------------------------------------------------------
// 通用的私有函数:所有服务器响应都具有 { status, data } 的形状
// (见 core/models/appointment_models.dart)。“如果 status != 0,则为错误”
// 这一规则在此处集中处理,只有一次,而不是
// 在下面每个方法中重复——与 Vue.js 端 extract<T>(...) 的
// 作用完全相同。
//
// [parseData] 与前面在 ServerResponse.fromJson(...)(见 appointment_models.dart)中
// 遇到的参数是同一类:这个函数知道如何从 [data] 字段的原始 JSON
// 重建出 T,因为 Dart
// 自己做不到(没有通用的 "T.fromJson(...)")。
// -----------------------------------------------------------------------
T _extract<T>(http.Response httpResponse, T Function(dynamic rawData) parseData) {
final envelope = ServerResponse<T>.fromJson(
jsonDecode(httpResponse.body) as Map<String, dynamic>,
parseData,
);
if (envelope.status != 0) {
// 服务器的“业务”错误被转换为经典的 Dart
// 异常,调用方组件(Widget)可以用
// 简单的 try/catch 捕获(见 lib/app.dart)——与 appointment.service.ts 的
// "throw new Error(...)" 完全一样,后者由
// src/app/App.vue 的 .catch(...) 捕获。
throw Exception('The server responded with error status ${envelope.status}');
}
return envelope.data as T;
}
// -----------------------------------------------------------------------
// 相当于:GET /getAllDoctors
// -----------------------------------------------------------------------
Future<List<Doctor>> getAllDoctors() async {
final httpResponse = await authHttp.get(Uri.parse('${settings.apiBaseUrl}/getAllDoctors'));
return _extract<List<Doctor>>(
httpResponse,
(data) => (data as List<dynamic>).map((e) => Doctor.fromJson(e as Map<String, dynamic>)).toList(),
);
}
// -----------------------------------------------------------------------
// 相当于:GET /getAllClients
// -----------------------------------------------------------------------
Future<List<Client>> getAllClients() async {
final httpResponse = await authHttp.get(Uri.parse('${settings.apiBaseUrl}/getAllClients'));
return _extract<List<Client>>(
httpResponse,
(data) => (data as List<dynamic>).map((e) => Client.fromJson(e as Map<String, dynamic>)).toList(),
);
}
// -----------------------------------------------------------------------
// 相当于:GET /getDoctorScheduleOfDay/{doctorId}/{day}
// -----------------------------------------------------------------------
Future<DoctorDaySchedule> getDoctorScheduleOfDay(int doctorId, String day) async {
final httpResponse = await authHttp.get(
Uri.parse('${settings.apiBaseUrl}/getDoctorScheduleOfDay/$doctorId/$day'),
);
return _extract<DoctorDaySchedule>(
httpResponse,
(data) => DoctorDaySchedule.fromJson(data as Map<String, dynamic>),
);
}
// -----------------------------------------------------------------------
// 相当于:POST /addAppointment JSON 请求体 { day, clientId, slotId }
// -----------------------------------------------------------------------
Future<AppointmentJson> addAppointment(String day, int clientId, int slotId) async {
final httpResponse = await authHttp.post(
Uri.parse('${settings.apiBaseUrl}/addAppointment'),
body: jsonEncode({'day': day, 'clientId': clientId, 'slotId': slotId}),
);
return _extract<AppointmentJson>(httpResponse, (data) => AppointmentJson.fromJson(data as Map<String, dynamic>));
}
// -----------------------------------------------------------------------
// 相当于:POST /deleteAppointment JSON 请求体 { appointmentId }
// -----------------------------------------------------------------------
Future<void> deleteAppointment(int appointmentId) async {
final httpResponse = await authHttp.post(
Uri.parse('${settings.apiBaseUrl}/deleteAppointment'),
body: jsonEncode({'appointmentId': appointmentId}),
);
_extract<Object?>(httpResponse, (data) => data);
}
}
|
我们来逐段讲解这段代码:
- 第 27–31 行:[class AppointmentService { final AuthHttpClient authHttp; final SettingsService settings; AppointmentService(this.authHttp, this.settings); }] ——回归为普通类,在 [lib/main.dart] 中构造一次,其依赖项通过构造函数传入;而 [Vue.js] 使用的是组合式函数(COMPOSABLE)[useAppointmentService()],它本身又由另外两个组合式函数构建而成。
- 第 45–59 行:[T _extract<T>(httpResponse, parseData)]——只集中处理一次规则“如果 [status != 0],就是错误”,其作用恰好等同于 [extract<T>(...)] 在 [Vue.js] 一侧的作用——参数 [parseData] 与我们在 [ServerResponse.fromJson(...)] 中已经遇到过的函数类型相同。
- 第 99–105 行:[addAppointment(day, clientId, slotId)] ——[jsonEncode({...})] 构造 POST 请求的 JSON 请求体,相当于 [Dart] 中的 [JSON.stringify({...})] 在 [Vue.js] 一侧的作用。
- 第 110–116 行:[Future<void> deleteAppointment(int appointmentId) async { ... }] ——调用 [_extract<Object?>(...)] 但不使用其结果:该路由下服务器返回 [ServerResponse.ok(null)] ,因此没有更具体的内容可指定——与 [extract<null>(httpResponse)] 在 [Vue.js] 一侧的选择相同。
5.7. core/http 层

5.7.1. lib/core/http/auth_http_client.dart
移植自 [core/interceptors/auth.interceptor.ts]:为每个受保护的请求添加 [JWT] 令牌,并在收到 401 响应时让用户退出登录。
| // =========================================================================
// core/http/auth_http_client.dart
// -------------------------------------------------------------------------
// core/interceptors/auth.interceptor.ts(本课程的 Vue.js 客户端)的移植。
// 此文件做两件事,与它的
// Vue.js 对应文件完全一样(后者本身移植自 Angular 和 React 客户端):
// 1. 如果用户已登录,则给每个请求添加 "Authorization: Bearer <token>" 头
// (见 AuthService.accessToken);
// 2. 如果服务器返回 401(令牌缺失、无效或过期),
// 则在客户端干净地让用户退出登录。
//
// [fetch](用于 Vue.js 和 React 端)和 Angular 的 [HttpClient] 在 Dart 中
// 没有直接的等价物:[http] 包(见 pubspec.yaml)
// 提供的是自由函数(http.get(...)、http.post(...)),而不是
// 可以全局拦截的对象。尽管如此,这个移植版在
// 精神上仍忠实于 useAuthFetch():这里编写的不是返回
// “增强版 fetch”的组合式函数,而是一个真正的类 [AuthHttpClient],
// 它的 get(...)/post(...) 方法起完全相同的作用——
// 任何想与服务器通信的代码(这里只有
// core/services/appointment_service.dart)都调用这些方法,而不是直接调用
// http 包。
//
// 编写类而不是组合式函数,在 Dart/Flutter 中是很自然的
// 选择:不同于 Vue.js 的 <script setup>(它
// 对每个组件实例只运行一次,见
// auth.interceptor.ts 的注释),ChangeNotifier 或 Dart 服务类
// 没有“每次渲染都执行的函数体”需要提防——
// 因此这里同样不需要 useCallback() 的等价物,
// 但原因不同:根本就不存在
// “每次渲染都重新创建”的函数,因为类
// 只由 lib/main.dart 构建一次(见下文)。
// =========================================================================
import 'dart:async' show unawaited;
import 'package:http/http.dart' as http;
import '../services/auth_service.dart';
class AuthHttpClient {
final AuthService auth;
final http.Client _client = http.Client();
AuthHttpClient(this.auth);
Future<http.Response> get(Uri url) => _send(() => _client.get(url, headers: _headers()));
Future<http.Response> post(Uri url, {required Object body}) => _send(
() => _client.post(
url,
headers: {..._headers(), 'Content-Type': 'application/json'},
body: body,
),
);
// 构建每个受保护请求共有的请求头——相当于
// Vue.js 端的 "new Headers(options.headers); if (auth.accessToken) {...}",
// 但这里是简单的 Map<String, String>(http 包
// 所期望的类型,在这里比 Headers 类更简单)。
Map<String, String> _headers() {
final accessToken = auth.accessToken;
return accessToken == null ? {} : {'Authorization': 'Bearer $accessToken'};
}
// 提取 get(...) 和 post(...) 的共同部分:执行 HTTP
// 调用,然后如果响应为 401,则让用户退出登录——作为参数收到的
// [call] 函数所起的作用,相当于 Vue.js 端 fetch(path, { ...options, headers }) 传入的
// "...options":在这一点上
// 我们还不知道它是 GET
// 还是 POST,只知道必须执行它并检查其响应。
Future<http.Response> _send(Future<http.Response> Function() call) async {
final response = await call();
// 会话期间出现 401 意味着令牌已不再有效
// (已过期,或服务器已重启):客户端被干净地退出登录,
// 而不是让应用处于不一致的状态(表面上已登录,
// 但再也没有请求能成功)。对 logOut() 没有
// "await":HTTP 响应(即使是错误响应)
// 必须返回给调用方,而不等待本地存储
// 清除完成,后者在后台自行完成。
if (response.statusCode == 401) {
unawaited(auth.logOut());
}
return response;
}
}
|
我们来逐段讲解这段代码:
- 第 12–31 行:头部注释解释了选择使用类([AuthHttpClient])而不是组合式函数的原因——[fetch]([Vue.js]/[React])和 [HttpClient] ([Angular])在 [Dart] 中没有直接对应物;[http] 包提供的是独立的函数,而不是可以被全局拦截的单个对象。
- 第 46–54 行:[get(...)]/[post(...)]——[appointment_service.dart] 调用的仅有的两个方法;它从不直接调用 [http] 包。
- 第 60–63 行:[_headers()] ——如果用户已登录,就构造 [{'Authorization': 'Bearer $accessToken'}] ;这相当于 [new Headers(options.headers); if (auth.accessToken) {...}] 在 [Vue.js] 一侧的做法,只不过采用了简单的 [Map<String, String>] 形式。
- 第 71–84 行:[_send(call)] ——提取出 [get(...)] 和 [post(...)] 的共同部分;[unawaited(auth.logOut())] 明确地表明了我们选择不等待 [Future]——HTTP 响应(即使其中包含错误)必须直接返回给调用者,而无需等待本地存储清除完成。
5.8. core/i18n 层

5.8.1. lib/core/i18n/translations_service.dart
合并移植了 [src/i18n.ts] 以及 [core/composables/language.composable.ts]:法语/英语界面的切换,不使用第三方库来重新实现(关于这一选择的原因,请参见该文件中的头部注释)。
| // =========================================================================
// core/i18n/translations_service.dart
// -------------------------------------------------------------------------
// src/i18n.ts(vue-i18n 配置)与
// core/composables/language.composable.ts(本课程的 Vue.js 客户端)的合并移植。
// Vue.js 将两者分开,是因为 vue-i18n 这个已经功能丰富的第三方库
// (复数、日期/数字格式……)
// 完成了全部实际的翻译工作;language.composable.ts
// 只是在其上增加了把语言选择存储到
// localStorage 中的功能。Flutter 默认没有直接对应于 vue-i18n/react-
// i18next/@ngx-translate/core 的东西:与其添加
// 额外的依赖,此文件用几行
// 代码重新实现了本课程所用的那部分子集——
// 带点号键("LOGIN.TITLE")的词典和一个 t(key) 函数。
//
// 重要的平台差异(另见“将应用移植到移动端、桌面端和
// Web 端”一章):src/i18n.ts 用 fetch("/i18n/{language}.json") 获取
// 每个词典——这是相对
// URL,它假定有 Web 服务器提供客户端的文件
// (开发时是 Vite,构建后是静态服务器)。移动端或桌面端的
// Flutter 应用没有任何 Web 服务器为其提供服务
// :代码及其静态资源(这里是 JSON 文件)
// 一起嵌入到安装在设备上的单个包中(.apk、
// .app、.exe……)。这就是此文件使用 rootBundle.loadString(...) 的原因
// ——这个 Flutter API 直接从该包中读取在 pubspec.yaml 的 [assets] 部分
// 声明的文件——而不是进行网络调用。
// 在 Web 目标上,rootBundle 在幕后依赖对应用旁边发布的文件发出的真实 HTTP
// 请求,但这个细节在此处
// 是不可见的:同样的 Dart 代码无需任何平台
// 条件判断,即可在这 3 种环境上运行——这正是本章的
// 核心论点。
// =========================================================================
import 'dart:convert';
import 'package:flutter/foundation.dart';
import 'package:flutter/services.dart' show rootBundle, ServicesBinding;
import 'package:shared_preferences/shared_preferences.dart';
const String _storageKey = 'rdvmedecins.language';
final String _defaultLanguage = ServicesBinding.instance.platformDispatcher.locale.languageCode == 'fr' ? 'fr' : 'en';
class TranslationsService extends ChangeNotifier {
String currentLanguage = _defaultLanguage;
// 已加载的词典(避免重新读取本次会话中已见过的资源文件)
// ——与 Vue.js 端(src/i18n.ts)的 loadedDictionaries 优化相同,
// 但这里保存的是解码后的词典本身,而不是
// 简单的已见语言 Set:Vue.js 可以满足于
// Set,因为 vue-i18n 自身会将已加载的词典保存在
// 内存中(setLocaleMessage);这里没有对应的
// 库,因此这一缓存角色必须直接由此
// 文件承担。
final Map<String, Map<String, dynamic>> _dictionaries = {};
// -----------------------------------------------------------------------
// 只应调用一次,在 lib/main.dart 中,位于 runApp(...) 之前:
// 恢复上一次启动时存储的语言(如果有的话),
// 并加载其词典——相当于
// Vue.js 端 createLanguageStore() 的最后一个代码块(在
// localStorage 中读取 savedLanguage),但出于
// 已在 core/services/auth_service.dart 中记录的相同原因而显式异步
// (shared_preferences 始终是异步的,不同于
// localStorage)。
// -----------------------------------------------------------------------
Future<void> init() async {
String startLanguage = _defaultLanguage;
try {
final prefs = await SharedPreferences.getInstance();
startLanguage = prefs.getString(_storageKey) ?? _defaultLanguage;
} catch (_) {
// 没有可读取的偏好设置:以默认语言启动(英语,在法语设备上
// 则为法语),与 Vue.js 端相同。
}
await _loadDictionary(startLanguage);
currentLanguage = startLanguage;
// 这里没有 notifyListeners(),原因与
// AuthService.init() 中相同:此方法在
// runApp(...) 之前被 await,因此还没有任何组件(Widget)在监听这个 ChangeNotifier。
}
// -----------------------------------------------------------------------
// 相当于 Vue.js 端的 changeLanguage(language)(由
// lib/app.dart 的 FR/EN 按钮触发,见本章后文)。
// -----------------------------------------------------------------------
Future<void> changeLanguage(String language) async {
if (language == currentLanguage) {
return;
}
await _loadDictionary(language);
currentLanguage = language;
notifyListeners(); // 而这里,相反,应用已经在运行:我们确实要通知
try {
final prefs = await SharedPreferences.getInstance();
await prefs.setString(_storageKey, language);
} catch (_) {
// 即使存储失败,语言更改在本次运行中仍然有效
// ——只有之后的重启才会受影响。
}
}
// -----------------------------------------------------------------------
// 相当于 Vue.js 端的 loadDictionary(language)——相同的
// 缓存原则(loadedDictionaries),但读取的是嵌入的
// 资源,而不是网络 fetch()(见本文件的头部注释)。
// -----------------------------------------------------------------------
Future<void> _loadDictionary(String language) async {
if (_dictionaries.containsKey(language)) {
return; // 在之前的语言切换中已加载
}
final content = await rootBundle.loadString('assets/i18n/$language.json');
_dictionaries[language] = jsonDecode(content) as Map<String, dynamic>;
}
// -----------------------------------------------------------------------
// 翻译函数本身——由组件(Widget)调用 t('LOGIN.TITLE')
// (见 lib/features/...),与 Vue.js 端的 t('LOGIN.TITLE')
// (useI18n().t)完全一样。键是“带点号的”(用点分隔
// 每一级):因此我们每次下降一段
// 进入嵌套的 JSON 词典,而不是像 vue-i18n 内部那样一次性
// 将词典展平——这个选择
// 对于这两个词典的规模来说已绰绰有余。
// -----------------------------------------------------------------------
String t(String key) {
final dictionary = _dictionaries[currentLanguage];
if (dictionary == null) {
return key; // 词典尚未加载:作为最后手段,显示键本身
}
dynamic currentValue = dictionary;
for (final segment in key.split('.')) {
if (currentValue is Map<String, dynamic> && currentValue.containsKey(segment)) {
currentValue = currentValue[segment];
} else {
return key; // 未找到键:与上面相同的回退
}
}
return currentValue is String ? currentValue : key;
}
}
|
我们来逐段讲解这段代码:
- 第 16–31 行:头部注释详细说明了整个客户端中最重要的平台差异(PLATFORM DIFFERENCE)——[src/i18n.ts] 通过 [fetch("/i18n/{language}.json")]获取每个字典,这个 URL 依赖于 Web 服务器(WEB SERVER);而移动应用或桌面应用并没有 Web 服务器,因此使用 [rootBundle.loadString(...)] 而不是网络调用——无论在哪个平台上,同一份代码都能在全部三种环境中正常工作(参见第 5 章)。
- 第 66–80 行:[init()] ——恢复已保存的语言(或默认语言:英语,在法语设备上则为法语)并加载其字典;与 [AuthService.init()] 一样,这里没有 [notifyListeners()] (现阶段没有任何组件在监听这个 [ChangeNotifier] )。
- 第 107–113 行:[_loadDictionary(language)] ——缓存原理与 [loadedDictionaries] 在 [Vue.js] 一侧相同,但它直接存储解码后的字典,而不是简单地用一个 [Set] 记录曾经见过的语言:[vue-i18n] 会把字典保存在内存中([setLocaleMessage]);而在这里,这一缓存职责必须由该文件自己直接承担。
- 第 124–138 行:[String t(String key) { ... }] ——逐段遍历嵌套的字典 JSON([key.split('.')]),而不是像 [vue-i18n] 在内部所做的那样一次性把字典展平——对于这两个字典的规模来说,这一选择已经绰绰有余。
5.8.2. assets/i18n/fr.json 和 assets/i18n/en.json
原样取自 [public/i18n/fr.json]/[en.json] ([Vue.js] 客户端),只有一处改动:键 [APP.TITLE] 现在指向 “[Flutter]”,而不再是 “[Vue.js]”。两个文件在结构上必须保持一致(两种语言中的键相同)——这可以确保每个键在两个字典中都存在。
5.9. 功能层

每个功能对应一个组件(Widget):登录屏幕、选择医生和日期、查看日程,以及预约对话框。
5.9.1. lib/features/login/login_page.dart
移植自 [src/app/features/login/Login.vue]:登录屏幕。
| // =========================================================================
// features/login/login_page.dart
// -------------------------------------------------------------------------
// src/app/features/login/Login.vue(本课程的 Vue.js 客户端)的移植:
// 登录界面。与它的 Vue.js 对应文件一样,这个组件(Widget)对日程或预约
// 一无所知:它只是收集一个
// (login, password)对,传给 AuthService.logIn(...),
// 并显示可能出现的错误。
//
// 与 Vue.js 的结构性差异:Login.vue 用简单的 ref(...) 声明其本地状态
// (login、password、submitting、error)——Vue.js 随后
// 会在其中一个 ref 变化时自动“重绘” <template>,
// 而没有“有状态或无状态的组件(Widget)”这种概念。Flutter 明确区分
// 两种组件(Widget):StatelessWidget(构造之后
// 什么都不会变)和 StatefulWidget(拥有可变状态,
// 并知道如何通过 setState(...) 重绘自身)。这个组件需要
// 记住用户输入的内容,并且在 submitting/error 变化时
// 知道如何重绘自身:所以它是 StatefulWidget——下面的
// LoginPage 类只声明 createState(),所有状态和
// 所有逻辑都在 _LoginPageState 中,即与之关联的“孪生”
// 类。
// =========================================================================
import 'package:flutter/material.dart';
import 'package:provider/provider.dart';
import '../../core/i18n/translations_service.dart';
import '../../core/services/auth_service.dart';
class LoginPage extends StatelessWidget {
const LoginPage({super.key});
@override
Widget build(BuildContext context) {
return const _LoginForm();
}
}
class _LoginForm extends StatefulWidget {
const _LoginForm();
@override
State<_LoginForm> createState() => _LoginFormState();
}
class _LoginFormState extends State<_LoginForm> {
// TextEditingController:不同于 Vue.js 端的 v-model="login"
// (它用单个属性
// 直接将字段与 ref 双向绑定),Flutter 的
// TextField 组件(Widget)没有内置的双向绑定——必须显式持有一个控制器,
// 读取它(controller.text),并在组件(Widget)销毁后释放它(dispose()),
// 见下面的 dispose()。写起来更冗长,
// 但让一种生命周期(创建 -> 读取 -> 释放
// 资源)变得显式,而 Vue.js 会在幕后为 ref 自行管理这一切。
final TextEditingController _loginController = TextEditingController();
final TextEditingController _passwordController = TextEditingController();
bool _submitting = false;
String? _error;
@override
void dispose() {
// 释放与控制器相关的资源——忘记这一步
// 会在每次重新创建此界面时造成内存泄漏。Vue.js 的 ref() 是
// 与其他对象一样由垃圾回收器回收的
// 简单 JavaScript 对象,
// 无需考虑这一步。
_loginController.dispose();
_passwordController.dispose();
super.dispose();
}
Future<void> _onSubmit() async {
final login = _loginController.text.trim();
final password = _passwordController.text;
if (login.isEmpty || password.isEmpty) {
return;
}
setState(() {
_error = null;
_submitting = true;
});
try {
// context.read<AuthService>():“一次性”读取,不重新订阅
// 后续变化(不同于 context.watch<...>(),见
// lib/app.dart)——恰好适合由
// 用户操作触发的一次性调用,而不是必须
// 保持最新的显示。它是 Flutter/provider 中相当于
// Vue.js 端 "const auth = useAuth();" 的写法,在那里 auth.logIn(...) 只是
// 直接调用,没有任何特殊区分(Vue.js 没有
// 这种一次性读取/重新订阅的区别:useAuth() 总是返回
// 同一个响应式对象,无论如何使用它)。
await context.read<AuthService>().logIn(login, password);
if (!mounted) return; // 在等待服务器期间,组件(Widget)可能已被销毁
setState(() => _submitting = false);
} catch (_) {
if (!mounted) return;
setState(() {
_submitting = false;
_error = 'LOGIN.ERROR';
});
}
}
@override
Widget build(BuildContext context) {
// context.watch<TranslationsService>():不同于上面 _onSubmit() 中使用的
// context.read<AuthService>(),我们在这里
// 希望此组件(Widget)在语言更改时自动重绘自身
// (lib/app.dart 的 FR/EN 按钮)——watch() 订阅
// 后续变化,而 read() 只做一次性读取。
final t = context.watch<TranslationsService>().t;
return Center(
child: ConstrainedBox(
constraints: const BoxConstraints(maxWidth: 420),
child: Card(
child: Padding(
padding: const EdgeInsets.all(24),
// Form 将各字段分组,并允许在其中任何一个字段中按
// “Enter”提交(下面的 onFieldSubmitted)——
// 相当于 Login.vue 的 <form @submit.prevent="onSubmit">:
// 在字段中按 Enter 和点击按钮
// 都会触发同一个 onSubmit()。
child: Column(
mainAxisSize: MainAxisSize.min,
crossAxisAlignment: CrossAxisAlignment.stretch,
children: [
Text(t('LOGIN.TITLE'), style: Theme.of(context).textTheme.titleLarge),
const SizedBox(height: 16),
if (_error != null) ...[
Container(
padding: const EdgeInsets.all(8),
decoration: BoxDecoration(
color: Theme.of(context).colorScheme.errorContainer,
borderRadius: BorderRadius.circular(4),
),
child: Text(
t(_error!),
style: TextStyle(color: Theme.of(context).colorScheme.onErrorContainer),
),
),
const SizedBox(height: 16),
],
TextField(
controller: _loginController,
decoration: InputDecoration(labelText: t('LOGIN.LOGIN_LABEL')),
textInputAction: TextInputAction.next,
),
const SizedBox(height: 12),
TextField(
controller: _passwordController,
decoration: InputDecoration(labelText: t('LOGIN.PASSWORD_LABEL')),
obscureText: true,
textInputAction: TextInputAction.done,
// onSubmitted:由“Enter”键(或其
// 移动端虚拟键盘的等价按键)触发——对应于在 Vue.js 端放在 <form> 标签上的
// @submit.prevent,
// 这里则直接放在表单的最后一个字段上。
onSubmitted: (_) => _onSubmit(),
),
const SizedBox(height: 20),
FilledButton(
onPressed: _submitting ? null : _onSubmit,
child: Text(_submitting ? t('LOGIN.SUBMITTING') : t('LOGIN.SUBMIT')),
),
const SizedBox(height: 16),
Text(
'${t('LOGIN.DEMO_ACCOUNTS_PREFIX')} admin / admin ${t('LOGIN.DEMO_ACCOUNTS_ADMIN')} '
'${t('LOGIN.DEMO_ACCOUNTS_OR')} user / user ${t('LOGIN.DEMO_ACCOUNTS_USER')}.',
style: Theme.of(context).textTheme.bodySmall,
),
],
),
),
),
),
);
}
}
|
我们来逐段讲解这段代码:
- 第 39–44 行:[LoginPage] (一个简单的 [StatelessWidget] 前端) 把一切(EVERYTHING)都委托给 [_LoginForm]/[_LoginFormState] ——头部注释解释了为什么这个屏幕必须保存用户输入的内容,并且在 [_submitting]/[_error] 变化时重绘自身,因此不能(CANNOT)只是一个 [StatelessWidget],这不同于 [Login.vue],在那里 [ref(...)] 并不做这样的区分。
- 第 55–56 行:[final TextEditingController _loginController = TextEditingController();] ——取代 [v-model="login"]:[TextField] 中没有内置的双向绑定,必须显式指定一个控制器。
- 第 61–71 行:[dispose() { _loginController.dispose(); _passwordController.dispose(); ... }] ——释放这两个控制器;如果在这里遗漏,每次重新创建该屏幕时都会造成内存泄漏,而 [Vue.js] 则无需考虑这一步(其 [ref()] 对象会直接被垃圾回收器回收)。
- 第 93–102 行:[await context.read<AuthService>().logIn(login, password);] 位于 [try/catch] 之中——[context.read<...>()](一次性读取,不重新订阅),而不是 [context.watch<...>()] (参见 [lib/app.dart]),它非常适合由用户操作触发的一次性调用。
- 第 160 行:[onSubmitted: (_) => _onSubmit(),] 放在最后一个字段(密码)上——对应于 [@submit.prevent="onSubmit"],它在 [Vue.js] 一侧设置在 [<form>] 标签上:在字段中按下回车键以及点击按钮,都会触发同一个 [_onSubmit()]。
5.9.2. lib/features/doctor_day_picker/doctor_day_picker.dart
移植自 [src/app/features/doctor-day-picker/DoctorDayPicker.vue]:选择医生和日期,然后请求查看其日程。
| // =========================================================================
// features/doctor_day_picker/doctor_day_picker.dart
// -------------------------------------------------------------------------
// 移植自 src/app/features/doctor-day-picker/DoctorDayPicker.vue(本课程的 Vue.js
// 客户端):用于选择医生和
// 日期,然后请求查看其日程的组件(Widget)。
//
// Vue.js 的 [defineProps]/[defineEmits](props 作为输入,事件作为
// 输出)在这里非常直接地变成了 Dart 的构造函数:props
// 就是构造函数的命名参数(doctors、onSearch),而
// “触发事件”就是调用作为参数收到的函数
// ——这与本课程的 React 客户端已经做出的选择完全相同
// (函数 prop,onSearch),而不是 Vue.js 特有的显式
// [defineEmits] 声明。Flutter 和 React 一样,
// 在语法上不区分“普通 prop”和“用于
// 通知父组件的 prop”:它就是一个普通函数,由
// 父组件在构建此组件时传入(参见 lib/app.dart)。
// =========================================================================
import 'package:flutter/material.dart';
import 'package:intl/intl.dart';
import 'package:provider/provider.dart';
import '../../core/i18n/translations_service.dart';
import '../../core/models/appointment_models.dart';
// "yyyy-MM-dd" 格式——与 Vue.js 一侧的日期格式相同
// (new Date().toISOString().slice(0, 10)),但这里通过 intl 包显式构建,
// 而不是通过截取字符串:Dart 的 DateTime
// 没有内置的 toISOString() 方法。
final DateFormat _dayFormat = DateFormat('yyyy-MM-dd');
class DoctorDayPicker extends StatefulWidget {
final List<Doctor> doctors;
// onSearch(doctorId, day):直接等价于
// Vue.js 一侧的 "search: [criteria: { doctorId: number; day: string }]"
// ——这里是两个位置参数,而不是单个对象
// {doctorId, day},在 Dart 中两种选择同样有效。
final void Function(int doctorId, String day) onSearch;
const DoctorDayPicker({super.key, required this.doctors, required this.onSearch});
@override
State<DoctorDayPicker> createState() => _DoctorDayPickerState();
}
class _DoctorDayPickerState extends State<DoctorDayPicker> {
// 纯粹属于此组件的本地状态(菜单中选中的内容,
// 在用户点击按钮之前)——直接等价于 Vue.js 一侧的 selectedDoctorId/selectedDay,
// 这里是 _DoctorDayPickerState 的普通字段,而不是 ref(...):
// Flutter 的 StatefulWidget 对本地字段无需任何特殊“包装”,
// 只需 setState(...)
// (参见下面的 _onDoctorChoice)
// 即可通知需要重绘。
int? _selectedDoctorId;
DateTime _selectedDay = DateTime.now();
Future<void> _pickDay() async {
// Flutter 没有 <input type="date"> 的直接等价物(一个
// 浏览器原生的日期输入组件,Vue.js 在 Web 上可以
// 受益于它):在此客户端面向的 3 种环境
// (移动端、桌面端、Web)中,日期选择器由 Flutter 自己绘制
// (见下面的 showDatePicker(...))——这是一个 Material
// 组件,在 3 个目标平台上外观一致。这是“一份代码库覆盖 3 种
// 环境”这一承诺的非常具体的例证:Vue.js 依赖浏览器的
// 内置构件
// (移动端和桌面端没有),
// 而 Flutter 提供自己的构件,在所有平台上都可用。
final picked = await showDatePicker(
context: context,
initialDate: _selectedDay,
firstDate: DateTime(2020),
lastDate: DateTime(2100),
);
if (picked != null) {
setState(() => _selectedDay = picked);
}
}
void _onSearchClick() {
final doctorId = _selectedDoctorId;
if (doctorId == null) {
return; // 在这种情况下按钮本来就是禁用的(参见下面的 build())
}
// widget.onSearch(...):调用从父组件收到的函数
// ——完全等价于 Vue.js 一侧的 emit('search', ...),或
// React 一侧对 onSearch(...) prop 的调用。这里需要 "widget."
// 前缀,因为 _DoctorDayPickerState 是与 DoctorDayPicker 分开的
// 另一个类(State/Widget 分离是 Flutter 特有的设计,
// 原因参见 lib/features/login/login_page.dart 的文件头):
// 状态对象正是通过它
// 来访问拥有它的组件的参数。
widget.onSearch(doctorId, _dayFormat.format(_selectedDay));
}
@override
Widget build(BuildContext context) {
final t = context.watch<TranslationsService>().t;
// 这三个字段在这里只构建一次,然后由下面的
// LayoutBuilder 进行布局:宽屏上并排(Row),
// 窄屏上堆叠(Column)。竖屏手机的宽度只有
// 约 360 像素:三个字段排成一行时,每个字段只有
// 大约一百像素宽,会发生溢出。
//
// DropdownButtonFormField<int>:Flutter 中等价于
// HTML <select> 的组件——与 Vue.js 一侧的 v-model="selectedDoctorId"
// (单个双向绑定)不同,
// Flutter
// 显式地区分“显示的值”(value:)和“对变化的响应”
// (onChanged:),与 React 的方式类似
// (:value + @change),原始 .vue 文件中已作过比较。
final doctorField = DropdownButtonFormField<int>(
// isExpanded:标签占满全部可用宽度(过长时会被
// 干净地截断),而不是溢出。
isExpanded: true,
decoration: InputDecoration(labelText: t('DOCTOR_DAY_PICKER.DOCTOR_LABEL')),
value: _selectedDoctorId,
hint: Text(t('DOCTOR_DAY_PICKER.CHOOSE_DOCTOR')),
// .map(...).toList():Flutter 中等价于
// v-for="doctor in doctors" :key="doctor.id"——这里,
// “稳定”标识符(Vue.js 一侧的 :key)就是
// 每个
// DropdownMenuItem 的 [value:](doctor.id),
// Flutter 自己用它来判断当前选中的是哪一项。
items: widget.doctors
.map(
(doctor) => DropdownMenuItem(
value: doctor.id,
child: Text('${doctor.title} ${doctor.firstName} ${doctor.lastName}'),
),
)
.toList(),
onChanged: (id) => setState(() => _selectedDoctorId = id),
);
// InkWell:使整个区域“可点击”——点击
// 其中任何位置都会打开日期选择器
// (上面的 _pickDay)。这是手工重建
// Vue.js 一侧由浏览器通过
// <input type="date" v-model="selectedDay"> “免费”提供的功能。
// 使用 InputDecorator(而不是“伪装”的 TextField)来显示
// 日期,而无需持有 TextEditingController——这里
// 没有任何内容需要用键盘输入,只需显示一个值
// 并拦截一次点击:因此不需要
// lib/features/login/login_page.dart 中为真正可编辑字段所遇到的
// 创建/销毁(create/dispose)生命周期。
final dayField = InkWell(
onTap: _pickDay,
child: InputDecorator(
decoration: InputDecoration(labelText: t('DOCTOR_DAY_PICKER.DAY_LABEL')),
child: Text(_dayFormat.format(_selectedDay)),
),
);
final scheduleButton = FilledButton(
onPressed: _selectedDoctorId == null ? null : _onSearchClick,
child: Text(t('DOCTOR_DAY_PICKER.VIEW_SCHEDULE')),
);
return Card(
child: Padding(
padding: const EdgeInsets.all(16),
// LayoutBuilder:用此处组件树中实际可用的宽度
// (constraints.maxWidth)调用其 builder,并在宽度变化时
// (屏幕旋转、窗口调整大小)再次调用
// ——因此布局会自行适应。
child: LayoutBuilder(
builder: (context, constraints) {
if (constraints.maxWidth < 600) {
return Column(
crossAxisAlignment: CrossAxisAlignment.stretch,
children: [
doctorField,
const SizedBox(height: 12),
dayField,
const SizedBox(height: 12),
scheduleButton,
],
);
}
return Row(
crossAxisAlignment: CrossAxisAlignment.end,
children: [
Expanded(flex: 5, child: doctorField),
const SizedBox(width: 12),
Expanded(flex: 4, child: dayField),
const SizedBox(width: 12),
Expanded(flex: 3, child: scheduleButton),
],
);
},
),
),
);
}
}
|
我们来逐段讲解这段代码:
- 第 59–79 行:[_pickDay()] 调用 [showDatePicker(...)]——这是“一份代码适用于三种环境”这一承诺的非常具体的例证:[Vue.js] 依赖的是 [<input type="date">],这是浏览器的原生构件(在移动端和桌面端不可用),而 [Flutter] 自行渲染一个选择器,它是一个 [Material] 组件,在全部三个目标上完全一致。
- 第 114–136 行:[DropdownButtonFormField<int>(value: _selectedDoctorId, ..., onChanged: (id) => setState(() => _selectedDoctorId = id))] ——用显式的 [value:]/[onChanged:] 取代 [v-model="selectedDoctorId"] 这一对,类似于本课程中在 [React] 方面已经遇到过的 [:value]/[@change] 这一对。
- 第 149–155 行:[InkWell(onTap: _pickDay, child: InputDecorator(...))] ——手动重新构建了浏览器通过 [<input type="date">]“免费”提供的功能;[InputDecorator] (而不是“伪装”的 [TextField])显示日期,而无需 [TextEditingController]。
- 第 169–194 行:[LayoutBuilder(builder: (context, constraints) { ... })] ——[Flutter] 对宽度未知的屏幕的应对方案:[builder] 接收该位置实际可用的宽度([constraints.maxWidth]),并在宽度变化(屏幕旋转、窗口调整大小)时再次被调用。在 600 像素以下——竖屏手机的宽度只有约 360 像素——三个字段会堆叠在一个 [Column] 中;超过这一宽度,它们则在一个 [Row] 中并排显示。这三个字段先前已在变量 [doctorField]、[dayField] 和 [scheduleButton]中构造一次:变化的只是它们的布局。如果只使用第一个版本中的 [Row] ,在竖屏手机上每个字段只有大约一百像素的宽度,内容就会溢出(调试模式下出现黄黑相间的横幅“RIGHT OVERFLOWED BY … PIXELS”);下拉列表中的 [isExpanded: true] 可以防止医生姓名过长时出现同样的溢出。
5.9.3. lib/features/schedule/schedule_view.dart
移植自 [src/app/features/schedule/Schedule.vue]:医生在某一天的日程——可预约的时段(“预约”按钮)或已被预约的时段(患者 + “取消”按钮)。
| // =========================================================================
// features/schedule/schedule_view.dart
// -------------------------------------------------------------------------
// 移植自 src/app/features/schedule/Schedule.vue(本课程的 Vue.js 客户端):
// 显示某位医生在指定日期的日程——其时间段列表,
// 每个时间段要么空闲(“预约”按钮),要么已被预约
// (患者姓名 + “取消”按钮)。
//
// 由于添加了身份验证,此组件还会接收
// canEdit:为 false(USER 角色)时,“预约”/“取消”按钮
// 会消失——仍可查看日程,但为只读(无论如何服务器
// 也会拒绝 USER 的这些操作,返回 403 Forbidden,
// 参见服务器端的 RolesGuard)。
//
// [v-if]/[v-else] 和 [v-for](Vue.js)在这里变成了普通的 Dart 表达式:
// Flutter 和之前的 React 一样(参见 Schedule.vue 的注释),
// 没有独立于编程语言之外的“模板语言”——
// 普通 Dart 的 const/if/for 以及 ?./?? 运算符
// 就足以
// 直接在下面的 build(...) 方法中表达条件和列表。
// =========================================================================
import 'package:flutter/material.dart';
import 'package:provider/provider.dart';
import '../../core/i18n/translations_service.dart';
import '../../core/models/appointment_models.dart';
class ScheduleView extends StatelessWidget {
final DoctorDaySchedule? schedule;
final bool canEdit;
final void Function(SlotJson slot) onBook;
final void Function(AppointmentJson appointment) onCancel;
const ScheduleView({
super.key,
required this.schedule,
required this.canEdit,
required this.onBook,
required this.onCancel,
});
// 小型格式化工具函数,输出 "8:05" 而不是 "8:5"
// ——与 Vue.js 一侧的 formatTime(...) 如出一辙。
static String _formatTime(int h, int m) => '$h:${m.toString().padLeft(2, '0')}';
void _onSlotClick(DoctorDaySlot daySlot) {
if (!canEdit) {
return; // 在这种情况下按钮本来就不显示(参见下面的 build())
}
final appointment = daySlot.appointment;
if (appointment == null) {
onBook(daySlot.slot); // 空闲时间段:提供预约功能
} else {
onCancel(appointment); // 已被预约的时间段:提供取消现有预约的功能
}
}
@override
Widget build(BuildContext context) {
final t = context.watch<TranslationsService>().t;
final schedule = this.schedule;
if (schedule == null) {
return Padding(
padding: const EdgeInsets.symmetric(vertical: 24),
child: Text(
t('SCHEDULE.EMPTY_STATE'),
style: TextStyle(color: Theme.of(context).colorScheme.outline),
),
);
}
return Card(
child: Padding(
padding: const EdgeInsets.all(16),
child: Column(
crossAxisAlignment: CrossAxisAlignment.start,
children: [
Text(
'${t('SCHEDULE.TITLE_PREFIX')} ${schedule.day} - ${schedule.doctor.title} '
'${schedule.doctor.firstName} ${schedule.doctor.lastName}',
style: Theme.of(context).textTheme.titleMedium,
),
const SizedBox(height: 12),
// DataTable:Flutter Material 中等价于 Schedule.vue 中 HTML <table>
// 的组件——与 HTML 不同,其行必须
// 在 Dart 中通过 .map(...).toList() 显式构建
// (这里同样等价于
// v-for="daySlot in
// schedule.slots" :key="daySlot.slot.id"——DataRow
// 不需要像 Vue.js/React 那样的显式 "key":列表在每次渲染时
// 都会被整体重建,Flutter 在这里不会尝试复用现有的行)。
SingleChildScrollView(
scrollDirection: Axis.horizontal,
child: DataTable(
columns: [
DataColumn(label: Text(t('SCHEDULE.COLUMN_SLOT'))),
DataColumn(label: Text(t('SCHEDULE.COLUMN_STATUS'))),
const DataColumn(label: Text('')),
],
rows: schedule.slots.map((daySlot) {
final appointment = daySlot.appointment;
final slot = daySlot.slot;
return DataRow(
// 空闲时间段使用略带色调的背景——对应
// Vue.js 一侧的 "free-slot" CSS 类。
color: appointment == null
? WidgetStateProperty.all(Theme.of(context).colorScheme.surfaceContainerLow)
: null,
cells: [
DataCell(Text(
'${_formatTime(slot.startHour, slot.startMinute)} - '
'${_formatTime(slot.endHour, slot.endMinute)}',
)),
DataCell(
appointment == null
? Chip(
label: Text(t('SCHEDULE.FREE')),
backgroundColor: Colors.green.shade100,
)
: Chip(
label: Text('${appointment.client?.title ?? ''} ${appointment.client?.firstName ?? ''} ${appointment.client?.lastName ?? ''}'),
),
),
DataCell(
// canEdit:USER 角色为 false(只读)
canEdit
? OutlinedButton(
onPressed: () => _onSlotClick(daySlot),
child: Text(appointment == null ? t('SCHEDULE.BOOK') : t('SCHEDULE.CANCEL_APPOINTMENT')),
)
: const SizedBox.shrink(),
),
],
);
}).toList(),
),
),
],
),
),
);
}
}
|
我们来逐段讲解这段代码:
- 第 43–57 行:[_formatTime(h, m)] 和 [_onSlotClick(daySlot)] ——后者根据 [daySlot.appointment] 是否为 [null] 来区分可预约的时段([onBook(...)])和已被预约的时段([onCancel(...)]),逻辑与 [Vue.js] 一侧完全相同,只不过纯粹用 [Dart] 表达,而不是用 [<template>]。
- 第 96–137 行:[DataTable(columns: [...], rows: schedule.slots.map((daySlot) { ... }).toList())] ——相当于 [Schedule.vue] 中的 [<table>] [HTML] 的 [Material] 版本:其行必须通过 [.map(...).toList()] 显式构造。
- 第 108–110 行:[color: appointment == null ? WidgetStateProperty.all(Theme.of(context).colorScheme.surfaceContainerLow) : null,] ——对应于 [Vue.js] 一侧的 ["free-slot"] [CSS] 类:有条件地为整行应用背景色,这里是通过函数而不是具名的 [CSS] 类来实现。
5.9.4. lib/features/booking_dialog/booking_dialog.dart
移植自 [src/app/features/booking-dialog/BookingDialog.vue]:选择一位患者来预订可预约的时间段——这是整个客户端中与 [Vue.js] 的结构性差异最为明显的文件。
| // =========================================================================
// features/booking_dialog/booking_dialog.dart
// -------------------------------------------------------------------------
// 移植自 src/app/features/booking-dialog/BookingDialog.vue(本课程的 Vue.js
// 客户端):用于选择患者以预约
// 空闲时间段的(模态)窗口。
//
// 与 Vue.js(以及 lib/features/ 中的其他三个
// 组件)的重要结构差异:BookingDialog.vue 是一个始终
// 存在于组件树中的组件,其 [open] prop(由
// App.vue 持有的布尔值)只是控制显示(v-if="open")——与本课程的 Angular 和
// React 客户端的选择完全相同,其动机是
// 避免 Vue.js 与 Bootstrap 的 JavaScript 争夺
// 同一条信息(“模态框是否打开?”)。
//
// Flutter 没有这个问题:对话框不是一个在组件树中
// 按条件显示或隐藏的组件,而是一个真正的
// 页面,在打开时通过 showDialog(...) 被压入导航栈(Navigator),
// 关闭时自动弹出。因此这里既不需要在父组件中持有
// “open: bool” 状态(参见 lib/app.dart,其中没有与 Vue.js 一侧
// slotBeingBooked 等价的字段),也不需要触发 “confirm”/“close” 事件:
// showDialog(...) 返回一个 Future,它以传给 Navigator.pop(...) 的
// 值完成——用户未选择就关闭则为 null,
// 否则为所选患者的 id。
// 由调用方组件(lib/app.dart)await 这个 Future
// 来决定下一步做什么——与 Vue.js 的两个事件相比,
// 通信方向
// 完全颠倒了。
// =========================================================================
import 'package:flutter/material.dart';
import 'package:provider/provider.dart';
import '../../core/i18n/translations_service.dart';
import '../../core/models/appointment_models.dart';
// -----------------------------------------------------------------------
// 辅助函数:打开对话框并返回所选
// 患者的 id(如果用户取消/未选择就关闭,则返回 null)。
// lib/app.dart 调用的正是这个函数,而绝不直接调用下面的
// _BookingDialogContent 的构造函数。
// -----------------------------------------------------------------------
Future<int?> openBookingDialog({
required BuildContext context,
required SlotJson slot,
required List<Client> clients,
}) {
return showDialog<int>(
context: context,
builder: (_) => _BookingDialogContent(slot: slot, clients: clients),
);
}
class _BookingDialogContent extends StatefulWidget {
final SlotJson slot;
final List<Client> clients;
const _BookingDialogContent({required this.slot, required this.clients});
@override
State<_BookingDialogContent> createState() => _BookingDialogContentState();
}
class _BookingDialogContentState extends State<_BookingDialogContent> {
int? _selectedClientId;
void _onConfirmClick() {
final clientId = _selectedClientId;
if (clientId == null) {
return;
}
// Navigator.pop(context, clientId):关闭对话框,并将 clientId
// 作为 openBookingDialog(...) 所返回 Future 的结果传出
// ——一次调用就相当于 Vue.js 一侧的
// emit('confirm', { clientId }) 再加上关闭(隐式,由父组件
// 通过 [open] 驱动)。
Navigator.pop(context, clientId);
}
void _onCloseClick() {
// 不带第二个参数的 Navigator.pop(context):openBookingDialog(...) 返回的
// Future 以 null 完成——相当于 Vue.js 一侧的
// emit('close')。
Navigator.pop(context);
}
@override
Widget build(BuildContext context) {
final t = context.watch<TranslationsService>().t;
final slot = widget.slot;
// AlertDialog:专用于对话框的 Material 组件——
// 自身就提供了变暗的背景(相当于 Vue.js 一侧 “手工” 放置的
// .modal-backdrop)以及标准的关闭行为
// (点击对话框外部,桌面端/Web 上按 Escape 键)——
// 这些行为 Vue.js 客户端必须自己重建,
// Bootstrap 只能自动处理其中一部分。
return AlertDialog(
title: Text(t('BOOKING_DIALOG.TITLE')),
content: Column(
mainAxisSize: MainAxisSize.min,
crossAxisAlignment: CrossAxisAlignment.start,
children: [
Text(
'${t('BOOKING_DIALOG.SLOT_FROM')} ${slot.startHour}:${slot.startMinute.toString().padLeft(2, '0')} '
'${t('BOOKING_DIALOG.SLOT_TO')} ${slot.endHour}:${slot.endMinute.toString().padLeft(2, '0')}',
),
const SizedBox(height: 16),
DropdownButtonFormField<int>(
decoration: InputDecoration(labelText: t('BOOKING_DIALOG.PATIENT_LABEL')),
value: _selectedClientId,
hint: Text(t('BOOKING_DIALOG.CHOOSE_PATIENT')),
items: widget.clients
.map(
(client) => DropdownMenuItem(
value: client.id,
child: Text('${client.title} ${client.firstName} ${client.lastName}'),
),
)
.toList(),
onChanged: (id) => setState(() => _selectedClientId = id),
),
],
),
actions: [
TextButton(onPressed: _onCloseClick, child: Text(t('BOOKING_DIALOG.CANCEL'))),
FilledButton(
onPressed: _selectedClientId == null ? null : _onConfirmClick,
child: Text(t('BOOKING_DIALOG.CONFIRM')),
),
],
);
}
}
|
我们来逐段讲解这段代码:
- 第 16–28 行:头部注释概括了该文件中最重要的结构性差异——[BookingDialog.vue] 是一个始终存在(ALWAYS PRESENT)于树中的组件,仅由一个布尔属性([open],由 [App.vue] 持有)控制其是否显示;而 [Flutter] 的对话框则相反,在通过 [showDialog(...)] 显式打开之前从不存在(NEVER present)——它是压入导航栈的一个真正的页面,关闭时会自动出栈。
- 第 43–52 行:[Future<int?> openBookingDialog({...}) { return showDialog<int>(context: context, builder: (_) => _BookingDialogContent(...)); }]——由 [lib/app.dart] 调用的函数;其返回类型([Future<int?>])已经表明它最终会返回所选患者的 ID,或者返回 [null]。
- 第 67–77 行:[Navigator.pop(context, clientId);] ——关闭对话框并(AND)返回 [clientId] ,作为 [Future] 的结果,该 Future 由 [openBookingDialog(...)] 返回——只需一次调用,就相当于在 [Vue.js] 一侧由 [emit('confirm', { clientId })] 加上由父组件驱动的关闭两者共同完成的工作。
- 第 80–84 行:[Navigator.pop(context);] 不带第二个参数——[Future] 随后以 [null] 结束,这相当于 [emit('close')] 在 [Vue.js] 一侧的作用。由 [lib/app.dart] ([_onBookingRequest(...)])来 [await] 这个 [Future],并根据结果是否为 [null] 来决定该做什么——与 Vue.js 的那两个事件相比,通信方向完全反转。
5.10. Flutter Web 应用分步使用指南
5.10.1. 1. 登录屏幕
首次加载时,[shared_preferences] 中没有存储任何会话:[AuthService.isLoggedIn] 等于 [false],于是 [AppRoot] 显示 [LoginPage]。使用无效的用户名/密码组合尝试登录时,会显示由 [_LoginFormState] 存储的错误消息(键 [LOGIN.ERROR])。始终可见的 FR/EN 选择器也会翻译这个屏幕。
| PS C:\Data\st-2026\dev\flutter-nestjs-sept-2026\rdvmedecins_flutter_client> flutter devices
Found 4 connected devices:
sdk gphone16k x86 64 (mobile) • emulator-5554 • android-x64 • Android 17 (API 37) (emulator)
Windows (desktop) • windows • windows-x64 • Microsoft Windows [version
10.0.26200.9457]
Chrome (web) • chrome • web-javascript • Google Chrome 153.0.8010.48
Edge (web) • edge • web-javascript • Microsoft Edge 153.0.4234.48
Run "flutter emulators" to list and start any available device emulators.
If you expected another device to be detected, please run "flutter doctor" to diagnose potential issues. You
may also try increasing the time to wait for connected devices with the "--device-timeout" flag. Visit
https://flutter.dev/setup/ for troubleshooting tips.
PS C:\Data\st-2026\dev\flutter-nestjs-sept-2026\rdvmedecins_flutter_client> flutter run -d edge
|

5.10.2. 2. 以管理员身份登录(角色 ADMIN,拥有完全访问权限)
使用 [admin]/[admin] 登录后,[AppRoot] 不再显示 [LoginPage] ,并加载医生/患者列表([_loadInitialLists()])。在 [DoctorDayPicker] 中选择医生和日期后,会显示日程表,并且可以看到“预约”/“取消”按钮(对于该角色,[canEdit] 等于 [true] )。点击“预约”会打开患者选择对话框([openBookingDialog(...)]);确认之后([AppointmentService.addAppointment(...)]),日程表会重新加载,该时间段显示为已预约。点击“取消”(针对已预约的时间段)会直接调用 [AppointmentService.deleteAppointment(...)] ,并使该时间段重新变为可预约。

- 在 [1] 中,NestJS 服务器的 URL(必须已启动);
- 在 [2-3] 中,管理员的凭据:admin / admin;
- 在 [4] 中:登录服务器;

- 在 [1] 中,选择一位医生;
- 在 [2] 中,选择一个日期;
- 在 [3] 中,查看所选医生在所选日期的日程;


- 在 [1] 中,该预约时间段已被预订;
- 在 [2] 中,退出登录。这会使您回到登录屏幕;
5.10.3. 3. 以普通用户身份登录(角色 USER,只读)
退出登录后,使用 [user]/[user] 登录会显示一个“USER”徽章。日程表仍可查看,但不会出现“预约”/“取消”按钮([canEdit] 等于 [false])——无论如何,服务器都会拒绝该角色执行这两项操作(403 Forbidden,参见第 2 章)。

无法添加或删除预约。
5.11. 尚未涉及或推迟的内容
- 与本课程中的 [Angular]、[React] 和 [Vue.js] 客户端一样,没有专门的演示/调试模式(没有“离线模式”开关)。
- 客户端不会为了教学目的而引入人为的网络延迟——观察到的响应时间就是 [NestJS] 服务器的实际响应时间。
- 没有路由器:与前面的四个变体一样,应用只占一个屏幕(预约对话框除外)。
- 由 [flutter create] ([android/]、[ios/]、[macos/]、[windows/]、[linux/]、[web/])生成的原生项目不随本文档提供(参见第 1 章)——它们会在本地重新生成,并且对任何 [Flutter] 源项目都是相同的。