Dart Stream用法及代碼示例

異步數據事件的來源。

Stream 提供了一種接收一係列事件的方法。每個事件或者是一個數據事件，也稱為流的element，或者是一個錯誤事件，它是某事失敗的通知。當一個流已經發出它的所有事件時，一個單一的"done" 事件會通知監聽器已經到達終點。

您可以通過調用async* 函數來生成流，然後該函數返回一個流。使用該流將導致函數發出事件，直到它結束，並且流關閉。您可以使用 await for 循環(可在 async 或 async* 函數內使用)或通過在 async* 函數內使用 yield* 直接轉發其事件來使用流。例子：

Stream<T> optionalMap<T>(
    Stream<T> source , [T Function(T)? convert]) async* {
  if (convert == null) {
    yield* source;
  } else {
    await for (var event in source) {
      yield convert(event);
    }
  }
}

調用此函數時，它會立即返回一個Stream<T> 對象。然後在有人嘗試使用該流之前不會再發生任何事情。此時，async* 函數的主體開始運行。如果省略convert 函數，yield* 將偵聽source 流並將所有事件、日期和錯誤轉發到返回的流。當source 流關閉時，yield* 完成，optionalMap 函數體也結束。這將關閉返回的流。如果提供了convert is，則該函數將偵聽源流並進入重複等待下一個數據事件的await for循環。在數據事件上，它使用該值調用convert，並在返回的流上發出結果。如果source 流沒有發出錯誤事件，則循環在source 流發出時結束，然後optionalMap 函數體完成，從而關閉返回的流。在來自source 流的錯誤事件中，await for 重新拋出該錯誤，從而中斷循環。然後錯誤到達optionalMap 函數體的末尾，因為它沒有被捕獲。這使得錯誤在返回的流上發出，然後關閉。

Stream 類還提供允許您手動偵聽來自流的事件，或將流轉換為另一個流或未來的函數。

forEach 函數對應於await for 循環，就像Iterable.forEach 對應於普通的for /in 循環一樣。像循環一樣，它會為每個數據事件調用一個函數並在錯誤時中斷。

更底層的listen 方法是所有其他方法的基礎。您在流上調用 listen 以告訴它您想要接收事件，並注冊將接收這些事件的回調。當您調用 listen 時，您會收到一個 StreamSubscription 對象，該對象是提供事件的活動對象，可用於再次停止偵聽或暫時暫停訂閱中的事件。

有兩種流："Single-subscription" 流和"broadcast" 流。

A single-subscription stream 在流的整個生命周期內隻允許一個偵聽器。它在擁有監聽器之前不會開始生成事件，並且當監聽器被取消訂閱時它會停止發送事件，即使事件源仍然可以提供更多。 async* 函數創建的流是single-subscription 流，但每次調用該函數都會創建一個新的此類流。

不允許在 single-subscription 流上收聽兩次，即使在第一次訂閱已被取消後也是如此。

Single-subscription 流通常用於流式傳輸較大的連續數據塊，例如文件 I/O。

A broadcast stream 允許任意數量的偵聽器，並在它們準備好時觸發其事件，無論是否有偵聽器。

廣播流用於獨立事件/觀察者。

如果多個聽眾想要收聽single-subscription 流，請使用asBroadcastStream 在非廣播流之上創建廣播流。

在任一類型的流上，流轉換(例如 where 和 skip )返回與調用該方法的流類型相同的流，除非另有說明。

當觸發事件時，當時的偵聽器將接收到該事件。如果在觸發事件時將偵聽器添加到廣播流，則該偵聽器將不會接收當前正在觸發的事件。如果一個監聽器被取消，它會立即停止接收事件。監聽廣播流可被視為監聽新流，該流僅包含在 listen 調用發生時尚未發出的事件。例如，first getter 偵聽流，然後返回偵聽器接收到的第一個事件。這不一定是流發出的第一個，而是廣播流的 remaining 事件中的第一個。

當"done" 事件被觸發時，訂閱者在接收到事件之前被取消訂閱。發送事件後，流沒有訂閱者。在此之後允許向廣播流添加新訂閱者，但他們隻會盡快收到新的 "done" 事件。

流訂閱始終尊重"pause" 請求。如有必要，他們需要緩衝他們的輸入，但通常，最好他們也可以簡單地請求他們的輸入暫停。

isBroadcast 的默認實現返回 false。從Stream 繼承的廣播流必須覆蓋isBroadcast 以返回true，如果它想發出信號表明它的行為類似於廣播流。

實施者

CustomStream ＞ ElementStream ＞ HttpClientResponse ＞ HttpRequest ＞ HttpServer ＞ RawDatagramSocket ＞ RawSecureServerSocket ＞ RawServerSocket ＞ RawSocket ＞ ReceivePort ＞ SecureServerSocket ＞ ServerSocket ＞ Socket ＞ Stdin ＞ StreamView ＞ WebSocket