Skip to content

6. 异步处理与共享状态

6.1. 示例 19:Future、Stream 与定时器

许多事情都发生在“稍后”:定时器的滴答、按键、服务器的响应。[Dart] 为此提供了两种类型,它们是语言的核心:

  • [Future<T>]:稍后得到一个值(服务器的响应、在窗口中做出的选择);
  • [Stream<T>]:随时间推移得到一系列值(滴答、消息、GPS 位置……)。

[Flutter] 为每一种都提供了一个组件来显示,值到达时重建:[FutureBuilder] 和 [StreamBuilder]。而对于必须延迟之后才发生的事情:[Timer]。

// =========================================================================
// lib/ex19_asynchronous/main.dart - Future、Stream、定时器
// -------------------------------------------------------------------------
// 许多事情发生在 "之后":定时器的滴答、
// 按键、服务器的响应。Dart 为此提供了两种类型,
// 它们是语言的核心:
//   - Future<T>:之后得到一个(ONE)值(服务器的响应);
//   - Stream<T>:随时间推移产生的一个值序列(SEQUENCE)(滴答、
//     消息……)。
// Flutter 有一个组件用来显示它们,并在
// 值到达时重建它:FutureBuilder 和 StreamBuilder。
// 对于必须在延迟之后发生的事情:Timer(dart:async)。
// =========================================================================

import 'dart:async';
import 'dart:math';

import 'package:flutter/material.dart';

const doctors = ['Marie PELISSIER', 'Paul TATOU', 'Sophie DUPONT', 'Jacques DURAND', 'Martine PELLETIER'];
final _random = Random();

// 一个模拟的 "服务器":响应(一个 Future)在随机延迟之后到达
Future<List<String>> search(String text) async {
  await Future<void>.delayed(Duration(milliseconds: 200 + _random.nextInt(600)));
  return doctors.where((m) => m.toLowerCase().contains(text)).toList();
}

// 1. 由 "async*" 函数产生的 Stream:每个 yield 向监听 Stream 的对象
// 发送(SENDS)一个值
Stream<int> countdown(int start) async* {
  for (var remaining = start; remaining >= 0; remaining--) {
    yield remaining;
    if (remaining > 0) await Future<void>.delayed(const Duration(seconds: 1));
  }
}

String currentTime() => DateTime.now().toString().substring(11, 19);

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

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

  @override
  State<AsynchronousPage> createState() => _AsynchronousPageState();
}

class _AsynchronousPageState extends State<AsynchronousPage> {
  final List<String> _log = [];
  // Stream 和 Future 只创建一次(ONCE)(而不是每次 build 都创建:
  // 每次调用 build 都会重新开始倒计时!)
  final Stream<int> _countdown = countdown(20);
  // 3. 一个在一秒之后完成的 Future
  final Future<String> _message = Future.delayed(const Duration(seconds: 1), () => 'three (one second later)');

  // 2. 边输入边搜索
  Timer? _debounce;
  int _requestNumber = 0; // 最近一次(LAST)发起的搜索的编号
  List<String> _results = [];

  void _trace(String message) => setState(() => _log.add('${currentTime()} $message'));

  // 每次按键时调用
  void _onInput(String text) {
    // 防抖(DEBOUNCE):每次按键都会取消上一次按键的定时器;
    // 只有在 400 毫秒内没有按键之后,搜索才会开始
    _debounce?.cancel();
    _debounce = Timer(const Duration(milliseconds: 400), () => _launch(text.trim().toLowerCase()));
  }

  Future<void> _launch(String text) async {
    // 少于两个字母:不搜索,没有结果
    if (text.length < 2) {
      _requestNumber++; // 仍在等待的响应将被忽略
      setState(() => _results = []);
      return;
    }
    // "过期":在另一次搜索已经发起之后(AFTER)才到达的响应
    // 必须被忽略(否则旧搜索的慢响应
    // 会覆盖新搜索的响应)
    final number = ++_requestNumber;
    _trace('search sent: "$text"');
    final found = await search(text);
    if (!mounted) return;
    if (number != _requestNumber) {
      _trace('response ignored (stale): "$text"');
      return;
    }
    setState(() => _results = found);
  }

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

  @override
  Widget build(BuildContext context) {
    final titleStyle = Theme.of(context).textTheme.titleSmall;
    return Scaffold(
      appBar: AppBar(title: const Text('Example 19 - asynchrony')),
      body: ListView(
        padding: const EdgeInsets.all(16),
        children: [
          Card(
            child: Padding(
              padding: const EdgeInsets.all(12),
              child: Column(
                crossAxisAlignment: CrossAxisAlignment.start,
                children: [
                  Text('A countdown (a Stream and StreamBuilder)', style: titleStyle),
                  // StreamBuilder:Stream 每产生一个值就重建它的内容;
                  // snapshot.data:最后收到的值(第一个值之前为 null)
                  StreamBuilder<int>(
                    stream: _countdown,
                    builder: (context, snapshot) =>
                        Text(snapshot.hasData ? '${snapshot.data}' : '...', style: Theme.of(context).textTheme.displaySmall),
                  ),
                ],
              ),
            ),
          ),
          Card(
            child: Padding(
              padding: const EdgeInsets.all(12),
              child: Column(
                crossAxisAlignment: CrossAxisAlignment.start,
                children: [
                  Text('A search as you type (debounce, stale responses)', style: titleStyle),
                  TextField(
                    decoration: const InputDecoration(hintText: 'at least two letters: pel, dur...'),
                    onChanged: _onInput,
                  ),
                  for (final r in _results) Text('• $r'),
                  if (_results.isEmpty) const Text('no result', style: TextStyle(color: Colors.grey)),
                ],
              ),
            ),
          ),
          Card(
            child: Padding(
              padding: const EdgeInsets.all(12),
              child: Column(
                crossAxisAlignment: CrossAxisAlignment.start,
                children: [
                  Text('Waiting for a Future (FutureBuilder)', style: titleStyle),
                  // 在 Future 完成之前:显示等待内容
                  FutureBuilder<String>(
                    future: _message,
                    builder: (context, snapshot) => switch (snapshot.connectionState) {
                      ConnectionState.done => Text('received: ${snapshot.data}'),
                      _ => const Text('waiting...', style: TextStyle(color: Colors.grey)),
                    },
                  ),
                ],
              ),
            ),
          ),
          Text('Log', style: titleStyle),
          for (final (i, line) in _log.indexed) Text('${i + 1}. $line', style: const TextStyle(fontSize: 12)),
        ],
      ),
    );
  }
}
  • 第 24–26 行:一个模拟的“服务器”:一个 [async] 函数,它的响应(一个 [Future])在随机延迟之后到达。[await Future<void>.delayed(...)] 等待这段延迟,而不会阻塞应用;
  • 第 31–34 行:一个由 [Stream] 函数 [async*] (带星号)生成的流:这是一个异步生成器。每个 [yield] 都会向监听 [Stream] 的对象发送一个值;在两个值之间,函数等待一秒;
  • 第 61–63 行:[Stream] 和 [Future] 只创建一次,放在 [State] 对象的字段中,而不是放在 [build] 中:每次重建都会让倒计时重新开始!这是使用 [FutureBuilder] 和 [StreamBuilder] 时最常见的错误;
  • 第 66–68 行:用户输入时搜索的状态:一个定时器、最近一次发起的搜索的编号,以及结果;
  • 第 73–77 行:防抖:程序等待用户停顿之后才查询服务器,而不是每次按键都发送请求。每次按键都会取消上一次按键设置的定时器([cancel()])并启动一个新的:只有在 400 毫秒内没有按键之后,才会触发搜索;
  • 第 80–98 行:搜索。必须忽略“过期”的响应(即在另一次搜索已经发起之后才到达的响应):否则,旧搜索的慢响应会覆盖新搜索的响应。每次搜索都被分配一个编号([++_requestNumber]);当它的响应到达时,如果它已不是最近一次搜索的编号,就被忽略。[if (!mounted) return;]:等待期间,屏幕可能已经消失;
  • 第 102–104 行:如果屏幕消失,定时器会被停止;
  • 第 124–127 行:[StreamBuilder] 监听 [Stream] ,并在每个新值到来时重新构建其内容。[builder] 接收一个快照([snapshot],一个 [AsyncSnapshot]):[snapshot.hasData]、[snapshot.data](收到的最后一个值)、[snapshot.hasError]、[snapshot.connectionState]。当组件消失时,[StreamBuilder] 会自行取消订阅;
  • 第 158–162 行:[FutureBuilder] 等待 [Future]:在它完成之前,显示占位内容;然后显示它的值。[switch] 根据 [snapshot.connectionState] 在两者之间做出选择。

我们快速输入“p”、“pe”、“pel”:只会发出一次搜索。然后输入“du”,在得到响应之前再输入“dup”:“du”的响应到得太晚,如果“dup”已经收到了它的响应,它就会被忽略:

在 [JavaScript] 中,同样的事情用 promise 和定时器来写;[Angular] 则加入了来自 [RxJS] 的“可观察对象”。在 [Dart] 中,[Future] 和 [Stream] 属于基础库,而 [async]、[await]、[async*]、[yield] 和 [await for] 属于语言本身:这就是为什么 [Flutter] 不需要为异步操作引入库。

6.2. 示例 20:共享状态

与前面几课相同的问题:应用数据的“作用域”有哪些?

  • 组件的局部状态会在该组件被移除时消失;
  • “store”的状态由所有组件共享,并且在它们被移除后依然存在……但应用关闭后就没有了;
  • 存储在设备上的状态在应用关闭后依然存在。

6.2.1. 购物车

// =========================================================================
// lib/ex20_shared_state/stores/cart.dart - 使用 provider 的共享状态(SHARED STATE)
// -------------------------------------------------------------------------
// "store" 是一种存在于界面之外(OUTSIDE)的状态,只有单一(SINGLE)
// 实例,由所有读取它的对象共享。示例 14 是
// 手工实现的(InheritedNotifier);provider 包是 Flutter 中使用最多的包
// (其文档也推荐它),它只用一行就能
// 做到同样的事情:
//
//     ChangeNotifierProvider(create: (_) => Cart(), child: ...)
//
// store 就是一个普通的 ChangeNotifier。通常的组织方式:
//   - 状态(STATE):私有数据(_items);
//   - 动作(ACTIONS):方法,是唯一可以修改状态的地方,它们以
//     notifyListeners() 结束;
//   - 计算值:getter。
// 组件通过它的 context 访问它:
//   - context.watch<Cart>()  :读取并订阅(每次变化都会重建);
//   - context.read<Cart>()   :读取但不订阅(用于调用某个动作);
//   - context.select<Cart, int>((p) => p.count) :订阅某一个(ONE)值:
//     仅当这个值变化时才重建。
// store 的存活时间与它的提供者一样长:它在界面被移除后依然存在……
// 但在应用停止后就不存在了。
// =========================================================================

import 'package:flutter/foundation.dart';

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

class Cart extends ChangeNotifier {
  final List<Item> _items = [];

  // 列表的一个不可修改视图:只有各个动作能改变它
  List<Item> get items => List.unmodifiable(_items);
  int get count => _items.length;
  double get total => _items.fold(0, (s, a) => s + a.price);

  void add(Item item) {
    _items.add(item);
    notifyListeners();
  }

  void clear() {
    _items.clear();
    notifyListeners();
  }
}

store 是跨越多个屏幕的状态,以单一实例的形式存在,由所有访问它的对象共享。示例 14 手动实现了这一点。[provider] 包是与 [Flutter] 搭配使用最广泛的包(也是其文档所推荐的),它用一行就完成了同样的事情:[ChangeNotifierProvider(create: (_) => Cart(), child: ...)]。

  • 第 31 行:状态:私有数据;
  • 第 34–36 行:计算值:getter。[List.unmodifiable]:列表的只读视图;只有操作才能修改它;
  • 第 38–45 行:操作:方法——只有它们才能修改状态——以 [notifyListeners()] 结尾。

6.2.2. 偏好设置

// =========================================================================
// lib/ex20_shared_state/stores/preferences.dart - 一个在应用停止后仍然保留的状态
// -------------------------------------------------------------------------
// 要让数据在应用停止后仍然保留,必须把它存储
// 在设备上(ON THE DEVICE)。shared_preferences 包提供了一个小型字典
// 键 -> 值(bool、int、double、String),它专属于该应用,并
// 保存在设备上(在 Web 上:保存在浏览器的 localStorage 中)。
//   - 启动时读取已存储的值(main.dart);
//   - 每次变化时再次写入它们。
// 绝不(NEVER)要在这里存储敏感数据(密码、令牌):它们是
// 以明文写入的。
// =========================================================================

import 'package:flutter/foundation.dart';
import 'package:shared_preferences/shared_preferences.dart';

class Preferences extends ChangeNotifier {
  static const _darkKey = 'example20.dark';
  static const _sizeKey = 'example20.size';

  final SharedPreferences _storage;
  bool _dark;
  double _size; // 文本大小

  // 初始状态:设备上已存储的内容,否则使用默认值
  Preferences(this._storage)
    : _dark = _storage.getBool(_darkKey) ?? false,
      _size = _storage.getDouble(_sizeKey) ?? 16;

  bool get dark => _dark;
  double get size => _size;

  // 每个偏好设置对应一个可选的命名参数:只有传入的内容才会改变
  void update({bool? dark, double? size}) {
    if (dark != null) {
      _dark = dark;
      _storage.setBool(_darkKey, dark); // 写入设备
    }
    if (size != null) {
      _size = size;
      _storage.setDouble(_sizeKey, size);
    }
    notifyListeners();
  }
}

要让数据在应用关闭后依然存在,就必须把它存储在设备上。[shared_preferences] 包提供了一个小型的键->值字典([bool]、[int]、[double]、[String]),它专属于该应用并存储在设备上(在 Web 上:存储在浏览器的 [localStorage] 中)。

  • 第 21 行:存储数据,在创建时接收;
  • 第 26–28 行:初始状态:设备中存储的内容,否则使用默认值。这些字段由构造函数的“初始化列表”(冒号之后)在函数体之前初始化;
  • 第 34–43 行:一个单一的操作,带有可选的命名参数:只修改传入的值,并立即把它们写入设备([setBool]、[setDouble])。

绝不要在这里存储任何敏感数据(密码、令牌):这类数据是以明文写入的。为此有 [flutter_secure_storage] 包,它使用系统的保险库([Keystore] 来自 [Android],[Keychain] 来自 [iOS])。

6.2.3. 各个组件

// lib/ex20_shared_state/components/shop.dart - 向共享购物车添加(ADDS)商品
import 'package:flutter/material.dart';
import 'package:provider/provider.dart';

import '../stores/cart.dart';

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

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

  @override
  Widget build(BuildContext context) {
    // read:我们只调用(CALL)一个动作;购物车变化时 Shop
    // 不会被重建
    final cart = context.read<Cart>();
    return Card(
      child: Padding(
        padding: const EdgeInsets.all(12),
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.start,
          children: [
            Text('Shop', style: Theme.of(context).textTheme.titleSmall),
            for (final p in products)
              TextButton.icon(
                icon: const Icon(Icons.add),
                label: Text('${p.label} (${p.price} €)'),
                onPressed: () => cart.add(p),
              ),
          ],
        ),
      ),
    );
  }
}
  • 第 16 行:[context.read<Cart>()] 读取上方提供的购物车;不订阅:store 只是调用一个操作;购物车变化时,它不需要被重建。
// lib/ex20_shared_state/components/cart_summary.dart - 读取(READS)同一个购物车
import 'package:flutter/material.dart';
import 'package:provider/provider.dart';

import '../stores/cart.dart';

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

  @override
  Widget build(BuildContext context) {
    // select:仅当数量或总额发生变化时才重建
    final count = context.select<Cart, int>((p) => p.count);
    final total = context.select<Cart, double>((p) => p.total);
    return Card(
      child: Padding(
        padding: const EdgeInsets.all(12),
        child: Row(
          children: [
            const Icon(Icons.shopping_cart),
            const SizedBox(width: 8),
            Expanded(child: Text('$count item(s), $total €')),
            TextButton(
              onPressed: count == 0 ? null : () => context.read<Cart>().clear(),
              child: const Text('Clear'),
            ),
          ],
        ),
      ),
    );
  }
}
  • 第 13–14 行:[context.select] 读取购物车的一个值,并让组件订阅这个值:只有该值变化时,组件才会被重建。[context.watch<Cart>()] 则会读取并订阅整个购物车。
// lib/ex20_shared_state/components/local_counter.dart - 一个本地(LOCAL)状态,随组件一起消失
import 'package:flutter/material.dart';

class LocalCounter extends StatefulWidget {
  final String title;

  const LocalCounter({super.key, required this.title});

  @override
  State<LocalCounter> createState() => _LocalCounterState();
}

class _LocalCounterState extends State<LocalCounter> {
  int _clicks = 0;

  @override
  Widget build(BuildContext context) {
    return Card(
      child: ListTile(
        title: Text(widget.title),
        trailing: OutlinedButton(onPressed: () => setState(() => _clicks++), child: Text('$_clicks click(s)')),
      ),
    );
  }
}

一个随组件消失的局部状态。

6.2.4. 应用

// =========================================================================
// lib/ex20_shared_state/main.dart - 三种数据 "作用域"
// -------------------------------------------------------------------------
//   - 组件的本地(LOCAL)状态(LocalCounter)随组件一起消失;
//   - store(购物车)的状态由所有组件共享,
//     在它们被移除后依然存在 - 但在应用停止后就不存在了;
//   - 存储在设备上的状态(偏好设置)在应用停止后依然保留。
// 还有 Visibility(maintainState: true):内容被隐藏(HIDDEN),但没有
// 被移除;它的本地状态得以保留。
// 取消勾选再重新勾选 "显示该区域",然后停止并重新启动
// 应用:进行比较。
// =========================================================================

import 'package:flutter/material.dart';
import 'package:provider/provider.dart';
import 'package:shared_preferences/shared_preferences.dart';

import 'components/shop.dart';
import 'components/local_counter.dart';
import 'components/cart_summary.dart';
import 'stores/cart.dart';
import 'stores/preferences.dart';

Future<void> main() async {
  // 在使用像 shared_preferences 这样的 "插件"(Android、iOS、
  // Web 等特有的代码)之前必须调用,且要在 runApp 之前(BEFORE)
  WidgetsFlutterBinding.ensureInitialized();
  final storage = await SharedPreferences.getInstance();
  runApp(
    // MultiProvider:多个提供者,彼此嵌套,
    // 位于整个应用之上
    MultiProvider(
      providers: [
        ChangeNotifierProvider(create: (_) => Cart()),
        ChangeNotifierProvider(create: (_) => Preferences(storage)),
      ],
      child: const Application(),
    ),
  );
}

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

  @override
  Widget build(BuildContext context) {
    // watch:偏好设置变化时,应用会被重建
    final preferences = context.watch<Preferences>();
    return MaterialApp(
      debugShowCheckedModeBanner: false,
      theme: ThemeData(colorSchemeSeed: Colors.indigo),
      // 深色主题,以及在两种主题之间的选择
      darkTheme: ThemeData(colorSchemeSeed: Colors.indigo, brightness: Brightness.dark),
      themeMode: preferences.dark ? ThemeMode.dark : ThemeMode.light,
      // builder:包裹所有(ALL)界面;这里用于设置文本大小
      builder: (context, child) => MediaQuery(
        data: MediaQuery.of(context).copyWith(textScaler: TextScaler.linear(preferences.size / 16)),
        child: child!,
      ),
      home: const SharedStatePage(),
    );
  }
}

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

  @override
  State<SharedStatePage> createState() => _SharedStatePageState();
}

class _SharedStatePageState extends State<SharedStatePage> {
  bool _areaVisible = true;

  @override
  Widget build(BuildContext context) {
    final preferences = context.watch<Preferences>();
    return Scaffold(
      appBar: AppBar(title: const Text('Example 20 - a shared state')),
      body: ListView(
        padding: const EdgeInsets.all(12),
        children: [
          SwitchListTile(
            title: const Text('dark theme'),
            value: preferences.dark,
            onChanged: (v) => preferences.update(dark: v),
          ),
          ListTile(
            title: Text('text size: ${preferences.size.round()}'),
            subtitle: Slider(
              value: preferences.size,
              min: 12,
              max: 22,
              divisions: 10,
              onChanged: (v) => preferences.update(size: v),
            ),
          ),
          CheckboxListTile(
            title: const Text('show the area'),
            value: _areaVisible,
            onChanged: (v) => setState(() => _areaVisible = v!),
          ),
          // removed:这些组件消失,连同它们的本地状态
          if (_areaVisible) ...[const Shop(), const CartSummary(), const LocalCounter(title: 'Local state')],
          // hidden:组件保留在内存中,它的状态得以保留
          Visibility(
            visible: _areaVisible,
            maintainState: true,
            child: const LocalCounter(title: 'Local state, in a Visibility'),
          ),
          const Padding(
            padding: EdgeInsets.symmetric(vertical: 8),
            child: Text('Outside the area, a second summary of the SAME cart (it stays there when the area disappears):'),
          ),
          const CartSummary(),
        ],
      ),
    );
  }
}
  • 第 27–28 行:[shared_preferences] 是一个“插件”:它使用特定于平台的代码([Android]、Web……)。要在 [runApp] 之前使用它,必须先初始化 [Flutter] ([ensureInitialized])。从存储中读取是异步的:[main] 会等待它完成;
  • 第 32–35 行:[MultiProvider] 在整个应用的顶部放置多个提供者,一个嵌套在另一个之内。[ChangeNotifierProvider] 创建 [ChangeNotifier] ([create]),把它提供给其后代组件,在它变化时重建订阅它的组件,并在它消失时释放它;
  • 第 48 行:应用读取偏好设置并订阅它们;它们变化时,应用被重建;
  • 第 53–54 行:两个主题,浅色和深色,以及在二者之间选择的选项([themeMode]);
  • 第 56–58 行:[MaterialApp] 的 [builder] 包裹所有屏幕。这里修改了整个应用的文字大小:[MediaQuery] 描述屏幕和用户的设置(包括 [textScaler],即文字放大系数,它也可以在手机的无障碍设置中调整);
  • 第 104 行:被移除;该区域消失,其中各组件的局部状态也随之消失;
  • 第 106–109 行:带 [Visibility] 的 [maintainState: true] 会隐藏其子组件而不移除它:它的状态被保留。(这就是 [<Activity mode="hidden">] 在 [React] 课程中的作用。)

我们添加两件商品,在每个局部计数器上各点击一次(左图);我们移除该区域并切换到深色模式(中图);我们恢复该区域(右图):

购物车在该区域被移除后依然保留(如第二个汇总所示);被移除的计数器重置为零;被隐藏的计数器保留了它的值。停止应用并重新启动:深色主题和文字大小被保留,而购物车是空的。

为什么选择 [provider]?[Flutter] 有许多状态管理库([Riverpod]、[Bloc]、[GetX]、[MobX]……)。[provider] 是最简单的:它只不过是书写示例 14 中 [InheritedWidget] 的一种便捷方式,基于 这个[ChangeNotifier] (来自 [Flutter])。它是 [Flutter] 文档中架构指南所使用的方案,也是案例研究中将要使用的方案。