ListView.separated constructor

ListView.separated({
  1. Key? key,
  2. Axis scrollDirection = Axis.vertical,
  3. bool reverse = false,
  4. ScrollController? controller,
  5. bool? primary,
  6. ScrollPhysics? physics,
  7. bool shrinkWrap = false,
  8. EdgeInsetsGeometry? padding,
  9. required NullableIndexedWidgetBuilder itemBuilder,
  10. @Deprecated('Use findItemIndexCallback instead. ' 'findChildIndexCallback returns child indices (which include separators), ' 'while findItemIndexCallback returns item indices (which do not). ' 'If you were multiplying results by 2 to account for separators, ' 'you can remove that workaround when migrating to findItemIndexCallback. ' 'This feature was deprecated after v3.37.0-1.0.pre.') ChildIndexGetter? findChildIndexCallback,
  11. ChildIndexGetter? findItemIndexCallback,
  12. required IndexedWidgetBuilder separatorBuilder,
  13. required int itemCount,
  14. bool addAutomaticKeepAlives = true,
  15. bool addRepaintBoundaries = true,
  16. bool addSemanticIndexes = true,
  17. double? cacheExtent,
  18. DragStartBehavior dragStartBehavior = DragStartBehavior.start,
  19. ScrollViewKeyboardDismissBehavior? keyboardDismissBehavior,
  20. String? restorationId,
  21. Clip clipBehavior = Clip.hardEdge,
  22. HitTestBehavior hitTestBehavior = HitTestBehavior.opaque,
})

Creates a fixed-length scrollable linear array of list "items" separated by list item "separators".

This constructor is appropriate for list views with a large number of item and separator children because the builders are only called for the children that are actually visible.

The itemBuilder callback will be called with indices greater than or equal to zero and less than itemCount.

Separators only appear between list items: separator 0 appears after item 0 and the last separator appears before the last item.

The separatorBuilder callback will be called with indices greater than or equal to zero and less than itemCount - 1.

The itemBuilder and separatorBuilder callbacks should always actually create widget instances when called. Avoid using a builder that returns a previously-constructed widget; if the list view's children are created in advance, or all at once when the ListView itself is created, it is more efficient to use the ListView constructor.

It is legal for itemBuilder to return null. If it does, the scroll view will stop calling itemBuilder, even if it has yet to reach itemCount. By returning null, the ScrollPosition.maxScrollExtent will not be accurate unless the user has reached the end of the ScrollView. This can also cause the Scrollbar to grow as the user scrolls.

For more accurate ScrollMetrics, consider specifying itemCount.

The findChildIndexCallback corresponds to the SliverChildBuilderDelegate.findChildIndexCallback property. If null, a child widget may not map to its existing RenderObject when the order of children returned from the children builder changes. This may result in state-loss. This callback needs to be implemented if the order of the children may change at a later time.

The findItemIndexCallback returns item indices (excluding separators), unlike the deprecated findChildIndexCallback which returns child indices (including both items and separators).

For example, in a list with 3 items and 2 separators:

  • Item indices: 0, 1, 2
  • Child indices: 0 (item), 1 (separator), 2 (item), 3 (separator), 4 (item)

This callback should be implemented if the order of items may change at a later time. If null, reordering items may result in state-loss as widgets may not map to their existing RenderObjects.

This example shows how to create ListView whose ListTile list items are separated by Dividers.
link 
ListView.separated(
  itemCount: 25,
  separatorBuilder: (BuildContext context, int index) => const Divider(),
  itemBuilder: (BuildContext context, int index) {
    return ListTile(
      title: Text('item $index'),
    );
  },
)

The addAutomaticKeepAlives argument corresponds to the SliverChildBuilderDelegate.addAutomaticKeepAlives property. The addRepaintBoundaries argument corresponds to the SliverChildBuilderDelegate.addRepaintBoundaries property. The addSemanticIndexes argument corresponds to the SliverChildBuilderDelegate.addSemanticIndexes property. None may be null.

Implementation

ListView.separated({
  super.key,
  super.scrollDirection,
  super.reverse,
  super.controller,
  super.primary,
  super.physics,
  super.shrinkWrap,
  super.padding,
  required NullableIndexedWidgetBuilder itemBuilder,
  @Deprecated(
    'Use findItemIndexCallback instead. '
    'findChildIndexCallback returns child indices (which include separators), '
    'while findItemIndexCallback returns item indices (which do not). '
    'If you were multiplying results by 2 to account for separators, '
    'you can remove that workaround when migrating to findItemIndexCallback. '
    'This feature was deprecated after v3.37.0-1.0.pre.',
  )
  ChildIndexGetter? findChildIndexCallback,
  ChildIndexGetter? findItemIndexCallback,
  required IndexedWidgetBuilder separatorBuilder,
  required int itemCount,
  bool addAutomaticKeepAlives = true,
  bool addRepaintBoundaries = true,
  bool addSemanticIndexes = true,
  super.cacheExtent,
  super.dragStartBehavior,
  super.keyboardDismissBehavior,
  super.restorationId,
  super.clipBehavior,
  super.hitTestBehavior,
}) : assert(itemCount >= 0),
     assert(
       findItemIndexCallback == null || findChildIndexCallback == null,
       'Cannot provide both findItemIndexCallback and findChildIndexCallback. '
       'Use findItemIndexCallback as findChildIndexCallback is deprecated.',
     ),
     itemExtent = null,
     itemExtentBuilder = null,
     prototypeItem = null,
     childrenDelegate = SliverChildBuilderDelegate(
       (BuildContext context, int index) {
         final int itemIndex = index ~/ 2;
         if (index.isEven) {
           return itemBuilder(context, itemIndex);
         }
         return separatorBuilder(context, itemIndex);
       },
       findChildIndexCallback: findItemIndexCallback != null
           ? (Key key) {
               final int? itemIndex = findItemIndexCallback(key);
               return itemIndex == null ? null : itemIndex * 2;
             }
           : findChildIndexCallback,
       childCount: _computeActualChildCount(itemCount),
       addAutomaticKeepAlives: addAutomaticKeepAlives,
       addRepaintBoundaries: addRepaintBoundaries,
       addSemanticIndexes: addSemanticIndexes,
       semanticIndexCallback: (Widget widget, int index) {
         return index.isEven ? index ~/ 2 : null;
       },
     ),
     super(semanticChildCount: itemCount);