dart:async
异步编程通常使用回调函数，但 Dart 提供了替代方案：Future 和 Stream 对象。Future 就像是对未来某个时刻将提供结果的承诺。Stream 是一种获取一系列值（例如事件）的方式。Future、Stream 等都在 dart:async 库中（API 参考）。
dart:async 库在 Web 应用和命令行应用中均可使用。要使用它，请导入 dart:async
import 'dart:async';Future
#Future 对象遍布 Dart 库中，通常作为异步方法返回的对象。当 Future 完成时，其值即可使用。
使用 await
#在直接使用 Future API 之前，请考虑改用 await。使用 await 表达式的代码比使用 Future API 的代码更容易理解。
考虑以下函数。它使用 Future 的 then() 方法按顺序执行三个异步函数，等待每个函数完成后再执行下一个。
void runUsingFuture() {
// ...
findEntryPoint()
.then((entryPoint) {
return runExecutable(entryPoint, args);
})
.then(flushThenExit);
}使用 await 表达式的等效代码看起来更像同步代码
Future<void> runUsingAsyncAwait() async {
// ...
var entryPoint = await findEntryPoint();
var exitCode = await runExecutable(entryPoint, args);
await flushThenExit(exitCode);
}async 函数可以捕获 Future 抛出的异常。例如
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 完成并可获取承诺的字符串值时运行一些代码
httpClient.read(url).then((String result) {
print(result);
});使用 catchError() 来处理 Future 对象可能抛出的任何错误或异常。
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 将以该值完成。
Future result = costlyQuery(url);
result
.then((value) => expensiveWork(value))
.then((_) => lengthyComputation())
.then((_) => print('Done!'))
.catchError((exception) {
/* Handle exception... */
});在前面的示例中，方法按以下顺序运行
costlyQuery()expensiveWork()lengthyComputation()
这是使用 await 编写的相同代码
try {
final value = await costlyQuery(url);
await expensiveWork(value);
await lengthyComputation();
print('Done!');
} catch (e) {
/* Handle exception... */
}等待多个 Future
#有时您的算法需要调用许多异步函数并等待它们全部完成后才能继续。使用 Future.wait() 静态方法来管理多个 Future 并等待它们完成
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.wait 不同，它们还允许您处理错误。
如果集合中的任何 Future 完成时出现错误，wait 会以 ParallelWaitError 完成。这允许调用者处理单个错误并在必要时处置成功的结果。
当您不需要每个 Future 的结果值时，请在 Future 的可迭代对象上使用 wait
Future<int> delete() async => ...;
Future<String> copy() async => ...;
Future<bool> errorResult() async => ...;
void main() 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 可以是不同类型的
Future<int> delete() async => ...;
Future<String> copy() async => ...;
Future<bool> errorResult() async => ...;
void main() async {
try {
// Wait for each future in a record.
// Returns a record of futures that you can destructure.
final (deleteInt, copyString, errorBool) =
await (delete(), copy(), errorResult()).wait;
// Do something with the results...
} on ParallelWaitError<
(int?, String?, bool?),
(AsyncError?, AsyncError?, AsyncError?)
> catch (e) {
// ...
}
}Stream
#Stream 对象在 Dart API 中随处可见，表示数据序列。例如，按钮点击等 HTML 事件是使用流传递的。您也可以将文件作为流读取。
使用异步 for 循环
#有时您可以使用异步 for 循环（await for）而不是使用 Stream API。
考虑以下函数。它使用 Stream 的 listen() 方法订阅文件列表，传入一个搜索每个文件或目录的函数字面量。
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））的等效代码看起来更像同步代码
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 语言功能的更多信息，请参阅异步编程教程。
监听流数据
#要获取每个到达的值，请使用 await for 或使用 listen() 方法订阅流
// 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() 等方法。
转换流数据
#通常，在使用流数据之前，您需要更改其格式。使用 transform() 方法生成具有不同类型数据的流
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 循环之后。
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 监听器，在流关闭后运行代码。
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 文档。另请参阅以下文章和教程