positioned_scroll_observer 2.0.0

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. No breaking for your current sliver widgets, e.g., ListView/GridView, SliverList/SliverGrid/SliverAppBar

• 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, e.g., SliverList, SliverGrid and so on.

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.

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

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