内容

dart:async

内容 keyboard_arrow_down keyboard_arrow_up
more_horiz

异步编程通常使用回调函数，但 Dart 提供了替代方案：Future 和 Stream 对象。Future 就像一个承诺，承诺在未来的某个时间提供结果。Stream 是一种获取值序列（例如事件）的方式。Future、Stream 等都位于 dart:async 库中（API 参考）。

dart:async 库在 Web 应用和命令行应用中均可使用。要使用它，请导入 dart:async

dart
import 'dart:async';

Future

#

Future 对象出现在整个 Dart 库中，通常作为异步方法返回的对象。当 future 完成时，其值就可以使用了。

使用 await

#

在直接使用 Future API 之前，请考虑改用 await。使用 await 表达式的代码可能比使用 Future API 的代码更容易理解。

考虑以下函数。它使用 Future 的 then() 方法依次执行三个异步函数，并在执行下一个函数之前等待每个函数完成。

dart
void runUsingFuture() {
  // ...
  findEntryPoint().then((entryPoint) {
    return runExecutable(entryPoint, args);
  }).then(flushThenExit);
}

使用 await 表达式的等效代码看起来更像同步代码

dart
Future<void> runUsingAsyncAwait() async {
  // ...
  var entryPoint = await findEntryPoint();
  var exitCode = await runExecutable(entryPoint, args);
  await flushThenExit(exitCode);
}

async 函数可以捕获来自 Future 的异常。例如

dart
var entryPoint = await findEntryPoint();
try {
  var exitCode = await runExecutable(entryPoint, args);
  await flushThenExit(exitCode);
} catch (e) {
  // Handle the error...
}

有关使用 await 和相关 Dart 语言功能的更多信息，请参阅 异步编程教程。

基本用法

#

您可以使用 then() 计划在 future 完成时运行的代码。例如，Client.read() 返回一个 Future，因为 HTTP 请求可能需要一段时间。使用 then() 允许您在该 Future 完成且承诺的字符串值可用时运行一些代码

dart
httpClient.read(url).then((String result) {
  print(result);
});

使用 catchError() 处理 Future 对象可能抛出的任何错误或异常。

dart
httpClient.read(url).then((String result) {
  print(result);
}).catchError((e) {
  // Handle or ignore the error.
});

then().catchError() 模式是 try-catch 的异步版本。

链接多个异步方法

#

then() 方法返回一个 Future，提供了一种以特定顺序运行多个异步函数的有用方法。如果使用 then() 注册的回调返回一个 Future，则 then() 返回一个 Future，该 Future 将与回调返回的 Future 的结果相同。如果回调返回任何其他类型的返回值，则 then() 会创建一个新的 Future，该 Future 将使用该值完成。

dart
Future result = costlyQuery(url);
result
    .then((value) => expensiveWork(value))
    .then((_) => lengthyComputation())
    .then((_) => print('Done!'))
    .catchError((exception) {
  /* Handle exception... */
});

在前面的示例中，方法按以下顺序运行

  1. costlyQuery()
  2. expensiveWork()
  3. lengthyComputation()

以下是使用 await 编写的相同代码

dart
try {
  final value = await costlyQuery(url);
  await expensiveWork(value);
  await lengthyComputation();
  print('Done!');
} catch (e) {
  /* Handle exception... */
}

等待多个 Future

#

有时您的算法需要调用许多异步函数，并在它们全部完成之前等待。使用 Future.wait() 静态方法来管理多个 Future 并等待它们完成

dart
Future<void> deleteLotsOfFiles() async =>  ...
Future<void> copyLotsOfFiles() async =>  ...
Future<void> checksumLotsOfOtherFiles() async =>  ...

await Future.wait([
  deleteLotsOfFiles(),
  copyLotsOfFiles(),
  checksumLotsOfOtherFiles(),
]);
print('Done with all the long steps!');

Future.wait() 返回一个 future，该 future 在所有提供的 future 完成后完成。它要么使用其结果完成，要么在任何提供的 future 失败时使用错误完成。

处理多个 Future 的错误

#

您还可以等待 可迭代对象 或 记录 中的 future 的并行操作。

这些扩展返回一个 future，其中包含所有提供的 future 的结果值。与 Future.wait 不同，它们还允许您处理错误。

如果集合中的任何 future 使用错误完成，则 wait 将使用 ParallelWaitError 完成。这允许调用者处理单个错误，并在必要时处理成功的结果。

当您不需要每个单独 future 的结果值时，请在 future 的可迭代对象上使用 wait

dart
void main() async {
  Future<void> delete() async =>  ...
  Future<void> copy() async =>  ...
  Future<void> errorResult() async =>  ...
  
  try {
    // Wait for each future in a list, returns a list of futures:
    var results = await [delete(), copy(), errorResult()].wait;

    } on ParallelWaitError<List<bool?>, List<AsyncError?>> catch (e) {

    print(e.values[0]);    // Prints successful future
    print(e.values[1]);    // Prints successful future
    print(e.values[2]);    // Prints null when the result is an error

    print(e.errors[0]);    // Prints null when the result is successful
    print(e.errors[1]);    // Prints null when the result is successful
    print(e.errors[2]);    // Prints error
  }

}

当您需要每个 future 的单个结果值时，请在 future 的记录上使用 wait。这提供了额外的优势，即 future 可以具有不同的类型

dart
void main() async {
  Future<int> delete() async =>  ...
  Future<String> copy() async =>  ...
  Future<bool> errorResult() async =>  ...

  try {    
    // Wait for each future in a record, returns a record of futures:
    (int, String, bool) result = await (delete(), copy(), errorResult()).wait;
  
  } on ParallelWaitError<(int?, String?, bool?),
      (AsyncError?, AsyncError?, AsyncError?)> catch (e) {
    // ...
    }

  // Do something with the results:
  var deleteInt  = result.$1;
  var copyString = result.$2;
  var errorBool  = result.$3;
}

Stream

#

Stream 对象出现在整个 Dart API 中，表示数据序列。例如，按钮点击等 HTML 事件是使用 Stream 传递的。您还可以将文件读取为 Stream。

使用异步 for 循环

#

有时您可以使用异步 for 循环（await for）代替使用 Stream API。

考虑以下函数。它使用 Stream 的 listen() 方法订阅文件列表，传入一个函数文字，该函数文字搜索每个文件或目录。

dart
void main(List<String> arguments) {
  // ...
  FileSystemEntity.isDirectory(searchPath).then((isDir) {
    if (isDir) {
      final startingDir = Directory(searchPath);
      startingDir.list().listen((entity) {
        if (entity is File) {
          searchFile(entity, searchTerms);
        }
      });
    } else {
      searchFile(File(searchPath), searchTerms);
    }
  });
}

使用 await 表达式（包括异步 for 循环 (await for)）的等效代码看起来更像同步代码

dart
void main(List<String> arguments) async {
  // ...
  if (await FileSystemEntity.isDirectory(searchPath)) {
    final startingDir = Directory(searchPath);
    await for (final entity in startingDir.list()) {
      if (entity is File) {
        searchFile(entity, searchTerms);
      }
    }
  } else {
    searchFile(File(searchPath), searchTerms);
  }
}

有关使用 await 和相关 Dart 语言功能的更多信息，请参阅 异步编程教程。

侦听 Stream 数据

#

要获取每个到达的值，可以使用await for或使用listen()方法订阅流。

dart
// Add an event handler to a button.
submitButton.onClick.listen((e) {
  // When the button is clicked, it runs this code.
  submitData();
});

在这个例子中，onClick属性是由提交按钮提供的Stream对象。

如果您只关心一个事件，可以使用诸如first、last或single之类的属性获取它。要测试事件在处理之前，可以使用诸如firstWhere()、lastWhere()或singleWhere()之类的方法。

如果您关心事件的一个子集，可以使用诸如skip()、skipWhile()、take()、takeWhile()和where()之类的方法。

转换 Stream 数据

#

通常，您需要在使用流数据之前更改其格式。使用transform()方法生成具有不同数据类型的流。

dart
var lines =
    inputStream.transform(utf8.decoder).transform(const LineSplitter());

此示例使用了两个转换器。首先它使用utf8.decoder将整数流转换为字符串流。然后它使用LineSplitter将字符串流转换为单独行的流。这些转换器来自dart:convert库（请参阅dart:convert 部分）。

处理错误和完成

#

您指定错误和完成处理代码的方式取决于您是否使用异步 for 循环 (await for) 或 Stream API。

如果您使用异步 for 循环，则使用 try-catch 处理错误。流关闭后执行的代码位于异步 for 循环之后。

dart
Future<void> readFileAwaitFor() async {
  var config = File('config.txt');
  Stream<List<int>> inputStream = config.openRead();

  var lines =
      inputStream.transform(utf8.decoder).transform(const LineSplitter());
  try {
    await for (final line in lines) {
      print('Got ${line.length} characters from stream');
    }
    print('file is now closed');
  } catch (e) {
    print(e);
  }
}

如果您使用 Stream API，则通过注册onError监听器来处理错误。通过注册onDone监听器在流关闭后运行代码。

dart
var config = File('config.txt');
Stream<List<int>> inputStream = config.openRead();

inputStream.transform(utf8.decoder).transform(const LineSplitter()).listen(
    (String line) {
  print('Got ${line.length} characters from stream');
}, onDone: () {
  print('file is now closed');
}, onError: (e) {
  print(e);
});

更多信息

#

有关在命令行应用程序中使用 Future 和 Stream 的一些示例，请查看dart:io 文档。另请参阅以下文章和教程

除非另有说明，否则本网站上的文档反映了 Dart 3.5.3。页面最后更新于 2024-06-10。 查看源代码 或 报告问题。