positioned_scroll_observer 2.2.2

An elegant scroll observer that support most scroll views could jump/animateToIndex without breaking current widgets.

Features

1. Using jumpToIndex and animateToIndex to scroll to the specific index

2. Jumping/animating to the position by specifying a ratio in a scroll view. See how to align the render object. That would be very useful if you want to quickly jump to the top, middle or end of a list/grid.

3. Using PositionRetainedScrollPhysics to retain the old offset to avoid scrolling when adding new items into the top of ListView. See retain old scroll offset.

4. Check if the specific index is visible on the screen. See check visibility.

5. Check which items are visible in the viewport. See get visible items

6. Check the visible ratio of the observed RenderObject in a viewport. See how to use it in a GroupList

7. No breaking for your current sliver widgets, e.g., ListView/GridView, SliverList/SliverGrid/SliverAppBar, just wrapping your item widgets using ObserverProxy. Supported:

• ✅ ListView
• ✅ GridView
• ✅ CustomScrollView
• ✅ SingleChildScrollView
• ✅ ListWheelScrollView
• ❌ NestedScrollView (waiting testing)

Getting started

1. First, creating and binding the observer to all items. (See box scroll observer and sliver scroll observer)

2. then, using the observer like:

   _observer.jumpToIndex(
       index,
       position: _controller.position,
   );
   
   _observer.animateToIndex(
       index,
       position: _controller.position,
       duration: const Duration(milliseconds: 200),
       curve: Curves.fastLinearToSlowEaseIn,
   );
   

Usage for scroll views that do not rely on RenderSliver, e.g., SingleChildScrollView and ListWheelScrollView

1. create a BoxScrollObserver for observing the box with multi children.

     final ScrollController _controller = ScrollController();
     late final _observer = ScrollObserver.boxMulti(
       axis: _axis,
       itemCount: 30,
     );
   

2. bind the observer to the box's children. (Using ObserverProxy to wrap each item).

   SingleChildScrollView(
     controller: _controller,
     scrollDirection: _axis,
     child: Column(
       children: [
         for (int i = 0; i < 30; i++)
           ObserverProxy(
             observer: _observer,
             child: DecoratedBox(
               decoration: BoxDecoration(border: Border.all()),
               child: SizedBox(
                 height: 100,
                 width: 100,
                 child: Center(
                   child: Text("Column item $i"),
                 ),
               ),
             ),
           ),
         ],
       ),
     );
   

Usage for slivers widgets.

1. create a SliverScrollObserver for observing the sliver with multi children.

     final ScrollController _controller = ScrollController();
     late final _observer = ScrollObserver.sliverMulti(itemCount: 30);
   

2. bind the observer to each item for the sliver.

       ListView.builder(
         controller: _controller,
         itemBuilder: (context, index) => ObserverProxy(
           observer: _observer,
           child: ListTile(
             key: ValueKey<int>(index),
             leading: const CircleAvatar(
               child: Text("L"),
             ),
             title: Text("Positioned List Example $index"),
           ),
         ),
         itemCount: _itemCount,
       );
   

For ListView.custom and GridView.custom, you could also use PositionedChildListDelegate and PositionedChildBuilderDelegate for wrapping items in ObserverProxy conveniently

Usage

For observing slivers:

1. observing a sliver with single child, using ScrollObserver.sliverSingle to create.
2. observing a sliver with multi children, using ScrollObserver.sliverMulti to create.

For observing other scroll views that have no sliver descendants.

1. observing a box with single child, using ScrollObserver.boxSingle to create. (rare cases and need more testing)
2. observing a box with multi children, using ScrollObserver.boxMulti to create.

Checking index is visible on the screen

get visible items

More details, see API reference.

Using PositionRetainedScrollPhysics for retaining the old scroll offset

ListView.builder(
  controller: _controller,
  reverse: true,
  physics: const PositionRetainedScrollPhysics(),
  itemBuilder: (context, index) => _items[index],
  itemCount: _itemCount,
);

Jump/animate to a ratio position in a viewport

_observer.showInViewport(
  _controller.position,
  alignment: 0.5,
);

By setting different alignment, you could jump/animate to the position according to the ratio: alignment.

1. for alignment = 0.0, it would align the render object' leading to the leading of the viewport's main axis extent.
2. for alignment = 0.5, it would align the render object's center to the center of the viewport;s main axis extent.
3. for alignment = 1.0, it would align the render object's trailing to the trailing of the viewport's main axis extent.

you could also specify alignment as the number between [0, 1]

Pay attention

• The item widget/builder must be wrapped using ObserverProxy
• All observers would normalizeIndex to ensure the index is in a valid range determined by itemCount of observers, so developers should also update observers' itemCount when the scroll views' item count changes.
• Items that have the same RenderObject observed by an observer should share the same observer instance, instead of creating different observers for each item.
• When using ScrollObserver.boxMulti, axis is required so that the observer could estimate the scroll offset along the correct main axis.

Examples:

• ListView example
• GridView example
• CustomScrollView example
• ReorderableListView example
• ListWheelScrollView example
• SingleChildScrollView example
• GroupList example

FAQ

TODO

Contributions

Feel free to contribute to this project.

If you find a bug or want a feature, but don't know how to fix/implement it, please fill an issue.

If you fixed a bug or implemented a feature, please send a pull request