animateScrollToKey method

Future<bool> animateScrollToKey(TKey key, { required ScrollController scrollController, Duration duration = const Duration(milliseconds: 300), Curve curve = Curves.linear, double alignment = 0.0, AncestorExpansionMode ancestorExpansion = AncestorExpansionMode.immediate, double extentEstimator(TKey key)?, double sliverBaseOffset = 0.0, bool avoidStickyHeaders = false, })

Animates scrollController to reveal key in its attached viewport.

ancestorExpansion controls how collapsed ancestors of key are handled:

• AncestorExpansionMode.none: ancestors are not expanded. If any ancestor of key is collapsed, returns false without scrolling.
• AncestorExpansionMode.immediate (default): ancestors are expanded synchronously (no animation) before the scroll begins. When this actually expanded something, the method waits one frame before computing the target so the enlarged sliver lays out first, otherwise the scroll would clamp against the pre-expansion maxScrollExtent and stop short of the target row.
• AncestorExpansionMode.animated: ancestors animate open while the scroll runs concurrently. Each animation tick the scroll target is re-derived from the current animated offsets so it stays glued to the moving target. A precise jump lands on the settled offset once both finish. In this mode the concurrent phase runs for max(duration, expandCollapse.duration) so both the expansion and the scroll have time to complete.

alignment controls placement within the viewport: 0.0 pins the row's top to the viewport top (default), 0.5 centers, 1.0 pins the row's bottom to the viewport bottom.

For nodes that have never been laid out, extentEstimator supplies a fallback height; without it, defaultExtent is used. A mismatch between estimate and actual measurement may cause slight over- or undershoot, the render pass that includes the target will snap to the exact offset on the next frame.

sliverBaseOffset is the scroll-space distance from the top of the scrollable's content to the top of this sliver. It is added to the computed sliver-local offset. Leave at 0.0 when SliverTree is the first (or only) sliver in the CustomScrollView.

A non-zero-duration call issued while tree animations are in flight follows the moving target (the same follower the animated mode uses) and therefore participates in the single-flight slot below; its future resolves once the scroll curve has finished, the tree is quiescent, and the final snap has run. duration: Duration.zero issued during an in-flight animation lands on the current animated geometry (plus the post-frame settle snap), not the settled one.

Scrolls are single-flight, in both directions: starting one while another is still in flight cancels the earlier scroll (its future resolves false), the newer target wins, whether either scroll is plain or animated-mode.

avoidStickyHeaders (default false, preserving today's landings) insets the target below the sticky band its own pinned ancestors will form after the scroll (stickyInsetOf); alignment then works against the viewport minus that band, which leaves bottom alignment untouched. The inset predicts the tree's OWN band from the sliver's paint origin; a preceding pinned sliver that overlaps the tree lowers the real band by its overlap, which this parameter does not see.

Returns true if a scroll was issued, false if key could not be resolved, scrollController has no attached position, or the scroll was cancelled (superseded, or the controller was disposed) before completing.

Implementation

Future<bool> animateScrollToKey(
  TKey key, {
  required ScrollController scrollController,
  Duration duration = const Duration(milliseconds: 300),
  Curve curve = Curves.linear,
  double alignment = 0.0,
  AncestorExpansionMode ancestorExpansion = AncestorExpansionMode.immediate,
  double Function(TKey key)? extentEstimator,
  double sliverBaseOffset = 0.0,
  bool avoidStickyHeaders = false,
}) => _scroll.animateScrollToKey(
  key,
  scrollController: scrollController,
  duration: duration,
  curve: curve,
  alignment: alignment,
  ancestorExpansion: ancestorExpansion,
  extentEstimator: extentEstimator,
  sliverBaseOffset: sliverBaseOffset,
  avoidStickyHeaders: avoidStickyHeaders,
);