Skip to content

4. 组件

编写自己的组件是使用 [Flutter] 的核心:一个写得好的屏幕由若干小组件构成,每个组件都有自己的参数、自己的 [build],必要时还有自己的状态。本章展示它们如何相互通信(参数、函数)、如何组装(组合)、如何运作(生命周期)、如何在不逐层传递的情况下共享数据(继承的数据),以及如何复用行为。

4.1. 示例 10:组件及其参数

4.1.1. 数据类型

父组件和子组件共用一个类,它定义在自己的文件中:

// 由父组件(DoctorsPage)和子组件(DoctorCard)共享的数据类型
class Doctor {
  final int id;
  final String title;
  final String firstName;
  final String lastName;
  final String specialty;
  final bool available;

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

  // 一个副本,其中只有可预约状态发生变化
  Doctor withAvailability(bool d) =>
      Doctor(id: id, title: title, firstName: firstName, lastName: lastName, specialty: specialty, available: d);
}
  • 第 10–16 行:一个带命名参数的构造函数,所有参数都是必需的:[Doctor(id: 1, title: 'Mme', ...)]。命名参数使调用更易读,并且它们的顺序无关紧要;
  • 第 20–21 行:一个只改变可用性的副本(对象本身永远不会改变)。

4.1.2. 子组件

// =========================================================================
// lib/ex10_widget_parameters/doctor_card.dart - 一个子组件
// -------------------------------------------------------------------------
// 它通过构造函数的参数(PARAMETERS)从父组件接收数据,
// 并存放在 final 字段中。它们的类型在
// 编译时检查:DoctorCard(doctor: 42) 会被拒绝。
//   - required:父组件必须(MUST)提供这个参数;
//   - this.compact = false:一个可选参数,带有默认值。
//
// 黄金法则:组件绝不(NEVER)修改自己的参数(它们是 final)。
// 数据从父组件流向子组件;要请求
// 变更,子组件调用父组件传给它的一个函数
// (见示例 11)。当父组件的数据变化时,它会用新的参数重建(REBUILDS)
// 它的子组件。
// =========================================================================

import 'package:flutter/material.dart';

import 'doctor.dart';

// 卡片的 "样式":此文件私有(PRIVATE)的常量(即 "_")。
// 其他组件既看不到它们,也不会受它们影响
const _initialsColor = Color(0xFF087EA4);
const _initialsStyle = TextStyle(color: Colors.white, fontWeight: FontWeight.bold);

class DoctorCard extends StatelessWidget {
  final Doctor doctor;
  final int rank;
  final bool compact;

  // const:如果所有参数都是常量,那么这个组件也是常量
  // (这样 Flutter 甚至不需要重建它)
  const DoctorCard({super.key, required this.doctor, required this.rank, this.compact = false});

  @override
  Widget build(BuildContext context) {
    // 由参数计算出来的值
    final initials = '${doctor.firstName[0]}${doctor.lastName[0]}';

    return Card(
      // 可预约的医生显示绿色边框
      shape: RoundedRectangleBorder(
        borderRadius: BorderRadius.circular(12),
        side: doctor.available ? const BorderSide(color: Colors.green, width: 2) : BorderSide.none,
      ),
      child: Padding(
        padding: const EdgeInsets.all(12),
        child: Row(
          children: [
            CircleAvatar(
              backgroundColor: _initialsColor,
              child: Text(initials, style: _initialsStyle),
            ),
            const SizedBox(width: 12),
            // Expanded:文本占据所有剩余宽度
            Expanded(
              child: Column(
                crossAxisAlignment: CrossAxisAlignment.start,
                children: [
                  Text(
                    '$rank. ${doctor.title} ${doctor.firstName} ${doctor.lastName}',
                    style: Theme.of(context).textTheme.titleMedium,
                  ),
                  if (!compact) Text(doctor.specialty, style: const TextStyle(color: Colors.grey)),
                ],
              ),
            ),
          ],
        ),
      ),
    );
  }
}
  • 第 23–24 行:卡片的“样式”:常量,私有 于此文件(带“_”)。其他文件无法看到它们,也不会受它们影响。在 [Flutter] 中,这相当于 [React] 的“CSS 模块”:没有全局样式表;组件的样式嵌入在它的代码中;
  • 第 27–29 行:组件的 参数,保存在 [final] 字段中;
  • 第 33 行:构造函数。[required this.doctor]:一个必需参数,直接存入字段;[this.compact = false]:一个带默认值的可选参数。构造函数是 [const] 的:如果所有参数都是常量,卡片也是常量;
  • 第 38 行:一个由参数计算得出的值;
  • 第 42–44 行:卡片的形状([Card]):如果医生可用,则为圆角和绿色边框(否则为 [BorderSide.none] );
  • 第 50–52 行:一个带有首字母的彩色圆盘;
  • 第 64 行:专业只在非紧凑视图中显示。

黄金法则:组件 绝不会修改它自己的参数(它们是 [final] 的;顺便说一句,编译器禁止这样做)。数据从父组件流向子组件;要请求更改,子组件调用父组件传给它的函数(示例 11)。当父组件更改其数据时,它会 重新构建 它的子组件,并传入新的参数。

4.1.3. 父组件

// =========================================================================
// lib/ex10_widget_parameters/main.dart - 父组件(PARENT)
// -------------------------------------------------------------------------
// 它导入 DoctorCard 组件,并按需要多次使用它,就像使用任何 Flutter 组件一样:
// 组件是一块可复用(REUSABLE)的界面,带有自己的参数、
// build() 和样式。编写自己的组件是
// Flutter 开发的核心:一个写得好的界面是由
// 小组件构成的。
// =========================================================================

import 'package:flutter/material.dart';

import 'doctor_card.dart';
import 'doctor.dart';

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> {
  List<Doctor> _doctors = const [
    Doctor(id: 1, title: 'Mme', firstName: 'Marie', lastName: 'PELISSIER', specialty: 'general practitioner', available: true),
    Doctor(id: 2, title: 'Mr', firstName: 'Paul', lastName: 'TATOU', specialty: 'pediatrician', available: false),
    Doctor(id: 3, title: 'Melle', firstName: 'Sophie', lastName: 'DUPONT', specialty: 'general practitioner', available: true),
  ];
  bool _compact = false;

  // 父组件修改它的(ITS)数据:Flutter 再次调用它的 build(),从而
  // 用新的参数重建子组件
  void _toggleAvailability() {
    setState(() {
      _doctors = [for (final m in _doctors) m.withAvailability(!m.available)];
    });
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Example 10 - the widgets and their parameters')),
      body: ListView(
        padding: const EdgeInsets.all(16),
        children: [
          SwitchListTile(
            contentPadding: EdgeInsets.zero,
            title: const Text('compact display'),
            value: _compact,
            onChanged: (v) => setState(() => _compact = v),
          ),
          Align(
            alignment: Alignment.centerLeft,
            child: OutlinedButton(onPressed: _toggleAvailability, child: const Text('Toggle the availabilities')),
          ),
          const SizedBox(height: 8),
          for (final (i, m) in _doctors.indexed)
            // 每张卡片接收它自己的(ITS)参数
            DoctorCard(key: ValueKey(m.id), doctor: m, rank: i + 1, compact: _compact),
          const SizedBox(height: 16),
          const Text(
            'The same card, in its compact version, by setting the parameter:',
            style: TextStyle(color: Colors.grey),
          ),
          SizedBox(width: 260, child: DoctorCard(doctor: _doctors[0], rank: 1, compact: true)),
        ],
      ),
    );
  }
}
  • 第 34–39 行:父组件的状态:医生列表(一个常量列表,它将被另一个列表替换)和紧凑显示;
  • 第 43–45 行:父组件把它自己的数据更改为一个新列表,其中由医生的副本组成。[Flutter] 会调用它的 [build],后者用新的参数重建这些卡片;
  • 第 69 行:每位医生一张卡片,带有其自己的参数。[DoctorCard] 组件的用法与 [Flutter] 自带的组件完全一样;
  • 第 75 行:同一张卡片,紧凑版本,放在一个 260 点宽的方框中。

最初,然后在紧凑视图中,可用性被反转:

用一个创建组件的方法(如示例 02 中的 [_line] )还是用一个真正的组件([DoctorCard])?真正的组件几乎总是更可取:它有名称,它的参数有类型并有文档,它可以在别处复用,而且 [Flutter] 可以避免重建它(如果它是 [const],或者它的参数没有变化)。

4.2. 示例 11:子组件通知其父组件

数据通过参数向下流动;信息则通过作为参数传递的 函数 向上回流。

4.2.1. 来自子组件的“事件”

// =========================================================================
// lib/ex11_lifting_state_up/counter.dart
// -------------------------------------------------------------------------
// 一个通知(NOTIFIES)父组件的子组件:父组件把函数(FUNCTIONS)作为
// 参数传给它(按惯例,其名称以 "on" 开头),子组件
// 在发生某事时调用它们:
//     Counter(label: 'Coffees', max: 3, onIncrement: ..., onLimit: ...)
// 这些函数的类型在 Flutter 中有现成的名称:
//   - ValueChanged<int> :接收一个 int 且不返回任何值的函数;
//   - VoidCallback      :没有参数且不返回任何值的函数。
// =========================================================================

import 'package:flutter/material.dart';

class Counter extends StatefulWidget {
  final String label;
  final int max;
  final ValueChanged<int> onIncrement; // 带着新的值
  final VoidCallback onLimit; // 不带数据

  const Counter({
    super.key,
    required this.label,
    required this.max,
    required this.onIncrement,
    required this.onLimit,
  });

  @override
  State<Counter> createState() => _CounterState();
}

class _CounterState extends State<Counter> {
  // 此计数器特有(SPECIFIC)的状态:每个 Counter 都有自己的状态
  int _value = 0;

  void _plus() {
    // widget:在 State 对象中,提供对该组件参数的访问
    if (_value >= widget.max) {
      widget.onLimit();
      return;
    }
    setState(() => _value++);
    // 父组件得到通知(NOTIFIED),并接收新的值
    widget.onIncrement(_value);
  }

  @override
  Widget build(BuildContext context) {
    return Row(
      children: [
        SizedBox(width: 110, child: Text(widget.label)),
        OutlinedButton(onPressed: _plus, child: const Text('+1')),
        const SizedBox(width: 12),
        Chip(label: Text('$_value / ${widget.max}')),
      ],
    );
  }
}
  • 第 18–19 行:两个函数类型的参数,计数器会调用它们。[ValueChanged<int>] 是接收一个 [int] 且不返回任何内容的函数的类型;[VoidCallback] 是无参数函数的类型。按惯例,它们的名称以“on”开头,例如 [onPressed] 或 [onChanged] ,见于 [Flutter] 的各个组件;
  • 第 35 行:此计数器专属的状态:每个 [Counter] 都有自己的状态;
  • 第 37–45 行:在 [State] 对象中,[widget] 可以访问组件的设置:[widget.max]、[widget.onLimit]... 如果超过最大值,计数器会通知其父组件([widget.onLimit()]);否则,它先更改自己的状态,然后传递新值来通知其父组件。与 [React] 不同,状态会立即更新:[_value] 在被传递时已经拥有新值。

4.2.2. 受控组件

// =========================================================================
// lib/ex11_lifting_state_up/labeled_text_field.dart - 一个受控(CONTROLLED)组件
// -------------------------------------------------------------------------
// 一个 "自制" 的表单输入框(标签 + 输入框 + 帮助文本 + 字符
// 计数器),其用法与受控输入框相同:
//     LabeledTextField(value: _name, onChanged: (v) => setState(() => _name = v), ...)
// 这个值属于父组件(PARENT),由它传入(value),并且
// 每次按键都通知它(onChanged)。由父组件说了算。
//
// Flutter 特有的一个难点:TextField 把它的文本保存在一个
// controller 中,而它必须在多次重建之间保持存活。因此这个组件有一个
// 状态(controller)……当父组件修改
// 值("清除" 按钮)时,它必须让其保持最新(UP TO DATE):这就是 didUpdateWidget 的作用。
// =========================================================================

import 'package:flutter/material.dart';

class LabeledTextField extends StatefulWidget {
  final String value;
  final ValueChanged<String> onChanged;
  final String label;
  final int max;
  final String help;

  const LabeledTextField({
    super.key,
    required this.value,
    required this.onChanged,
    required this.label,
    required this.max,
    this.help = '',
  });

  @override
  State<LabeledTextField> createState() => _LabeledTextFieldState();
}

class _LabeledTextFieldState extends State<LabeledTextField> {
  // late:该字段稍后(在 initState 中)、在任何使用之前初始化
  late final TextEditingController _controller;

  @override
  void initState() {
    super.initState();
    _controller = TextEditingController(text: widget.value);
  }

  // 当父组件用新的参数重建这个组件时调用;
  // oldWidget:旧的组件,用于比较
  @override
  void didUpdateWidget(LabeledTextField oldWidget) {
    super.didUpdateWidget(oldWidget);
    if (widget.value != _controller.text) {
      _controller.text = widget.value; // 父组件自己修改了值
    }
  }

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

  @override
  Widget build(BuildContext context) {
    final full = widget.value.length == widget.max;
    return TextField(
      controller: _controller,
      maxLength: widget.max, // 输入框拒绝多余的字符
      decoration: InputDecoration(
        labelText: widget.label,
        helperText: widget.help,
        // 输入框已满时边框变红
        errorText: full ? 'Maximum length reached' : null,
      ),
      onChanged: widget.onChanged, // 父组件的函数,原样传递
    );
  }
}

一个“自定义”表单字段(标签 + 输入框 + 提示 + 字符计数器),其作用相当于受控字段:值属于父组件,由父组件传给该字段([value]),并且每次按键都会通知父组件([onChanged])。

  • 第 40 行:[late]:该字段将在稍后初始化(在 [initState] 中),但早于它被使用。[Dart] 会在运行时检查这一点;
  • 第 43–45 行:控制器以父组件的值作为初始值;
  • 第 51–54 行:这正是 [Flutter] 特有的难点:[TextField] 把文本保存在控制器中,而控制器必须在页面重建后依然保留。因此该组件拥有状态(即控制器)……当父组件自行修改值时(“清除”按钮),它必须让这个状态保持同步。[didUpdateWidget] 在父组件每次以新参数重建该组件时被调用;它会收到旧的组件以便比较。如果父组件的值与字段中的文本不同,就把它复制过来;
  • 第 69 行:该字段拒绝超出的字符,并显示计数器(“12/20”);
  • 第 72 行:提示显示在字段下方;
  • 第 74 行:字段写满时,边框变红;
  • 第 76 行:父组件的函数,原样传给 [TextField]。

4.2.3. 父组件

// =========================================================================
// lib/ex11_lifting_state_up/main.dart - 父组件监听它的子组件
// -------------------------------------------------------------------------
// 数据向下流动(参数);信息通过作为参数传入的
// 函数向上流动:
//   1. 子组件的 "事件":onIncrement、onLimit;
//   2. 一个受控组件:value + onChanged,就像 Checkbox。状态
//      仍然属于父组件,父组件可以自己修改它(Clear)。
// =========================================================================

import 'package:flutter/material.dart';

import 'labeled_text_field.dart';
import 'counter.dart';

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

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

  @override
  State<ParentPage> createState() => _ParentPageState();
}

class _ParentPageState extends State<ParentPage> {
  int _total = 0;
  String _message = '';
  String _firstName = 'Marie';
  String _lastName = 'PELISSIER';

  // 计数器调用的函数:它接收计数器传来的值
  void _onIncrement(String label, int value) {
    setState(() {
      _total++;
      _message = '$label is now $value';
    });
  }

  void _clear() {
    setState(() {
      _firstName = '';
      _lastName = '';
    });
  }

  @override
  Widget build(BuildContext context) {
    final titleStyle = Theme.of(context).textTheme.titleSmall;
    return Scaffold(
      appBar: AppBar(title: const Text('Example 11 - the child notifies its parent')),
      body: ListView(
        padding: const EdgeInsets.all(16),
        children: [
          Card(
            child: Padding(
              padding: const EdgeInsets.all(12),
              child: Column(
                crossAxisAlignment: CrossAxisAlignment.start,
                children: [
                  Text('1. Functions called by the children', style: titleStyle),
                  Counter(
                    label: 'Coffees',
                    max: 3,
                    onIncrement: (v) => _onIncrement('Coffees', v),
                    onLimit: () => setState(() => _message = 'No more than 3 coffees!'),
                  ),
                  Counter(
                    label: 'Glasses of water',
                    max: 8,
                    onIncrement: (v) => _onIncrement('Glasses of water', v),
                    onLimit: () => setState(() => _message = 'Enough drinking.'),
                  ),
                  const SizedBox(height: 8),
                  Text('Total of the clicks: $_total - $_message', style: const TextStyle(fontStyle: FontStyle.italic)),
                ],
              ),
            ),
          ),
          Card(
            child: Padding(
              padding: const EdgeInsets.all(12),
              child: Column(
                crossAxisAlignment: CrossAxisAlignment.start,
                children: [
                  Text('2. Controlled widgets', style: titleStyle),
                  LabeledTextField(
                    value: _firstName,
                    onChanged: (v) => setState(() => _firstName = v),
                    label: 'First name',
                    max: 20,
                    help: 'Required',
                  ),
                  LabeledTextField(
                    value: _lastName,
                    onChanged: (v) => setState(() => _lastName = v),
                    label: 'Last name',
                    max: 20,
                    help: 'Upper-cased when displayed',
                  ),
                  const SizedBox(height: 8),
                  Text.rich(
                    TextSpan(
                      children: [
                        const TextSpan(text: "Parent's data: "),
                        TextSpan(
                          text: '$_firstName ${_lastName.toUpperCase()}',
                          style: const TextStyle(fontWeight: FontWeight.bold),
                        ),
                      ],
                    ),
                  ),
                  const SizedBox(height: 8),
                  OutlinedButton(onPressed: _clear, child: const Text('Clear (from the parent)')),
                ],
              ),
            ),
          ),
        ],
      ),
    );
  }
}
  • 第 40–43 行:计数器调用的函数;它接收计数器传来的值;
  • 第 69–73 行:一个计数器及其将要调用的函数。[(v) => _onIncrement('Coffees', v)]:一个匿名函数,它把自己的参数(标签)加进去;
  • 第 94–99 行:一个受控字段:它的值,以及修改父组件状态的函数;
  • 第 114 行:父组件的数据,它随输入而变化;
  • 第 121 行:父组件自行修改值:字段被清空(通过它们的 [didUpdateWidget])。

点击第一个计数器四次,第二个计数器一次,并输入姓名;然后从父组件清除这些字段:

4.3. 示例 12:组合

4.3.1. 卡片

组件的参数传递数据……但也传递内容:组件和其他值一样,是一个值,可以传给另一个组件。[Flutter] 到处都在使用这一点:[child] 属于 [Padding],[title] 属于 [AppBar],[body] 属于 [Scaffold]。

// =========================================================================
// lib/ex12_composition/info_card.dart - 一个可复用的模板
// -------------------------------------------------------------------------
// 组件的参数传递的是数据(DATA)……也可以传递
// 内容(CONTENT):组件和其他任何值一样,可以传给
// 另一个组件,由后者把它放在想放的位置。Flutter 到处都在使用这一点:
// Padding 的 child、AppBar 的 title、Scaffold 的 body……
//   - child:按惯例,是 "主要" 内容;
//   - header、footer:其他位置(一些 "插槽"),由
//     父组件提供;header 有默认内容,footer 是可选的。
// 卡片确定外框(边框、头部、底部),父组件提供
// 放在里面的内容。
// =========================================================================

import 'package:flutter/material.dart';

class InfoCard extends StatelessWidget {
  final Color? color; // "?":可选(默认为 null)
  final Widget header;
  final Widget? footer;
  final Widget child;

  const InfoCard({super.key, this.color, this.header = const Text('Untitled'), this.footer, required this.child});

  @override
  Widget build(BuildContext context) {
    final background = color ?? Colors.grey.shade300;
    return Card(
      // clipBehavior:彩色头部跟随卡片的圆角
      clipBehavior: Clip.antiAlias,
      shape: RoundedRectangleBorder(
        borderRadius: BorderRadius.circular(8),
        side: BorderSide(color: background),
      ),
      child: Column(
        crossAxisAlignment: CrossAxisAlignment.stretch,
        children: [
          Container(
            color: background,
            padding: const EdgeInsets.all(10),
            // DefaultTextStyle:头部所有(ALL)文本的样式,
            // 无论父组件提供的是什么组件
            child: DefaultTextStyle.merge(
              style: TextStyle(color: color == null ? Colors.black : Colors.white, fontWeight: FontWeight.bold),
              child: header,
            ),
          ),
          Padding(padding: const EdgeInsets.all(10), child: child),
          // 没有提供 footer:则完全没有底部
          if (footer != null)
            Container(
              color: Colors.grey.shade100,
              padding: const EdgeInsets.all(8),
              child: DefaultTextStyle.merge(
                style: const TextStyle(color: Colors.grey, fontSize: 12),
                child: footer!,
              ),
            ),
        ],
      ),
    );
  }
}
  • 第 18–21 行:参数:一个可选的颜色([Color?]),以及三个内容插槽:[header], [footer](可选),和 [child],即主要内容;
  • 第 23 行:标题区有默认内容:一个常量组件;
  • 第 27 行:标题区的颜色:传入的颜色,或浅灰色;
  • 第 30 行:带颜色的标题区被裁剪,以匹配卡片的圆角;
  • 第 43–45 行:[DefaultTextStyle] 设置其子树中所有文本的样式,而不论父组件提供的是哪个组件:标题区文字为粗体,在彩色背景上为白色;
  • 第 48 行:主要内容,由父组件提供;
  • 第 50–58 行:未提供页脚;则完全没有页脚。[footer!]:在这个分支中,[footer] 不是 [null] (对于字段,编译器无法推断出这一点,因此需要 [!])。

4.3.2. 泛型表格

// =========================================================================
// lib/ex12_composition/simple_table.dart - 一个泛型(GENERIC)表格
// -------------------------------------------------------------------------
// SimpleTable<T> 是一个泛型组件:它显示任意
// 类型 T 的行。它知道如何遍历各行,但不知道如何显示单独的
// 一行:由父组件告诉它,方法是传给它一个函数(FUNCTION),
// cells(row, index),该函数返回各单元格的组件。
// 这就是 Flutter "builder"(ListView.builder、
// FutureBuilder……)的原理:由父组件提供的内容使用
// 属于子组件的数据(行及其序号)。
// =========================================================================

import 'package:flutter/material.dart';

// 构建一行单元格的函数的类型
typedef CellsBuilder<T> = List<Widget> Function(T row, int index);

class SimpleTable<T> extends StatelessWidget {
  final List<T> rows;
  final List<String> columns;
  final CellsBuilder<T> cells;
  final Widget empty; // 没有任何行时显示的内容

  const SimpleTable({
    super.key,
    required this.rows,
    required this.columns,
    required this.cells,
    this.empty = const Text('No data.'),
  });

  // 一个单元格:内容周围留一点边距
  static Widget _cell(Widget content) => Padding(padding: const EdgeInsets.all(6), child: content);

  @override
  Widget build(BuildContext context) {
    if (rows.isEmpty) {
      return Column(
        crossAxisAlignment: CrossAxisAlignment.start,
        children: [
          Text(columns.join('   '), style: const TextStyle(fontWeight: FontWeight.bold)),
          const Divider(),
          DefaultTextStyle.merge(
            style: const TextStyle(color: Colors.grey),
            child: empty,
          ),
        ],
      );
    }
    return Table(
      defaultVerticalAlignment: TableCellVerticalAlignment.middle,
      border: TableBorder(horizontalInside: BorderSide(color: Colors.grey.shade300)),
      children: [
        TableRow(
          children: [for (final c in columns) _cell(Text(c, style: const TextStyle(fontWeight: FontWeight.bold)))],
        ),
        for (final (i, row) in rows.indexed)
          // 此行(THIS row)的单元格,由父组件的函数构建
          TableRow(children: [for (final c in cells(row, i)) _cell(c)]),
      ],
    );
  }
}
  • 第 16 行:一个函数的类型,该函数接收一行(类型为 [T])及其索引,并返回该行各单元格的组件;
  • 第 18 行:一个泛型组件:它显示任意类型([T])的行。它知道如何遍历各行,却不知道如何显示某一行;父组件通过传入函数 [cells] 告诉它怎么做。这就是 [Flutter] “构建器”([ListView.builder]、[FutureBuilder]……)背后的原理:内容由父组件提供,但使用的是属于子组件的数据(行及其索引)。[React] 把这称为“render prop”;
  • 第 33 行:一个 [static] 方法,它不使用该组件的任何字段;
  • 第 37–45 行:没有行:列标题和 [empty] 内容,由父组件提供;
  • 第 50–59 行:表格:一行表头,后面是每条数据对应的一行,其单元格由父组件的函数生成。

4.3.3. 父组件

// =========================================================================
// lib/ex12_composition/main.dart - 使用 InfoCard 和 SimpleTable 模板
// =========================================================================

import 'package:flutter/material.dart';

import 'info_card.dart';
import 'simple_table.dart';

// 一个 slot:一个具名 record(无需编写类)
typedef Slot = ({int id, String timeRange, String? patient});

const slots = <Slot>[
  (id: 1, timeRange: '8:00 - 8:20', patient: null),
  (id: 2, timeRange: '8:20 - 8:40', patient: 'Mme Alice DURAND'),
  (id: 3, timeRange: '8:40 - 9:00', patient: null),
];

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

class CompositionPage extends StatelessWidget {
  const CompositionPage({super.key});

  @override
  Widget build(BuildContext context) {
    final free = slots.where((c) => c.patient == null).length;

    return Scaffold(
      appBar: AppBar(title: const Text('Example 12 - the composition')),
      body: ListView(
        padding: const EdgeInsets.all(16),
        children: [
          // header 和 footer:作为参数传入的组件;child:内容
          InfoCard(
            color: Colors.indigo,
            header: const Row(
              children: [
                Icon(Icons.event, color: Colors.white),
                SizedBox(width: 8),
                // Expanded:文本占据剩余空间(并自动换行)
                Expanded(child: Text('Schedule of Mme PELISSIER')),
              ],
            ),
            footer: Text('$free free slot(s)'),
            // SimpleTable<Slot>:T 由各行的类型推断得出
            child: SimpleTable(
              rows: slots,
              columns: const ['#', 'Slot', 'Status'],
              // 构建单独一行(ONE row)单元格的函数;
              // c 接收该行,i 是它的序号
              cells: (c, i) => [
                Text('${i + 1}'),
                Text(c.timeRange),
                c.patient != null
                    ? Chip(label: Text(c.patient!), visualDensity: VisualDensity.compact)
                    : Chip(
                        label: const Text('Free'),
                        backgroundColor: Colors.green.shade100,
                        visualDensity: VisualDensity.compact,
                      ),
              ],
            ),
          ),
          const InfoCard(
            color: Colors.green,
            header: Text('A card without a footer'),
            child: Text('The footer is not provided: the card does not display it.'),
          ),
          // 没有提供 header:使用默认内容 "Untitled"
          InfoCard(
            child: SimpleTable<({int id, String name})>(
              rows: const [],
              columns: const ['Name'],
              cells: (p, _) => [Text(p.name)],
              empty: const Text('Nobody for now.'),
            ),
          ),
        ],
      ),
    );
  }
}
  • 第 11 行:一个插槽,采用具名记录的形式;
  • 第 42–52 行:一张卡片:它的颜色、标题区(一行:一个图标和文本)、页脚;
  • 第 54–66 行:它的内容:一个时间段表格。[T] 由 [rows] 的类型推导而来:它是 [SimpleTable<Slot>]。[cells] 函数接收一个时间段([c])及其序号([i]),并返回三个组件;
  • 第 72–75 行:一张没有页脚的卡片;
  • 第 79–83 行:一张没有标题区的卡片(默认内容“Untitled”);其表格为空。[SimpleTable<({int id, String name})>]:类型 [T] 被显式指定,因为 [rows: const []] 无法让它被推断出来。

Image

卡片定义框架(边框、标题区、页脚);父组件在其中提供内容。[Flutter] 自带的组件本身就是这样构建的:[Scaffold] 定义屏幕的结构,并接收顶部栏、主体和悬浮按钮。

4.4. 示例 13:组件的生命周期

4.4.1. 时钟

// =========================================================================
// lib/ex13_lifecycle/clock.dart - 一个会启动和停止的组件
// -------------------------------------------------------------------------
// StatefulWidget 的 State 对象的生命周期:
//   1. initState()              :它刚刚被创建,组件即将
//                                 出现。需要启动的东西在这里启动;
//   2. didChangeDependencies()  :紧接着调用,之后每当它所读取的
//                                 继承数据发生变化时再次调用(见示例 14);
//   3. build()                  :按需要调用任意多次;
//   4. didUpdateWidget(old)     :父组件用新的
//                                 参数重建了它;
//   5. dispose()                :组件永久消失。
//                                 已启动的东西在这里停止(STOPPED)。
// 时钟在出现时启动一个定时器(Timer.periodic)……
// 并且在消失时必须(imperatively)停止它:否则
// 定时器会白白继续运行,并对一个已销毁的对象
// 调用 setState()(这会出错)。
// =========================================================================

import 'dart:async';

import 'package:flutter/material.dart';

String currentTime() => DateTime.now().toString().substring(11, 19); // "12:05:09"

class Clock extends StatefulWidget {
  final ValueChanged<String> onLog;
  final Color color;

  const Clock({super.key, required this.onLog, this.color = Colors.indigo});

  @override
  State<Clock> createState() => _ClockState();
}

class _ClockState extends State<Clock> {
  String _time = currentTime();
  // late:在 initState 中初始化
  late final Timer _timer;

  // 通知父组件……要在当前界面构建完成之后(AFTER):我们不会在
  // 组件(父组件)正在构建时修改它的状态
  void _log(String message) {
    WidgetsBinding.instance.addPostFrameCallback((_) => widget.onLog(message));
  }

  @override
  void initState() {
    super.initState(); // 始终最先调用
    _log('Clock: initState - starting the timer');
    _timer = Timer.periodic(const Duration(seconds: 1), (_) {
      setState(() => _time = currentTime());
    });
  }

  @override
  void didUpdateWidget(Clock oldWidget) {
    super.didUpdateWidget(oldWidget);
    if (oldWidget.color != widget.color) {
      _log('Clock: didUpdateWidget - new color');
    }
  }

  @override
  void dispose() {
    _timer.cancel(); // 清理(CLEANUP)
    _log('Clock: dispose - timer stopped');
    super.dispose(); // 始终最后调用
  }

  @override
  Widget build(BuildContext context) {
    return Text(
      _time,
      style: TextStyle(fontSize: 40, fontFamily: 'RobotoMono', color: widget.color),
    );
  }
}

下面是 [State] 对象在 [StatefulWidget] 中的生命周期:

方法
何时调用?
initState()
对象刚刚创建;组件即将出现。需要启动的一切(定时器、订阅等)都在这里启动
didChangeDependencies()
紧跟在 initState 之后,此后每当它所读取的任何继承数据发生变化时也会调用(见示例 14)
build()
按需调用任意多次
didUpdateWidget(old)
父组件以新参数重建了它
dispose()
组件永久消失。在那里 启动的一切都被停止
  • 第 37–39 行:状态:显示的时间,以及一个定时器([Timer],来自 [dart:async] 库);
  • 第 43–44 行:时钟把其生命周期的每个阶段通知给父组件。但它是在 [initState] 或 [dispose] 期间这样做的——也就是在 [Flutter] 构建屏幕的时候:此刻父组件不能修改自己的状态([setState] 会引发错误)。[addPostFrameCallback] 会把调用推迟到当前画面渲染完成之后;
  • 第 48–52 行:[super.initState()] 始终放在最前。然后启动一个周期性定时器:它的函数每秒被调用一次并更新时间;
  • 第 57–60 行:父组件以不同的颜色重绘了时钟:对此做个记录;
  • 第 65–68 行:清理:我们停止定时器。否则,它会白白继续运行,并在一个已销毁的对象上调用 [setState] ,导致错误(“setState() called after dispose()”)和内存泄漏。[super.dispose()] 始终放在最后。

4.4.2. 父组件

// =========================================================================
// lib/ex13_lifecycle/main.dart
// -------------------------------------------------------------------------
//   - if (_withClock) Clock(...):勾选 / 取消勾选复选框会让
//     组件出现 / 消失(先 initState,再 dispose,见
//     clock.dart);修改它的颜色会重建它(didUpdateWidget);
//   - autofocus:输入框一出现就获得焦点
//     (手机键盘随之打开);
//   - 应用的标题跟随输入内容(Title 组件);
//   - AppLifecycleListener:应用本身(APPLICATION itself)的生命周期。在
//     手机上,它会转入后台(打开了另一个应用,
//     屏幕熄灭),然后再回来:我们可以对此做出响应(保存、
//     停止定时器……)。
// =========================================================================

import 'package:flutter/material.dart';

import 'clock.dart';

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

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

  @override
  State<LifecyclePage> createState() => _LifecyclePageState();
}

class _LifecyclePageState extends State<LifecyclePage> {
  bool _withClock = true;
  bool _red = false;
  final List<String> _log = [];
  String _search = '';
  bool _showSearch = false;
  late final AppLifecycleListener _listener;

  void _trace(String message) {
    // 时钟可能在界面消失之后(AFTER)才发出通知(应用关闭时)
    if (!mounted) return;
    setState(() => _log.add('${currentTime()} $message'));
  }

  @override
  void initState() {
    super.initState();
    // 应用改变状态:resumed(在前台)、inactive、
    // hidden、paused(在后台)……
    _listener = AppLifecycleListener(onStateChange: (state) => _trace('Application: ${state.name}'));
  }

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

  @override
  Widget build(BuildContext context) {
    return Title(
      title: _search.isEmpty ? 'Example 13' : 'Search: $_search',
      color: Colors.indigo,
      child: Scaffold(
        appBar: AppBar(title: const Text('Example 13 - the lifecycle')),
        body: ListView(
          padding: const EdgeInsets.all(16),
          children: [
            Card(
              child: Padding(
                padding: const EdgeInsets.all(12),
                child: Column(
                  crossAxisAlignment: CrossAxisAlignment.start,
                  children: [
                    CheckboxListTile(
                      contentPadding: EdgeInsets.zero,
                      controlAffinity: ListTileControlAffinity.leading,
                      title: const Text('show the clock'),
                      value: _withClock,
                      onChanged: (v) => setState(() => _withClock = v!),
                    ),
                    CheckboxListTile(
                      contentPadding: EdgeInsets.zero,
                      controlAffinity: ListTileControlAffinity.leading,
                      title: const Text('in red'),
                      value: _red,
                      onChanged: (v) => setState(() => _red = v!),
                    ),
                    if (_withClock) Clock(onLog: _trace, color: _red ? Colors.red : Colors.indigo),
                  ],
                ),
              ),
            ),
            Card(
              child: Padding(
                padding: const EdgeInsets.all(12),
                child: !_showSearch
                    ? Align(
                        alignment: Alignment.centerLeft,
                        child: OutlinedButton(
                          onPressed: () => setState(() => _showSearch = true),
                          child: const Text('Search...'),
                        ),
                      )
                    // autofocus:输入框一出现就获得焦点
                    : TextField(
                        autofocus: true,
                        decoration: const InputDecoration(hintText: 'the title follows the input'),
                        onChanged: (v) => setState(() => _search = v),
                      ),
              ),
            ),
            Text('Log', style: Theme.of(context).textTheme.titleSmall),
            for (final (i, line) in _log.indexed) Text('${i + 1}. $line', style: const TextStyle(fontSize: 12)),
          ],
        ),
      ),
    );
  }
}
  • 第 56–61 行:应用程序本身的生命周期。在手机上,应用会进入后台(打开另一个应用、屏幕熄灭),然后再返回:[AppLifecycleListener] 会通知每一次变化([resumed]:位于前台;[inactive]、[hidden]、[paused]:切换到后台……)。你可以响应这些通知来保存草稿或停止定时器。监听器在 [initState] 中创建,并在 [dispose] 中释放:与时钟定时器的模式相同;
  • 第 95 行:勾选复选框会显示时钟([initState]);取消勾选则隐藏它([dispose]);更改它的颜色则重绘它([didUpdateWidget]);
  • 第 112–115 行:一个只有在点击“Search...”之后才出现的字段。[autofocus: true]:它一出现就获得焦点,手机键盘随之打开;
  • 第 68 行:应用标题随着输入而更新。

我们更改颜色,移除再重新添加时钟,打开搜索,并输入一个名字:

Image

日志显示了时钟的活动:启动、颜色变化、停止、启动。

学习 [React] 课程的学生会把它与 [useEffect] 作比较:[React] 把一个副作用及其清理函数写在一起;[Flutter] 则把它分散到 [initState] 和 [dispose]中;[React] 通过副作用的依赖数组实现的功能,[Flutter] 是借助 [didUpdateWidget],通过比较旧组件与新组件来实现的。

4.5. 示例 14:继承数据

如何在相距很远的组件之间共享数据和函数,而不必通过所有中间层逐级传递参数?答案是使用继承数据,例如 [InheritedWidget]。这正是 [Flutter] 自身使用的机制:[Theme.of(context)]、[MediaQuery.of(context)]、[Navigator.of(context)]……都是对继承数据的读取。[React] 把这称为上下文(context);[Angular] 则称之为服务。

4.5.1. 整个应用共用一份数据

// =========================================================================
// lib/ex14_inherited_data/providers/log.dart - 整个(WHOLE)应用共用的一份数据
// -------------------------------------------------------------------------
// 如何在相距较远的组件之间共享数据和函数,而不必通过所有
// 中间层一级一级地用参数传递?
// 使用 InheritedWidget,即一份 "继承" 的数据:
//   1. 一个位于树的高层的提供者(PROVIDER)组件,携带数据;
//   2. 任何后代组件,无论处于多深的位置,都可以读取(READ)它,
//      方法是 context.dependOnInheritedWidgetOfExactType<Provider>();
//   3. 读取过它的后代组件随即订阅(SUBSCRIBED):当数据
//      变化时它会被重建。
// 这正是 Flutter 自身使用的机制:Theme.of(context)、
// MediaQuery.of(context)、Navigator.of(context)……都是对
// 继承数据的读取。
//
// InheritedNotifier 是一个现成的变体:数据是一个会
// 通知(NOTIFIES)其变化的对象(ChangeNotifier,它调用
// notifyListeners()),随后提供者会重建它的读取者。
// 约定:用一个静态的 of(context) 方法来读取数据。
// =========================================================================

import 'package:flutter/material.dart';

// 数据:一个 ChangeNotifier。notifyListeners() 通知它的订阅者
class Log extends ChangeNotifier {
  final List<String> lines = [];

  void trace(String message) {
    lines.insert(0, '${DateTime.now().toString().substring(11, 19)} $message');
    if (lines.length > 6) lines.removeLast();
    notifyListeners();
  }
}

// 提供者:它携带日志,并在日志通知发生变化时
// 重建它的读取者
class LogProvider extends InheritedNotifier<Log> {
  const LogProvider({super.key, required Log log, required super.child}) : super(notifier: log);

  // 读取:context 上方最近(CLOSEST)的提供者
  static Log of(BuildContext context) {
    final provider = context.dependOnInheritedWidgetOfExactType<LogProvider>();
    if (provider == null) {
      throw FlutterError('LogProvider.of: no LogProvider above this widget');
    }
    return provider.notifier!;
  }
}
  • 第 25–31 行:共享数据:一份日志。它是一个 [ChangeNotifier],一种会把变化通知其监听者的对象:每个修改它的方法都会调用 [notifyListeners()];
  • 第 37–38 行:提供者:位于树的较高位置、持有该日志的组件。[InheritedNotifier] 是为 [InheritedWidget] 准备好的、配合 [ChangeNotifier] 使用的组件:当日志通知发生变化时,提供者会重建所有读取过它的组件;
  • 第 41–46 行:通过静态方法 [of(context)] 读取,与 [Flutter] 中的用法一致。[context.dependOnInheritedWidgetOfExactType<LogProvider>()] 从 [context] 出发沿树向上遍历,直到最近的提供者,并让读取数据的组件订阅该数据:数据变化时,它将被重建。如果上方没有提供者,这是一个编程错误:会给出明确的提示。

4.5.2. 由组件提供的数据

// =========================================================================
// lib/ex14_inherited_data/providers/cart.dart - 由一个(ONE)组件提供的数据
// -------------------------------------------------------------------------
// 购物车只提供给树的一部分:即 CartProvider 所包裹的
// 组件(见 main.dart)。放在界面两个
// 位置的两个提供者会给出两个相互独立的购物车。
// 这里的提供者是一个 StatefulWidget:由它创建(CREATES)购物车
// (didChangeDependencies)并释放它(dispose)。它自己也使用日志。
// =========================================================================

import 'package:flutter/material.dart';

import 'log.dart';

typedef Item = ({String label, double price});

class Cart extends ChangeNotifier {
  final Log _log;
  final List<Item> items = [];

  Cart(this._log);

  // 一个计算值:fold 把列表 "折叠" 成单个值
  double get total => items.fold(0, (sum, a) => sum + a.price);

  void add(Item item) {
    items.add(item);
    _log.trace('cart: + ${item.label}');
    notifyListeners();
  }

  void remove(int index) {
    _log.trace('cart: - ${items[index].label}');
    items.removeAt(index);
    notifyListeners();
  }
}

class CartProvider extends StatefulWidget {
  final Widget child;

  const CartProvider({super.key, required this.child});

  // 读取,通过放在 build() 中的私有组件 _InheritedCart
  static Cart of(BuildContext context) {
    final inherited = context.dependOnInheritedWidgetOfExactType<_InheritedCart>();
    if (inherited == null) {
      throw FlutterError('CartProvider.of: no CartProvider above this widget');
    }
    return inherited.notifier!;
  }

  @override
  State<CartProvider> createState() => _CartProviderState();
}

class _CartProviderState extends State<CartProvider> {
  Cart? _cart; // 在创建之前为 null

  // 在 initState 之后立即调用:此时组件可以读取(READ)继承
  // 数据。getInheritedWidgetOfExactType:读取日志但不订阅
  // 它的变化(购物车的提供者不必在
  // 日志每次变化时都被重建)
  @override
  void didChangeDependencies() {
    super.didChangeDependencies();
    // ??=:购物车只在第一次创建
    _cart ??= Cart(context.getInheritedWidgetOfExactType<LogProvider>()!.notifier!);
  }

  @override
  void dispose() {
    _cart?.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) => _InheritedCart(notifier: _cart!, child: widget.child);
}

class _InheritedCart extends InheritedNotifier<Cart> {
  const _InheritedCart({required super.notifier, required super.child});
}
  • 第 17–24 行:购物车,另一个 [ChangeNotifier]。它在创建时接收日志,以便记录每一次添加和移除。[fold] 把列表“折叠”成单个值:价格之和;
  • 第 39–40 行:这一次,提供者是一个 [StatefulWidget]:由它来创建购物车并释放它。购物车只提供给它所包含的组件([child]);
  • 第 45–50 行:私有组件 [_InheritedCart]由提供者放在其子组件之上,用来读取数据;
  • 第 65–68 行:购物车在 [didChangeDependencies] 中创建,该方法紧接着 [initState] 之后被调用,组件可以在其中读取继承数据。[??=]:这样只在第一次创建。[getInheritedWidgetOfExactType] 读取日志时不订阅其变化:购物车提供者不需要在每次日志变化时都被重建;
  • 第 78 行:提供者把继承数据放在其子组件之上;
  • 第 81–82 行:继承数据本身,它是私有的。

4.5.3. 带配置的提供者

// =========================================================================
// lib/ex14_inherited_data/providers/clock.dart - 一个带参数(PARAMETERIZED)的提供者
// -------------------------------------------------------------------------
// 一个时钟,它的刷新周期是提供者的一个参数:
// ClockProvider(period: Duration(seconds: 5), ...)。
// 两个嵌套的提供者:组件读取离它最近(CLOSEST)的那一个。
// 这次我们 "手工" 编写一个 InheritedWidget:
// 由 updateShouldNotify 来告诉是否必须重建读取者。
// 当提供者消失时,时钟停止(dispose)。
// =========================================================================

import 'dart:async';

import 'package:flutter/material.dart';

class ClockProvider extends StatefulWidget {
  final Duration period;
  final Widget child;

  const ClockProvider({super.key, this.period = const Duration(seconds: 1), required this.child});

  // 默认值:一个固定的日期,由没有提供者的组件读取
  static DateTime of(BuildContext context) =>
      context.dependOnInheritedWidgetOfExactType<_InheritedClock>()?.now ?? DateTime(2026);

  @override
  State<ClockProvider> createState() => _ClockProviderState();
}

class _ClockProviderState extends State<ClockProvider> {
  DateTime _now = DateTime.now();
  Timer? _timer;

  void _start() {
    _timer?.cancel();
    _timer = Timer.periodic(widget.period, (_) => setState(() => _now = DateTime.now()));
  }

  @override
  void initState() {
    super.initState();
    _start();
  }

  // 如果父组件修改了周期,定时器会重新启动
  @override
  void didUpdateWidget(ClockProvider oldWidget) {
    super.didUpdateWidget(oldWidget);
    if (oldWidget.period != widget.period) _start();
  }

  @override
  void dispose() {
    _timer?.cancel();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) => _InheritedClock(now: _now, child: widget.child);
}

class _InheritedClock extends InheritedWidget {
  final DateTime now;

  const _InheritedClock({required this.now, required super.child});

  // 提供者被重建时调用:读取者是否必须
  // 重建?是的,如果时间发生了变化
  @override
  bool updateShouldNotify(_InheritedClock oldWidget) => oldWidget.now != now;
}
  • 第 23 行:读取操作;没有提供者时,使用默认值(一个固定的日期)。[?.]:如果找不到提供者,结果为 [null],然后 [??] 取默认值;
  • 第 34–36 行:一个定时器,其周期通过参数指定;
  • 第 47–49 行:如果父组件修改了周期,定时器会被重启;
  • 第 62–70 行:这一次,是一个“手工”编写的 [InheritedWidget] 。它携带一项数据(时间)。每当提供者被重建(每秒一次),[Flutter] 就会带着旧组件调用 [updateShouldNotify] :如果它返回 [true],读取该数据的组件就会被重建。

4.5.4. 各个组件

// lib/ex14_inherited_data/catalog.dart - 一个向购物车添加(ADDS)商品的后代组件
import 'package:flutter/material.dart';

import 'providers/cart.dart';

const catalog = <Item>[
  (label: 'Consultation', price: 30),
  (label: 'Vaccine', price: 12.5),
  (label: 'Certificate', price: 5),
];

class Catalog extends StatelessWidget {
  const Catalog({super.key});

  @override
  Widget build(BuildContext context) {
    // 由 ShopPage 提供的购物车(如果没有人提供则报错)
    final cart = CartProvider.of(context);
    return Card(
      child: Column(
        children: [
          for (final a in catalog)
            ListTile(
              dense: true,
              title: Text('${a.label} (${a.price} €)'),
              trailing: IconButton(icon: const Icon(Icons.add_shopping_cart), onPressed: () => cart.add(a)),
            ),
        ],
      ),
    );
  }
}
  • 第 18 行:商品目录读取上方提供的购物车,并向其中添加商品。
// =========================================================================
// lib/ex14_inherited_data/cart_summary.dart
// -------------------------------------------------------------------------
// 另一个后代组件:与 Catalog 相同(SAME)的购物车,但有它自己(ITS OWN)的
// 时钟,每 5 秒刷新一次。组件只读取位于它上方(ABOVE)的
// 提供者:因此 CartSummary 在它的内容周围放置第二个
// ClockProvider,并把内容交给一个小
// 组件 _Content(它的 context 本身位于这个提供者的下方(BELOW))。
// =========================================================================

import 'package:flutter/material.dart';

import 'providers/clock.dart';
import 'providers/cart.dart';

class CartSummary extends StatelessWidget {
  const CartSummary({super.key});

  @override
  Widget build(BuildContext context) {
    return const ClockProvider(period: Duration(seconds: 5), child: _Content());
  }
}

class _Content extends StatelessWidget {
  const _Content();

  @override
  Widget build(BuildContext context) {
    final cart = CartProvider.of(context);
    final now = ClockProvider.of(context); // 最近的那个:5 秒的那个
    return Card(
      child: Padding(
        padding: const EdgeInsets.all(12),
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.start,
          children: [
            Text(
              'Cart (${cart.items.length} item(s)) - ${now.toString().substring(11, 19)}',
              style: Theme.of(context).textTheme.titleSmall,
            ),
            for (final (i, a) in cart.items.indexed)
              Row(
                children: [
                  Text(a.label),
                  TextButton(onPressed: () => cart.remove(i), child: const Text('remove')),
                ],
              ),
            Text('Total: ${cart.total} €', style: const TextStyle(fontWeight: FontWeight.bold)),
          ],
        ),
      ),
    );
  }
}
  • 第 21 行:汇总组件在其内容周围放置了第二个时钟提供者,周期为 5 秒。组件只能读取位于其上方的提供者:因此内容是一个单独的组件 [_Content],它的 [context] 位于这个提供者之下(而 [CartSummary] 的 [context]则位于它之上);
  • 第 30–31 行:它读取与商品目录相同的购物车,但最近的时钟是 5 秒的那一个。
// =========================================================================
// lib/ex14_inherited_data/main.dart - 三个层级的继承数据
// -------------------------------------------------------------------------
//   - 日志:提供在最顶层(MaterialApp 之上),供整个
//     应用使用;
//   - 购物车,由 ShopPage 提供:由 Catalog 和
//     CartSummary 共享,它们看到的是同一个(SAME)购物车;
//   - 时钟,由 ShopPage(默认周期,1 秒)和
//     CartSummary(5 秒)提供:各有各的时钟。
// =========================================================================

import 'package:flutter/material.dart';

import 'catalog.dart';
import 'providers/clock.dart';
import 'providers/log.dart';
import 'providers/cart.dart';
import 'cart_summary.dart';

void main() {
  runApp(
    LogProvider(
      log: Log(),
      child: MaterialApp(
        debugShowCheckedModeBanner: false,
        theme: ThemeData(colorSchemeSeed: Colors.indigo),
        home: const ShopPage(),
      ),
    ),
  );
}

// 页面时钟显示的时间:一个小组件,放在提供者的下方(BELOW)
class _PageTime extends StatelessWidget {
  const _PageTime();

  @override
  Widget build(BuildContext context) {
    final time = ClockProvider.of(context).toString().substring(11, 19);
    return Text('Clock of the page: $time', style: const TextStyle(color: Colors.grey));
  }
}

class ShopPage extends StatelessWidget {
  const ShopPage({super.key});

  @override
  Widget build(BuildContext context) {
    // 页面读取日志:每出现一行新日志它都会被重建
    final log = LogProvider.of(context);
    return ClockProvider(
      child: CartProvider(
        child: Scaffold(
          appBar: AppBar(title: const Text('Example 14 - the inherited data')),
          body: ListView(
            padding: const EdgeInsets.all(16),
            children: [
              const _PageTime(),
              const Catalog(),
              const CartSummary(),
              const SizedBox(height: 12),
              Text('Log (provided to the whole application)', style: Theme.of(context).textTheme.titleSmall),
              for (final line in log.lines) Text(line, style: const TextStyle(fontSize: 12)),
            ],
          ),
        ),
      ),
    );
  }
}
  • 第 22–24 行:日志提供者被放在 [MaterialApp] 之上:日志在整个应用中都可用,包括在窗口和其他屏幕中;
  • 第 34–40 行:一个小组件,放在页面的时钟提供者之下;
  • 第 50 行:页面读取日志;每增加一行,它都会被重建;
  • 第 51–52 行:页面为其包含的所有内容提供一个时钟(默认周期:一秒)和一个购物车。

我们添加三件商品,然后移除一件:

Image

页面的时钟每秒走一次;购物车的时钟每五秒走一次。日志显示了添加和移除操作。示例 20 会把这一切工作委托给 [provider] 包,它只需一行就能写出,但完全基于这里的机制。

4.6. 示例 15:复用行为

组件复用的是一个视图。那么如何复用一个行为及其状态(高亮被点击的内容、长按后触发动作、启动时获取焦点)?[React] 有“自定义 Hook”;[Flutter] 和 [Dart] 有三种工具。

4.6.1. “包装”组件

// =========================================================================
// lib/ex15_behaviors/highlighter.dart - 组件中的一种行为
// -------------------------------------------------------------------------
// 复用一种行为(连同它的状态)的第一种方式:
// 一个 "包装" 组件,它为任何子组件添加这种行为。
//     Highlighter(color: ..., child: ListTile(...))
// 这个组件在其子组件被触摸(TOUCHED)时(手指按在
// 屏幕上)将其高亮,使用鼠标(Web、电脑)时则在鼠标悬停(HOVERED)时高亮。
// 每个 Highlighter 都有自己的状态:两行之间互不干扰。
// =========================================================================

import 'package:flutter/material.dart';

class Highlighter extends StatefulWidget {
  final Color color;
  final Widget child;

  const Highlighter({super.key, this.color = const Color(0xFFFFF3CD), required this.child});

  @override
  State<Highlighter> createState() => _HighlighterState();
}

class _HighlighterState extends State<Highlighter> {
  bool _touched = false;
  bool _hovered = false;

  @override
  Widget build(BuildContext context) {
    // MouseRegion:鼠标的移动;Listener:手指的接触
    // (或点击),位于最底层
    return MouseRegion(
      onEnter: (_) => setState(() => _hovered = true),
      onExit: (_) => setState(() => _hovered = false),
      child: Listener(
        onPointerDown: (_) => setState(() => _touched = true),
        onPointerUp: (_) => setState(() => _touched = false),
        onPointerCancel: (_) => setState(() => _touched = false),
        // AnimatedContainer:颜色的动画(ANIMATED)变化(200 毫秒)
        child: AnimatedContainer(
          duration: const Duration(milliseconds: 200),
          color: _touched || _hovered ? widget.color : Colors.transparent,
          child: widget.child,
        ),
      ),
    );
  }
}
  • 第 32–34 行:[MouseRegion] 在鼠标进入或离开该组件时发出通知(在 Web 或电脑上;手机没有鼠标);
  • 第 35–38 行:[Listener] 在最底层通知每一次手指触摸(或每一次点击):按下、抬起、取消;
  • 第 40–42 行:一个带动画的 [Container]:当它的颜色改变时,它会在 200 毫秒内从旧颜色过渡到新颜色,无需任何额外代码。[Flutter] 有一整个系列这样的“隐式动画”组件:[AnimatedOpacity]、[AnimatedPadding]、[AnimatedAlign]……

[Highlighter] 把它的行为应用于任何子组件:[Highlighter(child: ListTile(...))]。

4.6.2. 包含动画的组件

// =========================================================================
// lib/ex15_behaviors/long_press.dart - 一个长按按钮
// -------------------------------------------------------------------------
//     LongPressButton(duration: Duration(seconds: 1), onAction: remove, child: ...)
// 只有当按钮在整个时长内一直被按住时才会执行操作:
// 这是防止误触的保护措施。按压期间
// 圆环会逐渐填满。
// 填充是一个动画(ANIMATION):AnimationController 在给定的时长内、
// 随屏幕的每一帧产生一个
// 从 0 到 1 的值。它需要一个 "ticker"(帧的心跳):mixin
// SingleTickerProviderStateMixin 把它添加到 State 对象。MIXIN 是
// Dart 在多个类中复用代码的方式(见
// autofocus.dart)。
// =========================================================================

import 'package:flutter/material.dart';

class LongPressButton extends StatefulWidget {
  final Duration duration;
  final VoidCallback onAction;
  final Widget child;

  const LongPressButton({
    super.key,
    this.duration = const Duration(seconds: 1),
    required this.onAction,
    required this.child,
  });

  @override
  State<LongPressButton> createState() => _LongPressButtonState();
}

// "with":State 对象额外获得这个 mixin 的代码
class _LongPressButtonState extends State<LongPressButton> with SingleTickerProviderStateMixin {
  late final AnimationController _animation;

  @override
  void initState() {
    super.initState();
    // vsync: this:由 mixin 提供的 ticker
    _animation = AnimationController(vsync: this, duration: widget.duration)
      // 动画结束:按压持续的时间足够长
      ..addStatusListener((status) {
        if (status == AnimationStatus.completed) {
          _animation.reset();
          widget.onAction();
        }
      });
  }

  // 组件被移除时:不留下孤立的动画
  @override
  void dispose() {
    _animation.dispose();
    super.dispose();
  }

  void _start() => _animation.forward(from: 0);

  // 手指过早抬起:圆环清空
  void _stop() {
    if (_animation.isAnimating) _animation.reverse();
  }

  @override
  Widget build(BuildContext context) {
    return GestureDetector(
      onTapDown: (_) => _start(),
      onTapUp: (_) => _stop(),
      onTapCancel: _stop,
      // AnimatedBuilder:每一帧只(ONLY)重建这一小块
      child: AnimatedBuilder(
        animation: _animation,
        builder: (context, child) => Row(
          mainAxisSize: MainAxisSize.min,
          children: [
            SizedBox(
              width: 22,
              height: 22,
              child: CircularProgressIndicator(value: _animation.value, strokeWidth: 3, color: Colors.red),
            ),
            const SizedBox(width: 8),
            child!, // 子组件,一次性构建好
          ],
        ),
        child: widget.child,
      ),
    );
  }
}
  • 第 35 行:[with]:[State] 对象还从一个mixin 获得代码。mixin 是 [Dart] 在不使用继承的情况下跨多个类复用代码的方式。这个 mixin 提供了一个“ticker”——屏幕的刷新节拍(每秒 60 帧或更高)——这是动画所必需的;
  • 第 42–47 行:[AnimationController] 在指定时长内,为每一帧生成一个从 0 到 1 的值。[vsync: this]:由 mixin 提供的 ticker。[..addStatusListener(...)]:当动画到达终点([completed])时,说明按压持续的时间已经足够长:动画被重置为零,并执行相应的操作;
  • 第 59–63 行:手指触到按钮:动画从 0 开始;如果抬起得太早,动画会倒回;
  • 第 69–71 行:手势:按下、松开、取消(手指从按钮上滑开);
  • 第 73–87 行:[AnimatedBuilder] 在动画的每一帧中,只重建屏幕的这一部分:一个圆环([CircularProgressIndicator]),其值对应动画的进度。固定不变的部分(按钮文字)只构建一次([child]),并传给 [builder]。

4.6.3. mixin 中的行为

// =========================================================================
// lib/ex15_behaviors/autofocus.dart - MIXIN 中的一种行为
// -------------------------------------------------------------------------
// 复用行为的第二种方式:State 上的 mixin。
//     class _MyPageState extends State<MyPage> with FocusOnStart { ... }
// State 对象获得一个 FocusNode(startFocus),它在界面显示后
// 立即获得焦点,并随之释放:mixin
// 补全使用它的类的 initState 和 dispose。
// "on State<T>":这个 mixin 只适用于 State 对象,因此
// 它可以使用该对象的方法(initState、dispose、mounted……)。
// (对于简单的字段,TextField 的 autofocus: true 参数能
// 起到同样的作用:这个 mixin 展示的是机制,可复用于其他场景。)
// =========================================================================

import 'package:flutter/widgets.dart';

mixin FocusOnStart<T extends StatefulWidget> on State<T> {
  final startFocus = FocusNode();

  @override
  void initState() {
    super.initState(); // "上方" 的类(或 mixin)的 initState
    // 首次显示之后:输入框已存在,赋予它焦点
    WidgetsBinding.instance.addPostFrameCallback((_) {
      if (mounted) startFocus.requestFocus();
    });
  }

  @override
  void dispose() {
    startFocus.dispose();
    super.dispose();
  }
}
  • 第 17 行:一个只能应用于 [State] 对象([on State<T>])的 mixin:因此它可以使用该对象的方法;
  • 第 18 行:使用该 mixin 的 [State] 对象会获得这个字段;
  • 第 21–25 行:mixin 的 [initState] 被补全:[super.initState()] 调用“父”类的同名方法(即 [State] 的,或另一个 mixin 的)。首次显示之后,该字段已经存在:把焦点交给它。[mounted]:[State] 对象是否仍在树中?;
  • 第 30–32 行:它还补全了 [dispose],以释放 [FocusNode]。

4.6.4. 使用

// =========================================================================
// lib/ex15_behaviors/main.dart - 复用行为
// -------------------------------------------------------------------------
// Flutter 和 Dart 中用来复用行为(及
// 其状态)而非单纯显示的三种工具:
//   - "包装" 组件(Highlighter);
//   - 带有动画的组件(LongPressButton);
//   - State 上的 mixin(FocusOnStart)。
// =========================================================================

import 'package:flutter/material.dart';

import 'long_press.dart';
import 'autofocus.dart';
import 'highlighter.dart';

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

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

  @override
  State<BehaviorsPage> createState() => _BehaviorsPageState();
}

// FocusOnStart mixin:这个 State 对象获得 startFocus
class _BehaviorsPageState extends State<BehaviorsPage> with FocusOnStart {
  final List<String> _doctors = ['Mme Marie PELISSIER', 'Mr Paul TATOU', 'Melle Sophie DUPONT'];
  String _message = '';

  void _remove(String name) {
    setState(() {
      _doctors.remove(name);
      _message = '$name has been deleted.';
    });
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Example 15 - reusing behaviors')),
      body: ListView(
        padding: const EdgeInsets.all(16),
        children: [
          TextField(
            focusNode: startFocus, // 由 mixin 提供的 FocusNode
            decoration: const InputDecoration(hintText: 'this field received the focus on its own'),
          ),
          const SizedBox(height: 12),
          const Text(
            'Touch the rows; hold a button pressed for one second to delete.',
            style: TextStyle(color: Colors.grey),
          ),
          for (final (i, m) in _doctors.indexed)
            Highlighter(
              key: ValueKey(m),
              // 每两行中的一行:默认颜色;其他行为绿色
              color: i.isEven ? const Color(0xFFFFF3CD) : const Color(0xFFD1E7DD),
              child: ListTile(
                title: Text(m),
                trailing: LongPressButton(
                  onAction: () => _remove(m),
                  child: const Text('Delete', style: TextStyle(color: Colors.red)),
                ),
              ),
            ),
          const SizedBox(height: 12),
          if (_message.isNotEmpty) Text(_message, style: const TextStyle(color: Colors.indigo)),
        ],
      ),
    );
  }
}
  • 第 35 行:屏幕使用该 mixin;
  • 第 54 行:由 mixin 提供的 [FocusNode] ;
  • 第 63–71 行:每一行在被点击时高亮;其“Delete”按钮只有在按住一秒后才会生效。

按住第一个按钮时(圆环逐渐充满,该行高亮);然后完整按下第二个按钮之后:

4.7. 示例 16:可复用的确认窗口

“确定吗?”:[Flutter] 提供了你所需的一切。[showDialog] 函数在屏幕上方显示一个模态窗口,并返回一个 [Future],其结果是窗口关闭时传回的值。

4.7.1. 窗口

// =========================================================================
// lib/ex16_confirmation/confirmation.dart - "你确定吗?"
// -------------------------------------------------------------------------
// Flutter 提供了所需的一切:showDialog() 在界面上方显示一个模态(MODAL)
// 对话框,并返回一个 Future,其结果为
// 对话框关闭时传递的值:Navigator.pop(context, value)。
// 因此调用代码写起来非常简单:
//
//     if (await confirm(context, 'Delete this doctor?')) { ... }
//
// 不作回答就关闭对话框(点击对话框外部、手机的返回键、
// Esc 键)时,Future 的结果为 null:它被视为
// "否"。
// =========================================================================

import 'package:flutter/material.dart';

Future<bool> confirm(BuildContext context, String message) async {
  final answer = await showDialog<bool>(
    context: context,
    // AlertDialog:Material 对话框,带有标题、内容和按钮
    builder: (context) => AlertDialog(
      title: const Text('Confirmation'),
      content: Text(message),
      actions: [
        // autofocus:"No" 按钮(最不危险的选择)获得焦点
        TextButton(autofocus: true, onPressed: () => Navigator.pop(context, false), child: const Text('No, go back')),
        FilledButton(
          style: FilledButton.styleFrom(backgroundColor: Colors.red),
          onPressed: () => Navigator.pop(context, true),
          child: const Text('Yes, confirm'),
        ),
      ],
    ),
  );
  return answer ?? false; // null:对话框未作回答就被关闭
}
  • 第 18 行:一个标准函数,凡是有 [context] 可用的地方都可以使用;
  • 第 19–22 行:[showDialog] 打开由 [builder] 创建的窗口,并返回一个 [Future<bool?>]:窗口关闭时传回的值;
  • 第 23–25 行:[AlertDialog] 是 [Material Design] 的对话框:包含标题、内容和按钮;
  • 第 27 行:[Navigator.pop(context, false)] 关闭窗口并传回 [false]。[autofocus]:“No”按钮——风险最小的选项——获得焦点(不小心按下 Enter 键不会删除任何内容);
  • 第 36 行:不作回应就关闭窗口(点击窗口外部、按手机的返回键,或按 Esc 键),会使 [Future] 的结果为 [null]:这会被视为“否”。

于是,调用代码写起来就和使用浏览器的 [window.confirm] 一样简单:[if (await confirm(context, 'Delete this doctor?')) { ... }]。客户端 [React] 需要一个上下文、一个手工构造的 promise 和一个“portal”才能达到同样的效果;而在 [Flutter] 中,窗口本来就是这样工作的。

4.7.2. 使用

// =========================================================================
// lib/ex16_confirmation/main.dart - 使用确认对话框
// -------------------------------------------------------------------------
// 先删除,然后在屏幕底部显示一条短暂的消息(SnackBar),
// 带有 "撤销" 按钮:这是移动端非常常见的另一种
// 防止用户出错的方式。
// =========================================================================

import 'package:flutter/material.dart';

import 'confirmation.dart';

typedef Contact = ({int id, String name});

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

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

  @override
  State<ContactsPage> createState() => _ContactsPageState();
}

class _ContactsPageState extends State<ContactsPage> {
  final List<Contact> _contacts = [
    (id: 1, name: 'Jean MARTIN'),
    (id: 2, name: 'Alice DURAND'),
    (id: 3, name: 'Luc GERMAN'),
  ];
  String _message = '';

  // 一个 async 函数:它 "等待" 用户的回答
  Future<void> _remove(Contact c) async {
    final yes = await confirm(context, 'Delete the contact ${c.name}?');
    // await 之后,界面可能已经消失:我们检查它是否仍然存在
    if (!mounted) return;
    if (!yes) {
      setState(() => _message = 'Deletion abandoned.');
      return;
    }
    final position = _contacts.indexOf(c);
    setState(() {
      _contacts.remove(c);
      _message = '${c.name} has been deleted.';
    });
    // ScaffoldMessenger:在屏幕底部显示一条短暂的消息
    ScaffoldMessenger.of(context).showSnackBar(
      SnackBar(
        content: Text('${c.name} deleted'),
        action: SnackBarAction(
          label: 'Undo',
          onPressed: () => setState(() {
            _contacts.insert(position, c);
            _message = '${c.name} is back.';
          }),
        ),
      ),
    );
  }

  Future<void> _removeAll() async {
    final yes = await confirm(context, 'Delete the ${_contacts.length} contacts?');
    if (yes && mounted) {
      setState(() {
        _contacts.clear();
        _message = 'All the contacts have been deleted.';
      });
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Example 16 - a confirmation dialog')),
      body: ListView(
        padding: const EdgeInsets.all(16),
        children: [
          for (final c in _contacts)
            ListTile(
              leading: const Icon(Icons.person),
              title: Text(c.name),
              trailing: IconButton(
                icon: const Icon(Icons.delete_outline, color: Colors.red),
                onPressed: () => _remove(c),
              ),
            ),
          if (_contacts.isEmpty)
            const ListTile(
              title: Text('No contact.', style: TextStyle(color: Colors.grey)),
            ),
          const SizedBox(height: 12),
          Align(
            alignment: Alignment.centerLeft,
            child: FilledButton(
              style: FilledButton.styleFrom(backgroundColor: Colors.red),
              // null:列表为空时按钮被禁用
              onPressed: _contacts.isEmpty ? null : _removeAll,
              child: const Text('Delete all'),
            ),
          ),
          const SizedBox(height: 12),
          if (_message.isNotEmpty) Text(_message, style: const TextStyle(color: Colors.indigo)),
        ],
      ),
    );
  }
}
  • 第 41–44 行:一个 [async] 函数:它等待用户的回应。在 [await] 之后,屏幕可能已经消失(用户已离开):我们先检查用户是否仍在([mounted]),然后再修改状态或调用 [context]。分析器会提示遗漏了这项检查;
  • 第 55–62 行:删除之后,屏幕底部会出现一条临时消息([SnackBar]),带有一个“Undo”按钮,可把联系人恢复到原来的位置。这是在移动设备上非常常见的另一种保护用户免于误操作的方法:立即执行操作,但允许用户撤销;
  • 第 105 行:当列表为空时,[null] 会禁用该按钮。

确认窗口;然后删除完成,并显示那条转瞬即逝的消息: