DraggableScrollableSheet class

A container for a Scrollable that responds to drag gestures by resizing the scrollable until a limit is reached, and then scrolling.

This widget can be dragged along the vertical axis between its minChildSize, which defaults to 0.25 and maxChildSize, which defaults to 1.0. These sizes are percentages of the height of the parent container.

The widget coordinates resizing and scrolling of the widget returned by builder as the user drags along the horizontal axis.

The widget will initially be displayed at its initialChildSize which defaults to 0.5, meaning half the height of its parent. Dragging will work between the range of minChildSize and maxChildSize (as percentages of the parent container's height) as long as the builder creates a widget which uses the provided ScrollController. If the widget created by the ScrollableWidgetBuilder does not use the provided ScrollController, the sheet will remain at the initialChildSize.

By default, the widget will stay at whatever size the user drags it to. To make the widget snap to specific sizes whenever they lift their finger during a drag, set snap to true. The sheet will snap between minChildSize and maxChildSize. Use snapSizes to add more sizes for the sheet to snap between.

The snapping effect is only applied on user drags. Programmatically manipulating the sheet size via DraggableScrollableController.animateTo or DraggableScrollableController.jumpTo will ignore snap and snapSizes.

By default, the widget will expand its non-occupied area to fill available space in the parent. If this is not desired, e.g. because the parent wants to position sheet based on the space it is taking, the expand property may be set to false.

This is a sample widget which shows a ListView that has 25 ListTiles. It starts out as taking up half the body of the Scaffold, and can be dragged up to the full height of the scaffold or down to 25% of the height of the scaffold. Upon reaching full height, the list contents will be scrolled up or down, until they reach the top of the list again and the user drags the sheet back down.

On desktop and web running on desktop platforms, dragging to scroll with a mouse is disabled by default to align with the natural behavior found in other desktop applications.

This behavior is dictated by the ScrollBehavior, and can be changed by adding PointerDeviceKind.mouse to ScrollBehavior.dragDevices. For more info on this, please refer to https://docs.flutter.cn/release/breaking-changes/default-scroll-behavior-drag

Alternatively, this example illustrates how to add a drag handle for desktop applications.

link

To create a local project with this code sample, run:
flutter create --sample=widgets.DraggableScrollableSheet.1 mysample

Inheritance

Constructors

DraggableScrollableSheet({Key? key, double initialChildSize = 0.5, double minChildSize = 0.25, double maxChildSize = 1.0, bool expand = true, bool snap = false, List<double>? snapSizes, Duration? snapAnimationDuration, DraggableScrollableController? controller, bool shouldCloseOnMinExtent = true, required ScrollableWidgetBuilder builder})
Creates a widget that can be dragged and scrolled in a single gesture.
const

Properties

builder ScrollableWidgetBuilder
The builder that creates a child to display in this widget, which will use the provided ScrollController to enable dragging and scrolling of the contents.
final
controller DraggableScrollableController?
A controller that can be used to programmatically control this sheet.
final
expand bool
Whether the widget should expand to fill the available space in its parent or not.
final
hashCode int
The hash code for this object.
no setterinherited
initialChildSize double
The initial fractional value of the parent container's height to use when displaying the widget.
final
key Key?
Controls how one widget replaces another widget in the tree.
finalinherited
maxChildSize double
The maximum fractional value of the parent container's height to use when displaying the widget.
final
minChildSize double
The minimum fractional value of the parent container's height to use when displaying the widget.
final
runtimeType Type
A representation of the runtime type of the object.
no setterinherited
shouldCloseOnMinExtent bool
Whether the sheet, when dragged (or flung) to its minimum size, should cause its parent sheet to close.
final
snap bool
Whether the widget should snap between snapSizes when the user lifts their finger during a drag.
final
snapAnimationDuration Duration?
Defines a duration for the snap animations.
final
snapSizes List<double>?
A list of target sizes that the widget should snap to.
final

Methods

createElement() StatefulElement
Creates a StatefulElement to manage this widget's location in the tree.
inherited
createState() State<DraggableScrollableSheet>
Creates the mutable state for this widget at a given location in the tree.
override
debugDescribeChildren() List<DiagnosticsNode>
Returns a list of DiagnosticsNode objects describing this node's children.
inherited
debugFillProperties(DiagnosticPropertiesBuilder properties) → void
Add additional properties associated with the node.
inherited
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toDiagnosticsNode({String? name, DiagnosticsTreeStyle? style}) DiagnosticsNode
Returns a debug representation of the object that is used by debugging tools and by DiagnosticsNode.toStringDeep.
inherited
toString({DiagnosticLevel minLevel = DiagnosticLevel.info}) String
A string representation of this object.
inherited
toStringDeep({String prefixLineOne = '', String? prefixOtherLines, DiagnosticLevel minLevel = DiagnosticLevel.debug}) String
Returns a string representation of this node and its descendants.
inherited
toStringShallow({String joiner = ', ', DiagnosticLevel minLevel = DiagnosticLevel.debug}) String
Returns a one-line detailed description of the object.
inherited
toStringShort() String
A short, textual description of this widget.
inherited

Operators

operator ==(Object other) bool
The equality operator.
inherited