flutter_scrollview_observer

The SliverViewObserver widget is used to monitor the scroll behavior of slivers (such as RenderSliverList, RenderSliverFixedExtentList, and RenderSliverGrid) within a viewport. It provides callbacks to track which slivers are currently being displayed and general observation of sliver changes.

Key features include:

• onObserveViewport: A callback that returns a SliverViewportObserveModel containing information about the slivers currently visible in the viewport.
• sliverContexts: A function that provides the BuildContext for each sliver, allowing you to identify them.
• Custom Observation: You can provide customHandleObserve or extendedHandleObserve to implement custom logic for slivers not natively supported by the observer.
• Trigger Control: Use triggerOnObserveType to control when observation callbacks are fired.

SliverViewObserver(
  sliverContexts: () => mySliverContexts,
  onObserveViewport: (model) {
    // model contains viewport and displaying sliver information
    print('First visible sliver: ${model.firstChild.sliver}');
  },
  child: CustomScrollView(
    slivers: [
      // your slivers here
    ],
  ),
);

Call standby() to prepare the observer for an upcoming change in the scroll view's children (like inserting or removing messages). This method calculates the necessary offsets and indices to maintain the user's scroll position.

Parameters

• sliverContext: The BuildContext of the sliver.
• isRemove: Set to true if messages are being removed; otherwise, false (default).
• changeCount: The number of messages added (used when isRemove is false).
• mode: The ChatScrollObserverHandleMode determining how to find the reference item:
  • ChatScrollObserverHandleMode.normal: Uses the first item as the reference.
  • ChatScrollObserverHandleMode.generative: Calculates based on the first item plus changeCount.
  • ChatScrollObserverHandleMode.specified: Uses specific indices provided via refItemIndex or refItemRelativeIndex.
• refIndexType: Determines how refItemRelativeIndex is interpreted:
  • ChatScrollObserverRefIndexType.relativeIndexStartFromCacheExtent
  • ChatScrollObserverRefIndexType.relativeIndexStartFromDisplaying
  • ChatScrollObserverRefIndexType.itemIndex
• refItemIndex: The index of the reference message before the update.
• refItemIndexAfterUpdate: The index of the same reference message after the update.
• customAdjustPosition: (Optional) A custom function to define how the scroll position is adjusted.
• customAdjustPositionDelta: (Optional) A custom function to define the delta for position adjustment.

await observer.standby(
  sliverContext: context,
  isRemove: false,
  changeCount: 1,
  mode: ChatScrollObserverHandleMode.specified,
  refItemIndex: 10, // The index of the message before insertion
  refItemIndexAfterUpdate: 11, // The index of the same message after insertion
);

The ObserverWidget is the primary component used to observe the scroll position and visibility of items within a scrollable widget (like ListView or GridView). It wraps the scrollable widget and provides callbacks when the observed items change.

Key Properties

• child: The scrollable widget you want to observe.
• onObserve: Callback triggered when the first observed sliver's state changes.
• onObserveAll: Callback triggered when any observed sliver's state changes, providing a map of all results.
• sliverController: An optional controller to dispatch notifications or manage observation.
• tag: A unique string used to identify this specific ObserverWidget instance when multiple observers are nested.
• leadingOffset: A fixed offset used for calculations.
• dynamicLeadingOffset: A callback to calculate the offset dynamically.
• toNextOverPercent: A threshold (0.0 to 1.0) determining when the next child becomes the 'first' child based on how much of its size is visible.
• scrollNotificationPredicate: A predicate to filter which ScrollNotifications trigger observation (useful for performance).
• autoTriggerObserveTypes: A list of ObserverAutoTriggerObserveType (e.g., .scrollStart, .scrollUpdate, .scrollEnd) that trigger automatic observation.
• triggerOnObserveType: Determines the prerequisite for triggering onObserve. Defaults to ObserverTriggerOnObserveType.displayingItemsChange.
• customTargetRenderSliverType: A predicate to define which RenderObject types should be treated as target slivers (defaults to RenderSliverList, RenderSliverFixedExtentList, and RenderSliverGrid).
• customHandleObserve: Allows providing custom logic to generate the observation model M for a given BuildContext.

ObserverWidget(
  child: ListView.builder(
    itemBuilder: (context, index) => Text('Item $index'),
    itemCount: 100,
  ),
  onObserve: (model) {
    print('First item changed: $model');
  },
  onObserveAll: (map) {
    print('All items changed: $map');
  },
);

Use NestedScrollUtil.animateTo to smoothly scroll to a specific index within a NestedScrollView. This is useful for providing a polished user experience when navigating long lists in a nested structure.

Parameters:

• nestedScrollViewKey: The GlobalKey associated with your NestedScrollView.
• observerController: The SliverObserverController managing the scroll view.
• position: A NestedScrollUtilPosition indicating whether to target the header or the body.
• index: The target index to animate to.
• duration: The Duration of the animation.
• curve: The Curve to use for the animation.
• sliverContext: The BuildContext of the sliver.
• isFixedHeight: Whether the item has a fixed height.
• alignment: The alignment of the target item (default is 0).
• padding: Padding to apply (default is EdgeInsets.zero).
• offset: An optional ObserverLocateIndexOffsetCallback for custom offset calculation.
• renderSliverType: The type of render sliver to use.

await NestedScrollUtil().animateTo(
  nestedScrollViewKey: myNestedKey,
  observerController: myObserverController,
  position: NestedScrollUtilPosition.body,
  index: 10,
  duration: Duration(milliseconds: 300),
  curve: Curves.easeInOut,
  sliverContext: mySliverContext,
);

The package provides a hierarchy of notifications to track the lifecycle of a scrolling task (typically initiated via jumpTo or animateTo on an ObserverController).

To monitor a scroll task, you can listen for these specific notifications in this sequence:

1. ObserverScrollStartNotification: The scrolling task has started.
2. ObserverScrollDecisionNotification: The data for a specific index item has been determined during the scroll.
3. ObserverScrollEndNotification: The scrolling task has completed.

Additionally, you can listen for ObserverScrollInterruptionNotification if a scrolling task is interrupted by a new scroll command.

// Conceptual usage of listening to scroll lifecycle
listener(Notification notification) {
  if (notification is ObserverScrollStartNotification) {
    // Handle start
  } else if (notification is ObserverScrollDecisionNotification) {
    // Handle decision/index determination
  } else if (notification is ObserverScrollEndNotification) {
    // Handle end
  } else if (notification is ObserverScrollInterruptionNotification) {
    // Handle interruption
  }
}