区域表示一个在异步调用中保持稳定的运行环境。
所有代码都在区域的上下文中执行,该区域以 Zone.current 的形式提供给代码。初始的 main
函数在默认区域(Zone.root)中运行。可以使用 runZoned 或 runZonedGuarded 在不同的区域中运行代码以创建新区域并在其中运行代码,或者使用 Zone.run 在可能以前使用 Zone.fork 创建的区域上下文中运行代码。
开发者可以创建一个新的区域,该区域覆盖了现有区域的一些功能。例如,自定义区域可以替换或修改 print
、定时器、微任务或未捕获错误处理的行为。
区域类 Zone 不可继承,但用户可以通过使用 ZoneSpecification 通过 Zone.current 分叉现有区域来提供自定义区域。这与创建一个扩展基础类 Zone
并覆盖一些方法的类相似,但没有实际创建一个新类。相反,提供的覆盖方法是函数,它们显式接受它们自己的类、"super" 类以及 this
对象作为参数。
异步回调始终在其被安排的区域上下文中运行。这通过以下两个步骤来实现
- 回调首先使用 registerCallback、registerUnaryCallback 或 registerBinaryCallback 之一进行注册。这使得区域能够记录存在回调并可能修改它(通过返回不同的回调)。执行注册的代码(例如,
Future.then
)也记住当前区域,以便稍后可以在该区域中运行回调。 - 稍后,使用 run、runUnary 或 runBinary 中之一在记住的区域中运行已注册的回调。
所有这些都是由平台代码内部处理的,大多数用户无需担心。然而,由底层系统提供的新的异步操作的开发者必须遵循此协议以实现区域兼容性。
为了方便,区域提供了 bindCallback(以及相应的 bindUnaryCallback 和 bindBinaryCallback),以简化对区域合同的关注:这些函数首先调用相应的 register
函数,然后包装返回的函数,以便在稍后异步调用时在当前区域中运行。
类似地,区域提供 bindCallbackGuarded(以及相应的 bindUnaryCallbackGuarded 和 bindBinaryCallbackGuarded),当回调需要通过 Zone.runGuarded 调用。
- 注解
-
- @vmIsolateUnsendable
属性
方法
-
bindBinaryCallback<
R, T1, T2> (R callback(T1 argument1, T2 argument2)) → ZoneBinaryCallback< R, T1, T2> - 注册提供的
callback
并返回一个会在本区域执行函数。 -
bindBinaryCallbackGuarded<
T1, T2> (void callback(T1 argument1, T2 argument2)) → void Function(T1, T2) - 注册提供的
callback
并返回一个会在本区域执行函数。 -
bindCallback<
R> (R callback()) → ZoneCallback< R> - 注册提供的
callback
并返回一个会在本区域执行函数。 -
bindCallbackGuarded(
void callback()) → void Function() - 注册提供的
callback
并返回一个会在本区域执行函数。 -
bindUnaryCallback<
R, T> (R callback(T argument)) → ZoneUnaryCallback< R, T> - 注册提供的
callback
并返回一个会在本区域执行函数。 -
bindUnaryCallbackGuarded<
T> (void callback(T argument)) → void Function(T) - 注册提供的
callback
并返回一个会在本区域执行函数。 -
createPeriodicTimer(
Duration period, void callback(Timer timer)) → Timer - 创建一个周期性 Timer,回调将在本区域执行。
-
createTimer(
Duration duration, void callback()) → Timer - 创建一个回调在该区域内执行的计时器。
-
errorCallback(
Object error, StackTrace? stackTrace) → AsyncError? - 将错误拦截程序添加到Future或Stream时。
-
fork(
{ZoneSpecification? specification, Map< Object?, Object?> ? zoneValues}) → Zone - 创建一个新的区域作为此区域的子区域。
-
handleUncaughtError(
Object error, StackTrace stackTrace) → void - 处理未捕获的异步错误。
-
inSameErrorZone(
Zone otherZone) → bool - 此区域和
otherZone
是否在同一错误区域中。 -
noSuchMethod(
Invocation invocation) → dynamic - 当访问不存在的方法或属性时被调用。继承
-
print(
String line) → void - 打印给定的
line
。 -
registerBinaryCallback<
R, T1, T2> (R callback(T1 arg1, T2 arg2)) → ZoneBinaryCallback< R, T1, T2> - 在此区域中注册给定的回调。
-
registerCallback<
R> (R callback()) → ZoneCallback< R> - 在此区域中注册给定的回调。
-
registerUnaryCallback<
R, T> (R callback(T arg)) → ZoneUnaryCallback< R, T> - 在此区域中注册给定的回调。
-
run<
R> (R action()) → R - 在此区域中执行
action
。 -
runBinary<
R, T1, T2> (R action(T1 argument1, T2 argument2), T1 argument1, T2 argument2) → R - 在此区域中使用
argument1
和argument2
执行给定的action
。 -
runBinaryGuarded<
T1, T2> (void action(T1 argument1, T2 argument2), T1 argument1, T2 argument2) → void - 在此区域中以
argument1
和argument2
执行给定的action
并捕获同步错误。 -
runGuarded(
void action()) → void - 在此区域中执行给定的
action
并捕获同步错误。 -
runUnary<
R, T> (R action(T argument), T argument) → R - 在此区域中使用
argument
执行给定的action
。 -
runUnaryGuarded<
T> (void action(T argument), T argument) → void - 在此区域中使用
argument
执行给定的action
并捕获同步错误。 -
scheduleMicrotask(
void callback()) → void - 在此区域中异步运行
callback
。 -
toString(
) → String - 该对象的字符串表示。继承
运算符
-
operator ==(
Object other) → bool - 等号运算符。继承
-
operator [](
Object? key) → dynamic - 检索与
key
关联的区域值。