Flutter异步阶段通知插件async_phase_notifier的使用

Flutter异步阶段通知插件async_phase_notifier的使用

async_phase_notifier 是一个基于 ValueNotifier 的变种，用于表示异步操作的初始、等待、完成或错误阶段。它类似于 Riverpod 中的 AsyncNotifier 和 AsyncValue，但与 Riverpod 没有绑定关系。

样例应用

• Useless Facts - 简单示例
• pub.dev 探索者 - 高级示例

使用方法

更新方法 update()

AsyncPhaseNotifier 的 update() 方法执行一个异步函数，并根据异步操作的阶段自动更新 AsyncPhaseNotifier 的值，同时通知监听器。

1. 当操作开始时，通知器的值切换到 AsyncWaiting。
2. 通知监听器。
3. 根据结果，值切换到 AsyncComplete 或 AsyncError。
4. 通知监听器。

final notifier = AsyncPhaseNotifier(0);
notifier.update(() => someAsyncOperation());

更新仅限于阶段 updateOnlyPhase()

该方法与 update() 类似，但只更新阶段而不更新 value.data。此方法适用于在执行过程中需要更新阶段，但回调结果不应影响数据的情况。

notifier.updateOnlyPhase(() => someAsyncOperation());

异步阶段 AsyncPhase

AsyncPhaseNotifier 的值可以是 AsyncInitial、AsyncWaiting、AsyncComplete 或 AsyncError。这些类型都是 AsyncPhase 的子类型。

AsyncPhase 提供了 when() 和 whenOrNull() 方法，可用于根据当前阶段选择相应的操作。

child: phase.when(
  initial: (data) => Text('phase: AsyncInitial($data)'), // 可选
  waiting: (data) => Text('phase: AsyncWaiting($data)'),
  complete: (data) => Text('phase: AsyncComplete($data)'),
  error: (data, error, stackTrace) => Text('phase: AsyncError($data, $error)'),
)

value.data 与 data

data 是 value.data 的便捷获取器。如果 AsyncPhaseNotifier<T> 的泛型类型 T 是非空的，则返回类型也是非空的，这使得代码更安全。

监听阶段变化

listen()

通过 listen() 方法可以在阶段或其数据发生变化时触发某些动作。

final notifier = AsyncPhaseNotifier(Auth());
final cancel = notifier.listen((phase) { /* 一些动作 */ });

...

// 如果不再需要监听器，则移除它。
cancel();

listenFor()

通过 listenFor() 方法可以在阶段或其数据发生变化时触发某些动作。

final notifier = AsyncPhaseNotifier(Auth());
final cancel = notifier.listenFor(
  onWaiting: (isWaiting) { /* e.g. 切换指示器 */ },
  onComplete: (data) { /* e.g. 记录操作结果 */ }, 
  onError: (e, s) { /* e.g. 显示错误对话框 */ },
);

...

// 如果不再需要监听器，则移除它。
cancel();

AsyncPhaseListener

还可以使用 AsyncPhaseListener 小部件来监听阶段变化。

child: AsyncPhaseListener(
  notifier: notifier,
  onWaiting: (isWaiting) { /* e.g. 切换指示器 */ },
  onComplete: (data) { /* e.g. 记录操作结果 */ },
  onError: (e, s) { /* e.g. 显示错误对话框 */ },
  child: ...,
)

示例

下面是一个 WeatherNotifier 示例，它继承自 AsyncPhaseNotifier 并获取城市天气信息并通知其监听器。

class WeatherNotifier extends AsyncPhaseNotifier<Weather> {
  WeatherNotifier() : super(const Weather());

  final repository = WeatherRepository();

  void fetch() {
    update(() => repository.fetchWeather(Cities.tokyo));
  }
}

final notifier = WeatherNotifier();
notifier.fetch();

使用 ValueListenableBuilder

[@override](/user/override)
Widget build(BuildContext context) {
  return ValueListenableBuilder<AsyncPhase<Weather>>(
    valueListenable: notifier,
    builder: (context, phase, _) {
      return phase.when(
        waiting: (weather) => const CircularProgressIndicator(),
        complete: (weather) => Text('$weather'),
        error: (weather, e, s) => Text('$e'),
      );
    },
  ); 
}

使用 Provider

ValueListenableProvider<AsyncPhase<Weather>>.value(
  value: notifier,
  child: MaterialApp(home: ...),
)

[@override](/user/override)
Widget build(BuildContext context) {
  final phase = context.watch<AsyncPhase<Weather>>();

  return phase.when(
    waiting: (weather) => const CircularProgressIndicator(),
    complete: (weather) => Text('$weather'),
    error: (weather, e, s) => Text('$e'),
  );
}

使用 Grab

void main() {
  runApp(
    const Grab(child: App()),
  ); 
}

[@override](/user/override)
Widget build(BuildContext context) {
  final phase = notifier.grab(context);

  return phase.when(
    waiting: (weather) => const CircularProgressIndicator(),
    complete: (weather) => Text('$weather'),
    error: (weather, e, s) => Text('$e'),
  );
}