Flutter异步任务管理插件async_phase的使用

async_phase 是一个用于表示异步操作阶段的包，非常适合在Flutter应用中进行异步任务管理。本文将介绍如何使用 async_phase 包来管理异步任务，并提供完整的示例代码。

关于此包

该包主要用于与 AsyncPhaseNotifier 一起在Flutter应用中使用，但也可以独立用于纯Dart应用。有关 AsyncPhaseNotifier 的详细信息，请参阅其文档。

AsyncPhase 类

AsyncPhase 是一个密封类，类似于 package:riverpod 中的 AsyncValue，但它是独立的包，可以避免不必要的依赖，并且没有复杂的行为。

子类（阶段）

AsyncPhase 的四个子类用于表示异步操作的不同阶段：

• AsyncInitial
• AsyncWaiting
• AsyncComplete
• AsyncError

属性

• data: 异步操作的结果。
• error: 发生错误时的错误信息（仅存在于 AsyncError 中）。
• stackTrace: 错误的堆栈跟踪（仅存在于 AsyncError 中）。

使用方法

以下是如何在不使用 AsyncPhaseNotifier 的情况下使用 async_phase 的示例。

AsyncPhase.from()

使用 AsyncPhase.from() 执行异步函数并将结果转换为 AsyncComplete 或 AsyncError。

示例代码

class WeatherForecast {
  WeatherForecast({required this.onPhaseChanged});

  final void Function(AsyncPhase<Weather>) onPhaseChanged;

  AsyncPhase<Weather> _phase = AsyncInitial(Weather());

  Future<void> fetch() async {
    _phase = _phase.copyAsWaiting();
    onPhaseChanged(_phase);

    _phase = await AsyncPhase.from(
      () => repository.fetchWeather(Cities.tokyo),
      fallbackData: _phase.data,
    );
    onPhaseChanged(_phase);
  }
}

when()

when() 方法用于根据当前阶段返回相应的值或小部件。

final message = phase.when(
  initial: (data) => 'phase: AsyncInitial ($data)', // Optional
  waiting: (data) => 'phase: AsyncWaiting ($data)',
  complete: (data) => 'phase: AsyncComplete ($data)',
  error: (data, error, stackTrace) => 'phase: AsyncError ($error)',
);

模式匹配

作为 when() 的替代方案，可以使用模式匹配处理阶段。

final message = switch (phase) {
  AsyncInitial(:final data) => 'phase: AsyncInitial ($data)',
  AsyncWaiting(:final data) => 'phase: AsyncWaiting ($data)',
  AsyncComplete(:final data) => 'phase: AsyncComplete ($data)',
  AsyncError(:final error) => 'phase: AsyncError ($error)',
};

whenOrNull()

如果只需要某些阶段，可以使用 whenOrNull()。

final message = phase.whenOrNull(
  complete: (data) => 'phase: AsyncComplete ($data)',
  error: (data, error, stackTrace) => 'phase: AsyncError ($error)',
);

类型检查

可以使用 isInitial, isWaiting, isComplete, isError 来检查当前阶段。

if (phase is AsyncError<Weather>) {
  print(phase.error);
  return;
}

rethrowError()

AsyncError 提供了 rethrowError() 方法，用于重新抛出错误。

Future<AsyncPhase<Uint8List>> fetchImage({required Uri uri}) async {
  return AsyncPhase.from(() {
    final phase = await downloadFrom(uri: uri);
    if (phase case AsyncError()) {
      phase.rethrowError();
    }
    return resizeImage(phase.data, maxSize: ...);
  });
}

onComplete / onError

onComplete 和 onError 可以用于在操作成功或失败时执行特定的操作。

final phase = await AsyncPhase.from(
  () => someOperation(),
  onComplete: (data) {
    // Called when the operation completes successfully.
  },
  onError: (data, error, stackTrace) {
    // Called when the operation fails.
  },
);

完整示例

以下是一个完整的示例，展示如何使用 async_phase 进行异步计算。

import 'dart:async';
import 'package:async_phase/async_phase.dart';

Future<void> main() async {
  final calc = Calculation(80.0, onPhaseChanged: _onPhaseChanged);
  await wait();

  for (final divisor in [2, 4, 0]) {
    print('Dividing by $divisor...');
    await wait();

    await calc.divideBy(divisor);
    await wait();
  }
}

void _onPhaseChanged(AsyncPhase<double> phase) {
  final message = phase.when(
    initial: (data) => 'Initial value\n  $data',
    waiting: (data) => '  $data (waiting)',
    complete: (data) => '  $data (complete)',
    error: (data, e, s) => '  $data ($e)',
  );
  print(message);
}

class Calculation {
  Calculation(double initial, {required this.onPhaseChanged}) {
    phase = AsyncInitial(initial);
    onPhaseChanged(phase);
  }

  late AsyncPhase<double> phase;
  late void Function(AsyncPhase<double>) onPhaseChanged;

  Future<void> divideBy(num value) async {
    phase = phase.copyAsWaiting();
    onPhaseChanged(phase);

    phase = await AsyncPhase.from(
      () => phase.data!.divideBy(value),
      fallbackData: -1.0,
    );
    onPhaseChanged(phase);
  }
}

extension on double? {
  double divideBy(num value) {
    if (value == 0) throw ArgumentError('Division by zero');
    return this! / value.toDouble();
  }
}

Future<void> wait([int milliseconds = 500]) => Future.delayed(Duration(milliseconds: milliseconds));

通过上述示例和解释，您应该能够很好地理解并使用 async_phase 包来管理Flutter应用中的异步任务。