Flutter笔记：聊一聊Flutter中委托的设计方法

GridView({
    super.key,
    super.scrollDirection,
    super.reverse,
    super.controller,
    super.primary,
    super.physics,
    super.shrinkWrap,
    super.padding,
    required this.gridDelegate,
    bool addAutomaticKeepAlives = true,
    bool addRepaintBoundaries = true,
    bool addSemanticIndexes = true,
    super.cacheExtent,
    List<Widget> children = const <Widget>[],
    int? semanticChildCount,
    super.dragStartBehavior,
    super.clipBehavior,
    super.keyboardDismissBehavior,
    super.restorationId,
  }) : childrenDelegate = SliverChildListDelegate(
         children,
         addAutomaticKeepAlives: addAutomaticKeepAlives,
         addRepaintBoundaries: addRepaintBoundaries,
         addSemanticIndexes: addSemanticIndexes,
       ),
       super(
         semanticChildCount: semanticChildCount ?? children.length,
       );

/// 创建一个可滚动的，按需创建的二维部件数组。
  ///
  /// 对于具有大量（或无限）子部件的网格视图，此构造函数是合适的，因为构建器只会为实际可见的子部件调用。
  ///
  /// 提供非空的 `itemCount` 可以提高 [GridView] 估计最大滚动范围的能力。
  ///
  /// `itemBuilder` 只会被调用大于等于零且小于 `itemCount` 的索引。
  ///
  /// {@macro flutter.widgets.ListView.builder.itemBuilder}
  ///
  /// {@macro flutter.widgets.PageView.findChildIndexCallback}
  ///
  /// [gridDelegate] 参数是必需的。
  ///
  /// `addAutomaticKeepAlives` 参数对应于 [SliverChildBuilderDelegate.addAutomaticKeepAlives] 属性。
  /// `addRepaintBoundaries` 参数对应于 [SliverChildBuilderDelegate.addRepaintBoundaries] 属性。
  /// `addSemanticIndexes` 参数对应于 [SliverChildBuilderDelegate.addSemanticIndexes] 属性。
  GridView.builder({
    super.key,
    super.scrollDirection,
    super.reverse,
    super.controller,
    super.primary,
    super.physics,
    super.shrinkWrap,
    super.padding,
    required this.gridDelegate,
    required NullableIndexedWidgetBuilder itemBuilder,
    ChildIndexGetter? findChildIndexCallback,
    int? itemCount,
    bool addAutomaticKeepAlives = true,
    bool addRepaintBoundaries = true,
    bool addSemanticIndexes = true,
    super.cacheExtent,
    int? semanticChildCount,
    super.dragStartBehavior,
    super.keyboardDismissBehavior,
    super.restorationId,
    super.clipBehavior,
  }) : childrenDelegate = SliverChildBuilderDelegate(
         itemBuilder,
         findChildIndexCallback: findChildIndexCallback,
         childCount: itemCount,
         addAutomaticKeepAlives: addAutomaticKeepAlives,
         addRepaintBoundaries: addRepaintBoundaries,
         addSemanticIndexes: addSemanticIndexes,
       ),
       super(
         semanticChildCount: semanticChildCount ?? itemCount,
       );

/// 使用自定义 [SliverGridDelegate] 和自定义 [SliverChildDelegate] 创建一个可滚动的二维部件数组。
  ///
  /// 要使用 [IndexedWidgetBuilder] 回调来构建子部件，可以使用 [SliverChildBuilderDelegate] 或使用 [GridView.builder] 构造函数。
  ///
  /// [gridDelegate] 和 [childrenDelegate] 参数不能为空。
  const GridView.custom({
    super.key,
    super.scrollDirection,
    super.reverse,
    super.controller,
    super.primary,
    super.physics,
    super.shrinkWrap,
    super.padding,
    required this.gridDelegate,
    required this.childrenDelegate,
    super.cacheExtent,
    super.semanticChildCount,
    super.dragStartBehavior,
    super.keyboardDismissBehavior,
    super.restorationId,
    super.clipBehavior,
  });

/// 创建一个可滚动的，二维部件数组，交叉轴上有固定数量的格子。
  ///
  /// 使用 [SliverGridDelegateWithFixedCrossAxisCount] 作为 [gridDelegate]。
  ///
  /// `addAutomaticKeepAlives` 参数对应于 [SliverChildListDelegate.addAutomaticKeepAlives] 属性。
  /// `addRepaintBoundaries` 参数对应于 [SliverChildListDelegate.addRepaintBoundaries] 属性。两者都不能为空。
  ///
  /// 另请参阅：
  ///
  ///  * [SliverGrid.count]，[SliverGrid] 的等效构造函数。
  GridView.count({
    super.key,
    super.scrollDirection,
    super.reverse,
    super.controller,
    super.primary,
    super.physics,
    super.shrinkWrap,
    super.padding,
    required int crossAxisCount,
    double mainAxisSpacing = 0.0,
    double crossAxisSpacing = 0.0,
    double childAspectRatio = 1.0,
    bool addAutomaticKeepAlives = true,
    bool addRepaintBoundaries = true,
    bool addSemanticIndexes = true,
    super.cacheExtent,
    List<Widget> children = const <Widget>[],
    int? semanticChildCount,
    super.dragStartBehavior,
    super.keyboardDismissBehavior,
    super.restorationId,
    super.clipBehavior,
  }) : gridDelegate = SliverGridDelegateWithFixedCrossAxisCount(
         crossAxisCount: crossAxisCount,
         mainAxisSpacing: mainAxisSpacing,
         crossAxisSpacing: crossAxisSpacing,
         childAspectRatio: childAspectRatio,
       ),
       childrenDelegate = SliverChildListDelegate(
         children,
         addAutomaticKeepAlives: addAutomaticKeepAlives,
         addRepaintBoundaries: addRepaintBoundaries,
         addSemanticIndexes: addSemanticIndexes,
       ),
       super(
         semanticChildCount: semanticChildCount ?? children.length,
       );

/// 创建一个可滚动的，二维部件数组，每个格子在交叉轴上都有最大的范围。
  ///
  /// 使用 [SliverGridDelegateWithMaxCrossAxisExtent] 作为 [gridDelegate]。
  ///
  /// `addAutomaticKeepAlives` 参数对应于 [SliverChildListDelegate.addAutomaticKeepAlives] 属性。
  /// `addRepaintBoundaries` 参数对应于 [SliverChildListDelegate.addRepaintBoundaries] 属性。两者都不能为空。
  ///
  /// 另请参阅：
  ///
  ///  * [SliverGrid.extent]，[SliverGrid] 的等效构造函数。
  GridView.extent({
    super.key,
    super.scrollDirection,
    super.reverse,
    super.controller,
    super.primary,
    super.physics,
    super.shrinkWrap,
    super.padding,
    required double maxCrossAxisExtent,
    double mainAxisSpacing = 0.0,
    double crossAxisSpacing = 0.0,
    double childAspectRatio = 1.0,
    bool addAutomaticKeepAlives = true,
    bool addRepaintBoundaries = true,
    bool addSemanticIndexes = true,
    super.cacheExtent,
    List<Widget> children = const <Widget>[],
    int? semanticChildCount,
    super.dragStartBehavior,
    super.keyboardDismissBehavior,
    super.restorationId,
    super.clipBehavior,
  }) : gridDelegate = SliverGridDelegateWithMaxCrossAxisExtent(
         maxCrossAxisExtent: maxCrossAxisExtent,
         mainAxisSpacing: mainAxisSpacing,
         crossAxisSpacing: crossAxisSpacing,
         childAspectRatio: childAspectRatio,
       ),
       childrenDelegate = SliverChildListDelegate(
         children,
         addAutomaticKeepAlives: addAutomaticKeepAlives,
         addRepaintBoundaries: addRepaintBoundaries,
         addSemanticIndexes: addSemanticIndexes,
       ),
       super(
         semanticChildCount: semanticChildCount ?? children.length,
       );

const SliverGrid({
  super.key,
  required super.delegate,
  required this.gridDelegate,
});

/// 一个委托，控制 [GridView] 中子部件的布局。
  ///
  /// [GridView]，[GridView.builder] 和 [GridView.custom] 构造函数允许你明确指定这个委托。其他构造函数隐式创建一个 [gridDelegate]。
  final SliverGridDelegate gridDelegate;

/// 一个委托，为 [GridView] 提供子部件。
  ///
  /// [GridView.custom] 构造函数允许你明确指定这个委托。其他构造函数创建一个包装给定子部件列表的 [childrenDelegate]。
  final SliverChildDelegate childrenDelegate;

@override
  Widget buildChildLayout(BuildContext context) {
    return SliverGrid(
      delegate: childrenDelegate, // SliverChildDelegate 对象，它决定了如何创建和布局子项。
      gridDelegate: gridDelegate, // SliverGridDelegate 对象，它决定了网格的布局。
    );
  }

class MyListView {
  final ItemBuilder itemBuilder;
  final ItemLayoutDelegate itemLayoutDelegate;
  MyListView({required this.itemBuilder, required this.itemLayoutDelegate});
  // ...
}
typedef ItemBuilder = Widget Function(BuildContext context, int index);
abstract class ItemLayoutDelegate {
  double getItemSize(int index);
  // ...
}

/// 为 slivers 提供子组件的委托。
///
/// 许多 slivers 会懒加载它们的 box 子组件，以避免创建比视口可见的子组件更多。
/// 它们不是通过显式的 [List] 接收子组件，而是通过 [SliverChildDelegate] 接收子组件。
///
/// 子类化 [SliverChildDelegate] 是不常见的。相反，考虑使用已有的子类，
/// 它们提供了适配器到构建器回调或显式子列表。
///
/// {@template flutter.widgets.SliverChildDelegate.lifecycle}
/// ## 子元素的生命周期
///
/// ### 创建
///
/// 在布局列表时，可见子组件的元素、状态和渲染对象将基于现有组件（如 [SliverChildListDelegate] 的情况）
/// 或懒加载提供的组件（如 [SliverChildBuilderDelegate] 的情况）懒加载创建。
///
/// ### 销毁
///
/// 当一个子组件滚动出视图时，关联的元素子树、状态和渲染对象被销毁。
/// 当它滚动回来时，一个新的子组件在 sliver 的同一位置将懒加载重新创建，
/// 同时新的元素、状态和渲染对象也会被创建。
///
/// ### 减轻销毁
///
/// 为了在子元素滚动进出视图时保留状态，有以下可能的选项：
///
///  * 将非琐碎的驱动 UI 状态的业务逻辑的所有权移出 sliver 子组件子树。
///    例如，如果列表包含帖子，它们的点赞数来自缓存的网络响应，
///    将帖子列表和点赞数存储在列表外的数据模型中。让 sliver 子组件 UI 子树
///    能够从真实源模型对象轻松重新创建。在子组件子树中使用 [StatefulWidget] 
///    仅存储瞬时 UI 状态。
///
///  * 让 [KeepAlive] 成为需要保留的 sliver 子组件子树的根组件。
///    [KeepAlive] 组件将子组件子树的顶部渲染对象子组件标记为 keepalive。
///    当关联的顶部渲染对象滚动出视图时，sliver 将子组件的渲染对象（以及相应的元素和状态）
///    保留在缓存列表中，而不是销毁它们。当滚动回视图时，渲染对象会按原样重绘
///    （如果在此期间没有被标记为 dirty）。
///
///    这只有在 [SliverChildDelegate] 的子类不通过 `addAutomaticKeepAlives` 和
///    `addRepaintBoundaries` 将其他组件（如 [AutomaticKeepAlive] 和 [RepaintBoundary]）包装到
///    子组件子树中时才有效。
///
///  * 使用 [AutomaticKeepAlive] 组件（默认插入到 [SliverChildListDelegate] 或 [SliverChildListDelegate] 中）。
///    [AutomaticKeepAlive] 允许后代组件控制子树是否真的保持活动状态。这种行为与
///    [KeepAlive] 形成对比，后者将无条件地保持子树活动状态。
///
///    例如，[EditableText] 组件在其文本字段有输入焦点时，会发出信号让其 sliver 
///    组件在其文本字段有输入焦点时，会发出信号让其 sliver 子元素子树保持活动状态。
///    如果它没有焦点，且没有其他后代通过 [KeepAliveNotification] 发出保持活动的信号，
///    当滚动离开视图时，sliver 子元素子树将被销毁。
///
///    [AutomaticKeepAlive] 的后代通常通过使用 [AutomaticKeepAliveClientMixin]，
///    然后实现 [AutomaticKeepAliveClientMixin.wantKeepAlive] getter 和调用
///    [AutomaticKeepAliveClientMixin.updateKeepAlive] 来发出保持活动的信号。
///
/// ## 在 [Viewport] 中使用多个委托
///
/// 如果在单个滚动视图中使用多个委托，每个委托的第一个子组件总是会被布局，
/// 即使它超出了当前可视区域。这是因为至少需要一个子组件来为整个滚动视图
/// [estimateMaxScrollOffset]，因为它使用当前构建的子组件来估计剩余子组件的范围。
/// {@endtemplate}
///
/// 另请参阅：
///
///  * [SliverChildBuilderDelegate]，这是一个使用构建器回调来构造子组件的委托。
///  * [SliverChildListDelegate]，这是一个具有显式子列表的委托。
abstract class SliverChildDelegate {
  /// 抽象的 const 构造函数。这个构造函数使子类能够提供 const 构造函数，
  /// 以便它们可以在 const 表达式中使用。
  const SliverChildDelegate();
  /// 返回给定索引的子组件。
  ///
  /// 如果被要求构建一个大于存在的索引的组件，应返回 null。如果这返回 null，
  /// [estimatedChildCount] 必须随后返回一个精确的非 null 值
  /// （然后用于实现 [RenderSliverBoxChildManager.childCount]）。
  ///
  /// 子类通常覆盖此函数，并将其子组件包装在 [AutomaticKeepAlive]、[IndexedSemantics] 和
  /// [RepaintBoundary] 组件中。
  ///
  /// 此方法返回的值被缓存。要表示组件已更改，必须提供一个新的委托，
  /// 并且新委托的 [shouldRebuild] 方法必须返回 true。
  Widget? build(BuildContext context, int index);
  /// 返回此委托将构建的子组件数量的估计值。
  ///
  /// 用于估计最大滚动偏移量，如果 [estimateMaxScrollOffset] 返回 null。
  ///
  /// 如果有无限多的子组件，或者估计子组件数量太困难，返回 null。
  ///
  /// 一旦 [build] 返回 null，这必须返回一个精确的数字，
  /// 因为它用于实现 [RenderSliverBoxChildManager.childCount]。
  int? get estimatedChildCount => null;
  /// 返回所有子组件的最大滚动范围的估计值。
  ///
  /// 如果子类有关于其最大滚动范围的额外信息，应覆盖此函数。
  ///
  /// 默认实现返回 null，这会导致调用者从给定参数中推断最大滚动偏移量。
  double? estimateMaxScrollOffset(
    int firstIndex,
    int lastIndex,
    double leadingScrollOffset,
    double trailingScrollOffset,
  ) => null;
  /// 在布局结束时调用，表示现在布局已完成。
  ///
  /// `firstIndex` 参数是在当前布局中包含的第一个子组件的索引。
  /// `lastIndex` 参数是在当前布局中包含的最后一个子组件的索引。
  ///
  /// 对于希望跟踪哪些子组件包含在底层渲染树中的子类很有用。
  void didFinishLayout(int firstIndex, int lastIndex) { }
  /// 每当向 sliver 提供子委托类的新实例时调用。
  ///
  /// 如果新实例代表的信息与旧实例不同，则该方法应返回 true，否则应返回 false。
  ///
  /// 如果该方法返回 false，则可能会优化掉 [build] 调用。
  bool shouldRebuild(covariant SliverChildDelegate oldDelegate);
  /// 查找与关联键的子元素的索引。
  ///
  /// 在 [SliverMultiBoxAdaptorElement] 的 `performRebuild` 中调用，
  /// 以检查子组件是否移动到了不同的位置。它应返回与关联键的子元素的索引，如果未找到，返回 null。
  ///
  /// 如果未提供，当从子组件构建器返回的子组件顺序改变时，
  /// 子组件可能不会映射到其现有的 [RenderObject]。这可能导致状态丢失。
  int? findIndexByKey(Key key) => null;
  @override
  String toString() {
    final List<String> description = <String>[];
    debugFillDescription(description);
    return '${describeIdentity(this)}(${description.join(", ")})';
  }
   /// 为 [toString] 使用，向给定的描述中添加额外的信息。
  @protected
  @mustCallSuper
  void debugFillDescription(List<String> description) {
    try {
      final int? children = estimatedChildCount;
      if (children != null) {
        description.add('estimated child count: $children');
      }
    } catch (e) {
      // 异常被转发到组件检查器。
      description.add('estimated child count: EXCEPTION (${e.runtimeType})');
    }
  }
}

/// 使用明确列表为 slivers 提供子组件的委托。
///
/// 许多 slivers 会懒加载它们的 box 子组件，以避免创建比视口可见的子组件更多。
/// 这个委托使用一个明确的列表来提供子组件，这种方式很方便，但减少了懒加载子组件的优势。
///
/// 通常来说，预先构建所有的组件并不高效。更好的方式是使用 [SliverChildBuilderDelegate] 
/// 或直接继承 [SliverChildDelegate] 来创建一个可以按需构建组件的委托。
///
/// 这个类适用于以下情况：子组件列表在很早之前就已知（理想情况下，子组件本身就是编译时常量），
/// 因此每次创建委托时都不需要构建子组件，或者列表很小，很可能始终可见（因此没有必要按需构建）。
/// 例如，对话框的主体可能符合这两种情况。
///
/// 如果 [addAutomaticKeepAlives] 为 true（默认值），则给定 [children] 列表中的组件会自动包装在
/// [AutomaticKeepAlive] 组件中。如果 [addRepaintBoundaries] 为 true（也是默认值），则会包装在
/// [RepaintBoundary] 组件中。
///
/// ## 辅助功能
///
/// [CustomScrollView] 要求其语义子组件使用 [IndexedSemantics] 进行注释。
/// 默认情况下，委托会将 `addSemanticIndexes` 参数设置为 true 来完成这项工作。
///
/// 如果在单个滚动视图中使用了多个委托，那么默认情况下索引将不正确。
/// 可以使用 `semanticIndexOffset` 来偏移每个委托的语义索引，使索引单调递增。
/// 例如，如果滚动视图包含两个委托，第一个委托有 10 个子组件贡献语义，那么第二个委托应该将其子组件偏移 10。
///
/// 在某些情况下，只有子组件的一个子集应该用语义索引进行注释。
/// 例如，在 [ListView.separated()] 中，分隔符没有与之关联的索引。
/// 这是通过提供一个 `semanticIndexCallback` 来完成的，它为分隔符索引返回 null，
/// 并将非分隔符索引向下取整到一半。
///
/// 参见 [SliverChildBuilderDelegate]，了解使用 `semanticIndexOffset` 和 `semanticIndexCallback` 的示例代码。
///
/// 另请参见：
///
///  * [SliverChildBuilderDelegate]，这是一个使用构建器回调来构建子组件的委托。
class SliverChildListDelegate extends SliverChildDelegate {
  /// 使用给定列表为 slivers 提供子组件的委托。
  ///
  /// [children]、[addAutomaticKeepAlives]、[addRepaintBoundaries]、
  /// [addSemanticIndexes] 和 [semanticIndexCallback] 参数必须非 null。
  ///
  /// 如果子组件的顺序永远不会改变，考虑使用常量 [SliverChildListDelegate.fixed] 构造函数。
  SliverChildListDelegate(
    this.children, {
    this.addAutomaticKeepAlives = true,
    this.addRepaintBoundaries = true,
    this.addSemanticIndexes = true,
    this.semanticIndexCallback = _kDefaultSemanticIndexCallback,
    this.semanticIndexOffset = 0,
  }) : _keyToIndex = <Key?, int>{null: 0};
  /// 创建一个使用给定列表为 slivers 提供子组件的委托的常量版本。
  ///
  /// 如果子组件的顺序会改变，考虑使用常规 [SliverChildListDelegate] 构造函数。
  ///
  /// [children]、[addAutomaticKeepAlives]、[addRepaintBoundaries]、
  /// [addSemanticIndexes] 和 [semanticIndexCallback] 参数必须非 null。
  const SliverChildListDelegate.fixed(
    this.children, {
    this.addAutomaticKeepAlives = true,
    this.addRepaintBoundaries = true,
    this.addSemanticIndexes = true,
    this.semanticIndexCallback = _kDefaultSemanticIndexCallback,
    this.semanticIndexOffset = 0,
  }) : _keyToIndex = null;
  /// {@macro flutter.widgets.SliverChildBuilderDelegate.addAutomaticKeepAlives}
  final bool addAutomaticKeepAlives;
  /// {@macro flutter.widgets.SliverChildBuilderDelegate.addRepaintBoundaries}
  final bool addRepaintBoundaries;
  /// {@macro flutter.widgets.SliverChildBuilderDelegate.addSemanticIndexes}
  final bool addSemanticIndexes;
  /// {@macro flutter.widgets.SliverChildBuilderDelegate.semanticIndexOffset}
  final int semanticIndexOffset;
  /// {@macro flutter.widgets.SliverChildBuilderDelegate.semanticIndexCallback}
  final SemanticIndexCallback semanticIndexCallback;
  /// 要显示的组件。
  ///
  /// 如果这个列表将要被改变，通常最好在每个子组件上放一个 [Key]，
  /// 这样框架就可以匹配旧配置和新配置，并维护底层的渲染对象。
  ///
  /// 另外，在 Flutter 中，[Widget] 是不可变的，所以直接修改 [children]，
  /// 例如 `someWidget.children.add(...)` 或将原始列表值的引用传递给 [children] 参数，
  /// 将导致行为不正确。每次修改子组件列表时，都必须提供一个新的列表对象。
  ///
  /// 下面的代码纠正了上述问题。
  ///
  /// ```dart
  /// class SomeWidgetState extends State<SomeWidget> {
  ///   final List<Widget> _children = <Widget>[];
  ///
  ///   void someHandler() {
  ///     setState(() {
  ///       // 这里的 key 允许 Flutter 重用底层的渲染对象，即使子组件列表被重新创建。
  ///       _children.add(ChildWidget(key: UniqueKey()));
  ///     });
  ///   }
  ///
  ///   @override
  ///   Widget build(BuildContext context) {
  ///     // 由于 Widget 是不可变的，所以总是创建一个新的子组件列表。
  ///     return PageView(children: List<Widget>.of(_children));
  ///   }
  /// }
  /// ```
  final List<Widget> children;
  /// 用于缓存子组件的 key 到 index 查找的映射。
  ///
  /// 在 [_findChildIndex] 的懒加载过程中，_keyToIndex[null] 被用作当前索引。
  /// _keyToIndex 不应该用于查找 null key。
  final Map<Key?, int>? _keyToIndex;
  bool get _isConstantInstance => _keyToIndex == null;
  int? _findChildIndex(Key key) {
    if (_isConstantInstance) {
      return null;
    }
    // 懒加载填充 [_keyToIndex]。
    if (!_keyToIndex!.containsKey(key)) {
      int index = _keyToIndex![null]!;
      while (index < children.length) {
        final Widget child = children[index];
        if (child.key != null) {
          _keyToIndex![child.key] = index;
        }
        if (child.key == key) {
          // 记录当前索引以供下次函数调用。
          _keyToIndex![null] = index + 1;
          return index;
        }
        index += 1;
      }
      _keyToIndex![null] = index;
    } else {
      return _keyToIndex![key];
    }
    return null;
  }
  @override
  int? findIndexByKey(Key key) {
    final Key childKey;
    if (key is _SaltedValueKey) {
      final _SaltedValueKey saltedValueKey = key;
      childKey = saltedValueKey.value;
    } else {
      childKey = key;
    }
    return _findChildIndex(childKey);
  }
  @override
  Widget? build(BuildContext context, int index) {
    if (index < 0 || index >= children.length) {
      return null;
    }
    Widget child = children[index];
    final Key? key = child.key != null? _SaltedValueKey(child.key!) : null;
    if (addRepaintBoundaries) {
      child = RepaintBoundary(child: child);
    }
    if (addSemanticIndexes) {
      final int? semanticIndex = semanticIndexCallback(child, index);
      if (semanticIndex != null) {
        child = IndexedSemantics(index: semanticIndex + semanticIndexOffset, child: child);
      }
    }
    if (addAutomaticKeepAlives) {
      child = AutomaticKeepAlive(child: _SelectionKeepAlive(child: child));
    }
    return KeyedSubtree(key: key, child: child);
  }
  @override
  int? get estimatedChildCount => children.length;
  @override
  bool shouldRebuild(covariant SliverChildListDelegate oldDelegate) {
    return children != oldDelegate.children;
  }
}

/// 使用构建器回调为 slivers 提供子组件的委托。
///
/// 许多 slivers 会懒加载它们的 box 子组件，以避免创建比视口可见的子组件更多。
/// 这个委托使用 [NullableIndexedWidgetBuilder] 回调提供子组件，
/// 因此子组件甚至不需要在显示之前就构建。
///
/// 如果 [addAutomaticKeepAlives] 为 true（默认值），则构建器回调返回的组件会自动包装在
/// [AutomaticKeepAlive] 组件中。如果 [addRepaintBoundaries] 为 true（也是默认值），
/// 则会包装在 [RepaintBoundary] 组件中。
///
/// ## 辅助功能
///
/// [CustomScrollView] 要求其语义子组件使用 [IndexedSemantics] 进行注释。
/// 在默认的委托中，当 `addSemanticIndexes` 参数设置为 true 时，会自动完成此操作。
///
/// 如果在单个滚动视图中使用多个委托，则默认情况下索引将不正确。
/// `semanticIndexOffset` 可用于偏移每个委托的语义索引，使索引单调递增。
/// 例如，如果滚动视图包含两个委托，其中第一个有 10 个贡献语义的子组件，
/// 则第二个委托应将其子组件偏移 10。
///
/// {@tool snippet}
///
/// 此示例代码展示了如何使用 `semanticIndexOffset` 处理单个滚动视图中的多个委托。
///
/// ```dart
/// CustomScrollView(
///   semanticChildCount: 4,
///   slivers: <Widget>[
///     SliverGrid(
///       gridDelegate: _gridDelegate,
///       delegate: SliverChildBuilderDelegate(
///         (BuildContext context, int index) {
///            return const Text('...');
///          },
///          childCount: 2,
///        ),
///      ),
///     SliverGrid(
///       gridDelegate: _gridDelegate,
///       delegate: SliverChildBuilderDelegate(
///         (BuildContext context, int index) {
///            return const Text('...');
///          },
///          childCount: 2,
///          semanticIndexOffset: 2,
///        ),
///      ),
///   ],
/// )
/// ```
/// {@end-tool}
///
/// 在某些情况下，只有子组件的子集应使用语义索引进行注释。
/// 例如，在 [ListView.separated()] 中，分隔符没有与之关联的索引。
/// 这是通过提供一个 `semanticIndexCallback` 来完成的，它对分隔符索引返回 null，
/// 并将非分隔符索引减半。
///
/// {@tool snippet}
///
/// 此示例代码展示了如何使用 `semanticIndexCallback` 处理使用语义索引注释子节点的子集。
/// 在奇数索引处有一个 [Spacer] 组件，它不应该有语义索引。
///
/// ```dart
/// CustomScrollView(
///   semanticChildCount: 5,
///   slivers: <Widget>[
///     SliverGrid(
///       gridDelegate: _gridDelegate,
///       delegate: SliverChildBuilderDelegate(
///         (BuildContext context, int index) {
///            if (index.isEven) {
///              return const Text('...');
///            }
///            return const Spacer();
///          },
///          semanticIndexCallback: (Widget widget, int localIndex) {
///            if (localIndex.isEven) {
///              return localIndex ~/ 2;
///            }
///            return null;
///          },
///          childCount: 10,
///        ),
///      ),
///   ],
/// )
/// ```
/// {@end-tool}
///
/// 另请参阅：
///
///  * [SliverChildListDelegate]，这是一个具有显式子列表的委托。
///  * [IndexedSemantics]，这是手动使用语义索引注释子节点的示例。
class SliverChildBuilderDelegate extends SliverChildDelegate {
  /// 使用给定的构建器回调创建一个为 slivers 提供子组件的委托。
  ///
  /// [builder]、[addAutomaticKeepAlives]、[addRepaintBoundaries]、
  /// [addSemanticIndexes] 和 [semanticIndexCallback] 参数必须非 null。
  ///
  /// 如果 [builder] 返回子组件的顺序有变化，考虑提供一个 [findChildIndexCallback]。
  /// 这允许委托找到之前位于不同索引的子组件的新索引，以便将现有状态附加到新位置的 [Widget] 上。
  const SliverChildBuilderDelegate(
    this.builder, {
    this.findChildIndexCallback,
    this.childCount,
    this.addAutomaticKeepAlives = true,
    this.addRepaintBoundaries = true,
    this.addSemanticIndexes = true,
    this.semanticIndexCallback = _kDefaultSemanticIndexCallback,
    this.semanticIndexOffset = 0,
  });
  /// 用于为 sliver 构建子组件的回调。
  ///
  /// 只会为大于或等于零且小于 [childCount]（如果 [childCount] 非空）的索引调用。
  ///
  /// 如果被要求构建一个索引大于存在的索引的组件，应返回 null。
  ///
  /// 如果 [childCount] 为 null 并且 [builder] 总是提供零大小的组件（如 `Container()`
  /// 或 `SizedBox.shrink()`），可能会导致无限循环或内存耗尽。如果可能，提供非零大小的子组件，
  /// 从 [builder] 返回 null，或设置 [childCount]。
  ///
  /// 委托会将此构建器返回的子组件包装在 [RepaintBoundary] 组件中。
  final NullableIndexedWidgetBuilder builder;
  /// 此委托可以提供的子组件总数。
  ///
  /// 如果为 null，子组件的数量由 [builder] 返回 null 的最小索引确定。
  ///
  /// 如果 [childCount] 为 null 并且 [builder] 总是提供零大小的组件（如 `Container()`
  /// 或 `SizedBox.shrink()`），可能会导致无限循环或内存耗尽。如果可能，提供非零大小的子组件，
  /// 从 [builder] 返回 null，或设置 [childCount]。
  final int? childCount;
  /// {@template flutter.widgets.SliverChildBuilderDelegate.addAutomaticKeepAlives}
  /// 是否将每个子组件包装在 [AutomaticKeepAlive] 中。
  ///
  /// 通常，懒加载列表中的子组件会被包装在 [AutomaticKeepAlive] 组件中，
  /// 以便子组件可以使用 [KeepAliveNotification] 在它们否则会被滚动出屏幕时保留其状态。
  ///
  /// 如果子组件将手动维护其 [KeepAlive] 状态，必须禁用此功能（和 [addRepaintBoundaries]）。
  /// 如果提前知道没有任何子组件会尝试保持自己活动，禁用此功能可能更有效。
  ///
  /// 默认为 true。
  /// {@endtemplate}
  ///
  /// Defaults to true.
  /// {@endtemplate}
  final bool addAutomaticKeepAlives;
    /// {@template flutter.widgets.SliverChildBuilderDelegate.addRepaintBoundaries}
  /// 是否将每个子组件包装在 [RepaintBoundary] 中。
  ///
  /// 通常，滚动容器中的子组件被包装在重绘边界中，以便在列表滚动时不需要重绘。
  /// 如果子组件易于重绘（例如，纯色块或短文本片段），则不添加重绘边界并始终在滚动期间重绘子组件可能更有效。
  ///
  /// 默认为 true。
  /// {@endtemplate}
  final bool addRepaintBoundaries;
  /// {@template flutter.widgets.SliverChildBuilderDelegate.addSemanticIndexes}
  /// 是否将每个子组件包装在 [IndexedSemantics] 中。
  ///
  /// 通常，滚动容器中的子组件必须使用语义索引进行注释，以生成正确的辅助功能通知。
  /// 只有当索引已由 [IndexedSemantics] 组件提供时，才应将此设置为 false。
  ///
  /// 默认为 true。
  ///
  /// 另请参阅：
  ///
  ///  * [IndexedSemantics]，了解如何手动提供语义索引的说明。
  /// {@endtemplate}
  final bool addSemanticIndexes;
  /// {@template flutter.widgets.SliverChildBuilderDelegate.semanticIndexOffset}
  /// 添加到此组件生成的语义索引的初始偏移量。
  ///
  /// 默认为零。
  /// {@endtemplate}
  final int semanticIndexOffset;
  /// {@template flutter.widgets.SliverChildBuilderDelegate.semanticIndexCallback}
  /// 当 [addSemanticIndexes] 为 true 时使用的 [SemanticIndexCallback]。
  ///
  /// 默认为为每个组件提供索引。
  /// {@endtemplate}
  final SemanticIndexCallback semanticIndexCallback;
  /// {@template flutter.widgets.SliverChildBuilderDelegate.findChildIndexCallback}
  /// 在重新排序时，根据其键找到子组件的新索引的回调。
  ///
  /// 如果未提供，当从子组件构建器返回的子组件顺序改变时，
  /// 子组件可能不会映射到其现有的 [RenderObject]。这可能导致状态丢失。
  ///
  /// 此回调应接受一个输入 [Key]，并返回与该键关联的子元素的索引，如果未找到则返回 null。
  /// {@endtemplate}
  final ChildIndexGetter? findChildIndexCallback;
  @override
  int? findIndexByKey(Key key) {
    if (findChildIndexCallback == null) {
      return null;
    }
    final Key childKey;
    if (key is _SaltedValueKey) {
      final _SaltedValueKey saltedValueKey = key;
      childKey = saltedValueKey.value;
    } else {
      childKey = key;
    }
    return findChildIndexCallback!(childKey);
  }
  @override
  @pragma('vm:notify-debugger-on-exception')
  Widget? build(BuildContext context, int index) {
    if (index < 0 || (childCount != null && index >= childCount!)) {
      return null;
    }
    Widget? child;
    try {
      child = builder(context, index);
    } catch (exception, stackTrace) {
      child = _createErrorWidget(exception, stackTrace);
    }
    if (child == null) {
      return null;
    }
    final Key? key = child.key != null ? _SaltedValueKey(child.key!) : null;
    if (addRepaintBoundaries) {
      child = RepaintBoundary(child: child);
    }
    if (addSemanticIndexes) {
      final int? semanticIndex = semanticIndexCallback(child, index);
      if (semanticIndex != null) {
        child = IndexedSemantics(index: semanticIndex + semanticIndexOffset, child: child);
      }
    }
    if (addAutomaticKeepAlives) {
      child = AutomaticKeepAlive(child: _SelectionKeepAlive(child: child));
    }
    return KeyedSubtree(key: key, child: child);
  }
  @override
  int? get estimatedChildCount => childCount;
  @override
  bool shouldRebuild(covariant SliverChildBuilderDelegate oldDelegate) => true;
}