1// Copyright 2014 The Flutter Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5/// @docImport 'package:flutter/cupertino.dart';
6/// @docImport 'package:flutter/material.dart';
7/// @docImport 'package:flutter/widgets.dart';
8/// @docImport 'package:flutter_test/flutter_test.dart';
9library;
10
11import 'dart:math' as math;
12
13import 'package:flutter/gestures.dart';
14import 'package:flutter/rendering.dart';
15
16import 'basic.dart';
17import 'debug.dart';
18import 'focus_manager.dart';
19import 'focus_scope.dart';
20import 'framework.dart';
21import 'media_query.dart';
22import 'notification_listener.dart';
23import 'primary_scroll_controller.dart';
24import 'scroll_configuration.dart';
25import 'scroll_controller.dart';
26import 'scroll_delegate.dart';
27import 'scroll_notification.dart';
28import 'scroll_physics.dart';
29import 'scrollable.dart';
30import 'scrollable_helpers.dart';
31import 'sliver.dart';
32import 'sliver_prototype_extent_list.dart';
33import 'viewport.dart';
34
35// Examples can assume:
36// late int itemCount;
37
38/// A representation of how a [ScrollView] should dismiss the on-screen
39/// keyboard.
40enum ScrollViewKeyboardDismissBehavior {
41 /// `manual` means there is no automatic dismissal of the on-screen keyboard.
42 /// It is up to the client to dismiss the keyboard.
43 manual,
44
45 /// `onDrag` means that the [ScrollView] will dismiss an on-screen keyboard
46 /// when a drag begins.
47 onDrag,
48}
49
50/// A widget that combines a [Scrollable] and a [Viewport] to create an
51/// interactive scrolling pane of content in one dimension.
52///
53/// Scrollable widgets consist of three pieces:
54///
55/// 1. A [Scrollable] widget, which listens for various user gestures and
56/// implements the interaction design for scrolling.
57/// 2. A viewport widget, such as [Viewport] or [ShrinkWrappingViewport], which
58/// implements the visual design for scrolling by displaying only a portion
59/// of the widgets inside the scroll view.
60/// 3. One or more slivers, which are widgets that can be composed to created
61/// various scrolling effects, such as lists, grids, and expanding headers.
62///
63/// [ScrollView] helps orchestrate these pieces by creating the [Scrollable] and
64/// the viewport and deferring to its subclass to create the slivers.
65///
66/// To learn more about slivers, see [CustomScrollView.slivers].
67///
68/// To control the initial scroll offset of the scroll view, provide a
69/// [controller] with its [ScrollController.initialScrollOffset] property set.
70///
71/// {@template flutter.widgets.ScrollView.PageStorage}
72/// ## Persisting the scroll position during a session
73///
74/// Scroll views attempt to persist their scroll position using [PageStorage].
75/// This can be disabled by setting [ScrollController.keepScrollOffset] to false
76/// on the [controller]. If it is enabled, using a [PageStorageKey] for the
77/// [key] of this widget is recommended to help disambiguate different scroll
78/// views from each other.
79/// {@endtemplate}
80///
81/// See also:
82///
83/// * [ListView], which is a commonly used [ScrollView] that displays a
84/// scrolling, linear list of child widgets.
85/// * [PageView], which is a scrolling list of child widgets that are each the
86/// size of the viewport.
87/// * [GridView], which is a [ScrollView] that displays a scrolling, 2D array
88/// of child widgets.
89/// * [CustomScrollView], which is a [ScrollView] that creates custom scroll
90/// effects using slivers.
91/// * [ScrollNotification] and [NotificationListener], which can be used to watch
92/// the scroll position without using a [ScrollController].
93/// * [TwoDimensionalScrollView], which is a similar widget [ScrollView] that
94/// scrolls in two dimensions.
95abstract class ScrollView extends StatelessWidget {
96 /// Creates a widget that scrolls.
97 ///
98 /// The [ScrollView.primary] argument defaults to true for vertical
99 /// scroll views if no [controller] has been provided. The [controller] argument
100 /// must be null if [primary] is explicitly set to true. If [primary] is true,
101 /// the nearest [PrimaryScrollController] surrounding the widget is attached
102 /// to this scroll view.
103 ///
104 /// If the [shrinkWrap] argument is true, the [center] argument must be null.
105 ///
106 /// The [anchor] argument must be in the range zero to one, inclusive.
107 const ScrollView({
108 super.key,
109 this.scrollDirection = Axis.vertical,
110 this.reverse = false,
111 this.controller,
112 this.primary,
113 ScrollPhysics? physics,
114 this.scrollBehavior,
115 this.shrinkWrap = false,
116 this.center,
117 this.anchor = 0.0,
118 this.cacheExtent,
119 this.semanticChildCount,
120 this.paintOrder = SliverPaintOrder.firstIsTop,
121 this.dragStartBehavior = DragStartBehavior.start,
122 this.keyboardDismissBehavior,
123 this.restorationId,
124 this.clipBehavior = Clip.hardEdge,
125 this.hitTestBehavior = HitTestBehavior.opaque,
126 }) : assert(
127 !(controller != null && (primary ?? false)),
128 'Primary ScrollViews obtain their ScrollController via inheritance '
129 'from a PrimaryScrollController widget. You cannot both set primary to '
130 'true and pass an explicit controller.',
131 ),
132 assert(!shrinkWrap || center == null),
133 assert(anchor >= 0.0 && anchor <= 1.0),
134 assert(semanticChildCount == null || semanticChildCount >= 0),
135 physics =
136 physics ??
137 ((primary ?? false) ||
138 (primary == null &&
139 controller == null &&
140 identical(scrollDirection, Axis.vertical))
141 ? const AlwaysScrollableScrollPhysics()
142 : null);
143
144 /// {@template flutter.widgets.scroll_view.scrollDirection}
145 /// The [Axis] along which the scroll view's offset increases.
146 ///
147 /// For the direction in which active scrolling may be occurring, see
148 /// [ScrollDirection].
149 ///
150 /// Defaults to [Axis.vertical].
151 /// {@endtemplate}
152 final Axis scrollDirection;
153
154 /// {@template flutter.widgets.scroll_view.reverse}
155 /// Whether the scroll view scrolls in the reading direction.
156 ///
157 /// For example, if the reading direction is left-to-right and
158 /// [scrollDirection] is [Axis.horizontal], then the scroll view scrolls from
159 /// left to right when [reverse] is false and from right to left when
160 /// [reverse] is true.
161 ///
162 /// Similarly, if [scrollDirection] is [Axis.vertical], then the scroll view
163 /// scrolls from top to bottom when [reverse] is false and from bottom to top
164 /// when [reverse] is true.
165 ///
166 /// Defaults to false.
167 /// {@endtemplate}
168 final bool reverse;
169
170 /// {@template flutter.widgets.scroll_view.controller}
171 /// An object that can be used to control the position to which this scroll
172 /// view is scrolled.
173 ///
174 /// Must be null if [primary] is true.
175 ///
176 /// A [ScrollController] serves several purposes. It can be used to control
177 /// the initial scroll position (see [ScrollController.initialScrollOffset]).
178 /// It can be used to control whether the scroll view should automatically
179 /// save and restore its scroll position in the [PageStorage] (see
180 /// [ScrollController.keepScrollOffset]). It can be used to read the current
181 /// scroll position (see [ScrollController.offset]), or change it (see
182 /// [ScrollController.animateTo]).
183 /// {@endtemplate}
184 final ScrollController? controller;
185
186 /// {@template flutter.widgets.scroll_view.primary}
187 /// Whether this is the primary scroll view associated with the parent
188 /// [PrimaryScrollController].
189 ///
190 /// When this is true, the scroll view is scrollable even if it does not have
191 /// sufficient content to actually scroll. Otherwise, by default the user can
192 /// only scroll the view if it has sufficient content. See [physics].
193 ///
194 /// Also when true, the scroll view is used for default [ScrollAction]s. If a
195 /// ScrollAction is not handled by an otherwise focused part of the application,
196 /// the ScrollAction will be evaluated using this scroll view, for example,
197 /// when executing [Shortcuts] key events like page up and down.
198 ///
199 /// On iOS, this also identifies the scroll view that will scroll to top in
200 /// response to a tap in the status bar.
201 ///
202 /// Cannot be true while a [ScrollController] is provided to `controller`,
203 /// only one ScrollController can be associated with a ScrollView.
204 ///
205 /// Setting to false will explicitly prevent inheriting any
206 /// [PrimaryScrollController].
207 ///
208 /// Defaults to null. When null, and a controller is not provided,
209 /// [PrimaryScrollController.shouldInherit] is used to decide automatic
210 /// inheritance.
211 ///
212 /// By default, the [PrimaryScrollController] that is injected by each
213 /// [ModalRoute] is configured to automatically be inherited on
214 /// [TargetPlatformVariant.mobile] for ScrollViews in the [Axis.vertical]
215 /// scroll direction. Adding another to your app will override the
216 /// PrimaryScrollController above it.
217 ///
218 /// The following video contains more information about scroll controllers,
219 /// the PrimaryScrollController widget, and their impact on your apps:
220 ///
221 /// {@youtube 560 315 https://www.youtube.com/watch?v=33_0ABjFJUU}
222 ///
223 /// {@endtemplate}
224 final bool? primary;
225
226 /// {@template flutter.widgets.scroll_view.physics}
227 /// How the scroll view should respond to user input.
228 ///
229 /// For example, determines how the scroll view continues to animate after the
230 /// user stops dragging the scroll view.
231 ///
232 /// Defaults to matching platform conventions. Furthermore, if [primary] is
233 /// false, then the user cannot scroll if there is insufficient content to
234 /// scroll, while if [primary] is true, they can always attempt to scroll.
235 ///
236 /// To force the scroll view to always be scrollable even if there is
237 /// insufficient content, as if [primary] was true but without necessarily
238 /// setting it to true, provide an [AlwaysScrollableScrollPhysics] physics
239 /// object, as in:
240 ///
241 /// ```dart
242 /// physics: const AlwaysScrollableScrollPhysics(),
243 /// ```
244 ///
245 /// To force the scroll view to use the default platform conventions and not
246 /// be scrollable if there is insufficient content, regardless of the value of
247 /// [primary], provide an explicit [ScrollPhysics] object, as in:
248 ///
249 /// ```dart
250 /// physics: const ScrollPhysics(),
251 /// ```
252 ///
253 /// The physics can be changed dynamically (by providing a new object in a
254 /// subsequent build), but new physics will only take effect if the _class_ of
255 /// the provided object changes. Merely constructing a new instance with a
256 /// different configuration is insufficient to cause the physics to be
257 /// reapplied. (This is because the final object used is generated
258 /// dynamically, which can be relatively expensive, and it would be
259 /// inefficient to speculatively create this object each frame to see if the
260 /// physics should be updated.)
261 /// {@endtemplate}
262 ///
263 /// If an explicit [ScrollBehavior] is provided to [scrollBehavior], the
264 /// [ScrollPhysics] provided by that behavior will take precedence after
265 /// [physics].
266 final ScrollPhysics? physics;
267
268 /// {@macro flutter.widgets.scrollable.scrollBehavior}
269 final ScrollBehavior? scrollBehavior;
270
271 /// {@template flutter.widgets.scroll_view.shrinkWrap}
272 /// Whether the extent of the scroll view in the [scrollDirection] should be
273 /// determined by the contents being viewed.
274 ///
275 /// If the scroll view does not shrink wrap, then the scroll view will expand
276 /// to the maximum allowed size in the [scrollDirection]. If the scroll view
277 /// has unbounded constraints in the [scrollDirection], then [shrinkWrap] must
278 /// be true.
279 ///
280 /// Shrink wrapping the content of the scroll view is significantly more
281 /// expensive than expanding to the maximum allowed size because the content
282 /// can expand and contract during scrolling, which means the size of the
283 /// scroll view needs to be recomputed whenever the scroll position changes.
284 ///
285 /// Defaults to false.
286 ///
287 /// {@youtube 560 315 https://www.youtube.com/watch?v=LUqDNnv_dh0}
288 /// {@endtemplate}
289 final bool shrinkWrap;
290
291 /// The first child in the [GrowthDirection.forward] growth direction.
292 ///
293 /// Children after [center] will be placed in the [AxisDirection] determined
294 /// by [scrollDirection] and [reverse] relative to the [center]. Children
295 /// before [center] will be placed in the opposite of the axis direction
296 /// relative to the [center]. This makes the [center] the inflection point of
297 /// the growth direction.
298 ///
299 /// The [center] must be the key of one of the slivers built by [buildSlivers].
300 ///
301 /// Of the built-in subclasses of [ScrollView], only [CustomScrollView]
302 /// supports [center]; for that class, the given key must be the key of one of
303 /// the slivers in the [CustomScrollView.slivers] list.
304 ///
305 /// Most scroll views by default are ordered [GrowthDirection.forward].
306 /// Changing the default values of [ScrollView.anchor],
307 /// [ScrollView.center], or both, can configure a scroll view for
308 /// [GrowthDirection.reverse].
309 ///
310 /// {@tool dartpad}
311 /// This sample shows a [CustomScrollView], with [Radio] buttons in the
312 /// [AppBar.bottom] that change the [AxisDirection] to illustrate different
313 /// configurations. The [CustomScrollView.anchor] and [CustomScrollView.center]
314 /// properties are also set to have the 0 scroll offset positioned in the middle
315 /// of the viewport, with [GrowthDirection.forward] and [GrowthDirection.reverse]
316 /// illustrated on either side. The sliver that shares the
317 /// [CustomScrollView.center] key is positioned at the [CustomScrollView.anchor].
318 ///
319 /// ** See code in examples/api/lib/rendering/growth_direction/growth_direction.0.dart **
320 /// {@end-tool}
321 ///
322 /// See also:
323 ///
324 /// * [anchor], which controls where the [center] as aligned in the viewport.
325 final Key? center;
326
327 /// {@template flutter.widgets.scroll_view.anchor}
328 /// The relative position of the zero scroll offset.
329 ///
330 /// For example, if [anchor] is 0.5 and the [AxisDirection] determined by
331 /// [scrollDirection] and [reverse] is [AxisDirection.down] or
332 /// [AxisDirection.up], then the zero scroll offset is vertically centered
333 /// within the viewport. If the [anchor] is 1.0, and the axis direction is
334 /// [AxisDirection.right], then the zero scroll offset is on the left edge of
335 /// the viewport.
336 ///
337 /// Most scroll views by default are ordered [GrowthDirection.forward].
338 /// Changing the default values of [ScrollView.anchor],
339 /// [ScrollView.center], or both, can configure a scroll view for
340 /// [GrowthDirection.reverse].
341 ///
342 /// {@tool dartpad}
343 /// This sample shows a [CustomScrollView], with [Radio] buttons in the
344 /// [AppBar.bottom] that change the [AxisDirection] to illustrate different
345 /// configurations. The [CustomScrollView.anchor] and [CustomScrollView.center]
346 /// properties are also set to have the 0 scroll offset positioned in the middle
347 /// of the viewport, with [GrowthDirection.forward] and [GrowthDirection.reverse]
348 /// illustrated on either side. The sliver that shares the
349 /// [CustomScrollView.center] key is positioned at the [CustomScrollView.anchor].
350 ///
351 /// ** See code in examples/api/lib/rendering/growth_direction/growth_direction.0.dart **
352 /// {@end-tool}
353 /// {@endtemplate}
354 final double anchor;
355
356 /// {@macro flutter.rendering.RenderViewportBase.cacheExtent}
357 final double? cacheExtent;
358
359 /// The number of children that will contribute semantic information.
360 ///
361 /// Some subtypes of [ScrollView] can infer this value automatically. For
362 /// example [ListView] will use the number of widgets in the child list,
363 /// while the [ListView.separated] constructor will use half that amount.
364 ///
365 /// For [CustomScrollView] and other types which do not receive a builder
366 /// or list of widgets, the child count must be explicitly provided. If the
367 /// number is unknown or unbounded this should be left unset or set to null.
368 ///
369 /// See also:
370 ///
371 /// * [SemanticsConfiguration.scrollChildCount], the corresponding semantics property.
372 final int? semanticChildCount;
373
374 /// {@macro flutter.rendering.RenderViewportBase.paintOrder}
375 ///
376 /// Defaults to [SliverPaintOrder.firstIsTop].
377 final SliverPaintOrder paintOrder;
378
379 /// {@macro flutter.widgets.scrollable.dragStartBehavior}
380 final DragStartBehavior dragStartBehavior;
381
382 /// {@template flutter.widgets.scroll_view.keyboardDismissBehavior}
383 /// The [ScrollViewKeyboardDismissBehavior] defines how this [ScrollView] will
384 /// dismiss the keyboard automatically.
385 /// {@endtemplate}
386 ///
387 /// If [keyboardDismissBehavior] is null then it will fallback to
388 /// [scrollBehavior]. If that is also null, the inherited
389 /// [ScrollBehavior.getKeyboardDismissBehavior] will be used.
390 final ScrollViewKeyboardDismissBehavior? keyboardDismissBehavior;
391
392 /// {@macro flutter.widgets.scrollable.restorationId}
393 final String? restorationId;
394
395 /// {@macro flutter.material.Material.clipBehavior}
396 ///
397 /// Defaults to [Clip.hardEdge].
398 final Clip clipBehavior;
399
400 /// {@macro flutter.widgets.scrollable.hitTestBehavior}
401 ///
402 /// Defaults to [HitTestBehavior.opaque].
403 final HitTestBehavior hitTestBehavior;
404
405 /// Returns the [AxisDirection] in which the scroll view scrolls.
406 ///
407 /// Combines the [scrollDirection] with the [reverse] boolean to obtain the
408 /// concrete [AxisDirection].
409 ///
410 /// If the [scrollDirection] is [Axis.horizontal], the ambient
411 /// [Directionality] is also considered when selecting the concrete
412 /// [AxisDirection]. For example, if the ambient [Directionality] is
413 /// [TextDirection.rtl], then the non-reversed [AxisDirection] is
414 /// [AxisDirection.left] and the reversed [AxisDirection] is
415 /// [AxisDirection.right].
416 @protected
417 AxisDirection getDirection(BuildContext context) {
418 return getAxisDirectionFromAxisReverseAndDirectionality(context, scrollDirection, reverse);
419 }
420
421 /// Build the list of widgets to place inside the viewport.
422 ///
423 /// Subclasses should override this method to build the slivers for the inside
424 /// of the viewport.
425 ///
426 /// To learn more about slivers, see [CustomScrollView.slivers].
427 @protected
428 List<Widget> buildSlivers(BuildContext context);
429
430 /// Build the viewport.
431 ///
432 /// Subclasses may override this method to change how the viewport is built.
433 /// The default implementation uses a [ShrinkWrappingViewport] if [shrinkWrap]
434 /// is true, and a regular [Viewport] otherwise.
435 ///
436 /// The `offset` argument is the value obtained from
437 /// [Scrollable.viewportBuilder].
438 ///
439 /// The `axisDirection` argument is the value obtained from [getDirection],
440 /// which by default uses [scrollDirection] and [reverse].
441 ///
442 /// The `slivers` argument is the value obtained from [buildSlivers].
443 @protected
444 Widget buildViewport(
445 BuildContext context,
446 ViewportOffset offset,
447 AxisDirection axisDirection,
448 List<Widget> slivers,
449 ) {
450 assert(() {
451 switch (axisDirection) {
452 case AxisDirection.up:
453 case AxisDirection.down:
454 return debugCheckHasDirectionality(
455 context,
456 why: 'to determine the cross-axis direction of the scroll view',
457 hint:
458 'Vertical scroll views create Viewport widgets that try to determine their cross axis direction '
459 'from the ambient Directionality.',
460 );
461 case AxisDirection.left:
462 case AxisDirection.right:
463 return true;
464 }
465 }());
466 if (shrinkWrap) {
467 return ShrinkWrappingViewport(
468 axisDirection: axisDirection,
469 offset: offset,
470 slivers: slivers,
471 paintOrder: paintOrder,
472 clipBehavior: clipBehavior,
473 );
474 }
475 return Viewport(
476 axisDirection: axisDirection,
477 offset: offset,
478 slivers: slivers,
479 cacheExtent: cacheExtent,
480 center: center,
481 anchor: anchor,
482 paintOrder: paintOrder,
483 clipBehavior: clipBehavior,
484 );
485 }
486
487 @override
488 Widget build(BuildContext context) {
489 final List<Widget> slivers = buildSlivers(context);
490 final AxisDirection axisDirection = getDirection(context);
491
492 final bool effectivePrimary =
493 primary ??
494 controller == null && PrimaryScrollController.shouldInherit(context, scrollDirection);
495
496 final ScrollController? scrollController = effectivePrimary
497 ? PrimaryScrollController.maybeOf(context)
498 : controller;
499
500 final Scrollable scrollable = Scrollable(
501 dragStartBehavior: dragStartBehavior,
502 axisDirection: axisDirection,
503 controller: scrollController,
504 physics: physics,
505 scrollBehavior: scrollBehavior,
506 semanticChildCount: semanticChildCount,
507 restorationId: restorationId,
508 hitTestBehavior: hitTestBehavior,
509 viewportBuilder: (BuildContext context, ViewportOffset offset) {
510 return buildViewport(context, offset, axisDirection, slivers);
511 },
512 clipBehavior: clipBehavior,
513 );
514
515 final Widget scrollableResult = effectivePrimary && scrollController != null
516 // Further descendant ScrollViews will not inherit the same PrimaryScrollController
517 ? PrimaryScrollController.none(child: scrollable)
518 : scrollable;
519
520 final ScrollViewKeyboardDismissBehavior effectiveKeyboardDismissBehavior =
521 keyboardDismissBehavior ??
522 scrollBehavior?.getKeyboardDismissBehavior(context) ??
523 ScrollConfiguration.of(context).getKeyboardDismissBehavior(context);
524
525 if (effectiveKeyboardDismissBehavior == ScrollViewKeyboardDismissBehavior.onDrag) {
526 return NotificationListener<ScrollUpdateNotification>(
527 child: scrollableResult,
528 onNotification: (ScrollUpdateNotification notification) {
529 final FocusScopeNode currentScope = FocusScope.of(context);
530 if (notification.dragDetails != null &&
531 !currentScope.hasPrimaryFocus &&
532 currentScope.hasFocus) {
533 FocusManager.instance.primaryFocus?.unfocus();
534 }
535 return false;
536 },
537 );
538 } else {
539 return scrollableResult;
540 }
541 }
542
543 @override
544 void debugFillProperties(DiagnosticPropertiesBuilder properties) {
545 super.debugFillProperties(properties);
546 properties.add(EnumProperty<Axis>('scrollDirection', scrollDirection));
547 properties.add(FlagProperty('reverse', value: reverse, ifTrue: 'reversed', showName: true));
548 properties.add(
549 DiagnosticsProperty<ScrollController>(
550 'controller',
551 controller,
552 showName: false,
553 defaultValue: null,
554 ),
555 );
556 properties.add(
557 FlagProperty('primary', value: primary, ifTrue: 'using primary controller', showName: true),
558 );
559 properties.add(
560 DiagnosticsProperty<ScrollPhysics>('physics', physics, showName: false, defaultValue: null),
561 );
562 properties.add(
563 FlagProperty('shrinkWrap', value: shrinkWrap, ifTrue: 'shrink-wrapping', showName: true),
564 );
565 }
566}
567
568/// A [ScrollView] that creates custom scroll effects using [slivers].
569///
570/// A [CustomScrollView] lets you supply [slivers] directly to create various
571/// scrolling effects, such as lists, grids, and expanding headers. For example,
572/// to create a scroll view that contains an expanding app bar followed by a
573/// list and a grid, use a list of three slivers: [SliverAppBar], [SliverList],
574/// and [SliverGrid].
575///
576/// [Widget]s in these [slivers] must produce [RenderSliver] objects.
577///
578/// To control the initial scroll offset of the scroll view, provide a
579/// [controller] with its [ScrollController.initialScrollOffset] property set.
580///
581/// {@animation 400 376 https://flutter.github.io/assets-for-api-docs/assets/widgets/custom_scroll_view.mp4}
582///
583/// {@tool snippet}
584///
585/// This sample code shows a scroll view that contains a flexible pinned app
586/// bar, a grid, and an infinite list.
587///
588/// ```dart
589/// CustomScrollView(
590/// slivers: <Widget>[
591/// const SliverAppBar(
592/// pinned: true,
593/// expandedHeight: 250.0,
594/// flexibleSpace: FlexibleSpaceBar(
595/// title: Text('Demo'),
596/// ),
597/// ),
598/// SliverGrid(
599/// gridDelegate: const SliverGridDelegateWithMaxCrossAxisExtent(
600/// maxCrossAxisExtent: 200.0,
601/// mainAxisSpacing: 10.0,
602/// crossAxisSpacing: 10.0,
603/// childAspectRatio: 4.0,
604/// ),
605/// delegate: SliverChildBuilderDelegate(
606/// (BuildContext context, int index) {
607/// return Container(
608/// alignment: Alignment.center,
609/// color: Colors.teal[100 * (index % 9)],
610/// child: Text('Grid Item $index'),
611/// );
612/// },
613/// childCount: 20,
614/// ),
615/// ),
616/// SliverFixedExtentList(
617/// itemExtent: 50.0,
618/// delegate: SliverChildBuilderDelegate(
619/// (BuildContext context, int index) {
620/// return Container(
621/// alignment: Alignment.center,
622/// color: Colors.lightBlue[100 * (index % 9)],
623/// child: Text('List Item $index'),
624/// );
625/// },
626/// ),
627/// ),
628/// ],
629/// )
630/// ```
631/// {@end-tool}
632///
633/// {@tool dartpad}
634/// By default, if items are inserted at the "top" of a scrolling container like
635/// [ListView] or [CustomScrollView], the top item and all of the items below it
636/// are scrolled downwards. In some applications, it's preferable to have the
637/// top of the list just grow upwards, without changing the scroll position.
638/// This example demonstrates how to do that with a [CustomScrollView] with
639/// two [SliverList] children, and the [CustomScrollView.center] set to the key
640/// of the bottom SliverList. The top one SliverList will grow upwards, and the
641/// bottom SliverList will grow downwards.
642///
643/// ** See code in examples/api/lib/widgets/scroll_view/custom_scroll_view.1.dart **
644/// {@end-tool}
645///
646/// ## Accessibility
647///
648/// A [CustomScrollView] can allow Talkback/VoiceOver to make announcements
649/// to the user when the scroll state changes. For example, on Android an
650/// announcement might be read as "showing items 1 to 10 of 23". To produce
651/// this announcement, the scroll view needs three pieces of information:
652///
653/// * The first visible child index.
654/// * The total number of children.
655/// * The total number of visible children.
656///
657/// The last value can be computed exactly by the framework, however the first
658/// two must be provided. Most of the higher-level scrollable widgets provide
659/// this information automatically. For example, [ListView] provides each child
660/// widget with a semantic index automatically and sets the semantic child
661/// count to the length of the list.
662///
663/// To determine visible indexes, the scroll view needs a way to associate the
664/// generated semantics of each scrollable item with a semantic index. This can
665/// be done by wrapping the child widgets in an [IndexedSemantics].
666///
667/// This semantic index is not necessarily the same as the index of the widget in
668/// the scrollable, because some widgets may not contribute semantic
669/// information. Consider a [ListView.separated]: every other widget is a
670/// divider with no semantic information. In this case, only odd numbered
671/// widgets have a semantic index (equal to the index ~/ 2). Furthermore, the
672/// total number of children in this example would be half the number of
673/// widgets. (The [ListView.separated] constructor handles this
674/// automatically; this is only used here as an example.)
675///
676/// The total number of visible children can be provided by the constructor
677/// parameter `semanticChildCount`. This should always be the same as the
678/// number of widgets wrapped in [IndexedSemantics].
679///
680/// {@macro flutter.widgets.ScrollView.PageStorage}
681///
682/// See also:
683///
684/// * [SliverList], which is a sliver that displays linear list of children.
685/// * [SliverFixedExtentList], which is a more efficient sliver that displays
686/// linear list of children that have the same extent along the scroll axis.
687/// * [SliverGrid], which is a sliver that displays a 2D array of children.
688/// * [SliverPadding], which is a sliver that adds blank space around another
689/// sliver.
690/// * [SliverAppBar], which is a sliver that displays a header that can expand
691/// and float as the scroll view scrolls.
692/// * [ScrollNotification] and [NotificationListener], which can be used to watch
693/// the scroll position without using a [ScrollController].
694/// * [IndexedSemantics], which allows annotating child lists with an index
695/// for scroll announcements.
696class CustomScrollView extends ScrollView {
697 /// Creates a [ScrollView] that creates custom scroll effects using slivers.
698 ///
699 /// See the [ScrollView] constructor for more details on these arguments.
700 const CustomScrollView({
701 super.key,
702 super.scrollDirection,
703 super.reverse,
704 super.controller,
705 super.primary,
706 super.physics,
707 super.scrollBehavior,
708 super.shrinkWrap,
709 super.center,
710 super.anchor,
711 super.cacheExtent,
712 super.paintOrder,
713 this.slivers = const <Widget>[],
714 super.semanticChildCount,
715 super.dragStartBehavior,
716 super.keyboardDismissBehavior,
717 super.restorationId,
718 super.clipBehavior,
719 super.hitTestBehavior,
720 });
721
722 /// The slivers to place inside the viewport.
723 ///
724 /// ## What is a sliver?
725 ///
726 /// > _**sliver** (noun): a small, thin piece of something._
727 ///
728 /// A _sliver_ is a widget backed by a [RenderSliver] subclass, i.e. one that
729 /// implements the constraint/geometry protocol that uses [SliverConstraints]
730 /// and [SliverGeometry].
731 ///
732 /// This is as distinct from those widgets that are backed by [RenderBox]
733 /// subclasses, which use [BoxConstraints] and [Size] respectively, and are
734 /// known as box widgets. (Widgets like [Container], [Row], and [SizedBox] are
735 /// box widgets.)
736 ///
737 /// While boxes are much more straightforward (implementing a simple
738 /// two-dimensional Cartesian layout system), slivers are much more powerful,
739 /// and are optimized for one-axis scrolling environments.
740 ///
741 /// Slivers are hosted in viewports, also known as scroll views, most notably
742 /// [CustomScrollView].
743 ///
744 /// ## Examples of slivers
745 ///
746 /// The Flutter framework has many built-in sliver widgets, and custom widgets
747 /// can be created in the same manner. By convention, sliver widgets always
748 /// start with the prefix `Sliver` and are always used in properties called
749 /// `sliver` or `slivers` (as opposed to `child` and `children` which are used
750 /// for box widgets).
751 ///
752 /// Examples of widgets unique to the sliver world include:
753 ///
754 /// * [SliverList], a lazily-loading list of variably-sized box widgets.
755 /// * [SliverFixedExtentList], a lazily-loading list of box widgets that are
756 /// all forced to the same height.
757 /// * [SliverPrototypeExtentList], a lazily-loading list of box widgets that
758 /// are all forced to the same height as a given prototype widget.
759 /// * [SliverGrid], a lazily-loading grid of box widgets.
760 /// * [SliverAnimatedList] and [SliverAnimatedGrid], animated variants of
761 /// [SliverList] and [SliverGrid].
762 /// * [SliverFillRemaining], a widget that fills all remaining space in a
763 /// scroll view, and lays a box widget out inside that space.
764 /// * [SliverFillViewport], a widget that lays a list of boxes out, each
765 /// being sized to fit the whole viewport.
766 /// * [SliverPersistentHeader], a sliver that implements pinned and floating
767 /// headers, e.g. used to implement [SliverAppBar].
768 /// * [SliverToBoxAdapter], a sliver that wraps a box widget.
769 ///
770 /// Examples of sliver variants of common box widgets include:
771 ///
772 /// * [SliverOpacity], [SliverAnimatedOpacity], and [SliverFadeTransition],
773 /// sliver versions of [Opacity], [AnimatedOpacity], and [FadeTransition].
774 /// * [SliverIgnorePointer], a sliver version of [IgnorePointer].
775 /// * [SliverLayoutBuilder], a sliver version of [LayoutBuilder].
776 /// * [SliverOffstage], a sliver version of [Offstage].
777 /// * [SliverPadding], a sliver version of [Padding].
778 /// * [SliverReorderableList], a sliver version of [ReorderableList]
779 /// * [SliverSafeArea], a sliver version of [SafeArea].
780 /// * [SliverVisibility], a sliver version of [Visibility].
781 ///
782 /// ## Benefits of slivers over boxes
783 ///
784 /// The sliver protocol ([SliverConstraints] and [SliverGeometry]) enables
785 /// _scroll effects_, such as floating app bars, widgets that expand and
786 /// shrink during scroll, section headers that are pinned only while the
787 /// section's children are visible, etc.
788 ///
789 /// {@youtube 560 315 https://www.youtube.com/watch?v=Mz3kHQxBjGg}
790 ///
791 /// ## Mixing slivers and boxes
792 ///
793 /// In general, slivers always wrap box widgets to actually render anything
794 /// (for example, there is no sliver equivalent of [Text] or [Container]);
795 /// the sliver part of the equation is mostly about how these boxes should
796 /// be laid out in a viewport (i.e. when scrolling).
797 ///
798 /// Typically, the simplest way to combine boxes into a sliver environment is
799 /// to use a [SliverList] (maybe using a [ListView], which is a convenient
800 /// combination of a [CustomScrollView] and a [SliverList]). In rare cases,
801 /// e.g. if a single [Divider] widget is needed between two [SliverGrid]s,
802 /// a [SliverToBoxAdapter] can be used to wrap the box widgets.
803 ///
804 /// ## Performance considerations
805 ///
806 /// Because the purpose of scroll views is to, well, scroll, it is common
807 /// for scroll views to contain more contents than are rendered on the screen
808 /// at any particular time.
809 ///
810 /// To improve the performance of scroll views, the content can be rendered in
811 /// _lazy_ widgets, notably [SliverList] and [SliverGrid] (and their variants,
812 /// such as [SliverFixedExtentList] and [SliverAnimatedGrid]). These widgets
813 /// ensure that only the portion of their child lists that are actually
814 /// visible get built, laid out, and painted.
815 ///
816 /// The [ListView] and [GridView] widgets provide a convenient way to combine
817 /// a [CustomScrollView] and a [SliverList] or [SliverGrid] (respectively).
818 final List<Widget> slivers;
819
820 @override
821 List<Widget> buildSlivers(BuildContext context) => slivers;
822}
823
824/// A [ScrollView] that uses a single child layout model.
825///
826/// {@template flutter.widgets.BoxScroll.scrollBehaviour}
827/// [ScrollView]s are often decorated with [Scrollbar]s and overscroll indicators,
828/// which are managed by the inherited [ScrollBehavior]. Placing a
829/// [ScrollConfiguration] above a ScrollView can modify these behaviors for that
830/// ScrollView, or can be managed app-wide by providing a ScrollBehavior to
831/// [MaterialApp.scrollBehavior] or [CupertinoApp.scrollBehavior].
832/// {@endtemplate}
833///
834/// See also:
835///
836/// * [ListView], which is a [BoxScrollView] that uses a linear layout model.
837/// * [GridView], which is a [BoxScrollView] that uses a 2D layout model.
838/// * [CustomScrollView], which can combine multiple child layout models into a
839/// single scroll view.
840abstract class BoxScrollView extends ScrollView {
841 /// Creates a [ScrollView] uses a single child layout model.
842 ///
843 /// If the [primary] argument is true, the [controller] must be null.
844 const BoxScrollView({
845 super.key,
846 super.scrollDirection,
847 super.reverse,
848 super.controller,
849 super.primary,
850 super.physics,
851 super.shrinkWrap,
852 this.padding,
853 super.cacheExtent,
854 super.semanticChildCount,
855 super.dragStartBehavior,
856 super.keyboardDismissBehavior,
857 super.restorationId,
858 super.clipBehavior,
859 super.hitTestBehavior,
860 });
861
862 /// The amount of space by which to inset the children.
863 final EdgeInsetsGeometry? padding;
864
865 @override
866 List<Widget> buildSlivers(BuildContext context) {
867 Widget sliver = buildChildLayout(context);
868 EdgeInsetsGeometry? effectivePadding = padding;
869 if (padding == null) {
870 final MediaQueryData? mediaQuery = MediaQuery.maybeOf(context);
871 if (mediaQuery != null) {
872 // Automatically pad sliver with padding from MediaQuery.
873 final EdgeInsets mediaQueryHorizontalPadding = mediaQuery.padding.copyWith(
874 top: 0.0,
875 bottom: 0.0,
876 );
877 final EdgeInsets mediaQueryVerticalPadding = mediaQuery.padding.copyWith(
878 left: 0.0,
879 right: 0.0,
880 );
881 // Consume the main axis padding with SliverPadding.
882 effectivePadding = scrollDirection == Axis.vertical
883 ? mediaQueryVerticalPadding
884 : mediaQueryHorizontalPadding;
885 // Leave behind the cross axis padding.
886 sliver = MediaQuery(
887 data: mediaQuery.copyWith(
888 padding: scrollDirection == Axis.vertical
889 ? mediaQueryHorizontalPadding
890 : mediaQueryVerticalPadding,
891 ),
892 child: sliver,
893 );
894 }
895 }
896
897 if (effectivePadding != null) {
898 sliver = SliverPadding(padding: effectivePadding, sliver: sliver);
899 }
900 return <Widget>[sliver];
901 }
902
903 /// Subclasses should override this method to build the layout model.
904 @protected
905 Widget buildChildLayout(BuildContext context);
906
907 @override
908 void debugFillProperties(DiagnosticPropertiesBuilder properties) {
909 super.debugFillProperties(properties);
910 properties.add(DiagnosticsProperty<EdgeInsetsGeometry>('padding', padding, defaultValue: null));
911 }
912}
913
914/// A scrollable list of widgets arranged linearly.
915///
916/// {@youtube 560 315 https://www.youtube.com/watch?v=KJpkjHGiI5A}
917///
918/// [ListView] is the most commonly used scrolling widget. It displays its
919/// children one after another in the scroll direction. In the cross axis, the
920/// children are required to fill the [ListView].
921///
922/// If non-null, the [itemExtent] forces the children to have the given extent
923/// in the scroll direction.
924///
925/// If non-null, the [prototypeItem] forces the children to have the same extent
926/// as the given widget in the scroll direction.
927///
928/// Specifying an [itemExtent] or an [prototypeItem] is more efficient than
929/// letting the children determine their own extent because the scrolling
930/// machinery can make use of the foreknowledge of the children's extent to save
931/// work, for example when the scroll position changes drastically.
932///
933/// You can't specify both [itemExtent] and [prototypeItem], only one or none of
934/// them.
935///
936/// There are four options for constructing a [ListView]:
937///
938/// 1. The default constructor takes an explicit [List<Widget>] of children. This
939/// constructor is appropriate for list views with a small number of
940/// children because constructing the [List] requires doing work for every
941/// child that could possibly be displayed in the list view instead of just
942/// those children that are actually visible.
943///
944/// 2. The [ListView.builder] constructor takes an [IndexedWidgetBuilder], which
945/// builds the children on demand. This constructor is appropriate for list views
946/// with a large (or infinite) number of children because the builder is called
947/// only for those children that are actually visible.
948///
949/// 3. The [ListView.separated] constructor takes two [IndexedWidgetBuilder]s:
950/// `itemBuilder` builds child items on demand, and `separatorBuilder`
951/// similarly builds separator children which appear in between the child items.
952/// This constructor is appropriate for list views with a fixed number of children.
953///
954/// 4. The [ListView.custom] constructor takes a [SliverChildDelegate], which provides
955/// the ability to customize additional aspects of the child model. For example,
956/// a [SliverChildDelegate] can control the algorithm used to estimate the
957/// size of children that are not actually visible.
958///
959/// To control the initial scroll offset of the scroll view, provide a
960/// [controller] with its [ScrollController.initialScrollOffset] property set.
961///
962/// By default, [ListView] will automatically pad the list's scrollable
963/// extremities to avoid partial obstructions indicated by [MediaQuery]'s
964/// padding. To avoid this behavior, override with a zero [padding] property.
965///
966/// {@tool snippet}
967/// This example uses the default constructor for [ListView] which takes an
968/// explicit [List<Widget>] of children. This [ListView]'s children are made up
969/// of [Container]s with [Text].
970///
971/// ![A ListView of 3 amber colored containers with sample text.](https://flutter.github.io/assets-for-api-docs/assets/widgets/list_view.png)
972///
973/// ```dart
974/// ListView(
975/// padding: const EdgeInsets.all(8),
976/// children: <Widget>[
977/// Container(
978/// height: 50,
979/// color: Colors.amber[600],
980/// child: const Center(child: Text('Entry A')),
981/// ),
982/// Container(
983/// height: 50,
984/// color: Colors.amber[500],
985/// child: const Center(child: Text('Entry B')),
986/// ),
987/// Container(
988/// height: 50,
989/// color: Colors.amber[100],
990/// child: const Center(child: Text('Entry C')),
991/// ),
992/// ],
993/// )
994/// ```
995/// {@end-tool}
996///
997/// {@tool snippet}
998/// This example mirrors the previous one, creating the same list using the
999/// [ListView.builder] constructor. Using the [IndexedWidgetBuilder], children
1000/// are built lazily and can be infinite in number.
1001///
1002/// ![A ListView of 3 amber colored containers with sample text.](https://flutter.github.io/assets-for-api-docs/assets/widgets/list_view_builder.png)
1003///
1004/// ```dart
1005/// final List<String> entries = <String>['A', 'B', 'C'];
1006/// final List<int> colorCodes = <int>[600, 500, 100];
1007///
1008/// Widget build(BuildContext context) {
1009/// return ListView.builder(
1010/// padding: const EdgeInsets.all(8),
1011/// itemCount: entries.length,
1012/// itemBuilder: (BuildContext context, int index) {
1013/// return Container(
1014/// height: 50,
1015/// color: Colors.amber[colorCodes[index]],
1016/// child: Center(child: Text('Entry ${entries[index]}')),
1017/// );
1018/// }
1019/// );
1020/// }
1021/// ```
1022/// {@end-tool}
1023///
1024/// {@tool snippet}
1025/// This example continues to build from our the previous ones, creating a
1026/// similar list using [ListView.separated]. Here, a [Divider] is used as a
1027/// separator.
1028///
1029/// ![A ListView of 3 amber colored containers with sample text and a Divider
1030/// between each of them.](https://flutter.github.io/assets-for-api-docs/assets/widgets/list_view_separated.png)
1031///
1032/// ```dart
1033/// final List<String> entries = <String>['A', 'B', 'C'];
1034/// final List<int> colorCodes = <int>[600, 500, 100];
1035///
1036/// Widget build(BuildContext context) {
1037/// return ListView.separated(
1038/// padding: const EdgeInsets.all(8),
1039/// itemCount: entries.length,
1040/// itemBuilder: (BuildContext context, int index) {
1041/// return Container(
1042/// height: 50,
1043/// color: Colors.amber[colorCodes[index]],
1044/// child: Center(child: Text('Entry ${entries[index]}')),
1045/// );
1046/// },
1047/// separatorBuilder: (BuildContext context, int index) => const Divider(),
1048/// );
1049/// }
1050/// ```
1051/// {@end-tool}
1052///
1053/// ## Child elements' lifecycle
1054///
1055/// ### Creation
1056///
1057/// While laying out the list, visible children's elements, states and render
1058/// objects will be created lazily based on existing widgets (such as when using
1059/// the default constructor) or lazily provided ones (such as when using the
1060/// [ListView.builder] constructor).
1061///
1062/// ### Destruction
1063///
1064/// When a child is scrolled out of view, the associated element subtree,
1065/// states and render objects are destroyed. A new child at the same position
1066/// in the list will be lazily recreated along with new elements, states and
1067/// render objects when it is scrolled back.
1068///
1069/// ### Destruction mitigation
1070///
1071/// In order to preserve state as child elements are scrolled in and out of
1072/// view, the following options are possible:
1073///
1074/// * Moving the ownership of non-trivial UI-state-driving business logic
1075/// out of the list child subtree. For instance, if a list contains posts
1076/// with their number of upvotes coming from a cached network response, store
1077/// the list of posts and upvote number in a data model outside the list. Let
1078/// the list child UI subtree be easily recreate-able from the
1079/// source-of-truth model object. Use [StatefulWidget]s in the child
1080/// widget subtree to store instantaneous UI state only.
1081///
1082/// * Letting [KeepAlive] be the root widget of the list child widget subtree
1083/// that needs to be preserved. The [KeepAlive] widget marks the child
1084/// subtree's top render object child for keepalive. When the associated top
1085/// render object is scrolled out of view, the list keeps the child's render
1086/// object (and by extension, its associated elements and states) in a cache
1087/// list instead of destroying them. When scrolled back into view, the render
1088/// object is repainted as-is (if it wasn't marked dirty in the interim).
1089///
1090/// This only works if `addAutomaticKeepAlives` and `addRepaintBoundaries`
1091/// are false since those parameters cause the [ListView] to wrap each child
1092/// widget subtree with other widgets.
1093///
1094/// * Using [AutomaticKeepAlive] widgets (inserted by default when
1095/// `addAutomaticKeepAlives` is true). [AutomaticKeepAlive] allows descendant
1096/// widgets to control whether the subtree is actually kept alive or not.
1097/// This behavior is in contrast with [KeepAlive], which will unconditionally keep
1098/// the subtree alive.
1099///
1100/// As an example, the [EditableText] widget signals its list child element
1101/// subtree to stay alive while its text field has input focus. If it doesn't
1102/// have focus and no other descendants signaled for keepalive via a
1103/// [KeepAliveNotification], the list child element subtree will be destroyed
1104/// when scrolled away.
1105///
1106/// [AutomaticKeepAlive] descendants typically signal it to be kept alive
1107/// by using the [AutomaticKeepAliveClientMixin], then implementing the
1108/// [AutomaticKeepAliveClientMixin.wantKeepAlive] getter and calling
1109/// [AutomaticKeepAliveClientMixin.updateKeepAlive].
1110///
1111/// ## Transitioning to [CustomScrollView]
1112///
1113/// A [ListView] is basically a [CustomScrollView] with a single [SliverList] in
1114/// its [CustomScrollView.slivers] property.
1115///
1116/// If [ListView] is no longer sufficient, for example because the scroll view
1117/// is to have both a list and a grid, or because the list is to be combined
1118/// with a [SliverAppBar], etc, it is straight-forward to port code from using
1119/// [ListView] to using [CustomScrollView] directly.
1120///
1121/// The [key], [scrollDirection], [reverse], [controller], [primary], [physics],
1122/// and [shrinkWrap] properties on [ListView] map directly to the identically
1123/// named properties on [CustomScrollView].
1124///
1125/// The [CustomScrollView.slivers] property should be a list containing either:
1126/// * a [SliverList] if both [itemExtent] and [prototypeItem] were null;
1127/// * a [SliverFixedExtentList] if [itemExtent] was not null; or
1128/// * a [SliverPrototypeExtentList] if [prototypeItem] was not null.
1129///
1130/// The [childrenDelegate] property on [ListView] corresponds to the
1131/// [SliverList.delegate] (or [SliverFixedExtentList.delegate]) property. The
1132/// [ListView] constructor's `children` argument corresponds to the
1133/// [childrenDelegate] being a [SliverChildListDelegate] with that same
1134/// argument. The [ListView.builder] constructor's `itemBuilder` and
1135/// `itemCount` arguments correspond to the [childrenDelegate] being a
1136/// [SliverChildBuilderDelegate] with the equivalent arguments.
1137///
1138/// The [padding] property corresponds to having a [SliverPadding] in the
1139/// [CustomScrollView.slivers] property instead of the list itself, and having
1140/// the [SliverList] instead be a child of the [SliverPadding].
1141///
1142/// [CustomScrollView]s don't automatically avoid obstructions from [MediaQuery]
1143/// like [ListView]s do. To reproduce the behavior, wrap the slivers in
1144/// [SliverSafeArea]s.
1145///
1146/// Once code has been ported to use [CustomScrollView], other slivers, such as
1147/// [SliverGrid] or [SliverAppBar], can be put in the [CustomScrollView.slivers]
1148/// list.
1149///
1150/// {@tool snippet}
1151///
1152/// Here are two brief snippets showing a [ListView] and its equivalent using
1153/// [CustomScrollView]:
1154///
1155/// ```dart
1156/// ListView(
1157/// padding: const EdgeInsets.all(20.0),
1158/// children: const <Widget>[
1159/// Text("I'm dedicating every day to you"),
1160/// Text('Domestic life was never quite my style'),
1161/// Text('When you smile, you knock me out, I fall apart'),
1162/// Text('And I thought I was so smart'),
1163/// ],
1164/// )
1165/// ```
1166/// {@end-tool}
1167/// {@tool snippet}
1168///
1169/// ```dart
1170/// CustomScrollView(
1171/// slivers: <Widget>[
1172/// SliverPadding(
1173/// padding: const EdgeInsets.all(20.0),
1174/// sliver: SliverList(
1175/// delegate: SliverChildListDelegate(
1176/// <Widget>[
1177/// const Text("I'm dedicating every day to you"),
1178/// const Text('Domestic life was never quite my style'),
1179/// const Text('When you smile, you knock me out, I fall apart'),
1180/// const Text('And I thought I was so smart'),
1181/// ],
1182/// ),
1183/// ),
1184/// ),
1185/// ],
1186/// )
1187/// ```
1188/// {@end-tool}
1189///
1190/// ## Special handling for an empty list
1191///
1192/// A common design pattern is to have a custom UI for an empty list. The best
1193/// way to achieve this in Flutter is just conditionally replacing the
1194/// [ListView] at build time with whatever widgets you need to show for the
1195/// empty list state:
1196///
1197/// {@tool snippet}
1198///
1199/// Example of simple empty list interface:
1200///
1201/// ```dart
1202/// Widget build(BuildContext context) {
1203/// return Scaffold(
1204/// appBar: AppBar(title: const Text('Empty List Test')),
1205/// body: itemCount > 0
1206/// ? ListView.builder(
1207/// itemCount: itemCount,
1208/// itemBuilder: (BuildContext context, int index) {
1209/// return ListTile(
1210/// title: Text('Item ${index + 1}'),
1211/// );
1212/// },
1213/// )
1214/// : const Center(child: Text('No items')),
1215/// );
1216/// }
1217/// ```
1218/// {@end-tool}
1219///
1220/// ## Selection of list items
1221///
1222/// [ListView] has no built-in notion of a selected item or items. For a small
1223/// example of how a caller might wire up basic item selection, see
1224/// [ListTile.selected].
1225///
1226/// {@tool dartpad}
1227/// This example shows a custom implementation of [ListTile] selection in a [ListView] or [GridView].
1228/// Long press any [ListTile] to enable selection mode.
1229///
1230/// ** See code in examples/api/lib/widgets/scroll_view/list_view.0.dart **
1231/// {@end-tool}
1232///
1233/// {@macro flutter.widgets.BoxScroll.scrollBehaviour}
1234///
1235/// {@macro flutter.widgets.ScrollView.PageStorage}
1236///
1237/// See also:
1238///
1239/// * [SingleChildScrollView], which is a scrollable widget that has a single
1240/// child.
1241/// * [PageView], which is a scrolling list of child widgets that are each the
1242/// size of the viewport.
1243/// * [GridView], which is a scrollable, 2D array of widgets.
1244/// * [CustomScrollView], which is a scrollable widget that creates custom
1245/// scroll effects using slivers.
1246/// * [ListBody], which arranges its children in a similar manner, but without
1247/// scrolling.
1248/// * [ScrollNotification] and [NotificationListener], which can be used to watch
1249/// the scroll position without using a [ScrollController].
1250/// * The [catalog of layout widgets](https://docs.flutter.dev/ui/widgets/layout).
1251/// * Cookbook: [Use lists](https://docs.flutter.dev/cookbook/lists/basic-list)
1252/// * Cookbook: [Work with long lists](https://docs.flutter.dev/cookbook/lists/long-lists)
1253/// * Cookbook: [Create a horizontal list](https://docs.flutter.dev/cookbook/lists/horizontal-list)
1254/// * Cookbook: [Create lists with different types of items](https://docs.flutter.dev/cookbook/lists/mixed-list)
1255/// * Cookbook: [Implement swipe to dismiss](https://docs.flutter.dev/cookbook/gestures/dismissible)
1256class ListView extends BoxScrollView {
1257 /// Creates a scrollable, linear array of widgets from an explicit [List].
1258 ///
1259 /// This constructor is appropriate for list views with a small number of
1260 /// children because constructing the [List] requires doing work for every
1261 /// child that could possibly be displayed in the list view instead of just
1262 /// those children that are actually visible.
1263 ///
1264 /// Like other widgets in the framework, this widget expects that
1265 /// the [children] list will not be mutated after it has been passed in here.
1266 /// See the documentation at [SliverChildListDelegate.children] for more details.
1267 ///
1268 /// It is usually more efficient to create children on demand using
1269 /// [ListView.builder] because it will create the widget children lazily as necessary.
1270 ///
1271 /// The `addAutomaticKeepAlives` argument corresponds to the
1272 /// [SliverChildListDelegate.addAutomaticKeepAlives] property. The
1273 /// `addRepaintBoundaries` argument corresponds to the
1274 /// [SliverChildListDelegate.addRepaintBoundaries] property. The
1275 /// `addSemanticIndexes` argument corresponds to the
1276 /// [SliverChildListDelegate.addSemanticIndexes] property. None
1277 /// may be null.
1278 ListView({
1279 super.key,
1280 super.scrollDirection,
1281 super.reverse,
1282 super.controller,
1283 super.primary,
1284 super.physics,
1285 super.shrinkWrap,
1286 super.padding,
1287 this.itemExtent,
1288 this.itemExtentBuilder,
1289 this.prototypeItem,
1290 bool addAutomaticKeepAlives = true,
1291 bool addRepaintBoundaries = true,
1292 bool addSemanticIndexes = true,
1293 super.cacheExtent,
1294 List<Widget> children = const <Widget>[],
1295 int? semanticChildCount,
1296 super.dragStartBehavior,
1297 super.keyboardDismissBehavior,
1298 super.restorationId,
1299 super.clipBehavior,
1300 super.hitTestBehavior,
1301 }) : assert(
1302 (itemExtent == null && prototypeItem == null) ||
1303 (itemExtent == null && itemExtentBuilder == null) ||
1304 (prototypeItem == null && itemExtentBuilder == null),
1305 'You can only pass one of itemExtent, prototypeItem and itemExtentBuilder.',
1306 ),
1307 childrenDelegate = SliverChildListDelegate(
1308 children,
1309 addAutomaticKeepAlives: addAutomaticKeepAlives,
1310 addRepaintBoundaries: addRepaintBoundaries,
1311 addSemanticIndexes: addSemanticIndexes,
1312 ),
1313 super(semanticChildCount: semanticChildCount ?? children.length);
1314
1315 /// Creates a scrollable, linear array of widgets that are created on demand.
1316 ///
1317 /// This constructor is appropriate for list views with a large (or infinite)
1318 /// number of children because the builder is called only for those children
1319 /// that are actually visible.
1320 ///
1321 /// Providing a non-null `itemCount` improves the ability of the [ListView] to
1322 /// estimate the maximum scroll extent.
1323 ///
1324 /// The `itemBuilder` callback will be called only with indices greater than
1325 /// or equal to zero and less than `itemCount`.
1326 ///
1327 /// {@template flutter.widgets.ListView.builder.itemBuilder}
1328 /// It is legal for `itemBuilder` to return `null`. If it does, the scroll view
1329 /// will stop calling `itemBuilder`, even if it has yet to reach `itemCount`.
1330 /// By returning `null`, the [ScrollPosition.maxScrollExtent] will not be accurate
1331 /// unless the user has reached the end of the [ScrollView]. This can also cause the
1332 /// [Scrollbar] to grow as the user scrolls.
1333 ///
1334 /// For more accurate [ScrollMetrics], consider specifying `itemCount`.
1335 /// {@endtemplate}
1336 ///
1337 /// The `itemBuilder` should always create the widget instances when called.
1338 /// Avoid using a builder that returns a previously-constructed widget; if the
1339 /// list view's children are created in advance, or all at once when the
1340 /// [ListView] itself is created, it is more efficient to use the [ListView]
1341 /// constructor. Even more efficient, however, is to create the instances on
1342 /// demand using this constructor's `itemBuilder` callback.
1343 ///
1344 /// {@macro flutter.widgets.PageView.findChildIndexCallback}
1345 ///
1346 /// The `addAutomaticKeepAlives` argument corresponds to the
1347 /// [SliverChildBuilderDelegate.addAutomaticKeepAlives] property. The
1348 /// `addRepaintBoundaries` argument corresponds to the
1349 /// [SliverChildBuilderDelegate.addRepaintBoundaries] property. The
1350 /// `addSemanticIndexes` argument corresponds to the
1351 /// [SliverChildBuilderDelegate.addSemanticIndexes] property. None may be
1352 /// null.
1353 ListView.builder({
1354 super.key,
1355 super.scrollDirection,
1356 super.reverse,
1357 super.controller,
1358 super.primary,
1359 super.physics,
1360 super.shrinkWrap,
1361 super.padding,
1362 this.itemExtent,
1363 this.itemExtentBuilder,
1364 this.prototypeItem,
1365 required NullableIndexedWidgetBuilder itemBuilder,
1366 ChildIndexGetter? findChildIndexCallback,
1367 int? itemCount,
1368 bool addAutomaticKeepAlives = true,
1369 bool addRepaintBoundaries = true,
1370 bool addSemanticIndexes = true,
1371 super.cacheExtent,
1372 int? semanticChildCount,
1373 super.dragStartBehavior,
1374 super.keyboardDismissBehavior,
1375 super.restorationId,
1376 super.clipBehavior,
1377 super.hitTestBehavior,
1378 }) : assert(itemCount == null || itemCount >= 0),
1379 assert(semanticChildCount == null || semanticChildCount <= itemCount!),
1380 assert(
1381 (itemExtent == null && prototypeItem == null) ||
1382 (itemExtent == null && itemExtentBuilder == null) ||
1383 (prototypeItem == null && itemExtentBuilder == null),
1384 'You can only pass one of itemExtent, prototypeItem and itemExtentBuilder.',
1385 ),
1386 childrenDelegate = SliverChildBuilderDelegate(
1387 itemBuilder,
1388 findChildIndexCallback: findChildIndexCallback,
1389 childCount: itemCount,
1390 addAutomaticKeepAlives: addAutomaticKeepAlives,
1391 addRepaintBoundaries: addRepaintBoundaries,
1392 addSemanticIndexes: addSemanticIndexes,
1393 ),
1394 super(semanticChildCount: semanticChildCount ?? itemCount);
1395
1396 /// Creates a fixed-length scrollable linear array of list "items" separated
1397 /// by list item "separators".
1398 ///
1399 /// This constructor is appropriate for list views with a large number of
1400 /// item and separator children because the builders are only called for
1401 /// the children that are actually visible.
1402 ///
1403 /// The `itemBuilder` callback will be called with indices greater than
1404 /// or equal to zero and less than `itemCount`.
1405 ///
1406 /// Separators only appear between list items: separator 0 appears after item
1407 /// 0 and the last separator appears before the last item.
1408 ///
1409 /// The `separatorBuilder` callback will be called with indices greater than
1410 /// or equal to zero and less than `itemCount - 1`.
1411 ///
1412 /// The `itemBuilder` and `separatorBuilder` callbacks should always
1413 /// actually create widget instances when called. Avoid using a builder that
1414 /// returns a previously-constructed widget; if the list view's children are
1415 /// created in advance, or all at once when the [ListView] itself is created,
1416 /// it is more efficient to use the [ListView] constructor.
1417 ///
1418 /// {@macro flutter.widgets.ListView.builder.itemBuilder}
1419 ///
1420 /// {@macro flutter.widgets.PageView.findChildIndexCallback}
1421 ///
1422 /// {@tool snippet}
1423 ///
1424 /// This example shows how to create [ListView] whose [ListTile] list items
1425 /// are separated by [Divider]s.
1426 ///
1427 /// ```dart
1428 /// ListView.separated(
1429 /// itemCount: 25,
1430 /// separatorBuilder: (BuildContext context, int index) => const Divider(),
1431 /// itemBuilder: (BuildContext context, int index) {
1432 /// return ListTile(
1433 /// title: Text('item $index'),
1434 /// );
1435 /// },
1436 /// )
1437 /// ```
1438 /// {@end-tool}
1439 ///
1440 /// The `addAutomaticKeepAlives` argument corresponds to the
1441 /// [SliverChildBuilderDelegate.addAutomaticKeepAlives] property. The
1442 /// `addRepaintBoundaries` argument corresponds to the
1443 /// [SliverChildBuilderDelegate.addRepaintBoundaries] property. The
1444 /// `addSemanticIndexes` argument corresponds to the
1445 /// [SliverChildBuilderDelegate.addSemanticIndexes] property. None may be
1446 /// null.
1447 ListView.separated({
1448 super.key,
1449 super.scrollDirection,
1450 super.reverse,
1451 super.controller,
1452 super.primary,
1453 super.physics,
1454 super.shrinkWrap,
1455 super.padding,
1456 required NullableIndexedWidgetBuilder itemBuilder,
1457 ChildIndexGetter? findChildIndexCallback,
1458 required IndexedWidgetBuilder separatorBuilder,
1459 required int itemCount,
1460 bool addAutomaticKeepAlives = true,
1461 bool addRepaintBoundaries = true,
1462 bool addSemanticIndexes = true,
1463 super.cacheExtent,
1464 super.dragStartBehavior,
1465 super.keyboardDismissBehavior,
1466 super.restorationId,
1467 super.clipBehavior,
1468 super.hitTestBehavior,
1469 }) : assert(itemCount >= 0),
1470 itemExtent = null,
1471 itemExtentBuilder = null,
1472 prototypeItem = null,
1473 childrenDelegate = SliverChildBuilderDelegate(
1474 (BuildContext context, int index) {
1475 final int itemIndex = index ~/ 2;
1476 if (index.isEven) {
1477 return itemBuilder(context, itemIndex);
1478 }
1479 return separatorBuilder(context, itemIndex);
1480 },
1481 findChildIndexCallback: findChildIndexCallback,
1482 childCount: _computeActualChildCount(itemCount),
1483 addAutomaticKeepAlives: addAutomaticKeepAlives,
1484 addRepaintBoundaries: addRepaintBoundaries,
1485 addSemanticIndexes: addSemanticIndexes,
1486 semanticIndexCallback: (Widget widget, int index) {
1487 return index.isEven ? index ~/ 2 : null;
1488 },
1489 ),
1490 super(semanticChildCount: itemCount);
1491
1492 /// Creates a scrollable, linear array of widgets with a custom child model.
1493 ///
1494 /// For example, a custom child model can control the algorithm used to
1495 /// estimate the size of children that are not actually visible.
1496 ///
1497 /// {@tool dartpad}
1498 /// This example shows a [ListView] that uses a custom [SliverChildBuilderDelegate] to support child
1499 /// reordering.
1500 ///
1501 /// ** See code in examples/api/lib/widgets/scroll_view/list_view.1.dart **
1502 /// {@end-tool}
1503 const ListView.custom({
1504 super.key,
1505 super.scrollDirection,
1506 super.reverse,
1507 super.controller,
1508 super.primary,
1509 super.physics,
1510 super.shrinkWrap,
1511 super.padding,
1512 this.itemExtent,
1513 this.prototypeItem,
1514 this.itemExtentBuilder,
1515 required this.childrenDelegate,
1516 super.cacheExtent,
1517 super.semanticChildCount,
1518 super.dragStartBehavior,
1519 super.keyboardDismissBehavior,
1520 super.restorationId,
1521 super.clipBehavior,
1522 super.hitTestBehavior,
1523 }) : assert(
1524 (itemExtent == null && prototypeItem == null) ||
1525 (itemExtent == null && itemExtentBuilder == null) ||
1526 (prototypeItem == null && itemExtentBuilder == null),
1527 'You can only pass one of itemExtent, prototypeItem and itemExtentBuilder.',
1528 );
1529
1530 /// {@template flutter.widgets.list_view.itemExtent}
1531 /// If non-null, forces the children to have the given extent in the scroll
1532 /// direction.
1533 ///
1534 /// Specifying an [itemExtent] is more efficient than letting the children
1535 /// determine their own extent because the scrolling machinery can make use of
1536 /// the foreknowledge of the children's extent to save work, for example when
1537 /// the scroll position changes drastically.
1538 ///
1539 /// See also:
1540 ///
1541 /// * [SliverFixedExtentList], the sliver used internally when this property
1542 /// is provided. It constrains its box children to have a specific given
1543 /// extent along the main axis.
1544 /// * The [prototypeItem] property, which allows forcing the children's
1545 /// extent to be the same as the given widget.
1546 /// * The [itemExtentBuilder] property, which allows forcing the children's
1547 /// extent to be the value returned by the callback.
1548 /// {@endtemplate}
1549 final double? itemExtent;
1550
1551 /// {@template flutter.widgets.list_view.itemExtentBuilder}
1552 /// If non-null, forces the children to have the corresponding extent returned
1553 /// by the builder.
1554 ///
1555 /// Specifying an [itemExtentBuilder] is more efficient than letting the children
1556 /// determine their own extent because the scrolling machinery can make use of
1557 /// the foreknowledge of the children's extent to save work, for example when
1558 /// the scroll position changes drastically.
1559 ///
1560 /// This will be called multiple times during the layout phase of a frame to find
1561 /// the items that should be loaded by the lazy loading process.
1562 ///
1563 /// Should return null if asked to build an item extent with a greater index than
1564 /// exists.
1565 ///
1566 /// Unlike [itemExtent] or [prototypeItem], this allows children to have
1567 /// different extents.
1568 ///
1569 /// See also:
1570 ///
1571 /// * [SliverVariedExtentList], the sliver used internally when this property
1572 /// is provided. It constrains its box children to have a specific given
1573 /// extent along the main axis.
1574 /// * The [itemExtent] property, which allows forcing the children's extent
1575 /// to a given value.
1576 /// * The [prototypeItem] property, which allows forcing the children's
1577 /// extent to be the same as the given widget.
1578 /// {@endtemplate}
1579 final ItemExtentBuilder? itemExtentBuilder;
1580
1581 /// {@template flutter.widgets.list_view.prototypeItem}
1582 /// If non-null, forces the children to have the same extent as the given
1583 /// widget in the scroll direction.
1584 ///
1585 /// Specifying an [prototypeItem] is more efficient than letting the children
1586 /// determine their own extent because the scrolling machinery can make use of
1587 /// the foreknowledge of the children's extent to save work, for example when
1588 /// the scroll position changes drastically.
1589 ///
1590 /// See also:
1591 ///
1592 /// * [SliverPrototypeExtentList], the sliver used internally when this
1593 /// property is provided. It constrains its box children to have the same
1594 /// extent as a prototype item along the main axis.
1595 /// * The [itemExtent] property, which allows forcing the children's extent
1596 /// to a given value.
1597 /// * The [itemExtentBuilder] property, which allows forcing the children's
1598 /// extent to be the value returned by the callback.
1599 /// {@endtemplate}
1600 final Widget? prototypeItem;
1601
1602 /// A delegate that provides the children for the [ListView].
1603 ///
1604 /// The [ListView.custom] constructor lets you specify this delegate
1605 /// explicitly. The [ListView] and [ListView.builder] constructors create a
1606 /// [childrenDelegate] that wraps the given [List] and [IndexedWidgetBuilder],
1607 /// respectively.
1608 final SliverChildDelegate childrenDelegate;
1609
1610 @override
1611 Widget buildChildLayout(BuildContext context) {
1612 if (itemExtent != null) {
1613 return SliverFixedExtentList(delegate: childrenDelegate, itemExtent: itemExtent!);
1614 } else if (itemExtentBuilder != null) {
1615 return SliverVariedExtentList(
1616 delegate: childrenDelegate,
1617 itemExtentBuilder: itemExtentBuilder!,
1618 );
1619 } else if (prototypeItem != null) {
1620 return SliverPrototypeExtentList(delegate: childrenDelegate, prototypeItem: prototypeItem!);
1621 }
1622 return SliverList(delegate: childrenDelegate);
1623 }
1624
1625 @override
1626 void debugFillProperties(DiagnosticPropertiesBuilder properties) {
1627 super.debugFillProperties(properties);
1628 properties.add(DoubleProperty('itemExtent', itemExtent, defaultValue: null));
1629 }
1630
1631 // Helper method to compute the actual child count for the separated constructor.
1632 static int _computeActualChildCount(int itemCount) {
1633 return math.max(0, itemCount * 2 - 1);
1634 }
1635}
1636
1637/// A scrollable, 2D array of widgets.
1638///
1639/// {@youtube 560 315 https://www.youtube.com/watch?v=bLOtZDTm4H8}
1640///
1641/// The main axis direction of a grid is the direction in which it scrolls (the
1642/// [scrollDirection]).
1643///
1644/// The most commonly used grid layouts are [GridView.count], which creates a
1645/// layout with a fixed number of tiles in the cross axis, and
1646/// [GridView.extent], which creates a layout with tiles that have a maximum
1647/// cross-axis extent. A custom [SliverGridDelegate] can produce an arbitrary 2D
1648/// arrangement of children, including arrangements that are unaligned or
1649/// overlapping.
1650///
1651/// To create a grid with a large (or infinite) number of children, use the
1652/// [GridView.builder] constructor with either a
1653/// [SliverGridDelegateWithFixedCrossAxisCount] or a
1654/// [SliverGridDelegateWithMaxCrossAxisExtent] for the [gridDelegate].
1655///
1656/// To use a custom [SliverChildDelegate], use [GridView.custom].
1657///
1658/// To create a linear array of children, use a [ListView].
1659///
1660/// To control the initial scroll offset of the scroll view, provide a
1661/// [controller] with its [ScrollController.initialScrollOffset] property set.
1662///
1663/// ## Transitioning to [CustomScrollView]
1664///
1665/// A [GridView] is basically a [CustomScrollView] with a single [SliverGrid] in
1666/// its [CustomScrollView.slivers] property.
1667///
1668/// If [GridView] is no longer sufficient, for example because the scroll view
1669/// is to have both a grid and a list, or because the grid is to be combined
1670/// with a [SliverAppBar], etc, it is straight-forward to port code from using
1671/// [GridView] to using [CustomScrollView] directly.
1672///
1673/// The [key], [scrollDirection], [reverse], [controller], [primary], [physics],
1674/// and [shrinkWrap] properties on [GridView] map directly to the identically
1675/// named properties on [CustomScrollView].
1676///
1677/// The [CustomScrollView.slivers] property should be a list containing just a
1678/// [SliverGrid].
1679///
1680/// The [childrenDelegate] property on [GridView] corresponds to the
1681/// [SliverGrid.delegate] property, and the [gridDelegate] property on the
1682/// [GridView] corresponds to the [SliverGrid.gridDelegate] property.
1683///
1684/// The [GridView], [GridView.count], and [GridView.extent]
1685/// constructors' `children` arguments correspond to the [childrenDelegate]
1686/// being a [SliverChildListDelegate] with that same argument. The
1687/// [GridView.builder] constructor's `itemBuilder` and `childCount` arguments
1688/// correspond to the [childrenDelegate] being a [SliverChildBuilderDelegate]
1689/// with the matching arguments.
1690///
1691/// The [GridView.count] and [GridView.extent] constructors create
1692/// custom grid delegates, and have equivalently named constructors on
1693/// [SliverGrid] to ease the transition: [SliverGrid.count] and
1694/// [SliverGrid.extent] respectively.
1695///
1696/// The [padding] property corresponds to having a [SliverPadding] in the
1697/// [CustomScrollView.slivers] property instead of the grid itself, and having
1698/// the [SliverGrid] instead be a child of the [SliverPadding].
1699///
1700/// Once code has been ported to use [CustomScrollView], other slivers, such as
1701/// [SliverList] or [SliverAppBar], can be put in the [CustomScrollView.slivers]
1702/// list.
1703///
1704/// {@macro flutter.widgets.ScrollView.PageStorage}
1705///
1706/// ## Examples
1707///
1708/// {@tool snippet}
1709/// This example demonstrates how to create a [GridView] with two columns. The
1710/// children are spaced apart using the `crossAxisSpacing` and `mainAxisSpacing`
1711/// properties.
1712///
1713/// ![The GridView displays six children with different background colors arranged in two columns](https://flutter.github.io/assets-for-api-docs/assets/widgets/grid_view.png)
1714///
1715/// ```dart
1716/// GridView.count(
1717/// primary: false,
1718/// padding: const EdgeInsets.all(20),
1719/// crossAxisSpacing: 10,
1720/// mainAxisSpacing: 10,
1721/// crossAxisCount: 2,
1722/// children: <Widget>[
1723/// Container(
1724/// padding: const EdgeInsets.all(8),
1725/// color: Colors.teal[100],
1726/// child: const Text("He'd have you all unravel at the"),
1727/// ),
1728/// Container(
1729/// padding: const EdgeInsets.all(8),
1730/// color: Colors.teal[200],
1731/// child: const Text('Heed not the rabble'),
1732/// ),
1733/// Container(
1734/// padding: const EdgeInsets.all(8),
1735/// color: Colors.teal[300],
1736/// child: const Text('Sound of screams but the'),
1737/// ),
1738/// Container(
1739/// padding: const EdgeInsets.all(8),
1740/// color: Colors.teal[400],
1741/// child: const Text('Who scream'),
1742/// ),
1743/// Container(
1744/// padding: const EdgeInsets.all(8),
1745/// color: Colors.teal[500],
1746/// child: const Text('Revolution is coming...'),
1747/// ),
1748/// Container(
1749/// padding: const EdgeInsets.all(8),
1750/// color: Colors.teal[600],
1751/// child: const Text('Revolution, they...'),
1752/// ),
1753/// ],
1754/// )
1755/// ```
1756/// {@end-tool}
1757///
1758/// {@tool snippet}
1759/// This example shows how to create the same grid as the previous example
1760/// using a [CustomScrollView] and a [SliverGrid].
1761///
1762/// ![The CustomScrollView contains a SliverGrid that displays six children with different background colors arranged in two columns](https://flutter.github.io/assets-for-api-docs/assets/widgets/grid_view_custom_scroll.png)
1763///
1764/// ```dart
1765/// CustomScrollView(
1766/// primary: false,
1767/// slivers: <Widget>[
1768/// SliverPadding(
1769/// padding: const EdgeInsets.all(20),
1770/// sliver: SliverGrid.count(
1771/// crossAxisSpacing: 10,
1772/// mainAxisSpacing: 10,
1773/// crossAxisCount: 2,
1774/// children: <Widget>[
1775/// Container(
1776/// padding: const EdgeInsets.all(8),
1777/// color: Colors.green[100],
1778/// child: const Text("He'd have you all unravel at the"),
1779/// ),
1780/// Container(
1781/// padding: const EdgeInsets.all(8),
1782/// color: Colors.green[200],
1783/// child: const Text('Heed not the rabble'),
1784/// ),
1785/// Container(
1786/// padding: const EdgeInsets.all(8),
1787/// color: Colors.green[300],
1788/// child: const Text('Sound of screams but the'),
1789/// ),
1790/// Container(
1791/// padding: const EdgeInsets.all(8),
1792/// color: Colors.green[400],
1793/// child: const Text('Who scream'),
1794/// ),
1795/// Container(
1796/// padding: const EdgeInsets.all(8),
1797/// color: Colors.green[500],
1798/// child: const Text('Revolution is coming...'),
1799/// ),
1800/// Container(
1801/// padding: const EdgeInsets.all(8),
1802/// color: Colors.green[600],
1803/// child: const Text('Revolution, they...'),
1804/// ),
1805/// ],
1806/// ),
1807/// ),
1808/// ],
1809/// )
1810/// ```
1811/// {@end-tool}
1812///
1813/// {@tool dartpad}
1814/// This example shows a custom implementation of selection in list and grid views.
1815/// Use the button in the top right (possibly hidden under the DEBUG banner) to toggle between
1816/// [ListView] and [GridView].
1817/// Long press any [ListTile] or [GridTile] to enable selection mode.
1818///
1819/// ** See code in examples/api/lib/widgets/scroll_view/list_view.0.dart **
1820/// {@end-tool}
1821///
1822/// {@tool dartpad}
1823/// This example shows a custom [SliverGridDelegate].
1824///
1825/// ** See code in examples/api/lib/widgets/scroll_view/grid_view.0.dart **
1826/// {@end-tool}
1827///
1828/// ## Troubleshooting
1829///
1830/// ### Padding
1831///
1832/// By default, [GridView] will automatically pad the limits of the
1833/// grid's scrollable to avoid partial obstructions indicated by
1834/// [MediaQuery]'s padding. To avoid this behavior, override with a
1835/// zero [padding] property.
1836///
1837/// {@tool snippet}
1838/// The following example demonstrates how to override the default top padding
1839/// using [MediaQuery.removePadding].
1840///
1841/// ```dart
1842/// Widget myWidget(BuildContext context) {
1843/// return MediaQuery.removePadding(
1844/// context: context,
1845/// removeTop: true,
1846/// child: GridView.builder(
1847/// gridDelegate: const SliverGridDelegateWithFixedCrossAxisCount(
1848/// crossAxisCount: 3,
1849/// ),
1850/// itemCount: 300,
1851/// itemBuilder: (BuildContext context, int index) {
1852/// return Card(
1853/// color: Colors.amber,
1854/// child: Center(child: Text('$index')),
1855/// );
1856/// }
1857/// ),
1858/// );
1859/// }
1860/// ```
1861/// {@end-tool}
1862///
1863/// See also:
1864///
1865/// * [SingleChildScrollView], which is a scrollable widget that has a single
1866/// child.
1867/// * [ListView], which is scrollable, linear list of widgets.
1868/// * [PageView], which is a scrolling list of child widgets that are each the
1869/// size of the viewport.
1870/// * [CustomScrollView], which is a scrollable widget that creates custom
1871/// scroll effects using slivers.
1872/// * [SliverGridDelegateWithFixedCrossAxisCount], which creates a layout with
1873/// a fixed number of tiles in the cross axis.
1874/// * [SliverGridDelegateWithMaxCrossAxisExtent], which creates a layout with
1875/// tiles that have a maximum cross-axis extent.
1876/// * [ScrollNotification] and [NotificationListener], which can be used to watch
1877/// the scroll position without using a [ScrollController].
1878/// * The [catalog of layout widgets](https://flutter.dev/widgets/layout/).
1879class GridView extends BoxScrollView {
1880 /// Creates a scrollable, 2D array of widgets with a custom
1881 /// [SliverGridDelegate].
1882 ///
1883 /// The `addAutomaticKeepAlives` argument corresponds to the
1884 /// [SliverChildListDelegate.addAutomaticKeepAlives] property. The
1885 /// `addRepaintBoundaries` argument corresponds to the
1886 /// [SliverChildListDelegate.addRepaintBoundaries] property. Both must not be
1887 /// null.
1888 GridView({
1889 super.key,
1890 super.scrollDirection,
1891 super.reverse,
1892 super.controller,
1893 super.primary,
1894 super.physics,
1895 super.shrinkWrap,
1896 super.padding,
1897 required this.gridDelegate,
1898 bool addAutomaticKeepAlives = true,
1899 bool addRepaintBoundaries = true,
1900 bool addSemanticIndexes = true,
1901 super.cacheExtent,
1902 List<Widget> children = const <Widget>[],
1903 int? semanticChildCount,
1904 super.dragStartBehavior,
1905 super.clipBehavior,
1906 super.keyboardDismissBehavior,
1907 super.restorationId,
1908 super.hitTestBehavior,
1909 }) : childrenDelegate = SliverChildListDelegate(
1910 children,
1911 addAutomaticKeepAlives: addAutomaticKeepAlives,
1912 addRepaintBoundaries: addRepaintBoundaries,
1913 addSemanticIndexes: addSemanticIndexes,
1914 ),
1915 super(semanticChildCount: semanticChildCount ?? children.length);
1916
1917 /// Creates a scrollable, 2D array of widgets that are created on demand.
1918 ///
1919 /// This constructor is appropriate for grid views with a large (or infinite)
1920 /// number of children because the builder is called only for those children
1921 /// that are actually visible.
1922 ///
1923 /// Providing a non-null `itemCount` improves the ability of the [GridView] to
1924 /// estimate the maximum scroll extent.
1925 ///
1926 /// `itemBuilder` will be called only with indices greater than or equal to
1927 /// zero and less than `itemCount`.
1928 ///
1929 /// {@macro flutter.widgets.ListView.builder.itemBuilder}
1930 ///
1931 /// {@macro flutter.widgets.PageView.findChildIndexCallback}
1932 ///
1933 /// The [gridDelegate] argument is required.
1934 ///
1935 /// The `addAutomaticKeepAlives` argument corresponds to the
1936 /// [SliverChildBuilderDelegate.addAutomaticKeepAlives] property. The
1937 /// `addRepaintBoundaries` argument corresponds to the
1938 /// [SliverChildBuilderDelegate.addRepaintBoundaries] property. The
1939 /// `addSemanticIndexes` argument corresponds to the
1940 /// [SliverChildBuilderDelegate.addSemanticIndexes] property.
1941 GridView.builder({
1942 super.key,
1943 super.scrollDirection,
1944 super.reverse,
1945 super.controller,
1946 super.primary,
1947 super.physics,
1948 super.shrinkWrap,
1949 super.padding,
1950 required this.gridDelegate,
1951 required NullableIndexedWidgetBuilder itemBuilder,
1952 ChildIndexGetter? findChildIndexCallback,
1953 int? itemCount,
1954 bool addAutomaticKeepAlives = true,
1955 bool addRepaintBoundaries = true,
1956 bool addSemanticIndexes = true,
1957 super.cacheExtent,
1958 int? semanticChildCount,
1959 super.dragStartBehavior,
1960 super.keyboardDismissBehavior,
1961 super.restorationId,
1962 super.clipBehavior,
1963 super.hitTestBehavior,
1964 }) : childrenDelegate = SliverChildBuilderDelegate(
1965 itemBuilder,
1966 findChildIndexCallback: findChildIndexCallback,
1967 childCount: itemCount,
1968 addAutomaticKeepAlives: addAutomaticKeepAlives,
1969 addRepaintBoundaries: addRepaintBoundaries,
1970 addSemanticIndexes: addSemanticIndexes,
1971 ),
1972 super(semanticChildCount: semanticChildCount ?? itemCount);
1973
1974 /// Creates a scrollable, 2D array of widgets with both a custom
1975 /// [SliverGridDelegate] and a custom [SliverChildDelegate].
1976 ///
1977 /// To use an [IndexedWidgetBuilder] callback to build children, either use
1978 /// a [SliverChildBuilderDelegate] or use the [GridView.builder] constructor.
1979 const GridView.custom({
1980 super.key,
1981 super.scrollDirection,
1982 super.reverse,
1983 super.controller,
1984 super.primary,
1985 super.physics,
1986 super.shrinkWrap,
1987 super.padding,
1988 required this.gridDelegate,
1989 required this.childrenDelegate,
1990 super.cacheExtent,
1991 super.semanticChildCount,
1992 super.dragStartBehavior,
1993 super.keyboardDismissBehavior,
1994 super.restorationId,
1995 super.clipBehavior,
1996 super.hitTestBehavior,
1997 });
1998
1999 /// Creates a scrollable, 2D array of widgets with a fixed number of tiles in
2000 /// the cross axis.
2001 ///
2002 /// Uses a [SliverGridDelegateWithFixedCrossAxisCount] as the [gridDelegate].
2003 ///
2004 /// The `addAutomaticKeepAlives` argument corresponds to the
2005 /// [SliverChildListDelegate.addAutomaticKeepAlives] property. The
2006 /// `addRepaintBoundaries` argument corresponds to the
2007 /// [SliverChildListDelegate.addRepaintBoundaries] property. Both must not be
2008 /// null.
2009 ///
2010 /// See also:
2011 ///
2012 /// * [SliverGrid.count], the equivalent constructor for [SliverGrid].
2013 GridView.count({
2014 super.key,
2015 super.scrollDirection,
2016 super.reverse,
2017 super.controller,
2018 super.primary,
2019 super.physics,
2020 super.shrinkWrap,
2021 super.padding,
2022 required int crossAxisCount,
2023 double mainAxisSpacing = 0.0,
2024 double crossAxisSpacing = 0.0,
2025 double childAspectRatio = 1.0,
2026 bool addAutomaticKeepAlives = true,
2027 bool addRepaintBoundaries = true,
2028 bool addSemanticIndexes = true,
2029 super.cacheExtent,
2030 List<Widget> children = const <Widget>[],
2031 int? semanticChildCount,
2032 super.dragStartBehavior,
2033 super.keyboardDismissBehavior,
2034 super.restorationId,
2035 super.clipBehavior,
2036 super.hitTestBehavior,
2037 }) : gridDelegate = SliverGridDelegateWithFixedCrossAxisCount(
2038 crossAxisCount: crossAxisCount,
2039 mainAxisSpacing: mainAxisSpacing,
2040 crossAxisSpacing: crossAxisSpacing,
2041 childAspectRatio: childAspectRatio,
2042 ),
2043 childrenDelegate = SliverChildListDelegate(
2044 children,
2045 addAutomaticKeepAlives: addAutomaticKeepAlives,
2046 addRepaintBoundaries: addRepaintBoundaries,
2047 addSemanticIndexes: addSemanticIndexes,
2048 ),
2049 super(semanticChildCount: semanticChildCount ?? children.length);
2050
2051 /// Creates a scrollable, 2D array of widgets with tiles that each have a
2052 /// maximum cross-axis extent.
2053 ///
2054 /// Uses a [SliverGridDelegateWithMaxCrossAxisExtent] as the [gridDelegate].
2055 ///
2056 /// The `addAutomaticKeepAlives` argument corresponds to the
2057 /// [SliverChildListDelegate.addAutomaticKeepAlives] property. The
2058 /// `addRepaintBoundaries` argument corresponds to the
2059 /// [SliverChildListDelegate.addRepaintBoundaries] property. Both must not be
2060 /// null.
2061 ///
2062 /// See also:
2063 ///
2064 /// * [SliverGrid.extent], the equivalent constructor for [SliverGrid].
2065 GridView.extent({
2066 super.key,
2067 super.scrollDirection,
2068 super.reverse,
2069 super.controller,
2070 super.primary,
2071 super.physics,
2072 super.shrinkWrap,
2073 super.padding,
2074 required double maxCrossAxisExtent,
2075 double mainAxisSpacing = 0.0,
2076 double crossAxisSpacing = 0.0,
2077 double childAspectRatio = 1.0,
2078 bool addAutomaticKeepAlives = true,
2079 bool addRepaintBoundaries = true,
2080 bool addSemanticIndexes = true,
2081 super.cacheExtent,
2082 List<Widget> children = const <Widget>[],
2083 int? semanticChildCount,
2084 super.dragStartBehavior,
2085 super.keyboardDismissBehavior,
2086 super.restorationId,
2087 super.clipBehavior,
2088 super.hitTestBehavior,
2089 }) : gridDelegate = SliverGridDelegateWithMaxCrossAxisExtent(
2090 maxCrossAxisExtent: maxCrossAxisExtent,
2091 mainAxisSpacing: mainAxisSpacing,
2092 crossAxisSpacing: crossAxisSpacing,
2093 childAspectRatio: childAspectRatio,
2094 ),
2095 childrenDelegate = SliverChildListDelegate(
2096 children,
2097 addAutomaticKeepAlives: addAutomaticKeepAlives,
2098 addRepaintBoundaries: addRepaintBoundaries,
2099 addSemanticIndexes: addSemanticIndexes,
2100 ),
2101 super(semanticChildCount: semanticChildCount ?? children.length);
2102
2103 /// A delegate that controls the layout of the children within the [GridView].
2104 ///
2105 /// The [GridView], [GridView.builder], and [GridView.custom] constructors let you specify this
2106 /// delegate explicitly. The other constructors create a [gridDelegate]
2107 /// implicitly.
2108 final SliverGridDelegate gridDelegate;
2109
2110 /// A delegate that provides the children for the [GridView].
2111 ///
2112 /// The [GridView.custom] constructor lets you specify this delegate
2113 /// explicitly. The other constructors create a [childrenDelegate] that wraps
2114 /// the given child list.
2115 final SliverChildDelegate childrenDelegate;
2116
2117 @override
2118 Widget buildChildLayout(BuildContext context) {
2119 return SliverGrid(delegate: childrenDelegate, gridDelegate: gridDelegate);
2120 }
2121}
2122