Skip to content

3. Flutter 入门

3.1. 示例 01:Flutter 应用的结构

3.1.1. 项目

一个 [Flutter] 项目通过 [flutter create] 命令创建:

flutter create --org fr.stahe --platforms=android,web,windows my_application
  • [--org fr.stahe]:应用 ID 的前缀,像域名一样倒写。[Android] 应用将被命名为 [fr.stahe.my_application];同一部手机上安装的两个应用必须有不同的 ID;
  • [--platforms=...]:目标平台。对于每个平台,[flutter create] 会创建一个文件夹([android/]、[web/]、[windows/],如有需要还会有 [ios/]、[macos/]、[linux/] ):这是一个小型的平台专用项目,仅负责启动 [Flutter] 引擎并把应用加载到其中。我们很少修改它(应用的名称、图标和权限);
  • [my_application]:项目名称,同时也是 [Dart] 包名:小写字母、数字和下划线。

该命令会生成一个完整的、可直接运行的应用(一个计数器)。示例项目也是这样创建的,然后手动填充其 [lib/] 文件夹,将二十五个应用合并为一个项目:这样它们共享相同的包,这些包只需下载一次。

3.1.2. pubspec.yaml 文件

文件 [pubspec.yaml] 描述了项目:它的名称、所需的 [Dart] 版本、所使用的包,以及随应用一起打包的文件。示例项目的该文件如下:

# ==========================================================================
# pubspec.yaml - 示例项目的描述
# --------------------------------------------------------------------------
# 一个 Flutter 项目包含全部 25 个示例:每个示例在
# lib/ 下有自己的文件夹和自己的入口点(main.dart),通过
# flutter run 命令的 -t(target)选项指定:
#
#     flutter run -t lib/ex05_controlled_fields/main.dart
#
# 各个库(即 "packages")由
# flutter pub get 命令从 pub.dev 下载(flutter run 会自动执行它)。
# ==========================================================================

name: examples_flutter
description: The 25 small examples of the course Step-by-step introduction to the Flutter framework.
# 不发布到 pub.dev:这是一个应用,而不是库
publish_to: none
version: 1.0.0

environment:
  # 所需的 Dart 语言版本
  sdk: ^3.12.0

dependencies:
  flutter:
    sdk: flutter
  # Web 上的 "干净" 地址(示例 17)
  flutter_web_plugins:
    sdk: flutter
  # Flutter 自身的文本(对话框按钮、日历……)
  # 提供英语和法语两种语言(示例 05、21)
  flutter_localizations:
    sdk: flutter
  # 按语言格式化的日期和数字(示例 09、21)
  intl: any
  # 路由器(示例 17、18)
  go_router: ^16.2.0
  # 由整个应用共享的状态(示例 20、24、25)
  provider: ^6.1.5
  # 保存在设备上的小型键 -> 值字典(示例 20、21、23)
  shared_preferences: ^2.5.3
  # HTTP 请求(示例 22 至 25)
  http: ^1.5.0
  # 显示 SVG 图像(示例 03,以及示例 22 至 25 的验证码)
  flutter_svg: ^2.2.1

dev_dependencies:
  # 测试(以及课程截图,见 test/captures)
  flutter_test:
    sdk: flutter
  # Flutter 团队推荐的风格规则(见 analysis_options.yaml)
  flutter_lints: ^6.0.0

flutter:
  # Material Design 图标(Icons.add、Icons.delete……)
  uses-material-design: true
  # 随应用一起发布的文件:通过路径读取
  assets:
    - assets/
    - assets/i18n/
  # 一种等宽字体(用于显示 JSON),随应用一起发布
  fonts:
    - family: RobotoMono
      fonts:
        - asset: assets/fonts/RobotoMono-Regular.ttf
        - asset: assets/fonts/RobotoMono-Bold.ttf
          weight: 700
  • 第 14–18 行:项目名称(同时也是包名——项目文件通过 [package:examples_flutter/...] 导入)、描述和版本。[publish_to: none]:该项目不是库,永远不会发布到 [pub.dev];
  • 第 20–22 行:所需的 [Dart] 语言版本。前缀 [^] 表示接受同一主版本内的任何更新版本(3.12、3.13……但不包括 4.0);
  • 第 24–45 行:应用所需的包。其中一些来自 [Flutter] SDK 本身([sdk: flutter]):[flutter] (框架)、[flutter_localizations] ([Flutter] 的文本被翻译成各种语言)、[flutter_web_plugins] (Web 专用配置)。其余的从 pub.dev 下载,那里是 [Dart] 包的仓库:它们的用途在注释中有说明,每个包都会在使用它的示例中演示。[intl: any]:任意版本([flutter_localizations] 会自行规定);
  • 第 47–52 行:仅在开发时使用、不包含在发布应用中的包:[flutter_test] (测试)和 [flutter_lints] (分析器风格规则);
  • 第 54–67 行:特定于 [Flutter] 的配置:
    • [uses-material-design: true]:应用使用 [Material Design] 的图标字体([Icons.add]、[Icons.delete]……);
    • [assets]:随 应用 一起提供的文件(图像、词典等),通过其路径读取。指定一个文件夹([assets/])即可直接交付其中包含的所有文件;
    • [fonts]:随应用一起打包的字体;[Roboto Mono] 是一种等宽字体,用于显示 JSON。[Material Design] 的标准字体 [Roboto] 是 [Android] 的系统字体:无需包含它。

包版本遵循与 [npm] 相同的约定:[^16.2.0] 表示接受从 16.2.0 开始的任何 16.x.y 版本。命令 [flutter pub get] 会下载这些包,并将所选的确切版本写入文件 [pubspec.lock]。当 [flutter run] 发现 [pubspec.yaml] 已更改时会自动执行它;[VS Code] 也会在保存该文件时立即运行它。要添加一个包,除了手动编辑该文件,还可以输入 [flutter pub add go_router]:该命令会添加一行,写入该包的最新版本。

3.1.3. analysis_options.yaml 文件

在输入代码时,[Dart] 分析器会检查代码:[VS Code] 用红色下划线标出错误,用黄色或蓝色标出警告。你也可以用 [flutter analyze] 对整个项目运行它。它的规则:

# ==========================================================================
# analysis_options.yaml - Dart 代码分析器的规则
# --------------------------------------------------------------------------
# 分析器在输入代码时就进行检查(VS Code 会为错误加下划线),
# 也可通过 flutter analyze 命令检查。我们以
# Flutter 团队推荐的规则(flutter_lints 包)为基础……
# ==========================================================================

include: package:flutter_lints/flutter.yaml

analyzer:
  language:
    # ……并使其更严格:不允许 dynamic 类型的隐式转换
    strict-casts: true
    strict-raw-types: true

linter:
  rules:
    # 到处使用单引号,与课程示例一致
    prefer_single_quotes: true
    # 从不重新赋值的局部变量使用 "final"
    prefer_final_locals: true
    # 允许过长的字符串(示例中的文本)
    lines_longer_than_80_chars: false
  • 第 9 行:由 [Flutter] 团队推荐的规则([flutter_lints] 包):组件在可能时必须有 [const] 构造函数,控制器必须被释放,等等;
  • 第 14–15 行:更严格的类型检查。[Dart] 是一种静态类型语言,但它有一个类型 [dynamic] (“任意类型”):例如,解码后的 JSON 就由 [dynamic] 构成。[strict-casts] 禁止隐式转换为另一种类型:必须显式书写([json['lastName'] as String]),这样任何错误都会在那里发生并且可见;
  • 第 20–24 行:几条风格规则:字符串使用单引号(如果字符串包含撇号,则使用双引号:["it's"]),以及 [final] 用于从不重新赋值的变量。

3.1.4. 入口点:main.dart

例如,有一个名为 [main.dart] 的文件,其中包含函数 [main]——任何 [Dart] 程序的入口点。示例 01 中的该文件如下:

// =========================================================================
// lib/ex01_first_application/main.dart - 第一个应用
// -------------------------------------------------------------------------
// 在 Flutter 应用中,一切都是组件(WIDGET):一个描述屏幕中某一部分
// (文本、按钮、边距、列……)的对象。
// 组件相互嵌套,形成一棵树(TREE)。
// 组件有一个 build() 方法,它返回(RETURNS)构成该组件的各个组件。
// Flutter 调用 build() 来生成屏幕;每当组件的状态发生变化(setState)时,
// 它都会再次调用(CALLS IT AGAIN)build(),
// 并用新的结果更新屏幕。
// =========================================================================

import 'package:flutter/material.dart';

// "普通" 数据,位于组件之外:它们永远不会改变
const title = 'Welcome to Flutter';
const languages = ['Dart', 'Flutter', 'Material Design'];

// "12:05:09":当前时间,各部分用两位数表示
String currentTime() {
  final d = DateTime.now();
  String twoDigits(int n) => n.toString().padLeft(2, '0');
  return '${twoDigits(d.hour)}:${twoDigits(d.minute)}:${twoDigits(d.second)}';
}

// 每个 Dart 程序的入口点
void main() {
  // runApp:Flutter 接管屏幕,并在其上显示根组件(ROOT widget)
  runApp(const Application());
}

// 根组件:它配置整个应用(标题、主题、第一个界面)。
// StatelessWidget:无状态(WITHOUT state)的组件,完全由其参数描述
class Application extends StatelessWidget {
  const Application({super.key});

  @override
  Widget build(BuildContext context) {
    // MaterialApp:采用 Material Design(Google 的视觉语言)的
    // 颜色和行为的应用
    return MaterialApp(
      title: 'Example 01',
      // 屏幕角落不显示 "DEBUG" 横幅
      debugShowCheckedModeBanner: false,
      // 整个应用的颜色,由一个基础颜色派生而来
      theme: ThemeData(colorSchemeSeed: Colors.indigo),
      home: const HomePage(),
    );
  }
}

// 有状态(WITH state)的组件:它由两部分组成,即组件本身(永不
// 改变)和一个 State 对象(保存会变化的数据)
class HomePage extends StatefulWidget {
  const HomePage({super.key});

  @override
  State<HomePage> createState() => _HomePageState();
}

// "_":这个类是私有的(PRIVATE),在该文件之外不可见
class _HomePageState extends State<HomePage> {
  // 状态(STATE):State 对象的简单字段
  int _counter = 0;
  String _time = currentTime();

  // 按钮所调用的函数
  void _increment() {
    // setState:状态在传给 setState 的函数内部(INSIDE)修改;
    // 然后 Flutter 再次调用 build() 来更新屏幕。我们从不
    // 自己去修改屏幕
    setState(() {
      _counter++;
      _time = currentTime();
    });
  }

  @override
  Widget build(BuildContext context) {
    // Scaffold:Material 界面的结构(顶部栏、主体……)
    return Scaffold(
      appBar: AppBar(title: const Text('Example 01 - a first application')),
      // Padding:在其子组件周围留出边距
      body: Padding(
        padding: const EdgeInsets.all(16),
        // Column:子组件上下排列
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.start,
          children: [
            Text(title, style: Theme.of(context).textTheme.headlineSmall),
            const SizedBox(height: 12),
            const Text(
              'This screen is produced by Flutter, from the main function '
              'and the Application and HomePage widgets.',
            ),
            const SizedBox(height: 8),
            // ${expression} 把表达式的值插入字符串
            Text('It is written in ${languages.join(', ')} (${languages.length} languages).'),
            const SizedBox(height: 16),
            // onPressed:按下按钮时要调用的函数(见示例 04)
            FilledButton(onPressed: _increment, child: const Text('Click me')),
            const SizedBox(height: 16),
            Text(
              'You clicked $_counter times (last click: $_time).',
              style: const TextStyle(fontWeight: FontWeight.bold, color: Color(0xFF087EA4)),
            ),
          ],
        ),
      ),
    );
  }
}

让我们从末尾开始:程序。

  • 第 13 行:[Material] 库,来自 [Flutter]:包含 [Material Design] 的所有组件,这是 [Google] 的视觉语言(按钮、输入字段、栏、窗口等)。它会自行导入 [Flutter] 的其余部分;
  • 第 16–17 行:两个普通的数据值,声明在组件之外:它们永远不会改变。[const]:编译时已知的常量;
  • 第 20–23 行:一个普通函数,返回当前时间,格式为“12:05:09”。它自己包含一个小函数 [twoDigits],用 [=>] 写在一行里;
  • 第 27–29 行:函数 [main],在启动时被调用。[runApp] 启动 [Flutter]:它接管屏幕,并显示传给它的组件——即应用的 根 组件。

根组件 [Application]:

  • 第 34 行:组件就是一个类。这个类继承自 [StatelessWidget],即一个 无状态组件:它显示的内容完全取决于其参数,自身永远不会改变;
  • 第 29 行:它的构造函数。[{super.key}]:传给父类的可选命名参数。每个组件都有一个:用于标识它的“key”(见示例 04)。该构造函数是 [const] 的:[Application()] 可以是一个常量,[Flutter] 永远不需要重新构造它;
  • 第 38–47 行:[build] 方法,是组件的核心。它返回构成该组件的各个组件。[@override]:它重写了父类的 [build] 方法。参数 [context] 表示该组件在组件树中的位置:它用于获取其祖先提供的内容(例如第 90 行的主题);
  • 第 41–47 行:[MaterialApp] 是把组件树变成 [Material] 应用的组件:包含标题([title],即应用在手机最近应用列表或浏览器标签页中的名称)、主题([theme])和主屏幕([home])。[debugShowCheckedModeBanner: false] 会移除开发版应用在角落显示的“DEBUG”横幅。[ThemeData(colorSchemeSeed: Colors.indigo)]:应用中的所有颜色(按钮、栏、字段等)都由一种基础颜色派生,依据 [Material Design] 3 的规则。

第一个屏幕 [HomePage] 带有会变化的数据:它是一个 有状态组件。

  • 第 54–58 行:[StatefulWidget] 由两部分组成。组件本身和任何组件一样永远不会改变(它的字段是 [final] 的);它唯一的任务是通过 [createState] 创建一个 [State] 对象,由这个对象来保存会变化的数据。[Flutter] 只创建该对象一次,只要组件仍停留在树中的同一位置,就一直保留它;
  • 第 62 行:对象 [State]。它的名称以下划线开头:在 [Dart] 中,以 [_] 开头的一切都是 私有的 ,在文件之外不可见;
  • 第 64–65 行:状态:简单字段,属于 [State] 对象;
  • 第 68–75 行:按钮调用的方法。它不影响屏幕:它修改状态,在 传给 [setState] 的函数内部进行。[setState] 执行这个函数,然后通知 [Flutter] 状态已改变:[Flutter] 会调用 [build],将新的组件树与旧的组件树进行比较,并重绘发生变化的部分;
  • 第 79–105 行:屏幕的 [build] 方法:
    • [Scaffold] (“脚手架”)是 [Material] 屏幕的结构:顶部栏([appBar])、主体([body]),以及按需提供的底部栏、浮动按钮和侧边菜单;
    • [AppBar]:顶部栏;它的标题是一个组件([Text]),就像 [Flutter] 中几乎所有的东西一样;
    • [Padding]:围绕其唯一子组件 [child] 的边距。[EdgeInsets.all(16)]:每一边 16 个点(逻辑“点”,与屏幕密度无关:在截图所示的手机上约为 2.6 像素);
    • [Column]:它的子组件 [children] 上下依次排列。[crossAxisAlignment: CrossAxisAlignment.start]:左对齐(列的“交叉”轴是水平轴);
    • [Text]:文本。它的样式可以从主题派生:[Theme.of(context).textTheme.headlineSmall] 是“小标题”的样式;
    • [SizedBox]:指定高度的空盒子——两个组件之间的间隔;
    • 第 98 行:[${expression}] 把表达式的值插入字符串;对于简单变量,[$_counter] 就够了(第 104 行);
    • 第 101 行:一个按钮。[onPressed] 接收按下按钮时要调用的函数。我们传入函数本身,不带 括号:[onPressed: _increment()] 会在构建屏幕时立即调用它;
    • 第 104–105 行:取决于状态的文本。状态改变时,会调用 [build] ,这段文本随之改变。

关于 [Dart] 的两点说明:

  • 几乎所有组件的参数都是 命名参数 ([title: ...]、[child: ...]):组件树读起来就像一份描述,参数的顺序无关紧要。命名参数是可选的,除非它被声明为 [required];
  • 位于组件前的关键字 [const] ([const SizedBox(height: 12)])会在编译时一次性创建该组件。[Flutter] 于是知道它永远不会改变,也不会浪费时间去比较它。分析器会标出所有被遗漏的 [const]。[VS Code] 知道如何自动添加它们。

屏幕的组件树,由 [Flutter DevTools] 工具(组件检查器)显示:

Application
└── MaterialApp
    └── HomePage
        └── Scaffold
            ├── AppBar
            │   └── Text
            └── Padding
                └── Column
                    ├── Text          (the title)
                    ├── SizedBox
                    ├── Text
                    ├── SizedBox
                    ├── Text
                    ├── SizedBox
                    ├── FilledButton
                    │   └── Text
                    ├── SizedBox
                    └── Text          (the counter)

在 [Flutter] 应用中,你写的“实现”代码很少,“描述性”代码很多:屏幕是一棵组件树,每个组件由其参数配置。这与 [React] 的 JSX 是同一概念,只是没有模板语言:这棵树是用 [Dart] 写的。

3.1.5. 运行

在打开到 [examples_flutter] 文件夹的控制台中,在 [Android] 模拟器运行的情况下:

flutter run -d emulator-5554 -t lib/ex01_first_application/main.dart

控制台显示:

Launching lib/ex01_first_application/main.dart on sdk gphone16k x86 64 in debug mode...
Running Gradle task 'assembleDebug'...                             24,1s
√ Built build\app\outputs\flutter-apk\app-debug.apk
Installing build\app\outputs\flutter-apk\app-debug.apk...          1 523ms
Syncing files to device sdk gphone16k x86 64...                       88ms

Flutter run key commands.
r Hot reload.
R Hot restart.
h List all available interactive commands.
d Detach (terminate "flutter run" but leave application running).
c Clear the screen
q Quit (terminate the application on the device).

A Dart VM Service on sdk gphone16k x86 64 is available at: http://127.0.0.1:54321/...
The Flutter DevTools debugger and profiler on sdk gphone16k x86 64 is available at: http://127.0.0.1:9101?uri=...

第一次构建 [Android] 应用(使用 [Gradle] 工具)需要一两分钟;之后的构建只需几秒钟。应用会安装到模拟器上并启动。左侧是启动屏幕;右侧是按两次按钮之后的屏幕:

可以尝试两个实验:

  • 修改 [main.dart] 中的标题文本,保存文件,然后在控制台中键入 `r` (或者直接在 [VS Code] 中保存文件):屏幕会在一秒内更新,计数器保持其值。这就是“热重载”:新代码被注入到正在运行的应用中;[Flutter] 会调用 [build],但 [State] 对象会被保留。R (“热重启”)会从 [main] 重新启动应用:计数器重置为 0;
  • 在浏览器中启动同一个应用:[flutter run -d chrome -t lib/ex01_first_application/main.dart]。屏幕是同一个,由同一个引擎渲染;变化的只有窗口大小。使用 [-d windows] 时,它就是一个 [Windows] 应用。

3.2. 示例 02:状态与计算值

状态是 [Flutter] 的核心,就像它在 [React] 中一样。这个示例计算一件商品的含税价格:

// =========================================================================
// lib/ex02_state/main.dart - 状态与计算值
// -------------------------------------------------------------------------
// 一个含增值税价格的小计算器:
//   - 状态(STATE):State 对象的各个字段;在 setState() 内部修改它们
//     会使 build() 再次运行,从而用新的值生成屏幕;
//   - 由状态计算(COMPUTED)出来的值不是状态:它是一个
//     "getter"(或 build 的局部变量),每次调用
//     build() 时重新计算。它始终是最新的,无需任何同步;
//   - 依赖于状态的连续(SUCCESSIVE)取值的数据(合计的
//     历史记录)在状态变化的地方更新:即在 setState 中;
//   - 应用的标题(浏览器标签页、手机最近使用的应用
//     列表)同样是一个组件,Title:
//     它和屏幕的其余部分一样跟随状态变化。
// =========================================================================

import 'package:flutter/material.dart';
import 'package:intl/intl.dart';

// 一个欧元金额格式化器,采用美式写法(€1,234.50),见示例 09
final euros = NumberFormat.currency(locale: 'en_US', symbol: '€');

void main() {
  runApp(
    MaterialApp(
      debugShowCheckedModeBanner: false,
      theme: ThemeData(colorSchemeSeed: Colors.indigo),
      home: const CalculatorPage(),
    ),
  );
}

class CalculatorPage extends StatefulWidget {
  const CalculatorPage({super.key});

  @override
  State<CalculatorPage> createState() => _CalculatorPageState();
}

class _CalculatorPageState extends State<CalculatorPage> {
  // 状态
  String _label = 'Pen';
  double _priceExclVat = 2.5;
  int _quantity = 1;
  double _vatRate = 20; // 单位为 %
  // 含税合计最近 5 次变化的历史记录
  final List<String> _history = [];

  // controller 提供对输入框文本(TEXT)的访问:这里需要一个
  // 来把它恢复为初始值(Reset)。示例 05
  // 会详细讲解它们
  final _labelField = TextEditingController(text: 'Pen');
  final _priceField = TextEditingController(text: '2.5');

  // 计算值(COMPUTED):getter,每次读取时重新计算
  double get _totalExclVat => _quantity * _priceExclVat;
  double get _vatAmount => _totalExclVat * _vatRate / 100;
  double get _totalInclVat => _totalExclVat + _vatAmount;

  // 所有(ALL)状态变更都经过这个方法:它记下变更前的
  // 含税合计,应用变更,并在合计发生变化时
  // 补充历史记录
  void _change(void Function() change) {
    final oldTotal = _totalInclVat;
    setState(() {
      change();
      if (_totalInclVat != oldTotal) {
        _history.insert(0, '${euros.format(oldTotal)} -> ${euros.format(_totalInclVat)}');
        if (_history.length > 5) {
          _history.removeLast();
        }
      }
    });
  }

  // 更换商品会把数量重置为 1:我们在知道状态
  // 为何(WHY)变化的地方完成这件事
  void _changeLabel(String newValue) {
    _change(() {
      _label = newValue;
      _quantity = 1;
    });
  }

  void _reset() {
    _change(() {
      _label = 'Pen';
      _priceExclVat = 2.5;
      _quantity = 1;
      _vatRate = 20;
    });
    _labelField.text = 'Pen';
    _priceField.text = '2.5';
  }

  // State 对象消失(我们离开该界面):controller 被释放
  @override
  void dispose() {
    _labelField.dispose();
    _priceField.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    final totalStyle = Theme.of(context).textTheme.titleMedium!.copyWith(fontWeight: FontWeight.bold);

    // Title:应用的标题和其他一切一样,跟随(FOLLOWS)状态
    return Title(
      title: 'Incl. VAT: ${euros.format(_totalInclVat)}',
      color: Colors.indigo,
      child: Scaffold(
        appBar: AppBar(title: const Text('Example 02 - the state')),
        // ListView:超出屏幕高度时可滚动的一列
        body: ListView(
          padding: const EdgeInsets.all(16),
          children: [
            Card(
              child: Padding(
                padding: const EdgeInsets.all(16),
                child: Column(
                  children: [
                    // onChanged:每次按键时调用,参数为新的文本
                    TextField(
                      controller: _labelField,
                      decoration: const InputDecoration(labelText: 'Item'),
                      onChanged: _changeLabel,
                    ),
                    TextField(
                      controller: _priceField,
                      decoration: const InputDecoration(labelText: 'Unit price excl. VAT'),
                      // 手机的数字键盘,带小数点
                      keyboardType: const TextInputType.numberWithOptions(decimal: true),
                      // tryParse:如果文本不是数字则返回 null;也接受逗号
                      onChanged: (text) => _change(() => _priceExclVat = double.tryParse(text.replaceAll(',', '.')) ?? 0),
                    ),
                    const SizedBox(height: 12),
                    Row(
                      children: [
                        const Expanded(child: Text('Quantity (back to 1 if the item changes)')),
                        IconButton(
                          icon: const Icon(Icons.remove),
                          // null:按钮被禁用
                          onPressed: _quantity > 0 ? () => _change(() => _quantity--) : null,
                        ),
                        Text('$_quantity', style: totalStyle),
                        IconButton(icon: const Icon(Icons.add), onPressed: () => _change(() => _quantity++)),
                      ],
                    ),
                    const SizedBox(height: 8),
                    // 只能选中一个(ONE)的按钮:增值税税率
                    SegmentedButton<double>(
                      segments: const [
                        ButtonSegment(value: 5.5, label: Text('5.5%')),
                        ButtonSegment(value: 10, label: Text('10%')),
                        ButtonSegment(value: 20, label: Text('20%')),
                      ],
                      selected: {_vatRate},
                      onSelectionChanged: (choice) => _change(() => _vatRate = choice.first),
                    ),
                    const SizedBox(height: 12),
                    OutlinedButton(onPressed: _reset, child: const Text('Reset')),
                  ],
                ),
              ),
            ),
            Card(
              child: Padding(
                padding: const EdgeInsets.all(16),
                child: Column(
                  crossAxisAlignment: CrossAxisAlignment.start,
                  children: [
                    Text('$_quantity x $_label', style: Theme.of(context).textTheme.titleLarge),
                    const Divider(),
                    _line('Total excl. VAT', euros.format(_totalExclVat)),
                    _line('VAT ($_vatRate%)', euros.format(_vatAmount)),
                    _line('Total incl. VAT', euros.format(_totalInclVat), style: totalStyle),
                  ],
                ),
              ),
            ),
            Card(
              child: Padding(
                padding: const EdgeInsets.all(16),
                child: Column(
                  crossAxisAlignment: CrossAxisAlignment.start,
                  children: [
                    Text('History of the total incl. VAT', style: Theme.of(context).textTheme.titleSmall),
                    // 历史记录的每个元素对应一行文本(见示例 03)
                    for (final line in _history) Text('• $line'),
                  ],
                ),
              ),
            ),
          ],
        ),
      ),
    );
  }

  // 一行 "标签 ....... 金额":一个生成组件的方法
  Widget _line(String label, String amount, {TextStyle? style}) {
    return Padding(
      padding: const EdgeInsets.symmetric(vertical: 4),
      child: Row(
        children: [
          Expanded(child: Text(label, style: style)),
          Text(amount, style: style),
        ],
      ),
    );
  }
}
  • 第 21 行:一个美式英语风格的金额格式化器(€1,234.50),在组件之外一次性创建,使用 [intl] 包(见示例 09)。[final]:只赋值一次的变量,但其值在运行时才能确定(与 [const] 不同);
  • 第 23–28 行:程序;这一次,[MaterialApp] 直接写在 [main] 中。大多数示例都会这样开头;
  • 第 42–45 行:四项状态数据,都是简单字段,类型分别为:[String]、[double]、[int]。在 [Dart] 中,[int] 和 [double]、是两种不同的数字类型;
  • 第 47 行:最近五次总额变化的历史记录,一个列表。该字段是 [final]:列表永远不会被替换,只会被修改(添加、删除);
  • 第 52–53 行:两个输入字段的 控制器。[Flutter] 的输入字段把文本存放在控制器中,控制器被创建并分配给它:这样就可以在代码中读取或修改该文本(“重置”按钮)。示例 05 会详细介绍;
  • 第 56–58 行:由状态计算得出的三个值。它们不是状态字段;它们是 getter——不带括号、像字段一样使用的方法([_totalInclVat])。每次读取时都会重新计算,因此始终是最新的。这和我们在 [React] 中已经见过的规则相同:只把无法计算的内容存入状态,其余一律计算得出;
  • 第 63–73 行:含税总额的历史记录取决于总额的 先后取值,而 getter 无法表达这一点。因此,所有状态更改都通过 [_change] 方法进行,该方法接收要执行的更改作为参数(一个无参数、无返回值的函数,类型为 [void Function()]):它记录更改前的总额,在 `[setState]` 中应用更改,将其与更改后的总额比较,如有变化则更新历史记录。这是进行该计算的自然位置:即状态发生变化的地方,而不是 `[build]`(它只应该 描述 屏幕);
  • 第 78–81 行:更改商品时会把数量重置为 1。这是在处理字段更改的方法中完成的,在那里我们知道状态为什么会改变;
  • 第 85–93 行:在同一个 [setState] 中进行多项状态更改:[build] 只会被调用一次。然后控制器接收其初始文本:字段会立即显示它;
  • 第 98–101 行:[dispose] 会在 [State] 对象永久消失(退出该屏幕)时被调用。在这里,释放所创建的对象——此处即控制器。示例 13 将说明 [State] 对象的生命周期。

方法 [build]:

  • 第 106 行:根据主题计算出的文本样式——中号标题样式([titleMedium]),加粗。[copyWith] 创建一个属性被修改过的对象副本:这是 [Flutter] 的一个惯例,我们会经常看到。[!] 告诉 [Dart] 该值不是 [null]([titleMedium] 的类型是 [TextStyle?],即一个样式,或 [null]);
  • 第 109–111 行:[Title] 组件提供应用的标题:在 Web 上,它是浏览器标签页的标题;在 [Android] 上,它是最近应用列表中显示的名称。在 [React] 中要用 effect([useEffect])来修改 [document.title] (在页面显示之后),而 [Flutter] 不需要任何特殊处理:标题就是一个组件,和屏幕的其余部分一样由 [build] 描述,并且会自动更新其状态;
  • 第 115 行:[ListView] 是一个列,超出屏幕高度时会 滚动 。在手机上,这几乎总是你所需要的:一个过高的 [Column] 会被截断(并且 [Flutter] 会显示黄黑相间的条带,表示“溢出”);
  • 第 124–127 行:一个输入字段([TextField]):它的控制器、它的标签([decoration: InputDecoration(labelText: ...)]),以及 [onChanged],即每次按键时调用的函数,并附带新的文本;
  • 第 130–135 行:价格。[keyboardType] 选择手机的键盘:这里是数字键盘,包括逗号。输入的文本由 [double.tryParse] 转换为数字,如果文本不是数字,则返回 [null] ([?? 0]:此处为 0)。把法语的小数逗号替换为句点后,它也能被接受;
  • 第 138–147 行:数量,带有两个按钮“–”和“+”。[Row] 把它的子组件并排放置;[Expanded] 让它的子组件占满剩余的全部宽度。[IconButton]:只有图标的按钮。[onPressed: null] 会禁用 按钮:数值不能低于 0;
  • 第 152–159 行:增值税税率,三个“分段”按钮,只能选中其中一个。[selected] 接收一个值的 集合 ([{_vatRate}]:只含一个元素的 [Set] ),[onSelectionChanged] 接收新的选中集合;
  • 第 173–177 行:结果:由 [_line] 方法生成的三行;
  • 第 190 行:历史记录中的每个元素对应一行文本,由一个 [for] 循环生成,该循环直接写 在 子组件列表中(见示例 03);
  • 第 202–208 行:一个创建组件的方法。[{TextStyle? style}]:可选的命名参数,如果未提供,则默认为 [null] 。把一个 [build] 拆分为若干方法可以提高可读性;示例 10 将表明,更好的做法通常是把它们变成真正的组件。

我们依次修改价格、数量和税率,然后修改商品:

每当含税总额发生变化时,历史记录中就会增加一行。更改商品会把数量重置为 1(见右图)。

与 [React] 的区别在于一个细节:[React] 体现的是组件的 行为,它每次都会重新创建其变量;因此状态必须通过 [useState] 单独存储。在 [Flutter] 中,状态存在于一个 对象 ([State])中,它只创建一次并被保留:状态就是它的字段,而 [build] 只是它的一个方法。因此,我们既不需要 Hook,也不需要它们的规则(例如不能在条件中调用它们,或管理它们的依赖项)。黄金法则保持不变:我们只在 [setState] 中修改状态,而 [build] 只是根据状态描述屏幕。

3.3. 示例 03:编写组件树

在 [Flutter] 中没有模板语言:屏幕是用 [Dart] 编写的。对于条件和循环,[Dart] 提供了创建子组件列表的工具。这个示例显示一个可以过滤的医生列表:

// =========================================================================
// lib/ex03_widgets/main.dart - 编写组件树
// -------------------------------------------------------------------------
// Flutter 没有模板语言(没有 HTML,也没有 JSX):
// 界面用 Dart 编写,通过嵌套的组件构造函数。
// 对于条件和循环,Dart 提供了专门用来
// 构建子组件列表(children: [...])的工具:
//   - if (condition) widget          :仅当条件为真时才存在(EXISTS)
//                                      的子组件("collection if");
//   - if (c) widgetA else widgetB    :二者取其一(OR);
//   - condition ? widgetA : widgetB  :同上,用在表达式中;
//   - for (final x in list) widget   :列表的每个元素对应一个子组件
//                                      ("collection for");
//   - ...otherList                   :另一个列表的元素,
//                                      插入到此处("spread");
//   - switch (value) { pattern => ... } :在多个值中选一个。
// 而 build() 的 return 之前的所有内容都是普通代码。
// =========================================================================

import 'package:flutter/material.dart';
import 'package:flutter_svg/flutter_svg.dart';

// 一个 "枚举":某个专业所有可能的取值
enum Specialty { generalPractitioner, pediatrician, cardiologist }

// 一个数据类:它的字段都是 final,Doctor 对象
// 永远不会改变。"const" 构造函数允许用它创建常量
class Doctor {
  final int id;
  final String title;
  final String firstName;
  final String lastName;
  final Specialty specialty;
  final bool available;

  const Doctor(this.id, this.title, this.firstName, this.lastName, this.specialty, this.available);
}

const doctors = [
  Doctor(1, 'Mme', 'Marie', 'PELISSIER', Specialty.generalPractitioner, true),
  Doctor(2, 'Mr', 'Paul', 'TATOU', Specialty.pediatrician, false),
  Doctor(3, 'Melle', 'Sophie', 'DUPONT', Specialty.cardiologist, true),
];

// "根据某个值在多个值中选一个":一个 switch 表达式(EXPRESSION)。
// 编译器会检查枚举的所有情况是否都已处理
String label(Specialty s) => switch (s) {
  Specialty.generalPractitioner => 'general practitioner',
  Specialty.pediatrician => 'pediatrician',
  Specialty.cardiologist => 'cardiologist',
};

Icon icon(Specialty s) => switch (s) {
  Specialty.pediatrician => const Icon(Icons.child_care, color: Colors.orange),
  Specialty.cardiologist => const Icon(Icons.favorite, color: Colors.red),
  _ => const Icon(Icons.medical_services, color: Colors.teal), // "_":所有其他情况
};

void main() {
  runApp(
    MaterialApp(
      debugShowCheckedModeBanner: false,
      theme: ThemeData(colorSchemeSeed: Colors.indigo),
      home: const DoctorsPage(),
    ),
  );
}

class DoctorsPage extends StatefulWidget {
  const DoctorsPage({super.key});

  @override
  State<DoctorsPage> createState() => _DoctorsPageState();
}

class _DoctorsPageState extends State<DoctorsPage> {
  String _filter = ''; // 被搜索的文本
  bool _onlyAvailable = false;
  bool _showHelp = true;

  @override
  Widget build(BuildContext context) {
    // 显示的列表:一个普通变量,每次 build() 时重新计算
    final text = _filter.trim().toLowerCase();
    final displayed = doctors
        .where(
          (m) =>
              (!_onlyAvailable || m.available) &&
              '${m.firstName} ${m.lastName} ${label(m.specialty)}'.toLowerCase().contains(text),
        )
        .toList();

    // "三个块中的一个":在 return 之前用 if 计算得出
    final Widget content;
    if (doctors.isEmpty) {
      content = const Text('No doctor.');
    } else if (displayed.isEmpty) {
      content = Text('No doctor matches "$_filter".', style: const TextStyle(color: Colors.deepOrange));
    } else {
      content = Column(
        children: [
          // 每位医生对应一个子组件:"collection for",带有序号(indexed)
          for (final (i, m) in displayed.indexed)
            // Opacity:不可预约的医生显示为灰色
            Opacity(
              opacity: m.available ? 1 : 0.5,
              // ListTile:Material 列表行(图标、标题、副标题、尾部组件)
              child: ListTile(
                leading: CircleAvatar(child: Text('${i + 1}')),
                title: Text('${m.title} ${m.firstName} ${m.lastName}'),
                // Wrap:类似 Row,但空间不足时会换到下一行
                subtitle: Wrap(
                  spacing: 6,
                  crossAxisAlignment: WrapCrossAlignment.center,
                  children: [icon(m.specialty), Text(label(m.specialty))],
                ),
                trailing: Chip(
                  label: Text(m.available ? 'available' : 'unavailable'),
                  // 由条件表达式选择的颜色
                  backgroundColor: m.available ? Colors.green.shade100 : Colors.grey.shade300,
                ),
              ),
            ),
        ],
      );
    }

    return Scaffold(
      appBar: AppBar(
        // 随应用一起发布的 SVG 图像(assets/ 文件夹,见 pubspec.yaml)
        leading: Padding(padding: const EdgeInsets.all(12), child: SvgPicture.asset('assets/doctor.svg')),
        title: const Text('Example 03 - the widgets'),
      ),
      body: ListView(
        padding: const EdgeInsets.all(16),
        children: [
          TextField(
            decoration: const InputDecoration(hintText: 'search...', prefixIcon: Icon(Icons.search)),
            onChanged: (value) => setState(() => _filter = value),
          ),
          // SwitchListTile:带标签的开关
          SwitchListTile(
            title: const Text('available only'),
            value: _onlyAvailable,
            onChanged: (value) => setState(() => _onlyAvailable = value),
          ),
          Align(
            alignment: Alignment.centerLeft,
            child: TextButton(
              onPressed: () => setState(() => _showHelp = !_showHelp),
              child: Text(_showHelp ? 'Hide help' : 'Show help'),
            ),
          ),
          // "collection if":仅当 _showHelp 为 true 时,这个组件才存在(EXISTS)
          if (_showHelp)
            Card(
              color: Colors.lightBlue.shade50,
              child: const Padding(
                padding: EdgeInsets.all(12),
                child: Text('Type a name or a specialty. The unavailable doctors are grayed out.'),
              ),
            ),
          content,
          const SizedBox(height: 12),
          // 一个计算(COMPUTED)出来的样式:文本大小取决于所显示医生的数量
          Text(
            '${displayed.length} doctor(s) displayed - the size of this text depends on it.',
            style: TextStyle(fontSize: 12 + displayed.length * 2.0),
          ),
        ],
      ),
    );
  }
}
  • 第 24 行:一个 枚举:专业只有三个可能的值([Specialty.pediatrician]……);
  • 第 28–36 行:一个数据类。它的字段是 [final]:一个 [Doctor] 永远不会改变。构造函数 [Doctor(this.id, this.title, ...)] 直接把它的参数赋给同名的字段。它是 [const] 的:可以创建常量医生(第 39 行);
  • 第 47–50 行:“根据某个值,在多个值中取其一”:一个 [switch] 表达式 (不是语句),它有一个值。每个分支写成 [pattern => value]。对于枚举,编译器会验证所有情况都已处理:新增一个专业而不补全这个 [switch] 会导致编译错误;
  • 第 53–56 行:选择图标时也是同样的原理;模式 [_] 表示“所有其他情况”。在 [Material Design] 中,图标是类 [Icons] 的常量;
  • 第 77–79 行:屏幕的状态。

方法 [build]:

  • 第 84–91 行:显示的列表:一个在每次调用 [build] 时重新计算的变量。[where] 保留满足条件的元素;[toList()] 把结果转换为列表;
  • 第 94–100 行:三个可能的值之一,通过 [if] 在 [return] 之前选定。组件是和其他值一样的值:可以存放在变量中。[final Widget content;] 声明变量但不初始化:编译器会验证每个分支恰好给它赋一次值;
  • 第 103–117 行:列表。一个 `[for]` 直接写 在 列表字面量(`[children: [ ... ]]`)中时,会在每次循环迭代时向其中添加一个元素:这就是“集合 for”。[displayed.indexed] 返回元组(序号、医生),[(i, m)] 把它“解包”为两个变量;
  • 第 106 行:[Opacity] 使其子组件部分透明:不可用的医生显示为灰色。该值由运算符 [? :] 计算得出;
  • 第 108–112 行:[ListTile] 是 [Material Design] 的列表项:包括头部元素([leading],这里是显示序号的圆盘)、标题、副标题和末尾元素([trailing])。这些全都是组件:可以是任意组件。副标题是一个 [Wrap]:一种在空间不足时换行到下一行的 [Row] (在手机上,图标和专业不一定能与“可用”标签并排放下);
  • 第 117–120 行:一个“标签”([Chip]),其文本和颜色取决于医生。[Colors.green.shade100]:浅绿色。

[return]:

  • 第 131 行:一张随应用一起提供的 SVG 图像(文件夹 [assets/],在 [pubspec.yaml] 中声明)。[Flutter] 无法自行渲染 SVG:[flutter_svg] 包提供了 [SvgPicture] 组件。对于 PNG 或 JPEG 图像,[Flutter] 有 [Image.asset] 组件;
  • 第 138–139 行:搜索字段。[hintText] 是字段为空时显示的灰色文本;[prefixIcon] 是左侧的图标。这一次没有控制器:我们只需要输入的值,通过 [onChanged] 接收;
  • 第 142–145 行:一个开关,带有其标签:一个点按即可切换的列表项;
  • 第 150 行:一个直接写在参数中的匿名函数:它切换状态;
  • 第 155–160 行:一个“if 集合”:帮助卡片 只有 当 [_showHelp] 为 true 时才存在。不存在“隐藏”的组件:条件为 false 时,子组件列表就少了一项;
  • 第 163 行:先前选定的内容;
  • 第 167–168 行:一个计算得出的样式:文本大小取决于所显示的医生数量。

小结一下 [Dart] 中的这些工具,在子组件列表中,它们取代了其他框架在模板中编写的内容:

在 Dart 中
作用
if (condition) widget
仅当条件为 true 时才存在的子组件
if (c) widgetA else widgetB
二者择一
condition? widgetA : widgetB
在表达式中二者择一
for (final x in list) widget
列表中每个元素对应一个子组件
...otherList
另一个列表的元素,插入到此处
...[widgetA, widgetB]
一次添加多个子组件(常用在 `if` 语句之后)
switch (value) { pattern => widget }
根据某个值,在多个子组件中选择一个

启动时,然后输入“gen”并隐藏帮助后,再输入“xyz”时:

3.4. 示例 04:事件

交互式组件接收 函数 作为参数,在发生某些事情时调用;这些函数通常被称为“回调”。这个示例管理一个待办事项列表:

// =========================================================================
// lib/ex04_events/main.dart - 响应用户的操作
// -------------------------------------------------------------------------
// 交互式组件接收的参数是发生某事时要调用的函数(FUNCTIONS)("回调"):
// - onPressed: f                  :按下时调用 f(按钮);
//   - onPressed: () => remove(t)    :一个匿名函数,用来传入
//   自己的参数;
//                                     - onChanged、onSubmitted...     :函数接收一份数据(文本、
//   勾选状态……);
//                                     - GestureDetector               :为任何(ANY)组件添加手势
//   (点按、长按、
//                                     双击、拖动……);
//                                     - Dismissible                   :滑动一行将其删除,
//   这是手机上的典型手势。
//                                     要在代码中操作输入框(读取或清空其文本,赋予其焦点),
// 我们给它附加一个 CONTROLLER
// 和一个 FocusNode。
// =========================================================================

import 'package:flutter/material.dart';
import 'package:flutter/services.dart';

class Task {
  final int id;
  final String label;
  bool done;

  Task(this.id, this.label, {this.done = false});
}

void main() {
  runApp(
    MaterialApp(
      debugShowCheckedModeBanner: false,
      theme: ThemeData(colorSchemeSeed: Colors.indigo),
      home: const TasksPage(),
    ),
  );
}

class TasksPage extends StatefulWidget {
  const TasksPage({super.key});

  @override
  State<TasksPage> createState() => _TasksPageState();
}

class _TasksPageState extends State<TasksPage> {
  final List<Task> _tasks = [
    Task(1, 'Install Flutter', done: true),
    Task(2, 'Read the chapter on events'),
  ];
  final List<String> _log = [];
  // 输入框的 controller:它的文本(读取、写入);
  // FocusNode:它的焦点(光标和手机键盘)
  final _field = TextEditingController();
  final _focus = FocusNode();
  // State 对象中不显示(NOT displayed)的字段:修改它
  // 不需要 setState
  int _nextId = 3;

  @override
  void dispose() {
    _field.dispose();
    _focus.dispose();
    super.dispose();
  }

  void _trace(String message) {
    final t = TimeOfDay.now();
    _log.insert(0, '${t.format(context)} $message');
  }

  // 由按钮和键盘的回车键(onSubmitted)共同调用
  void _add() {
    final label = _field.text.trim();
    if (label.isEmpty) {
      return;
    }
    setState(() {
      _tasks.add(Task(_nextId++, label));
      _trace('added "$label"');
    });
    _field.clear();
    // 焦点回到输入框:可以输入下一个任务
    _focus.requestFocus();
  }

  void _toggle(Task task, bool done) {
    setState(() {
      task.done = done;
      _trace('"${task.label}": ${done ? 'done' : 'to do'}');
    });
  }

  void _remove(Task task, String how) {
    setState(() {
      _tasks.remove(task);
      _trace('removed "${task.label}" ($how)');
    });
  }

  // 点按的详细信息:其位置,相对于被触碰的组件
  void _position(TapDownDetails details) {
    final p = details.localPosition;
    setState(() => _trace('tap at (${p.dx.round()}, ${p.dy.round()})'));
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Example 04 - the events')),
      body: ListView(
        padding: const EdgeInsets.all(16),
        children: [
          Row(
            children: [
              Expanded(
                // CallbackShortcuts:键盘快捷键(用于物理
                // 键盘:电脑、模拟器、平板);Esc 清空输入框
                child: CallbackShortcuts(
                  bindings: {const SingleActivator(LogicalKeyboardKey.escape): _field.clear},
                  child: TextField(
                    controller: _field,
                    focusNode: _focus,
                    decoration: const InputDecoration(hintText: 'new task (Esc to clear)'),
                    // 手机键盘的 "Enter" 键
                    textInputAction: TextInputAction.done,
                    onSubmitted: (_) => _add(),
                  ),
                ),
              ),
              const SizedBox(width: 8),
              FilledButton(onPressed: _add, child: const Text('Add')),
            ],
          ),
          const SizedBox(height: 12),
          for (final t in _tasks)
            // Dismissible:向左滑动该行即可将其删除。
            // key:该行的标识(IDENTITY),使 Flutter 知道哪一行
            // 消失了(见课程中的说明)
            Dismissible(
              key: ValueKey(t.id),
              direction: DismissDirection.endToStart,
              background: Container(
                color: Colors.red.shade100,
                alignment: Alignment.centerRight,
                padding: const EdgeInsets.only(right: 16),
                child: const Icon(Icons.delete),
              ),
              onDismissed: (_) => _remove(t, 'swipe'),
              child: CheckboxListTile(
                // 复选框在左侧(ON THE LEFT),就像任务列表中一样
                controlAffinity: ListTileControlAffinity.leading,
                value: t.done,
                // 复选框传递它的新值(bool?,因此要加 "!")
                onChanged: (checked) => _toggle(t, checked!),
                title: Text(
                  t.label,
                  style: t.done ? const TextStyle(decoration: TextDecoration.lineThrough, color: Colors.grey) : null,
                ),
                // 一个匿名函数:以此行(THIS row)的任务作为参数
                secondary: IconButton(
                  icon: const Icon(Icons.delete_outline, color: Colors.red),
                  onPressed: () => _remove(t, 'button'),
                ),
              ),
            ),
          const SizedBox(height: 12),
          // GestureDetector:让任何组件都能响应手势
          GestureDetector(
            onTapDown: _position,
            onDoubleTap: () => setState(() => _trace('double tap')),
            onLongPress: () => setState(() => _trace('long press')),
            child: Container(
              height: 80,
              alignment: Alignment.center,
              decoration: BoxDecoration(color: const Color(0xFFE7F5FF), borderRadius: BorderRadius.circular(8)),
              child: const Text('Touch this area (tap, double tap, long press)'),
            ),
          ),
          const SizedBox(height: 16),
          Text('Log', style: Theme.of(context).textTheme.titleSmall),
          for (final line in _log) Text(line, style: const TextStyle(fontSize: 12)),
        ],
      ),
    );
  }
}
  • 第 23–28 行:一个任务。[done] 不是 [final]:我们会修改它。[{this.done = false}]:一个带默认值的可选命名参数;
  • 第 49–53 行:状态:任务列表和一份事件日志;
  • 第 56–57 行:为了在代码中操作输入字段,与它关联了两个对象:一个 控制器 ([TextEditingController]),用于访问它的文本,以及一个 [FocusNode],用于访问它的 焦点 (闪烁的光标和手机键盘,字段获得焦点时键盘会弹出);
  • 第 60 行:[State] 对象中一个不显示的字段:修改它不需要 [setState]。这就是 [React] 所说的“引用”([useRef]);在 [Flutter] 中,它就是一个普通字段;
  • 第 63–66 行:控制器和 [FocusNode] 会在屏幕消失时被释放;
  • 第 69–71 行:在日志顶部增加一行。[TimeOfDay] 是来自 [Flutter] 的一天中的时间;[format(context)] 按照应用语言的惯例对其进行格式化;
  • 第 75–86 行:添加任务,由按钮和键盘上的 Enter 键触发。我们读取控制器中的文本([_field.text]),添加任务(在 [setState] 中),清空字段([_field.clear()]),并把焦点还给它([_focus.requestFocus()]):现在可以输入下一个任务了;
  • 第 89–92 行:勾选或取消勾选一个任务:我们直接修改 [Task] 对象本身,在 [setState] 中进行。与 [React] 不同,这里不需要创建新列表:[setState] 会通知 [Flutter] 状态已经改变,而不管它是如何改变的;
  • 第 96–99 行:删除,可以通过按钮,也可以通过滑动(见下文);
  • 第 104–106 行:点按底部区域时调用的函数。它接收事件的 详细信息:此处是 [localPosition],即手指相对于被点按组件的位置。

方法 [build]:

  • 第 121–122 行:[CallbackShortcuts] 为物理键盘(计算机、模拟器、带键盘的平板)把键盘快捷键与函数关联起来:Esc 键清空字段。[{ key: function }] 是一个 [Map] 字面量;
  • 第 124–129 行:输入字段,与其控制器和 [FocusNode] 相关联。[textInputAction] 选择手机键盘上的“Enter”键;[onSubmitted] 在按下该键时被调用,并附带文本(这里没有用到它:按惯例,该参数命名为 [_]);
  • 第 134 行:按钮调用同一个方法;
  • 第 138–151 行:每个任务一行,放在 [Dismissible] 中:这个组件可以用手指 滑动 来删除,这是手机上列表的典型手势。[direction]:只能向左;[background]:滑动期间出现在该行下方的内容(红色背景上的垃圾桶图标);[onDismissed]:当该行被滑出屏幕时调用的函数;
  • 第 143 行:key 用于 [Dismissible]。当组件列表发生变化时,[Flutter] 会把旧列表与新列表比较,以确定保留哪些组件:没有 key 时,它按序号配对(第一个对第一个,第二个对第二个,依此类推)。如果第一个任务消失,第二个任务就会取代它的位置……并带着第一个任务的状态。key 赋予每个组件一个 标识:[Flutter] 随后按 key 来匹配组件。key 在兄弟组件之间必须唯一且稳定:应使用任务的标识符,而不是它的序号。[Dismissible] 必须有 key;
  • 第 152–157 行:带复选框的列表项。[controlAffinity] 把复选框放在左侧。[onChanged] 接收复选框的新值,类型为 [bool?] (复选框可以有第三种状态,“未确定”):[!] 表示它不是 [null];
  • 第 160 行:标签的样式取决于任务:已完成则带删除线并显示为灰色,否则使用默认样式([null]);
  • 第 163–165 行:一个“垃圾桶”按钮。匿名函数 [() => _remove(t, 'button')] 允许传递参数:即 这一 行上的任务;
  • 第 171–174 行:[GestureDetector] 让 任何 组件都能响应手势:点按([onTap]、[onTapDown]……)、双击、长按、滑动、捏合……这里,一个简单的彩色方框([Container])响应三种手势;
  • 第 175–178 行:[Container] 是一个方框,可指定边距、背景、边框、大小和对齐方式。[decoration] 描述它的背景:颜色、圆角。[Color(0xFFE7F5FF)]:用 ARGB 代码指定的颜色(不透明度 FF,然后是红、绿、蓝);
  • 第 184 行:日志。

添加一个任务,勾选第二个任务,点按底部区域;然后把第一个任务向左拖动(拖动过程中位于中间;该行被移除后位于右侧):

在 [React] 中,浏览器事件([click]、[keydown]……)对所有元素都相同;在 [Flutter] 中,每个交互式组件声明自己的事件,带有类型化的参数([onPressed]、[onChanged]、[onSubmitted]……),而 [GestureDetector] 为没有手势的组件添加手势。知道每个组件有哪些参数的编辑器会在你输入时给出提示。

3.5. 示例 05:所有类型的字段

这个示例使用课程 [React] 的示例 05 中的表单,并使用 [Flutter] 的输入字段:文本框、单选按钮、复选框、下拉列表、项目符号列表、滑块和日历。

// =========================================================================
// lib/ex05_controlled_fields/main.dart - 所有类型的输入框
// -------------------------------------------------------------------------
// 受控(CONTROLLED)输入框显示状态中的某个值,并在每次变化(onChanged)时通知组件,
// 由组件更新状态:状态是
// 唯一的数据来源。修改状态(通过代码)会修改输入框。
// onChanged 传递什么取决于输入框的类型:
//   - TextField(带 controller)     -> 文本(String);
//   - Checkbox、Switch                -> bool? / bool;
//   - Radio(位于 RadioGroup 中)     -> 所选按钮的值;
//   - DropdownButton                  -> 所选项的值;
//   - FilterChip                      -> bool:该 chip 是否被选中?
//   - Slider                          -> double;
//   - showDatePicker(一个对话框)   -> 一个 Future<DateTime?>。
// TextField 是特殊情况:它把文本保存在
// TextEditingController 中,我们创建它、读取它(controller.text)、
// 修改它……并释放它(dispose)。
// 表单与 React 课程的示例 05 相同;所有操作都在
// 手机上完成,无需服务器。
// =========================================================================

import 'dart:convert';

import 'package:flutter/material.dart';
import 'package:flutter_localizations/flutter_localizations.dart';

const titles = ['Mr', 'Mme', 'Melle'];
const hobbies = ['sport', 'music', 'reading', 'cinema'];
const countries = {'fr': 'France', 'be': 'Belgium', 'ch': 'Switzerland'};
const languages = {'fr': 'French', 'en': 'English', 'es': 'Spanish'};

void main() {
  runApp(
    MaterialApp(
      debugShowCheckedModeBanner: false,
      theme: ThemeData(colorSchemeSeed: Colors.indigo),
      // Flutter 自身的文本(日历、OK / CANCEL 按钮)为
      // 英语(见示例 21)
      locale: const Locale('en'),
      supportedLocales: const [Locale('en'), Locale('fr')],
      localizationsDelegates: GlobalMaterialLocalizations.delegates,
      home: const FormPage(),
    ),
  );
}

class FormPage extends StatefulWidget {
  const FormPage({super.key});

  @override
  State<FormPage> createState() => _FormPageState();
}

class _FormPageState extends State<FormPage> {
  // 表单的每个输入框对应一个状态
  String _title = 'Mme';
  final _name = TextEditingController();
  final _age = TextEditingController(text: '30');
  String _presentation = '';
  bool _newsletter = false;
  final Set<String> _hobbies = {'reading'}; // 一个集合(SET):没有重复项
  String _country = 'fr';
  final Set<String> _languages = {};
  DateTime? _birthDate; // null:尚未选择
  double _satisfaction = 3;
  String? _sent;

  @override
  void initState() {
    super.initState();
    // controller 会在文本每次变化时通知(NOTIFIES)它的监听者:
    // 屏幕会重绘(模型实时显示)
    _name.addListener(_redraw);
    _age.addListener(_redraw);
  }

  void _redraw() => setState(() {});

  @override
  void dispose() {
    _name.dispose();
    _age.dispose();
    super.dispose();
  }

  // "2026-10-05":RdvMedecins API 的日期格式
  String? get _birthDateText => _birthDate?.toIso8601String().substring(0, 10);

  // 所有的值汇集成一个对象(即将发送给服务器的内容)
  Map<String, Object?> get _model => {
    'title': _title,
    'name': _name.text.trim(),
    'age': int.tryParse(_age.text), // 如果输入框为空则为 null
    'presentation': _presentation,
    'newsletter': _newsletter,
    'hobbies': _hobbies.toList(),
    'country': _country,
    'languages': _languages.toList(),
    'birthDate': _birthDateText,
    'satisfaction': _satisfaction.round(),
  };

  // 出生日期:一个日历对话框。showDatePicker 返回
  // 一个 Future,即所选日期(或 null:对话框关闭且未选择)
  Future<void> _chooseBirthDate() async {
    final choice = await showDatePicker(
      context: context,
      initialDate: _birthDate ?? DateTime(2000, 1, 1),
      firstDate: DateTime(1900),
      lastDate: DateTime.now(),
    );
    if (choice != null) {
      setState(() => _birthDate = choice);
    }
  }

  // 由代码(BY THE CODE)修改的状态:输入框随之变化
  void _example() {
    setState(() {
      _title = 'Mr';
      _name.text = 'MARTIN';
      _age.text = '42';
      _hobbies
        ..clear()
        ..addAll(['sport', 'cinema']);
      _country = 'be';
    });
  }

  void _send() {
    // JsonEncoder.withIndent:带缩进的 JSON;jsonEncode:单行 JSON
    setState(() => _sent = jsonEncode(_model));
  }

  @override
  Widget build(BuildContext context) {
    final titleStyle = Theme.of(context).textTheme.titleSmall;
    return Scaffold(
      appBar: AppBar(title: const Text('Example 05 - the controlled fields')),
      body: ListView(
        padding: const EdgeInsets.all(16),
        children: [
          Text('Title', style: titleStyle),
          // RadioGroup:所选的值(groupValue),以及其中包含的某个 Radio 按钮
          // 被选中时调用的函数
          RadioGroup<String>(
            groupValue: _title,
            onChanged: (value) => setState(() => _title = value!),
            child: Row(
              children: [
                for (final t in titles) ...[Radio<String>(value: t), Text(t), const SizedBox(width: 12)],
              ],
            ),
          ),
          Row(
            children: [
              Expanded(
                flex: 2,
                child: TextField(
                  controller: _name,
                  decoration: const InputDecoration(labelText: 'Name'),
                ),
              ),
              const SizedBox(width: 12),
              Expanded(
                child: TextField(
                  controller: _age,
                  decoration: const InputDecoration(labelText: 'Age'),
                  keyboardType: TextInputType.number,
                ),
              ),
            ],
          ),
          const SizedBox(height: 8),
          // Focus:当其子组件获得(GAINS)或失去(LOSES)焦点时发出通知。该输入框
          // 并不在每次按键时与状态关联:只在
          // 离开输入框时才读取其文本(类似 HTML 中的 onBlur)
          Focus(
            onFocusChange: (hasFocus) {
              if (!hasFocus) setState(() {});
            },
            child: TextFormField(
              initialValue: _presentation,
              maxLines: 2,
              decoration: const InputDecoration(labelText: 'Presentation (updated when leaving the field)'),
              onChanged: (text) => _presentation = text, // 没有 setState:什么都不会重绘
            ),
          ),
          // 单个复选框:true / false
          CheckboxListTile(
            contentPadding: EdgeInsets.zero,
            controlAffinity: ListTileControlAffinity.leading,
            title: const Text('Receive the newsletter'),
            value: _newsletter,
            onChanged: (checked) => setState(() => _newsletter = checked!),
          ),
          Text('Hobbies', style: titleStyle),
          // 多个 chip 对应一个(ONE)集合:值被添加或移除
          Wrap(
            spacing: 8,
            children: [
              for (final l in hobbies)
                FilterChip(
                  label: Text(l),
                  selected: _hobbies.contains(l),
                  onSelected: (selected) => setState(() => selected ? _hobbies.add(l) : _hobbies.remove(l)),
                ),
            ],
          ),
          const SizedBox(height: 8),
          Row(
            children: [
              Text('Country', style: titleStyle),
              const SizedBox(width: 16),
              // 一个下拉列表:value 指明选中了哪一项
              DropdownButton<String>(
                value: _country,
                items: [
                  for (final MapEntry(key: code, value: name) in countries.entries)
                    DropdownMenuItem(value: code, child: Text(name)),
                ],
                onChanged: (code) => setState(() => _country = code!),
              ),
            ],
          ),
          Text('Spoken languages', style: titleStyle),
          Wrap(
            spacing: 8,
            children: [
              for (final MapEntry(key: code, value: name) in languages.entries)
                FilterChip(
                  label: Text(name),
                  selected: _languages.contains(code),
                  onSelected: (selected) => setState(() => selected ? _languages.add(code) : _languages.remove(code)),
                ),
            ],
          ),
          const SizedBox(height: 8),
          Row(
            children: [
              Text('Satisfaction: ${_satisfaction.round()} / 5', style: titleStyle),
              Expanded(
                // 一个滑块:5 个刻度,从 1 到 5
                child: Slider(
                  value: _satisfaction,
                  min: 1,
                  max: 5,
                  divisions: 4,
                  onChanged: (v) => setState(() => _satisfaction = v),
                ),
              ),
            ],
          ),
          ListTile(
            contentPadding: EdgeInsets.zero,
            leading: const Icon(Icons.cake),
            title: const Text('Date of birth'),
            subtitle: Text(_birthDateText ?? 'not chosen'),
            trailing: OutlinedButton(onPressed: _chooseBirthDate, child: const Text('Choose')),
          ),
          const SizedBox(height: 8),
          // Wrap:在窄屏上按钮会换到下一行
          Wrap(
            spacing: 8,
            runSpacing: 8,
            children: [
              FilledButton(onPressed: _send, child: const Text('Send')),
              OutlinedButton(onPressed: _example, child: const Text('Fill from the code')),
            ],
          ),
          const SizedBox(height: 16),
          Text('The model, live', style: titleStyle),
          Container(
            padding: const EdgeInsets.all(8),
            color: Colors.grey.shade100,
            // JsonEncoder.withIndent('  '):JSON,缩进 2 个空格
            child: Text(
              const JsonEncoder.withIndent('  ').convert(_model),
              style: const TextStyle(fontFamily: 'RobotoMono', fontSize: 12),
            ),
          ),
          // 仅在发送之后才存在的块;...[ ] 会插入多个(SEVERAL)组件
          if (_sent != null) ...[
            const SizedBox(height: 8),
            Text('Last send', style: titleStyle),
            Container(
              padding: const EdgeInsets.all(8),
              color: Colors.green.shade50,
              child: Text(_sent!, style: const TextStyle(fontFamily: 'RobotoMono', fontSize: 12)),
            ),
          ],
        ],
      ),
    );
  }
}

一个 受控 字段显示来自状态的值,并把任何更改通知组件([onChanged]),组件据此更新状态:状态是唯一的事实来源。这一点适用于 [Flutter] 中的所有字段……文本框除外,它们把文本存放在控制器中。

  • 第 39–41 行:[Flutter] 自身的文本(日历的星期和月份、其窗口中的“OK”和“CANCEL”按钮)默认是英文的。我们声明应用的语言([supportedLocales])、所选语言([locale]),以及为 [Flutter] 提供翻译的“委托”(delegate),位于 [flutter_localizations] 包中。示例 21 将再次讨论这一点;
  • 第 56–66 行:每个字段对应一个状态。[final _name = TextEditingController()]:对于文本字段,状态就是控制器本身;[Set<String>]:爱好和语言的集合(无重复项);[DateTime? _birthDate]:一个日期,或者 [null] (在选定日期之前);
  • 第 69–74 行:[initState] 只在 [State] 对象创建时调用一次(见示例 13)。控制器会把文本的每一次更改 通知 给它的监听器([addListener]):屏幕会重绘,使底部显示的模型跟上输入。[setState(() {})]:无需更改任何内容,只需重绘;
  • 第 87 行:采用 [RdvMedecins] API 格式的日期,“2026-10-05”。[_birthDate?.toIso8601String()]:[?.] 运算符仅在 [_birthDate] 不是 [null] 时才调用该方法(否则结果为 [null]);
  • 第 90–100 行:所有的值,合并成一个 [Map] (它将被发送到服务器)。[int.tryParse(_age.text)]:年龄,或者 [null] (如果该字段不是数字);
  • 第 105–113 行:出生日期从日历窗口中选择。[showDatePicker] 打开该窗口,并返回一个 [Future]:即选定的日期,稍后在用户关闭窗口时给出(如果用户没有做出选择就关闭了窗口,则为 [null] )。该方法是 [async] 的:[await] 会等待 [Future] 完成,而不阻塞应用。凡是需要等待的地方(窗口、服务器),都使用这一机制;
  • 第 118–126 行:状态 由代码修改:字段随之变化。对于文本框,我们写入其控制器。[..clear()..addAll([...])]:这是 [Dart] 的“级联”写法,即对同一个对象进行多次方法调用;
  • 第 132 行:[jsonEncode] (来自 [dart:convert])根据 [Map] 创建 JSON。

字段位于 [build] 中:

  • 第 146–151 行:单选按钮。[RadioGroup] 包含选中的值([groupValue])以及选中另一个值时调用的函数([onChanged]);它包含各个按钮 [Radio],每个按钮有自己的值。[...[a, b, c]] 一次插入多个组件:为每个标题生成一个按钮、它的标签和一个间隔;
  • 第 160–169 行:两个文本字段并排放在一个 [Row] 中。[Expanded(flex: 2, ...)]:姓名占用的空间是年龄的两倍。年龄字段使用数字键盘;
  • 第 178–186 行:一个 非受控 字段:[TextFormField] 可以接收初始值([initialValue])来代替控制器,并自行管理它的文本。每次按键时文本都会更新,但不使用 [setState]:不会重绘任何内容。[Focus] 组件会在其子组件获得或失去焦点时发出通知([onFocusChange]):只有在离开该字段时才会重绘。这相当于 HTML 的 [blur] 事件;
  • 第 190–195 行:一个单独的复选框及其标签;
  • 第 199–206 行:针对同一个集合的多项选择:用于选择的标签([FilterChip])。如果集合包含某个标签的值,该标签即为选中状态;点按它会添加或移除该值。[Wrap] 把它的子组件并排放置,空间不足时换到下一行;
  • 第 216–222 行:一个下拉列表。[value] 指定选中的是哪一项;[items] 列出各项,每项带有其值和组件。[for (final MapEntry(key: code, value: name) in countries.entries)] 遍历 [Map] [countries] 的各个条目 ,把每个条目“解包”为两个变量,[code] 和 [name];
  • 第 230–234 行:所说的语言,也用标签列出。(在 [Flutter] 中没有多选列表:标签或复选框就起这个作用);
  • 第 244–249 行:一个滑块,范围从 1 到 5,分为四个区间([divisions])。它的值是一个 [double];
  • 第 254–259 行:出生日期和打开日历的按钮;
  • 第 278–279 行:实时显示的模型:它的 JSON,缩进两个空格,使用随应用一起提供的等宽字体;
  • 第 283–289 行:只有在发送消息之后才出现的块:[if] 后接 [...[ ]] 会插入若干个组件,或者一个也不插入。

你选择称谓、姓名、爱好和语言;然后打开日历;然后发送:

下表总结了每种字段向其对应的函数 [onChanged] 传递的内容:

字段
传递的值
TextField, TextFormField
String(文本);或者读取控制器
Checkbox, CheckboxListTile
bool?(已选中、未选中或未确定)
Switch, SwitchListTile
bool
Radio(位于 RadioGroup 中)
所选按钮的值(T?)
DropdownButton<T>
所选元素的值(T?)
FilterChip
bool:该标签是否被选中?
SegmentedButton<T>
Set<T>:所选的值
Slider
double
showDatePicker
Future<DateTime?>:所选的日期,稍后给出

3.6. 示例 06:表单、对象、归约器

示例 05 为每个表单字段都设置了一个状态字段。对于真正的表单,我们更倾向于使用 一个 对象来包含所有的值——即 模型——并在一个函数中描述它的变化,也就是 归约器:[reducer(currentState, action) -> newState]。这就是 Hook [useReducer] 在 [React] 中所做的事;在 [Flutter] 中,无需导入任何东西:[Dart] 提供了所需的一切。

// =========================================================================
// lib/ex06_reducer/main.dart - 表单、对象、reducer
// -------------------------------------------------------------------------
// 示例 05 的每个表单输入框对应一个状态字段。对于真实的
// 表单,我们更倾向于用一个(ONE)对象保存所有的值,
// 即模型(MODEL)(这里是一个不可修改的 Profile 对象),并在一个函数中描述
// 它的变化,即 REDUCER:
//
//     reducer(currentState, action) -> newState
//
// 组件不再修改状态:它用一个 ProfileAction 对象
// (Edit(Field.lastName, 'Dupont')、Leave(Field.lastName)……)描述(DESCRIBES)发生了什么,
// 再由 reducer 据此推导出新的状态。所有逻辑集中在
// 一个位置,即一个纯(PURE)函数中(相同输入,相同输出,没有副
// 作用),易于测试。
// Dart 很适合这种写法:"sealed" 类列出所有可能的
// 动作,对动作的 switch 由编译器检查
// (遗漏某个情况就是错误)。
//
// 状态还会为每个输入框记录是否已被 "触碰"(至少离开过
// 一次);据此推导出它是否 "已修改"(其值不同于
// 初始值)以及是否被禁用。
// =========================================================================

import 'dart:convert';

import 'package:flutter/material.dart';

// 表单中每个输入框的名称
enum Field { title, firstName, lastName, age, newsletter, email, country, birthDate, presentation }

// 表单的数据:一个不可修改(NON-MODIFIABLE)的对象(它的所有字段都是
// final)。要 "修改" 它,我们构建一个新对象(copyWith)
class Profile {
  final String title;
  final String firstName;
  final String lastName;
  final int age;
  final bool newsletter;
  final String email;
  final String country;
  final String birthDate;
  final String presentation;

  const Profile({
    required this.title,
    required this.firstName,
    required this.lastName,
    required this.age,
    required this.newsletter,
    required this.email,
    required this.country,
    required this.birthDate,
    required this.presentation,
  });

  // 一个副本,其中少数字段被更改(其余保持不变);
  // "??":如果提供了新值就用新值,否则用旧值
  Profile copyWith({
    String? title,
    String? firstName,
    String? lastName,
    int? age,
    bool? newsletter,
    String? email,
    String? country,
    String? birthDate,
    String? presentation,
  }) {
    return Profile(
      title: title ?? this.title,
      firstName: firstName ?? this.firstName,
      lastName: lastName ?? this.lastName,
      age: age ?? this.age,
      newsletter: newsletter ?? this.newsletter,
      email: email ?? this.email,
      country: country ?? this.country,
      birthDate: birthDate ?? this.birthDate,
      presentation: presentation ?? this.presentation,
    );
  }

  // 由名称指定的某个输入框的值
  Object value(Field c) => switch (c) {
    Field.title => title,
    Field.firstName => firstName,
    Field.lastName => lastName,
    Field.age => age,
    Field.newsletter => newsletter,
    Field.email => email,
    Field.country => country,
    Field.birthDate => birthDate,
    Field.presentation => presentation,
  };

  // 一个副本,其中由名称指定的某一个(ONE)字段有了新值
  Profile withField(Field c, Object v) => switch (c) {
    Field.title => copyWith(title: v as String),
    Field.firstName => copyWith(firstName: v as String),
    Field.lastName => copyWith(lastName: v as String),
    Field.age => copyWith(age: v as int),
    Field.newsletter => copyWith(newsletter: v as bool),
    Field.email => copyWith(email: v as String),
    Field.country => copyWith(country: v as String),
    Field.birthDate => copyWith(birthDate: v as String),
    Field.presentation => copyWith(presentation: v as String),
  };

  Map<String, Object> toJson() => {for (final c in Field.values) c.name: value(c)};
}

const initial = Profile(
  title: 'Mme',
  firstName: 'Marie',
  lastName: 'PELISSIER',
  age: 30,
  newsletter: false,
  email: '',
  country: 'fr',
  birthDate: '',
  presentation: '',
);

// 完整的状态:各个值,以及已经离开过的输入框
class ProfileState {
  final Profile values;
  final Set<Field> touched;

  const ProfileState(this.values, this.touched);
}

// 可能的动作。"sealed":除了本文件中的动作之外没有别的动作,
// 编译器知道这一点
sealed class ProfileAction {
  const ProfileAction();
}

class Edit extends ProfileAction {
  final Field field;
  final Object value;
  const Edit(this.field, this.value);
}

class Leave extends ProfileAction {
  final Field field;
  const Leave(this.field);
}

class Uppercase extends ProfileAction {
  const Uppercase();
}

class Reset extends ProfileAction {
  const Reset();
}

// reducer:它从不(NEVER)修改接收到的状态,而是返回一个新状态。
// switch 会 "解构" 每个动作:Edit(:final field, ...) 把
// 它的字段读入同名变量
ProfileState reducer(ProfileState state, ProfileAction action) => switch (action) {
  Edit(:final field, :final value) => ProfileState(state.values.withField(field, value), state.touched),
  Leave(:final field) => ProfileState(state.values, {...state.touched, field}),
  Uppercase() => ProfileState(
    state.values.copyWith(firstName: state.values.firstName.toUpperCase(), lastName: state.values.lastName.toUpperCase()),
    state.touched,
  ),
  Reset() => const ProfileState(initial, {}),
};

const titles = ['Mr', 'Mme', 'Melle'];
const trackedFields = [Field.firstName, Field.lastName, Field.age, Field.email];
// 文本输入框:每个都有自己的 controller
const textFields = [Field.firstName, Field.lastName, Field.email, Field.presentation];

void main() {
  runApp(
    MaterialApp(
      debugShowCheckedModeBanner: false,
      theme: ThemeData(colorSchemeSeed: Colors.indigo),
      home: const ProfilePage(),
    ),
  );
}

class ProfilePage extends StatefulWidget {
  const ProfilePage({super.key});

  @override
  State<ProfilePage> createState() => _ProfilePageState();
}

class _ProfilePageState extends State<ProfilePage> {
  ProfileState _state = const ProfileState(initial, {});
  // 每个文本输入框一个 controller;一个 "map":Field -> controller
  final _controllers = {for (final c in textFields) c: TextEditingController(text: initial.value(c) as String)};

  @override
  void dispose() {
    for (final c in _controllers.values) {
      c.dispose();
    }
    super.dispose();
  }

  // 改变状态的唯一(THE)方式:描述发生了什么
  void _dispatch(ProfileAction action) {
    setState(() => _state = reducer(_state, action));
    // reducer 可能改变了某段文本(Uppercase、Reset):
    // 输入框必须把它显示出来
    for (final MapEntry(key: field, value: controller) in _controllers.entries) {
      final value = _state.values.value(field) as String;
      if (controller.text != value) {
        controller.text = value;
      }
    }
  }

  Profile get _v => _state.values;

  // 由状态推导(DEDUCED)出来的值
  bool _modified(Field c) => _v.value(c) != initial.value(c);
  bool _disabled(Field c) => c == Field.email && !_v.newsletter; // 电子邮件要求订阅新闻通讯
  bool get _formModified => Field.values.any(_modified);

  // 与模型关联的文本输入框:一个构建它的方法
  Widget _field(Field field, String label, {int lines = 1}) {
    // Focus:我们知道输入框何时被离开(它失去焦点)
    return Focus(
      onFocusChange: (hasFocus) {
        if (!hasFocus) _dispatch(Leave(field));
      },
      child: TextField(
        controller: _controllers[field],
        enabled: !_disabled(field),
        maxLines: lines,
        decoration: InputDecoration(labelText: label),
        onChanged: (text) => _dispatch(Edit(field, text)),
      ),
    );
  }

  @override
  Widget build(BuildContext context) {
    final titleStyle = Theme.of(context).textTheme.titleSmall;
    return Scaffold(
      appBar: AppBar(title: const Text('Example 06 - a reducer')),
      body: ListView(
        padding: const EdgeInsets.all(16),
        children: [
          RadioGroup<String>(
            groupValue: _v.title,
            onChanged: (t) => _dispatch(Edit(Field.title, t!)),
            child: Row(
              children: [
                for (final t in titles) ...[Radio<String>(value: t), Text(t), const SizedBox(width: 12)],
              ],
            ),
          ),
          Row(
            children: [
              Expanded(child: _field(Field.firstName, 'First name')),
              const SizedBox(width: 12),
              Expanded(child: _field(Field.lastName, 'Last name')),
            ],
          ),
          Row(
            children: [
              Text('Age: ${_v.age}', style: titleStyle),
              Expanded(
                child: Slider(
                  value: _v.age.toDouble(),
                  max: 120,
                  divisions: 120,
                  onChanged: (a) => _dispatch(Edit(Field.age, a.round())),
                  // 滑块被松开:该输入框已被 "离开"
                  onChangeEnd: (_) => _dispatch(const Leave(Field.age)),
                ),
              ),
            ],
          ),
          SwitchListTile(
            contentPadding: EdgeInsets.zero,
            title: const Text('Receive the newsletter'),
            value: _v.newsletter,
            onChanged: (yes) => _dispatch(Edit(Field.newsletter, yes)),
          ),
          _field(Field.email, 'E-mail (if newsletter)'),
          const SizedBox(height: 8),
          DropdownButton<String>(
            value: _v.country,
            items: const [
              DropdownMenuItem(value: 'fr', child: Text('France')),
              DropdownMenuItem(value: 'be', child: Text('Belgium')),
              DropdownMenuItem(value: 'ch', child: Text('Switzerland')),
            ],
            onChanged: (p) => _dispatch(Edit(Field.country, p!)),
          ),
          _field(Field.presentation, 'Presentation', lines: 2),
          const SizedBox(height: 12),
          Wrap(
            spacing: 8,
            children: [
              OutlinedButton(onPressed: () => _dispatch(const Uppercase()), child: const Text('Name in upper case')),
              OutlinedButton(onPressed: () => _dispatch(const Reset()), child: const Text('Reset')),
            ],
          ),
          const SizedBox(height: 16),
          Text('The model, live', style: titleStyle),
          Container(
            padding: const EdgeInsets.all(8),
            color: Colors.grey.shade100,
            child: Text(
              const JsonEncoder.withIndent('  ').convert(_v.toJson()),
              style: const TextStyle(fontFamily: 'RobotoMono', fontSize: 12),
            ),
          ),
          const SizedBox(height: 16),
          Text('The state of the fields', style: titleStyle),
          // DataTable:一个表格,带有列和行
          DataTable(
            columnSpacing: 16,
            headingRowHeight: 36,
            dataRowMinHeight: 28,
            dataRowMaxHeight: 32,
            columns: const [
              DataColumn(label: Text('field')),
              DataColumn(label: Text('touched')),
              DataColumn(label: Text('modified')),
              DataColumn(label: Text('disabled')),
            ],
            rows: [
              for (final c in trackedFields)
                DataRow(
                  cells: [
                    DataCell(Text(c.name)),
                    DataCell(Text('${_state.touched.contains(c)}')),
                    DataCell(Text('${_modified(c)}')),
                    DataCell(Text('${_disabled(c)}')),
                  ],
                ),
            ],
          ),
          const SizedBox(height: 8),
          Text.rich(
            TextSpan(
              children: [
                const TextSpan(text: 'form modified: '),
                TextSpan(
                  text: '$_formModified',
                  style: const TextStyle(fontWeight: FontWeight.bold),
                ),
              ],
            ),
          ),
        ],
      ),
    );
  }
}

模型:

  • 第 30 行:表单中每个字段的名称;
  • 第 34–43 行:表单数据:一个 不可修改 的对象,其所有字段都是 [final] 的;
  • 第 45–54 行:一个带命名参数的构造函数,所有参数都是必需的([required]);
  • 第 59–79 行:要“修改”一个不可修改的对象,就创建一个副本,其中某些字段被更改:这就是方法 [copyWith],它是 [Flutter] 的一种惯用写法(我们在 [TextStyle] 中遇到过)。每个参数都是可选的([String? title]:一个字符串或 [null]);[title ?? this.title]:如果提供了新值就用新值,否则用旧值;
  • 第 84–93 行:以名称指定的字段的值:一个针对该枚举的 [switch] 表达式;
  • 第 97–106 行:一个副本,其中以名称指定的某一个字段有了新值。[v as String]:收到的值(类型为 [Object],可以是任何东西)被转换为字符串;如果它不是字符串,就会导致运行时错误;
  • 第 109 行:一个 [Map] “字段名 -> 值”,由一个 [for] 在 [Map] 字面量内创建。[c.name]:枚举值的名称(“firstName”);
  • 第 112–121 行:初始值;
  • 第 125–129 行:完整的状态:各个值,以及所有已经处理过(“触碰过”)的字段。

动作与归约器:

  • 第 134–154 行:可能的动作:一个 密封 类([sealed])及其四个子类。[sealed] 告诉编译器,除了此文件中的子类之外没有其他子类。一个动作 描述发生了什么:[Edit(Field.lastName, 'Dupont')], [Leave(Field.lastName)]……;
  • 第 160–167 行:归约器。它是一个 纯函数:相同的输入,相同的输出,没有副作用;它从不修改收到的状态,而是返回一个新状态。[switch] 作用于动作,每个分支都是一个 模式 ,用来测试其类型:[Edit(:final field, :final value)] 验证该动作是一个 [Edit],并把它的 [field] 和 [value] 字段 存入同名变量。由于该类是密封的,编译器会验证全部四个动作都已处理;如果增加第五个动作而不补全归约器,就会导致编译错误;
  • 第 162 行:一个新的集合,由旧集合的元素([...state.touched])和刚离开的字段组成。

屏幕:

  • 第 193 行:屏幕的状态:只有一个字段,即对象 [ProfileState];
  • 第 195 行:每个文本字段的控制器,保存在一个 [Map] 中,该 Map 由一个 [for] 创建;
  • 第 206–213 行:修改状态的唯一方法:描述发生了什么。[_dispatch](这是 [React] 给它起的名字) 使用归约器计算新状态,在 [setState] 中进行。然后,由于归约器可能修改了某些文本(Uppercase、Reset),这些值会被复制到尚未拥有它们的控制器中;
  • 第 221–223 行:值 由状态派生 :如果字段的值与初始值不同,则该字段已被修改;不订阅 newsletter 时,电子邮件被禁用;只要有任一字段被修改,表单就被视为已修改([any])。[Field.values]:枚举值的列表;
  • 第 226–237 行:一个创建与模型关联的文本字段的方法:它的控制器、它的禁用状态([enabled]),以及两个动作:[Edit] 对应每次按键,[Leave] 对应字段失去焦点;
  • 在 [build] 中,每个字段 描述 它的更改,使用的是动作:[_dispatch(Edit(Field.title, t!))], [_dispatch(const Uppercase())]……;
  • 第 320–338 行:一个表格([DataTable]),带有列和行:每个被跟踪字段的状态;
  • 第 344–349 行:由若干种不同样式的部分组成的文本:[Text.rich] 及其 [TextSpan]。

我们修改姓名,离开该字段,并订阅 newsletter;然后把姓名首字母大写:

表单的全部逻辑都包含在归约器中——一个只有几行、不含任何组件的函数——它可以单独测试。组件现在只负责显示状态并描述发生了什么。

3.7. 示例 07:手动验证表单

一个 纯 函数 [validate(account)] 返回各字段的错误;每次执行 [build] 时都会调用它,因此错误始终是最新的。它们不会立即显示(一个满是红色的空表单会让人不舒服),只对已经离开过的字段显示。提交表单会显示所有错误。

// =========================================================================
// lib/ex07_validation/main.dart - 手动验证表单
// -------------------------------------------------------------------------
// 一个纯(PURE)函数 validate(account) 返回各输入框的错误;
// 我们在每次 build() 时调用它,因此错误始终是最新的。
// 我们不会立即显示错误(满屏红色的空表单
// 令人不快):只对已离开("touched")的输入框显示。发送
// 会把所有输入框标记为 touched,然后只有在表单
// 有效时才会执行。给 TextField 提供错误文本时,它会在输入框下方以红色显示错误:
// InputDecoration(errorText: ...)。
//
// 与 RdvMedecins 服务器("创建账户" 表单)的规则相同。
// 警告:这种验证只是为用户提供的一种便利(CONVENIENCE)(
// 即时反馈,无需往返服务器)。它什么也
// 保护不了:任何人都可以向服务器发送手工构造的
// 请求(curl……)。因此服务器总是(ALWAYS)重新验证所有内容(见示例 25)。
// =========================================================================

import 'package:flutter/material.dart';

enum Field { title, firstName, lastName, login, password, confirmation }

// 一个 "record":一小组命名的值,无需编写类
typedef Account = ({String title, String firstName, String lastName, String login, String password, String confirmation});

const titles = ['Mr', 'Mme', 'Melle'];
final loginFormat = RegExp(r'^[a-z0-9._-]{1,30}$');
const passwordMin = 6;

// 规则:一个纯函数,只依赖于它的参数。
// 它为每个出错的输入框返回对应的消息
Map<Field, String> validate(Account c) {
  final errors = <Field, String>{};
  if (!titles.contains(c.title)) errors[Field.title] = 'Choose a title from the list.';
  if (c.firstName.trim().isEmpty) {
    errors[Field.firstName] = 'The first name is required.';
  } else if (c.firstName.length > 20) {
    errors[Field.firstName] = 'The first name must not exceed 20 characters.';
  }
  if (c.lastName.trim().isEmpty) {
    errors[Field.lastName] = 'The last name is required.';
  } else if (c.lastName.length > 20) {
    errors[Field.lastName] = 'The last name must not exceed 20 characters.';
  }
  if (c.login.isEmpty) {
    errors[Field.login] = 'The login is required.';
  } else if (!loginFormat.hasMatch(c.login)) {
    errors[Field.login] = 'Unaccented lower-case letters, digits, dot, hyphen, underscore.';
  }
  if (c.password.isEmpty) {
    errors[Field.password] = 'The password is required.';
  } else if (c.password.length < passwordMin) {
    errors[Field.password] = 'At least $passwordMin characters.';
  }
  // 一条比较两个(TWO)输入框的规则
  if (c.confirmation != c.password) {
    errors[Field.confirmation] = 'The confirmation does not match the password.';
  }
  return errors;
}

void main() {
  runApp(
    MaterialApp(
      debugShowCheckedModeBanner: false,
      theme: ThemeData(colorSchemeSeed: Colors.indigo),
      home: const AccountPage(),
    ),
  );
}

class AccountPage extends StatefulWidget {
  const AccountPage({super.key});

  @override
  State<AccountPage> createState() => _AccountPageState();
}

class _AccountPageState extends State<AccountPage> {
  String _title = 'Mr';
  // 每个文本输入框一个 controller
  final _texts = {
    for (final c in [Field.firstName, Field.lastName, Field.login, Field.password, Field.confirmation])
      c: TextEditingController(),
  };
  final Set<Field> _touched = {};
  bool _submitAttempted = false;
  bool _success = false;

  @override
  void dispose() {
    for (final c in _texts.values) {
      c.dispose();
    }
    super.dispose();
  }

  // 账户,按输入内容构建:一个按需创建的 record
  Account get _account => (
    title: _title,
    firstName: _texts[Field.firstName]!.text,
    lastName: _texts[Field.lastName]!.text,
    login: _texts[Field.login]!.text,
    password: _texts[Field.password]!.text,
    confirmation: _texts[Field.confirmation]!.text,
  );

  void _send() {
    setState(() {
      _submitAttempted = true;
      _touched.addAll(Field.values); // 所有错误都显示
      // 在这里,账户将被发送到服务器(见示例 25)
      _success = validate(_account).isEmpty;
    });
  }

  @override
  Widget build(BuildContext context) {
    // 错误:每次 build() 时重新计算,从不存入状态
    final errors = validate(_account);

    // 某个输入框要显示(DISPLAY)的错误:仅当它已被 touched 时才显示
    String? error(Field c) => _touched.contains(c) ? errors[c] : null;

    // 一个文本输入框:标签、错误,以及在它已 touched 且有效时显示的绿色对勾
    Widget field(Field c, String label, {bool secret = false}) {
      final valid = _touched.contains(c) && !errors.containsKey(c);
      return Focus(
        onFocusChange: (hasFocus) {
          if (!hasFocus) setState(() => _touched.add(c));
        },
        child: TextField(
          controller: _texts[c],
          obscureText: secret, // 字符被隐藏
          decoration: InputDecoration(
            labelText: label,
            errorText: error(c),
            // 错误信息可能跨两行
            errorMaxLines: 2,
            suffixIcon: valid ? const Icon(Icons.check_circle, color: Colors.green) : null,
          ),
          onChanged: (_) => setState(() => _success = false),
        ),
      );
    }

    return Scaffold(
      appBar: AppBar(title: const Text('Example 07 - the validation')),
      body: ListView(
        padding: const EdgeInsets.all(16),
        children: [
          DropdownButton<String>(
            value: _title,
            items: [for (final t in titles) DropdownMenuItem(value: t, child: Text(t))],
            onChanged: (t) => setState(() => _title = t!),
          ),
          field(Field.firstName, 'First name'),
          field(Field.lastName, 'Last name'),
          field(Field.login, 'Login'),
          field(Field.password, 'Password', secret: true),
          field(Field.confirmation, 'Confirmation', secret: true),
          const SizedBox(height: 16),
          FilledButton(onPressed: _send, child: const Text('Create the account')),
          const SizedBox(height: 12),
          if (_submitAttempted && errors.isNotEmpty)
            _Message('The form contains ${errors.length} error(s).', color: Colors.red.shade50),
          if (_success)
            _Message('Valid form: it could be sent to the server.', color: Colors.green.shade50),
        ],
      ),
    );
  }
}

// 一个小的私有组件:彩色背景上的一条消息
class _Message extends StatelessWidget {
  final String text;
  final Color color;

  const _Message(this.text, {required this.color});

  @override
  Widget build(BuildContext context) {
    return Container(
      padding: const EdgeInsets.all(12),
      decoration: BoxDecoration(color: color, borderRadius: BorderRadius.circular(8)),
      child: Text(text),
    );
  }
}
  • 第 24 行:输入的账户是一个 记录(record):一小组具名的值,无需编写类。[typedef] 为它指定一个名称。记录写成 [(title: 'Mr', firstName: 'Marie', ...)] ,读取方式为 [account.firstName];
  • 第 27–28 行:一个正则表达式(登录名的格式)和一个常量:规则与 [RdvMedecins] 服务器相同;
  • 第 32–59 行:规则:一个只依赖其参数的纯函数,返回一个 [Map] “出错字段 → 消息”。最后一条规则比较两个字段:确认密码和密码;
  • 第 82–84 行:每个文本字段一个验证器;
  • 第 86 行:已经离开过的字段;
  • 第 99–105 行:账户,按输入时的样子:根据验证器按需生成的记录。[_texts[Field.firstName]!]:访问 [Map] 会返回一个值或 [null] (键可能不存在);[!] 确认它存在;
  • 第 108–113 行:提交会把所有字段标记为已触碰(错误随之出现),然后仅在表单有效时才采取行动;
  • 第 120 行:在 [build] 中,错误每次都会重新计算;它们从不存储在状态中;
  • 第 123 行:一个局部函数:要 显示 的某个字段的错误,仅当该字段被触碰过时才有;
  • 第 126–142 行:一个创建字段的局部函数。[InputDecoration] 知道如何显示错误:[errorText]。当它不是 [null] 时,字段会被红色轮廓框住,并在其下方显示消息(最多两行:[errorMaxLines])。[suffixIcon]:字段右侧的图标——这里是用于已填写且有效字段的绿色对勾。[obscureText] 会遮蔽密码的字符;
  • 第 165–168 行:表单末尾的消息;
  • 第 176–187 行:一个小型私有组件,避免把同一个彩色方框重复写两次。

填写几个字段,然后提交;再把所有内容改正,重新提交:

注意:这种验证只是为用户提供的 便利 ——无需与服务器往返通信即可立即得到响应。它不保护任何东西:任何人都可以向服务器发送手工构造的请求([curl]……),而移动应用的代码也可以被修改。因此服务器始终会重新验证一切(见示例 25)。

3.8. 示例 08:Flutter 表单、Form 和 FormField

示例 07 中的表单,使用由 [Flutter] 自身提供的工具编写。[React] 需要一个库([React Hook Form]),而 [Flutter] 有自己的表单组件:

// =========================================================================
// lib/ex08_form/main.dart - Flutter 的表单:Form 和 FormField
// -------------------------------------------------------------------------
// 示例 07 的表单,改用 Flutter 自身提供的表单工具编写:
// - Form:把表单输入框(FormField)分组(GROUPS)的组件;
//   通过一个 "global key" 访问它,即 GlobalKey<FormState>;
//     - TextFormField、DropdownButtonFormField……:能够自行
//   验证的输入框。它们的 validator 参数是一个函数:
//     (value) -> 值没问题时返回 null,否则返回错误消息;
//         - autovalidateMode:何时(WHEN)验证(这里是用户
//   修改输入框之后,随后每次按键都验证);
//     - form.validate():验证所有(ALL)输入框,
//   显示它们的错误,并在一切正常时返回 true;
//     - form.save():调用每个输入框的 onSaved,由它把自己的
//   值存到我们想要的任何地方。
//     这些输入框不是受控的(NOT controlled):
// 每个都保存自己的值,Form 只在
// 验证和保存时才读取它们。
// =========================================================================

import 'dart:convert';

import 'package:flutter/material.dart';

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

void main() {
  runApp(
    MaterialApp(
      debugShowCheckedModeBanner: false,
      theme: ThemeData(colorSchemeSeed: Colors.indigo),
      home: const AccountPage(),
    ),
  );
}

class AccountPage extends StatefulWidget {
  const AccountPage({super.key});

  @override
  State<AccountPage> createState() => _AccountPageState();
}

class _AccountPageState extends State<AccountPage> {
  // 用于访问表单状态(validate、save、reset)的 key
  final _formKey = GlobalKey<FormState>();
  // 单个输入框的 key:用于在密码变化时重新验证确认密码
  final _confirmationKey = GlobalKey<FormFieldState<String>>();
  // 确认密码的规则中读取密码:一个 controller
  final _password = TextEditingController();
  // 由 onSaved 回调存储的值
  final Map<String, String> _account = {};
  // null:尚未发送;'':发送被拒绝;否则为已发送的 JSON
  String? _sent;

  @override
  void dispose() {
    _password.dispose();
    super.dispose();
  }

  void _create() {
    final form = _formKey.currentState!;
    if (!form.validate()) {
      setState(() => _sent = '');
      return;
    }
    form.save(); // 每个 onSaved 把自己的值存入 _account
    setState(() => _sent = jsonEncode(_account));
  }

  // 规则工厂(FACTORIES):每个都返回一个验证函数
  FormFieldValidator<String> _required(String message) =>
      (v) => (v == null || v.trim().isEmpty) ? message : null;

  FormFieldValidator<String> _maximum(int max, FormFieldValidator<String> other) =>
      (v) => other(v) ?? (v!.length > max ? 'At most $max characters.' : null);

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Example 08 - Form and FormField')),
      body: Form(
        key: _formKey,
        child: ListView(
          padding: const EdgeInsets.all(16),
          children: [
            // initialValue:初始值;之后输入框自行管理它的值
            DropdownButtonFormField<String>(
              initialValue: 'Mr',
              decoration: const InputDecoration(labelText: 'Title'),
              items: [for (final t in titles) DropdownMenuItem(value: t, child: Text(t))],
              onChanged: (_) {},
              onSaved: (t) => _account['title'] = t!,
            ),
            TextFormField(
              decoration: const InputDecoration(labelText: 'First name'),
              autovalidateMode: AutovalidateMode.onUserInteraction,
              validator: _maximum(20, _required('The first name is required.')),
              onSaved: (v) => _account['firstName'] = v!.trim(),
            ),
            TextFormField(
              decoration: const InputDecoration(labelText: 'Last name'),
              autovalidateMode: AutovalidateMode.onUserInteraction,
              validator: _maximum(20, _required('The last name is required.')),
              onSaved: (v) => _account['lastName'] = v!.trim(),
            ),
            TextFormField(
              decoration: const InputDecoration(labelText: 'Login', errorMaxLines: 2),
              autovalidateMode: AutovalidateMode.onUserInteraction,
              // 直接写出的规则:一个匿名函数
              validator: (v) {
                if (v == null || v.isEmpty) return 'The login is required.';
                if (!RegExp(r'^[a-z0-9._-]{1,30}$').hasMatch(v)) {
                  return 'Unaccented lower-case letters, digits, dot, hyphen, underscore.';
                }
                return null;
              },
              onSaved: (v) => _account['login'] = v!,
            ),
            TextFormField(
              controller: _password,
              obscureText: true,
              decoration: const InputDecoration(labelText: 'Password'),
              autovalidateMode: AutovalidateMode.onUserInteraction,
              validator: (v) {
                if (v == null || v.isEmpty) return 'The password is required.';
                return v.length < 6 ? 'At least 6 characters.' : null;
              },
              // 密码变化:确认密码会被重新验证
              // (如果它已经输入过)
              onChanged: (_) {
                final confirmation = _confirmationKey.currentState!;
                if (confirmation.value?.isNotEmpty ?? false) confirmation.validate();
              },
              onSaved: (v) => _account['password'] = v!,
            ),
            TextFormField(
              key: _confirmationKey,
              obscureText: true,
              decoration: const InputDecoration(labelText: 'Confirmation', errorMaxLines: 2),
              autovalidateMode: AutovalidateMode.onUserInteraction,
              // 一条读取另一个(ANOTHER)输入框的规则
              validator: (v) => v == _password.text ? null : 'The confirmation does not match the password.',
            ),
            const SizedBox(height: 16),
            FilledButton(onPressed: _create, child: const Text('Create the account')),
            const SizedBox(height: 12),
            if (_sent != null)
              Container(
                padding: const EdgeInsets.all(12),
                decoration: BoxDecoration(
                  color: _sent!.isEmpty ? Colors.red.shade50 : Colors.green.shade50,
                  borderRadius: BorderRadius.circular(8),
                ),
                child: Text(_sent!.isEmpty ? 'Invalid form.' : 'Valid form: $_sent'),
              ),
          ],
        ),
      ),
    );
  }
}
  • 第 46 行:一个 [Form] 包含若干表单字段。要在代码中与它交互(验证、保存),我们给它分配一个 全局 key,即 [GlobalKey]:一个能让你访问组件树中某个组件状态的对象([_formKey.currentState]);
  • 第 48 行:某一个字段的 key,以便单独对它重新验证;
  • 第 50 行:密码的控制器:确认密码的规则必须读取它;
  • 第 52 行:提交时保存的值;
  • 第 62–69 行:[validate()] 验证所有表单字段,显示出现的错误,如果一切正确则返回 [true] 。[save()] 随后对每个字段调用函数 [onSaved] ,由它设置该字段的值;
  • 第 73–77 行:规则生成器。验证规则([FormFieldValidator])是一个接收字段值的函数,如果值有效则返回 [null] ;否则返回错误消息。[_required('...')] 创建一条规则;[_maximum(20, other)] 创建一条规则,它先应用规则 [other],再应用它自己的规则([??]:如果第一条规则没有发现问题);
  • 第 83 行:表单及其 key;
  • 第 89–94 行:一个同时也是表单字段的下拉列表。[initialValue]:它的初始值;此后,该字段自行管理其值;
  • 第 96–100 行:[TextFormField] 就是一个 [TextField] ,同时也是一个表单字段:它有一条规则([validator])、一个保存函数([onSaved]),以及一种自动验证模式:[AutovalidateMode.onUserInteraction] 会在用户一修改字段时就验证它,此后每次按键都会验证;
  • 第 112–117 行:一条直接写出的规则,带有两项测试;
  • 第 132–134 行:密码更改时,如果确认密码已经输入过,就用该字段的 key 对确认密码重新验证;
  • 第 144 行:一条读取另一个字段的规则。

输入一些不正确的值并提交;然后改正它们:

该选择这两种方法中的哪一种?[Form] 和 [TextFormField] 足以应对规则写在应用中的表单。但在本课程中,服务器的规则优先:案例研究的应用中没有任何规则,而是在每个字段下方显示服务器返回的错误(示例 25)。这就是示例 07 中使用的方法,它涵盖了字段及其错误。

3.9. 示例 09:格式化值

表格的每一行显示一段代码及其显示结果。

3.9.1. 格式化函数

[Flutter] 没有内置的格式化机制(即 [Angular] 中的“管道”):在 [build] 中,我们调用保存在一个文件中的标准函数,这些函数可以单独测试:

// =========================================================================
// lib/ex09_formatting/formatting.dart - "自制" 的格式化函数
// -------------------------------------------------------------------------
// Flutter 自身没有格式化机制(Angular 有
// "管道"):在 build() 中,我们调用普通的函数(FUNCTIONS),存放
// 在一个文件中,并且可以单独测试:
//     timeRange(slot)           -> "8:00 - 8:20"
//     timeRange(slot, Part.start) -> "8:00"
// Dart 还允许用 "extension" 为现有类型添加(ADDING)方法:
// 'marie pelissier'.capitalized -> 'Marie Pelissier'。
// 对于日期、数字、金额,intl 包了解
// 各种语言的惯例(见 main.dart)。
// =========================================================================

// RdvMedecins API 所描述的时间段
class Slot {
  final int startHour;
  final int startMinute;
  final int endHour;
  final int endMinute;

  const Slot(this.startHour, this.startMinute, this.endHour, this.endMinute);
}

enum Part { all, start, end }

// "8:05" 而不是 "8:5"
String _time(int h, int m) => '$h:${m.toString().padLeft(2, '0')}';

// 一个可选(OPTIONAL)参数,带有默认值:[Part part = Part.all]
String timeRange(Slot c, [Part part = Part.all]) => switch (part) {
  Part.start => _time(c.startHour, c.startMinute),
  Part.end => _time(c.endHour, c.endMinute),
  Part.all => '${_time(c.startHour, c.startMinute)} - ${_time(c.endHour, c.endMinute)}',
};

// String 类型的一个扩展(EXTENSION):为所有(ALL)字符串提供新方法
extension Formatting on String {
  // "marie pelissier" -> "Marie Pelissier";\p{L}:一个字母,带不带重音均可
  String get capitalized => replaceAllMapped(
    RegExp(r'\p{L}+', unicode: true),
    (m) => m[0]![0].toUpperCase() + m[0]!.substring(1).toLowerCase(),
  );

  // "Marie PELISSIER" -> "MP"
  String get initials =>
      split(RegExp(r'\s+')).where((word) => word.isNotEmpty).map((word) => word[0].toUpperCase()).join();
}

// "2026-10-05"(RdvMedecins API 的格式)-> 一个日期
DateTime toDate(String day) => DateTime.parse(day);
  • 第 16–22 行:一个时间段,如 [RdvMedecins] 的 API 中所描述:小时和分钟,均为数字;
  • 第 28 行:“8:05”而不是“8:5”:[padLeft(2, '0')] 在左侧补零;
  • 第 31–34 行:一个带有 可选位置 参数(在方括号中)的函数,以及它的默认值:[timeRange(c)] 或 [timeRange(c, Part.start)];
  • 第 38–47 行:一个 扩展:它为 [String] 类型添加方法(这里是 getter),作用于所有字符串:['marie pelissier'.capitalized]。这是 [Dart] 的一个特色,对格式化非常有用。[replaceAllMapped] 把每个单词(由带重音或不带重音的字母组成的序列:[\p{L}+] 配合 [unicode: true])替换为函数的返回值;
  • 第 51 行:“2026-10-05”(API 的格式)-> 一个日期([DateTime])。

3.9.2. 屏幕

// =========================================================================
// lib/ex09_formatting/main.dart - 格式化值
// -------------------------------------------------------------------------
// 表格的每一行显示一段代码及其显示结果。
// intl 包的格式化器(DateFormat、NumberFormat)只创建
// 一次,且放在组件之外:创建它们比
// 使用它们代价更高。
// 各种语言的星期和月份名称默认不会被加载:
// initializeDateFormatting() 会加载它们,并且要在 runApp 之前(BEFORE)调用。
// =========================================================================

import 'dart:convert';

import 'package:flutter/material.dart';
import 'package:intl/date_symbol_data_local.dart';
import 'package:intl/intl.dart';

import 'formatting.dart';

// 日期:"现成的" 格式(yMMMd、yMMMMEEEEd、Hms……),或自定义模式
final shortDate = DateFormat.yMMMd('en_US');
final fullDate = DateFormat.yMMMMEEEEd('en_US');
final timeOnly = DateFormat.Hms('en_US');
final frenchDay = DateFormat.yMMMMd('fr_FR');
final pattern = DateFormat('MM/dd/yyyy HH:mm', 'en_US');
// 数字和金额
final euros = NumberFormat.currency(locale: 'en_US', symbol: '€');
final integer = NumberFormat.decimalPattern('en_US');
final percent = NumberFormat.decimalPercentPattern(locale: 'en_US', decimalDigits: 1);

const day = '2026-10-05'; // RdvMedecins API 格式的日期
const price = 1234.5;
const rate = 0.055;
const name = 'marie pelissier';
const doctor = {'title': 'Mme', 'firstName': 'Marie', 'lastName': 'PELISSIER'};
const languages = ['Dart', 'Flutter', 'Kotlin', 'Swift', 'SQL'];
const slots = [Slot(8, 0, 8, 20), Slot(8, 20, 8, 40), Slot(14, 5, 14, 25)];

// main 可以是异步的(ASYNCHRONOUS):我们等待语言加载完成
Future<void> main() async {
  await initializeDateFormatting('fr_FR');
  await initializeDateFormatting('en_US');
  runApp(
    MaterialApp(
      debugShowCheckedModeBanner: false,
      theme: ThemeData(colorSchemeSeed: Colors.indigo),
      home: const FormattingPage(),
    ),
  );
}

class FormattingPage extends StatefulWidget {
  const FormattingPage({super.key});

  @override
  State<FormattingPage> createState() => _FormattingPageState();
}

class _FormattingPageState extends State<FormattingPage> {
  DateTime _now = DateTime.now();

  @override
  Widget build(BuildContext context) {
    // (显示的代码,值):表格的一行,用 "record" 表示
    final rows = <(String, String)>[
      ('shortDate.format(now)', shortDate.format(_now)),
      ('fullDate.format(now)', fullDate.format(_now)),
      ('timeOnly.format(now)', timeOnly.format(_now)),
      ('pattern.format(now)', pattern.format(_now)),
      ('fullDate.format(toDate(day))', fullDate.format(toDate(day))),
      ('frenchDay.format(toDate(day))', frenchDay.format(toDate(day))),
      ('now.toString()', _now.toString()),
      ('euros.format(price)', euros.format(price)),
      ('integer.format(price)', integer.format(price)),
      ('price.toStringAsFixed(1)', price.toStringAsFixed(1)),
      ('percent.format(rate)', percent.format(rate)),
      ('name.toUpperCase()', name.toUpperCase()),
      ('name.capitalized', name.capitalized),
      ("'RDV'.toLowerCase()", 'RDV'.toLowerCase()),
      ("languages.take(3).join(', ')", languages.take(3).join(', ')),
      ('jsonEncode(doctor)', jsonEncode(doctor)),
      // 连续两次转换:第一次的结果传给第二次
      ('name.capitalized.initials', name.capitalized.initials),
    ];

    const codeStyle = TextStyle(fontFamily: 'RobotoMono', fontSize: 11, color: Color(0xFFC7254E));
    return Scaffold(
      appBar: AppBar(title: const Text('Example 09 - the formatting')),
      body: ListView(
        padding: const EdgeInsets.all(12),
        children: [
          // Table:简单表格;第一列占 55% 的宽度
          Table(
            columnWidths: const {0: FractionColumnWidth(0.55)},
            border: TableBorder(horizontalInside: BorderSide(color: Colors.grey.shade300)),
            children: [
              const TableRow(
                children: [
                  Padding(
                    padding: EdgeInsets.all(4),
                    child: Text('In the code', style: TextStyle(fontWeight: FontWeight.bold)),
                  ),
                  Padding(
                    padding: EdgeInsets.all(4),
                    child: Text('Displayed', style: TextStyle(fontWeight: FontWeight.bold)),
                  ),
                ],
              ),
              // record 可以被 "解构":(code, value)
              for (final (code, value) in rows)
                TableRow(
                  children: [
                    Padding(
                      padding: const EdgeInsets.all(4),
                      child: Text(code, style: codeStyle),
                    ),
                    Padding(padding: const EdgeInsets.all(4), child: Text(value)),
                  ],
                ),
            ],
          ),
          const SizedBox(height: 16),
          Text('Iterating over the entries of a Map', style: Theme.of(context).textTheme.titleSmall),
          for (final MapEntry(:key, :value) in doctor.entries) Text('$key = $value'),
          const SizedBox(height: 16),
          Text('A home-made function: timeRange', style: Theme.of(context).textTheme.titleSmall),
          for (final c in slots) Text('${timeRange(c)} (start: ${timeRange(c, Part.start)})'),
          const SizedBox(height: 16),
          Align(
            alignment: Alignment.centerLeft,
            child: OutlinedButton(
              onPressed: () => setState(() => _now = DateTime.now()),
              child: const Text('Refresh the time'),
            ),
          ),
        ],
      ),
    );
  }
}
  • 第 21–25 行:来自 [intl] 包的日期格式化器。[DateFormat] 包含“预定义”格式,由要显示的部分来标识:[yMMMd] (年、缩写的月、日)、[yMMMMEEEEd] (外加完整的星期几)、[Hms] (时、分、秒)……你也可以指定一个模式:['MM/dd/yyyy HH:mm']。第二个参数是语言;
  • 第 27–29 行:数字格式化器:金额、整数、百分比;
  • 第 40–42 行:每种语言的星期和月份名称默认并不加载:[initializeDateFormatting] 会在 [runApp] 之前加载它们。[main] 可以是异步的;
  • 第 65–83 行:表格:一个由 位置式 记录 [(code, value)] 构成的列表,不带字段名;
  • 第 93–111 行:[Table] 绘制一个简单的表格。[columnWidths]:第一列占宽度的 55%;[border]:行与行之间的线。[for (final (code, value) in rows)] 拆解每一条记录;
  • 第 124 行:遍历 [Map] 中的条目:[:key] 是 [key: key] 的简写;
  • 第 127 行:自定义函数。

对于日期、数字和金额,[intl] 的作用与 Web 浏览器中的 [Intl] API 相同:它理解每种语言的惯例(分隔符、月份名称、各部分的顺序)。该表使用美式英语的惯例(€1,234.50、“month day, year”);请注意,在法语中,千位用细的不换行空格分隔(1 234,50 €),顺序是“日 月 年”([frenchDay] 一行)。