-
-
Notifications
You must be signed in to change notification settings - Fork 44
2、Scrolling to the specified index location
It should be used with the scrollView's cacheExtent
property. Assigning an appropriate value to it can avoid unnecessary page turning.
The recommendations are as follows:
- If child widgets are fixed height in scrollView, use
isFixedHeight
instead ofcacheExtent
. - For scrollView such as detail page, it is recommended to set
cacheExtent
todouble.maxFinite
. - If child widgets are dynamic height in scrollView, it is recommended that setting
cacheExtent
to a large and reasonable value depending on your situation.
Create and use instance of ScrollController
normally.
ScrollController scrollController = ScrollController();
ListView _buildListView() {
return ListView.separated(
controller: scrollController,
...
);
}
Create an instance of ListObserverController
pass it to ListViewObserver
ListObserverController observerController = ListObserverController(controller: scrollController);
ListViewObserver(
controller: observerController,
child: _buildListView(),
...
)
Now you can scroll to the specified index position
// Jump to the specified index position without animation.
observerController.jumpTo(index: 1)
// Jump to the specified index position with animation.
observerController.animateTo(
index: 1,
duration: const Duration(milliseconds: 250),
curve: Curves.ease,
);
If you use CustomScrollView
and its slivers
contain SliverList
and SliverGrid
, this is also supported, but you need to use SliverViewObserver
, and pass the corresponding BuildContext
to distinguish the corresponding Sliver
when calling the scroll method.
SliverViewObserver(
controller: observerController,
child: CustomScrollView(
controller: scrollController,
slivers: [
_buildSliverListView1(),
_buildSliverListView2(),
],
),
sliverListContexts: () {
return [
if (_sliverViewCtx1 != null) _sliverViewCtx1!,
if (_sliverViewCtx2 != null) _sliverViewCtx2!,
];
},
...
)
observerController.animateTo(
sliverContext: _sliverViewCtx2, // _sliverViewCtx1
index: 10,
duration: const Duration(milliseconds: 300),
curve: Curves.easeInOut,
);
If your ListView or GridView uses its padding parameter, you need to sync that value as well! Such as:
ListView.separated(padding: _padding, ...);
GridView.builder(padding: _padding, ...);
observerController.jumpTo(index: 1, padding: _padding);
If the height of a list child widget is fixed, it is recommended to use the 'isFixedHeight' parameter to improve performance.
This feature has supported
ListView/SliverList
,GridView/SliverGrid
and otherScrollView
built by third-party package since version1.17.0
. The previous version only supportedListView/SliverList
.
// Jump to the specified index position without animation.
observerController.jumpTo(index: 150, isFixedHeight: true)
// Jump to the specified index position with animation.
observerController.animateTo(
index: 150,
isFixedHeight: true
duration: const Duration(milliseconds: 250),
curve: Curves.ease,
);
It should be noted that if your ScrollView is built by third-party package, you may need to use the renderSliverType
parameter to specify the processing method. If sliver is SliverList
and SliverGrid
, you do not need to specify it.
Type of renderSliverType
:
enum ObserverRenderSliverType {
list,
grid,
}
For example, the waterfall flow view built by waterfall_flow
needs to specify renderSliverType
as ObserverRenderSliverType.grid
when calling the jumpTo
method.
observerController.jumpTo(
index: 13,
isFixedHeight: true,
renderSliverType: ObserverRenderSliverType.grid,
);
Used to set the whole scrollView offset when scrolling to a specified index.
For example, in the scene with SliverAppBar
, its height will change with the scrolling of ScrollView
. After reaching a certain offset, it will be suspended on the top with a fixed height, and then we must pass this fixed height to the offset
parameter.
SliverAppBar(
key: appBarKey,
pinned: true,
expandedHeight: 200,
flexibleSpace: FlexibleSpaceBar(
title: const Text('AppBar'),
background: Container(color: Colors.orange),
),
);
observerController.animateTo(
...
offset: (offset) {
// The height of the SliverAppBar is calculated base on target offset and is returned in the current callback.
// The observerController internally adjusts the appropriate offset based on the return value.
return ObserverUtils.calcPersistentHeaderExtent(
key: appBarKey,
offset: offset,
);
},
);
The alignment
specifies the desired position for the leading edge of the child widget. It must be a value in the range [0.0, 1.0]
. Such as:
-
alignment: 0
: Scrolling to thetop
position of the child widget. -
alignment: 0.5
: Scrolling to themiddle
position of the child widget. -
alignment: 1
: Scrolling to thetail
position of the child widget.
For performance reasons, ScrollController
will caches the child's information by default when the listView jump
or animate
to the specified location, so that it can be used next time directly.
However, in scence where the height of child widget is always changing dynamically, this will cause unnecessary trouble, so you can turn this off by setting the cacheJumpIndexOffset
property to false
.
You can use the clearIndexOffsetCache
method if you want to preserve the cache function of scrolling and only want to clear the cache in certain cases.
/// Clear the offset cache that jumping to a specified index location.
clearIndexOffsetCache(BuildContext? sliverContext) {
...
}
The parameter sliverContext
needs to be passed only if you manage ScrollView
's BuildContext
by yourself.
- Method 1:
initialIndex
The simplest way to use, directly set the location index.
observerController = ListObserverController(controller: scrollController)
..initialIndex = 10;
- Method 2:
initialIndexModel
You can customize the configuration of the initial index position. See the end of this section for property descriptions.
observerController = ListObserverController(controller: scrollController)
..initialIndexModel = ObserverIndexPositionModel(
index: 10,
isFixedHeight = true,
alignment = 0.5,
);
- Method 3:
initialIndexModelBlock
You need return ObserverIndexPositionModel
object within the callback.
This method applies to some of scenarios those the parameters can't be determined from the start, such as sliverContext
.
observerController = SliverObserverController(controller: scrollController)
..initialIndexModelBlock = () {
return ObserverIndexPositionModel(
index: 6,
sliverContext: _sliverListCtx,
offset: calcPersistentHeaderExtent,
);
};
The structure of ObserverIndexPositionModel
:
ObserverIndexPositionModel({
required this.index,
this.sliverContext,
this.isFixedHeight = false,
this.alignment = 0,
this.offset,
this.padding = EdgeInsets.zero,
});
Property | Type | Desc |
---|---|---|
index |
int |
The index of child widget. |
sliverContext |
BuildContext |
The target sliver [BuildContext] . |
isFixedHeight |
bool |
If the height of the child widget and the height of the separator are fixed, please pass true to this property. Defaults to false
|
alignment |
double |
The alignment specifies the desired position for the leading edge of the child widget. It must be a value in the range [0.0, 1.0] . Defaults to 1.0
|
offset |
double Function(double targetOffset) |
Use this property when locating position needs an offset. |
padding |
EdgeInsets |
If your ListView or GridView uses its padding parameter, you need to sync that value as well! Otherwise it is not required. |
Starting from version 1.18.0
, some new scrolling notifications have been added to facilitate listening of scrolling state. Note that they will only be emitted after the jumpTo
method or animateTo
method of ObserverController
is called.
Notification | Desc |
---|---|
ObserverScrollStartNotification |
Start executing the scrolling task, the target item has not been found yet |
ObserverScrollInterruptionNotification |
The scrolling task is interrupted, such as: a non-existent index is passed in, there is no ScrollController , etc. |
ObserverScrollDecisionNotification |
The scrolling task decision is completed, the target item is currently found. |
ObserverScrollEndNotification |
The scrolling task is end normally |
The above notifications all extend from ObserverScrollNotification
and can be used as the generic type required by NotificationListener
.
Notification sequence:
ObserverScrollStartNotification
-> ObserverScrollDecisionNotification
-> ObserverScrollEndNotification
.
ObserverScrollInterruptionNotification
does not participate in the above sequence. It will be issued when the scrolling conditions are not met. After it is issued, the scrolling task will end and no other notifications will be posted!
NotificationListener<ObserverScrollNotification>(
child: widget,
onNotification: (notification) {
if (notification is ObserverScrollStartNotification) {
} else if (notification is ObserverScrollInterruptionNotification) {
} else if (notification is ObserverScrollDecisionNotification) {
} else if (notification is ObserverScrollEndNotification) {
}
return true;
},
);
The jumpTo
method and animateTo
method also officially support await
in the 1.18.0
version. There are two possibilities for the result after await
:
- Interruption (same as
ObserverScrollInterruptionNotification
) - End normally (same as
ObserverScrollEndNotification
)