CustomScrollView class Null safety

A ScrollView that creates custom scroll effects using slivers.

A CustomScrollView lets you supply slivers directly to create various scrolling effects, such as lists, grids, and expanding headers. For example, to create a scroll view that contains an expanding app bar followed by a list and a grid, use a list of three slivers: SliverAppBar, SliverList, and SliverGrid.

Widgets in these slivers must produce RenderSliver objects.

To control the initial scroll offset of the scroll view, provide a controller with its ScrollController.initialScrollOffset property set.

This sample code shows a scroll view that contains a flexible pinned app bar, a grid, and an infinite list.

CustomScrollView(
  slivers: <Widget>[
    const SliverAppBar(
      pinned: true,
      expandedHeight: 250.0,
      flexibleSpace: FlexibleSpaceBar(
        title: Text('Demo'),
      ),
    ),
    SliverGrid(
      gridDelegate: const SliverGridDelegateWithMaxCrossAxisExtent(
        maxCrossAxisExtent: 200.0,
        mainAxisSpacing: 10.0,
        crossAxisSpacing: 10.0,
        childAspectRatio: 4.0,
      ),
      delegate: SliverChildBuilderDelegate(
        (BuildContext context, int index) {
          return Container(
            alignment: Alignment.center,
            color: Colors.teal[100 * (index % 9)],
            child: Text('Grid Item $index'),
          );
        },
        childCount: 20,
      ),
    ),
    SliverFixedExtentList(
      itemExtent: 50.0,
      delegate: SliverChildBuilderDelegate(
        (BuildContext context, int index) {
          return Container(
            alignment: Alignment.center,
            color: Colors.lightBlue[100 * (index % 9)],
            child: Text('List Item $index'),
          );
        },
      ),
    ),
  ],
)

By default, if items are inserted at the "top" of a scrolling container like ListView or CustomScrollView, the top item and all of the items below it are scrolled downwards. In some applications, it's preferable to have the top of the list just grow upwards, without changing the scroll position. This example demonstrates how to do that with a CustomScrollView with two SliverList children, and the CustomScrollView.center set to the key of the bottom SliverList. The top one SliverList will grow upwards, and the bottom SliverList will grow downwards.

To create a local project with this code sample, run:
flutter create --sample=widgets.CustomScrollView.2 mysample

Accessibility

A CustomScrollView can allow Talkback/VoiceOver to make announcements to the user when the scroll state changes. For example, on Android an announcement might be read as "showing items 1 to 10 of 23". To produce this announcement, the scroll view needs three pieces of information:

The first visible child index.
The total number of children.
The total number of visible children.

The last value can be computed exactly by the framework, however the first two must be provided. Most of the higher-level scrollable widgets provide this information automatically. For example, ListView provides each child widget with a semantic index automatically and sets the semantic child count to the length of the list.

To determine visible indexes, the scroll view needs a way to associate the generated semantics of each scrollable item with a semantic index. This can be done by wrapping the child widgets in an IndexedSemantics.

This semantic index is not necessarily the same as the index of the widget in the scrollable, because some widgets may not contribute semantic information. Consider a ListView.separated: every other widget is a divider with no semantic information. In this case, only odd numbered widgets have a semantic index (equal to the index ~/ 2). Furthermore, the total number of children in this example would be half the number of widgets. (The ListView.separated constructor handles this automatically; this is only used here as an example.)

The total number of visible children can be provided by the constructor parameter semanticChildCount. This should always be the same as the number of widgets wrapped in IndexedSemantics.

Constructors

CustomScrollView({Key? key, Axis scrollDirection = Axis.vertical, bool reverse = false, ScrollController? controller, bool? primary, ScrollPhysics? physics, ScrollBehavior? scrollBehavior, bool shrinkWrap = false, Key? center, double anchor = 0.0, double? cacheExtent, List<Widget> slivers = const <Widget>[], int? semanticChildCount, DragStartBehavior dragStartBehavior = DragStartBehavior.start, ScrollViewKeyboardDismissBehavior keyboardDismissBehavior = ScrollViewKeyboardDismissBehavior.manual, String? restorationId, Clip clipBehavior = Clip.hardEdge}): Creates a ScrollView that creates custom scroll effects using slivers.
const

Properties

anchor → double: The relative position of the zero scroll offset.
finalinherited
cacheExtent → double?: The viewport has an area before and after the visible area to cache items that are about to become visible when the user scrolls.
finalinherited
center → Key?: The first child in the GrowthDirection.forward growth direction.
finalinherited
clipBehavior → Clip: The content will be clipped (or not) according to this option.
finalinherited
controller → ScrollController?: An object that can be used to control the position to which this scroll view is scrolled.
finalinherited
dragStartBehavior → DragStartBehavior: Determines the way that drag start behavior is handled.
finalinherited
hashCode → int: The hash code for this object.
nonVirtual">@nonVirtualread-onlyinherited
key → Key?: Controls how one widget replaces another widget in the tree.
finalinherited
keyboardDismissBehavior → ScrollViewKeyboardDismissBehavior: ScrollViewKeyboardDismissBehavior the defines how this ScrollView will dismiss the keyboard automatically.
finalinherited
physics → ScrollPhysics?: How the scroll view should respond to user input.
finalinherited
primary → bool?: Whether this is the primary scroll view associated with the parent PrimaryScrollController.
finalinherited
restorationId → String?: Restoration ID to save and restore the scroll offset of the scrollable.
finalinherited
reverse → bool: Whether the scroll view scrolls in the reading direction.
finalinherited
runtimeType → Type: A representation of the runtime type of the object.
read-onlyinherited
scrollBehavior → ScrollBehavior?: A ScrollBehavior that will be applied to this widget individually.
finalinherited
scrollDirection → Axis: The axis along which the scroll view scrolls.
finalinherited
semanticChildCount → int?: The number of children that will contribute semantic information.
finalinherited
shrinkWrap → bool: Whether the extent of the scroll view in the scrollDirection should be determined by the contents being viewed.
finalinherited
slivers → List<Widget>: The slivers to place inside the viewport.
final

Methods

build(BuildContext context) → Widget: Describes the part of the user interface represented by this widget.
inherited
buildSlivers(BuildContext context) → List<Widget>: Build the list of widgets to place inside the viewport.
override
buildViewport(BuildContext context, ViewportOffset offset, AxisDirection axisDirection, List<Widget> slivers) → Widget: Build the viewport.
protected">@protectedinherited
createElement() → StatelessElement: Creates a StatelessElement to manage this widget's location in the tree.
inherited
debugDescribeChildren() → List<DiagnosticsNode>: Returns a list of DiagnosticsNode objects describing this node's children.
protected">@protectedinherited
debugFillProperties(DiagnosticPropertiesBuilder properties) → void: Add additional properties associated with the node.
inherited
getDirection(BuildContext context) → AxisDirection: Returns the AxisDirection in which the scroll view scrolls.
protected">@protectedinherited
noSuchMethod(Invocation invocation) → dynamic: Invoked when a non-existent method or property is accessed.
inherited
toDiagnosticsNode({String? name, DiagnosticsTreeStyle? style}) → DiagnosticsNode: Returns a debug representation of the object that is used by debugging tools and by DiagnosticsNode.toStringDeep.
inherited
toString({DiagnosticLevel minLevel = DiagnosticLevel.info}) → String: A string representation of this object.
inherited
toStringDeep({String prefixLineOne = '', String? prefixOtherLines, DiagnosticLevel minLevel = DiagnosticLevel.debug}) → String: Returns a string representation of this node and its descendants.
inherited
toStringShallow({String joiner = ', ', DiagnosticLevel minLevel = DiagnosticLevel.debug}) → String: Returns a one-line detailed description of the object.
inherited
toStringShort() → String: A short, textual description of this widget.
inherited

Operators

operator ==(Object other) → bool: The equality operator.
nonVirtual">@nonVirtualinherited