From 52f923c360845d7262773a7988124e91848237c3 Mon Sep 17 00:00:00 2001 From: Valentin Vignal <32538273+ValentinVignal@users.noreply.github.com> Date: Tue, 13 Feb 2024 02:25:57 +0800 Subject: [PATCH] Add documentation for best practices for `StreamBuilder` like `FutureBuilder` (#143295) Fixes https://github.com/flutter/flutter/issues/142189 --- packages/flutter/lib/src/widgets/async.dart | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/packages/flutter/lib/src/widgets/async.dart b/packages/flutter/lib/src/widgets/async.dart index cf4e0ca697..27d33a4f1f 100644 --- a/packages/flutter/lib/src/widgets/async.dart +++ b/packages/flutter/lib/src/widgets/async.dart @@ -321,6 +321,20 @@ typedef AsyncWidgetBuilder = Widget Function(BuildContext context, AsyncSnaps /// /// {@youtube 560 315 https://www.youtube.com/watch?v=MkKEWHfy99Y} /// +/// ## Managing the stream +/// +/// The [stream] must have been obtained earlier, e.g. during [State.initState], +/// [State.didUpdateWidget], or [State.didChangeDependencies]. It must not be +/// created during the [State.build] or [StatelessWidget.build] method call when +/// constructing the [StreamBuilder]. If the [stream] is created at the same +/// time as the [StreamBuilder], then every time the [StreamBuilder]'s parent is +/// rebuilt, the asynchronous task will be restarted. +/// +/// A general guideline is to assume that every `build` method could get called +/// every frame, and to treat omitted calls as an optimization. +/// +/// ## Timing +/// /// Widget rebuilding is scheduled by each interaction, using [State.setState], /// but is otherwise decoupled from the timing of the stream. The [builder] /// is called at the discretion of the Flutter pipeline, and will thus receive a