animateScrollToKey method

Future<bool> animateScrollToKey(
  1. TKey key, {
  2. required ScrollController scrollController,
  3. Duration duration = const Duration(milliseconds: 300),
  4. Curve curve = Curves.easeInOut,
  5. double alignment = 0.0,
  6. AncestorExpansionMode ancestorExpansion = AncestorExpansionMode.immediate,
  7. double extentEstimator(
    1. TKey key
    )?,
  8. double sliverBaseOffset = 0.0,
})

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, so layout is already settled when scrollController starts moving.
  • 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, animationDuration) 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.

Returns true if a scroll was issued, false if key could not be resolved or scrollController has no attached position.

Implementation

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