區域

目錄 keyboard_arrow_down keyboard_arrow_up

非同步動態範圍
區域基礎
處理未捕獲的錯誤
- 範例：錯誤無法跨越至錯誤區域
- 範例：錯誤無法離開錯誤區域
將區域與 Stream 一起使用
- 範例：將 Stream 與 runZonedGuarded() 一起使用
儲存區域本機值
- 範例：使用區域本機值進行除錯記錄
覆寫功能
摘要
- 更多資源
- 更多範例

more_horiz

本文討論 dart:async 函式庫中與區域相關的 API，重點在於最上層的 runZoned() 和 runZonedGuarded() 函式。在閱讀本文之前，請複習Future 和錯誤處理中涵蓋的技術。

區域可以實現以下任務

保護您的應用程式，使其不會因未捕獲的例外狀況而退出。例如，簡單的 HTTP 伺服器可能會使用以下非同步程式碼
dart
```
runZonedGuarded(() {
  HttpServer.bind('0.0.0.0', port).then((server) {
    server.listen(staticFiles.serveRequest);
  });
},
(error, stackTrace) => print('Oh noes! $error $stackTrace'));
```
在區域中執行 HTTP 伺服器可讓應用程式在伺服器的非同步程式碼中發生未捕獲（但非致命）的錯誤時繼續執行。
將資料（稱為區域本機值）與個別區域建立關聯。
覆寫有限的方法集，例如程式碼部分或全部中的 print() 和 scheduleMicrotask()。
在程式碼每次進入或離開區域時執行操作。這類操作可以包括啟動或停止計時器，或儲存堆疊追蹤。

您可能在其他語言中遇到過類似區域的東西。Node.js 中的網域是 Dart 區域的靈感來源。Java 的執行緒本機儲存也有一些相似之處。最相似的是 Brian Ford 的 Dart 區域 JavaScript 連接埠 zone.js，他在此影片中描述了該連接埠。

區域代表呼叫的非同步動態範圍。它是作為呼叫的一部分執行的計算，以及透過該程式碼註冊的非同步回呼。

例如，在 HTTP 伺服器範例中，bind()、then() 和 then() 的回呼都在同一個區域中執行，該區域是使用 runZoned() 建立的。

在下一個範例中，程式碼在 3 個不同的區域中執行：區域 #1 (根區域)、區域 #2 和區域 #3。

import 'dart:async';

main() {
  foo();
  var future;
  runZoned(() {          // Starts a new child zone (zone #2).
    future = new Future(bar).then(baz);
  });
  future.then(qux);
}

foo() => ...foo-body...  // Executed twice (once each in two zones).
bar() => ...bar-body...
baz(x) => runZoned(() => foo()); // New child zone (zone #3).
qux(x) => ...qux-body...

下圖顯示程式碼的執行順序，以及程式碼在其中執行的區域。

illustration of program execution

每次呼叫 runZoned() 都會建立一個新的區域，並在該區域中執行程式碼。當該程式碼排定工作（例如呼叫 baz()）時，該工作會在排定的區域中執行。例如，呼叫 qux()（main() 的最後一行）會在區域 #1 (根區域) 中執行，即使它附加到本身在區域 #2 中執行的 Future。

子區域不會完全取代其父區域。相反，新的區域會巢狀置於其周圍的區域內。例如，區域 #2 包含區域 #3，而區域 #1（根區域）包含區域 #2 和區域 #3。

所有 Dart 程式碼都在根區域中執行。程式碼也可能會在其他巢狀子區域中執行，但至少始終會在根區域中執行。

區域可以捕獲並處理未捕獲的錯誤。

未捕獲的錯誤通常是因為程式碼使用 throw 引發例外狀況，但沒有搭配的 catch 陳述式來處理它而發生。當 Future 以錯誤結果完成時，也可能會在 async 函式中產生未捕獲的錯誤，但遺失了對應的 await 來處理錯誤。

未捕獲的錯誤會回報給目前未能捕獲它的區域。根據預設，區域會回應未捕獲的錯誤而使程式當機。您可以將您自己的自訂未捕獲錯誤處理常式安裝到新的區域，以攔截和處理未捕獲的錯誤，無論您偏好哪種方式。

若要引入具有未捕獲錯誤處理常式的新區域，請使用 runZoneGuarded 方法。其 onError 回呼會成為新區域的未捕獲錯誤處理常式。此回呼會處理呼叫擲回的任何同步錯誤。

dartrunZonedGuarded(() {
  Timer.run(() { throw 'Would normally kill the program'; });
}, (error, stackTrace) {
  print('Uncaught error: $error');
});

其他有助於處理未捕獲錯誤的區域 API 包括 Zone.fork、Zone.runGuarded 和 ZoneSpecification.uncaughtErrorHandler。

上述程式碼具有一個非同步回呼（透過 Timer.run()），該回呼會擲回例外狀況。通常，此例外狀況會是未處理的錯誤，並達到最上層（在獨立的 Dart 可執行檔中，會終止正在執行的程序）。但是，透過區域錯誤處理常式，錯誤會傳遞至錯誤處理常式，而且不會關閉程式。

try-catch 和區域錯誤處理常式之間的一個顯著差異是，區域會在發生未捕獲的錯誤後繼續執行。如果區域內排定了其他非同步回呼，它們仍然會執行。因此，可能會多次叫用區域錯誤處理常式。

任何具有未捕獲錯誤處理器的區域都稱為錯誤區域。錯誤區域可能會處理源自該區域後代中的錯誤。一個簡單的規則決定了在未來轉換序列（使用 then() 或 catchError()）中錯誤的處理位置：Future 鏈上的錯誤永遠不會跨越錯誤區域的邊界。

如果錯誤到達錯誤區域的邊界，則在該點會被視為未處理的錯誤。

在以下範例中，第一行引發的錯誤無法跨越到錯誤區域。

dartvar f = new Future.error(499);
f = f.whenComplete(() { print('Outside of zones'); });
runZoned(() {
  f = f.whenComplete(() { print('Inside non-error zone'); });
});
runZonedGuarded(() {
  f = f.whenComplete(() { print('Inside error zone (not called)'); });
}, (error) { print(error); });

這是您執行範例時看到的輸出

Outside of zones
Inside non-error zone
Uncaught Error: 499
Unhandled exception:
499
...stack trace...

如果您移除對 runZoned() 或 runZonedGuarded() 的呼叫，您會看到此輸出

Outside of zones
Inside non-error zone
Inside error zone (not called)
Uncaught Error: 499
Unhandled exception:
499
...stack trace...

請注意，移除區域或錯誤區域都會導致錯誤進一步傳播。

堆疊追蹤之所以出現，是因為錯誤發生在錯誤區域之外。如果您在整個程式碼片段周圍新增一個錯誤區域，則可以避免堆疊追蹤。

如前面的程式碼所示，錯誤無法跨越到錯誤區域。同樣地，錯誤也無法跨越離開錯誤區域。請考慮以下範例

dartvar completer = new Completer();
var future = completer.future.then((x) => x + 1);
var zoneFuture;
runZonedGuarded(() {
  zoneFuture = future.then((y) => throw 'Inside zone');
}, (error) { print('Caught: $error'); });

zoneFuture.catchError((e) { print('Never reached'); });
completer.complete(499);

即使 future 鏈以 catchError() 結束，非同步錯誤也無法離開錯誤區域。在 runZonedGuarded() 中找到的區域錯誤處理器會處理該錯誤。因此，zoneFuture 永遠不會完成 — 無論是帶有值，還是帶有錯誤。

區域和串流的規則比 Future 簡單

此規則遵循串流在被監聽之前不應有副作用的準則。同步程式碼中的類似情況是 Iterables 的行為，只有在您請求值時才會進行評估。

以下範例設定一個帶有回呼的串流，然後使用 runZonedGuarded() 在新區域中執行該串流

dartvar stream = new File('stream.dart').openRead()
    .map((x) => throw 'Callback throws');

runZonedGuarded(() { stream.listen(print); },
         (e) { print('Caught error: $e'); });

runZonedGuarded() 中的錯誤處理器會捕獲回呼拋出的錯誤。這是輸出

Caught error: Callback throws

如輸出所示，回呼與監聽區域相關聯，而不是與呼叫 map() 的區域相關聯。

如果您曾經想使用靜態變數，但因為多個並行運行的計算彼此干擾而無法使用，請考慮使用區域本地值。您可能會新增一個區域本地值來協助除錯。另一個使用案例是處理 HTTP 請求：您可以將使用者 ID 和其授權權杖放在區域本地值中。

使用 runZoned() 的 zoneValues 引數將值儲存在新建立的區域中

dartrunZoned(() {
  print(Zone.current[#key]);
}, zoneValues: { #key: 499 });

若要讀取區域本地值，請使用區域的索引運算子和值的鍵：[key]。任何物件都可以用作鍵，只要它具有相容的 operator == 和 hashCode 實作。通常，鍵是一個符號字面值：#identifier。

您無法變更鍵對應到的物件，但您可以操作該物件。例如，以下程式碼會將項目新增至區域本地列表

dartrunZoned(() {
  Zone.current[#key].add(499);
  print(Zone.current[#key]); // [499]
}, zoneValues: { #key: [] });

區域會從其父區域繼承區域本地值，因此新增巢狀區域不會意外丟失現有的值。但是，巢狀區域可以遮蔽父值。

假設您有兩個檔案 foo.txt 和 bar.txt，並且想要列印它們的所有行。該程式可能看起來像這樣

dartimport 'dart:async';
import 'dart:convert';
import 'dart:io';

Future splitLinesStream(stream) {
  return stream
      .transform(ASCII.decoder)
      .transform(const LineSplitter())
      .toList();
}

Future splitLines(filename) {
  return splitLinesStream(new File(filename).openRead());
}
main() {
  Future.forEach(['foo.txt', 'bar.txt'],
                 (file) => splitLines(file)
                     .then((lines) { lines.forEach(print); }));
}

這個程式可以運作，但假設您現在想知道每一行來自哪個檔案，並且您不能只是將檔案名稱引數新增到 splitLinesStream()。使用區域本地值，您可以將檔案名稱新增到傳回的字串（新行會被反白顯示）

dartimport 'dart:async';
import 'dart:convert';
import 'dart:io';

Future splitLinesStream(stream) {
  return stream
      .transform(ASCII.decoder)
      .transform(const LineSplitter())
      .map((line) => '${Zone.current[#filename]}: $line')
      .toList();
}

Future splitLines(filename) {
  return runZoned(() {
    return splitLinesStream(new File(filename).openRead());
  }, zoneValues: { #filename: filename });
}

main() {
  Future.forEach(['foo.txt', 'bar.txt'],
                 (file) => splitLines(file)
                     .then((lines) { lines.forEach(print); }));
}

請注意，新程式碼不會修改函式簽名，也不會將檔案名稱從 splitLines() 傳遞到 splitLinesStream()。相反地，它使用區域本地值來實作類似於在非同步環境中運作的靜態變數的功能。

使用 runZoned() 的 zoneSpecification 引數來覆寫由區域管理的功能。引數的值是一個 ZoneSpecification 物件，您可以使用它來覆寫下列任何功能

分叉子區域
在區域中註冊和執行回呼
排程微任務和計時器
處理未捕獲的非同步錯誤（runZonedGuarded() 是這個的捷徑）
列印

作為覆寫功能的簡單範例，以下是一種靜音區域內所有列印的方式

dartimport 'dart:async';

main() {
  runZoned(() {
    print('Will be ignored');
  }, zoneSpecification: new ZoneSpecification(
    print: (self, parent, zone, message) {
      // Ignore message.
    }));
}

在分叉的區域內，print() 函式會被指定的列印攔截器覆寫，該攔截器只會捨棄訊息。覆寫列印是可行的，因為 print()（與 scheduleMicrotask() 和 Timer 建構函式一樣）會使用目前區域 (Zone.current) 來執行其工作。

如列印範例所示，攔截器會將三個引數新增至 Zone 類別對應方法中定義的引數。例如，Zone 的 print() 方法有一個引數：print(String line)。由 ZoneSpecification 定義的 print() 的攔截器版本有四個引數：print(Zone self, ZoneDelegate parent, Zone zone, String line)。

三個攔截器引數始終以相同的順序出現在任何其他引數之前。

self: 正在處理回呼的區域。
parent: 代表父區域的 ZoneDelegate。使用它將操作轉發到父區域。
zone: 操作來源的區域。有些操作需要知道在哪個區域上調用操作。例如，zone.fork(specification) 必須建立一個新的區域作為 zone 的子區域。另一個範例是，即使您將 scheduleMicrotask() 委派給另一個區域，原始的 zone 也必須是執行微任務的區域。

當攔截器將方法委派給父區域時，父區域 (ZoneDelegate) 版本的方法只有一個額外引數：zone，即原始呼叫來源的區域。例如，ZoneDelegate 上 print() 方法的簽名是 print(Zone zone, String line)。

以下是另一個可攔截方法 scheduleMicrotask() 的引數範例

以下是一個範例，說明如何委派給父區域

dartimport 'dart:async';

main() {
  runZoned(() {
    var currentZone = Zone.current;
    scheduleMicrotask(() {
      print(identical(currentZone, Zone.current));  // prints true.
    });
  }, zoneSpecification: new ZoneSpecification(
    scheduleMicrotask: (self, parent, zone, task) {
      print('scheduleMicrotask has been called inside the zone');
      // The origin `zone` needs to be passed to the parent so that
      // the task can be executed in it.
      parent.scheduleMicrotask(zone, task);
    }));
}

假設您想知道某些非同步程式碼執行所花費的時間。您可以將程式碼放在一個區域中，在每次進入該區域時啟動計時器，並在每次離開該區域時停止計時器來完成此操作。

將 run* 參數提供給 ZoneSpecification 可讓您指定區域執行的程式碼。

run* 參數 — run、runUnary 和 runBinary — 指定每次要求區域執行程式碼時要執行的程式碼。這些參數分別適用於零引數、一引數和兩引數的回呼。run 參數也適用於在呼叫 runZoned() 之後立即執行的初始同步程式碼。

以下是一個使用 run* 分析程式碼的範例

dartfinal total = new Stopwatch();
final user = new Stopwatch();

final specification = new ZoneSpecification(
  run: (self, parent, zone, f) {
    user.start();
    try { return parent.run(zone, f); } finally { user.stop(); }
  },
  runUnary: (self, parent, zone, f, arg) {
    user.start();
    try { return parent.runUnary(zone, f, arg); } finally { user.stop(); }
  },
  runBinary: (self, parent, zone, f, arg1, arg2) {
    user.start();
    try {
      return parent.runBinary(zone, f, arg1, arg2);
    } finally {
      user.stop();
    }
  });

runZoned(() {
  total.start();
  // ... Code that runs synchronously...
  // ... Then code that runs asynchronously ...
    .then((...) {
      print(total.elapsedMilliseconds);
      print(user.elapsedMilliseconds);
    });
}, zoneSpecification: specification);

在此程式碼中，每個 run* 覆寫只會啟動使用者計時器、執行指定的函式，然後停止使用者計時器。

提供 register*Callback 參數給 ZoneSpecification 來包裝或變更回呼程式碼 — 在區域中非同步執行的程式碼。與 run* 參數類似，register*Callback 參數有三種形式：registerCallback（適用於沒有引數的回呼）、registerUnaryCallback（一個引數）和 registerBinaryCallback（兩個引數）。

以下是一個範例，讓區域在程式碼消失到非同步環境之前儲存堆疊追蹤。

dartimport 'dart:async';

get currentStackTrace {
  try {
    throw 0;
  } catch(_, st) {
    return st;
  }
}

var lastStackTrace = null;

bar() => throw "in bar";
foo() => new Future(bar);

main() {
  final specification = new ZoneSpecification(
    registerCallback: (self, parent, zone, f) {
      var stackTrace = currentStackTrace;
      return parent.registerCallback(zone, () {
        lastStackTrace = stackTrace;
        return f();
      });
    },
    registerUnaryCallback: (self, parent, zone, f) {
      var stackTrace = currentStackTrace;
      return parent.registerUnaryCallback(zone, (arg) {
        lastStackTrace = stackTrace;
        return f(arg);
      });
    },
    registerBinaryCallback: (self, parent, zone, f) {
      var stackTrace = currentStackTrace;
      return parent.registerBinaryCallback(zone, (arg1, arg2) {
        lastStackTrace = stackTrace;
        return f(arg1, arg2);
      });
    },
    handleUncaughtError: (self, parent, zone, error, stackTrace) {
      if (lastStackTrace != null) print("last stack: $lastStackTrace");
      return parent.handleUncaughtError(zone, error, stackTrace);
    });

  runZoned(() {
    foo();
  }, zoneSpecification: specification);
}

繼續執行該範例。您將看到一個「最後堆疊」追蹤 (lastStackTrace)，其中包括 foo()，因為 foo() 是同步呼叫的。下一個堆疊追蹤 (stackTrace) 來自非同步環境，它知道 bar() 但不知道 foo()。

即使您正在實作非同步 API，您可能根本不需要處理區域。例如，雖然您可能會期望 dart:io 程式庫追蹤目前的區域，但它反而依賴於 dart:async 類別（例如 Future 和 Stream）的區域處理。

如果您明確處理區域，則需要註冊所有非同步回呼，並確保在註冊回呼的區域中調用每個回呼。Zone 的 bind*Callback 輔助方法使此任務更容易。它們是 register*Callback 和 run* 的捷徑，可確保每個回呼都在該區域中註冊和執行。

如果您需要比 bind*Callback 給您更多的控制權，那麼您需要使用 register*Callback 和 run*。您可能還想使用 Zone 的 run*Guarded 方法，該方法會將呼叫包裝在 try-catch 中，並且如果發生錯誤，則會調用 uncaughtErrorHandler。

區域適用於保護您的程式碼免受非同步程式碼中未捕獲的例外狀況影響，但它們可以做更多的事情。您可以將資料與區域關聯，並且可以覆寫核心功能，例如列印和任務排程。區域可實現更好的除錯，並提供可用於分析等功能的掛鉤。

與區域相關的 API 文件: 閱讀 runZoned()、runZonedGuarded()、Zone、ZoneDelegate 和 ZoneSpecification 的文件。
stack_trace: 使用 stack_trace 程式庫的 Chain 類別，您可以獲得針對非同步執行程式碼更好的堆疊追蹤。如需更多資訊，請參閱 pub.dev 網站上的 stack_trace 套件。

以下是一些更複雜的使用區域範例。

task_interceptor 範例: task_interceptor.dart 中的玩具區域會攔截 scheduleMicrotask、createTimer 和 createPeriodicTimer，以模擬 Dart 基本元素的行為，而無需讓步於事件迴圈。
stack_trace 套件的原始碼: stack_trace 套件使用區域來形成用於除錯非同步程式碼的堆疊追蹤鏈。使用的區域功能包括錯誤處理、區域本地值和回呼。您可以在 stack_trace GitHub 專案中找到 stack_trace 原始碼。
dart:html 和 dart:async 的原始碼: 這兩個 SDK 函式庫實作了具有非同步回呼的 API，因此它們會處理區域 (zones)。您可以在 Dart GitHub 專案的 sdk/lib 目錄下瀏覽或下載它們的原始碼。

感謝 Anders Johnsen 和 Lasse Reichstein Nielsen 對本文的審閱。

除非另有說明，本網站上的文件反映的是 Dart 3.6.0 版本。頁面最後更新於 2014-03-03。檢視原始碼或回報問題。

此頁面的部分內容可能已過時。

區域

非同步動態範圍

區域基礎

處理未捕獲的錯誤

範例：錯誤無法跨越至錯誤區域

範例：錯誤無法離開錯誤區域

將區域與 Stream 一起使用

範例：將串流與 `runZonedGuarded()` 搭配使用

儲存區域本機值

範例：使用區域本機值進行除錯記錄

覆寫功能

範例：覆寫 print

攔截器和委派的引數

範例：委派給父區域

範例：在進入和離開區域時執行程式碼

範例：處理回呼

實作非同步回呼

摘要

更多資源

更多範例