bottom_sheet.dart 17.9 KB
Newer Older
1 2 3 4 5 6
// Copyright 2015 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

import 'dart:async';

7
import 'package:flutter/foundation.dart';
8
import 'package:flutter/scheduler.dart';
9 10
import 'package:flutter/widgets.dart';

11
import 'bottom_sheet_theme.dart';
12
import 'colors.dart';
13
import 'debug.dart';
14
import 'material.dart';
15
import 'material_localizations.dart';
16
import 'scaffold.dart';
17
import 'theme.dart';
18

19 20 21
const Duration _bottomSheetDuration = Duration(milliseconds: 200);
const double _minFlingVelocity = 700.0;
const double _closeProgressThreshold = 0.5;
22

23 24 25 26 27 28 29 30
/// A material design bottom sheet.
///
/// There are two kinds of bottom sheets in material design:
///
///  * _Persistent_. A persistent bottom sheet shows information that
///    supplements the primary content of the app. A persistent bottom sheet
///    remains visible even when the user interacts with other parts of the app.
///    Persistent bottom sheets can be created and displayed with the
31 32
///    [ScaffoldState.showBottomSheet] function or by specifying the
///    [Scaffold.bottomSheet] constructor parameter.
33 34 35 36 37 38 39
///
///  * _Modal_. A modal bottom sheet is an alternative to a menu or a dialog and
///    prevents the user from interacting with the rest of the app. Modal bottom
///    sheets can be created and displayed with the [showModalBottomSheet]
///    function.
///
/// The [BottomSheet] widget itself is rarely used directly. Instead, prefer to
40 41
/// create a persistent bottom sheet with [ScaffoldState.showBottomSheet] or
/// [Scaffold.bottomSheet], and a modal bottom sheet with [showModalBottomSheet].
42 43 44
///
/// See also:
///
45 46 47 48 49
///  * [showBottomSheet] and [ScaffoldState.showBottomSheet], for showing
///    non-modal "persistent" bottom sheets.
///  * [showModalBottomSheet], which can be used to display a modal bottom
///    sheet.
///  * <https://material.io/design/components/sheets-bottom.html>
50
class BottomSheet extends StatefulWidget {
51 52 53
  /// Creates a bottom sheet.
  ///
  /// Typically, bottom sheets are created implicitly by
54
  /// [ScaffoldState.showBottomSheet], for persistent bottom sheets, or by
55
  /// [showModalBottomSheet], for modal bottom sheets.
56
  const BottomSheet({
57
    Key key,
58
    this.animationController,
59
    this.enableDrag = true,
60
    this.backgroundColor,
61 62
    this.elevation,
    this.shape,
63
    this.clipBehavior,
64
    @required this.onClosing,
65
    @required this.builder,
66 67
  }) : assert(enableDrag != null),
       assert(onClosing != null),
68
       assert(builder != null),
69
       assert(elevation == null || elevation >= 0.0),
70
       super(key: key);
71

72 73
  /// The animation controller that controls the bottom sheet's entrance and
  /// exit animations.
74 75 76
  ///
  /// The BottomSheet widget will manipulate the position of this animation, it
  /// is not just a passive observer.
77
  final AnimationController animationController;
78 79 80

  /// Called when the bottom sheet begins to close.
  ///
81
  /// A bottom sheet might be prevented from closing (e.g., by user
82 83
  /// interaction) even after this callback is called. For this reason, this
  /// callback might be call multiple times for a given bottom sheet.
84
  final VoidCallback onClosing;
85 86 87 88 89

  /// A builder for the contents of the sheet.
  ///
  /// The bottom sheet will wrap the widget produced by this builder in a
  /// [Material] widget.
90 91
  final WidgetBuilder builder;

92 93
  /// If true, the bottom sheet can be dragged up and down and dismissed by
  /// swiping downards.
94 95 96 97
  ///
  /// Default is true.
  final bool enableDrag;

98 99 100 101 102 103 104
  /// The bottom sheet's background color.
  ///
  /// Defines the bottom sheet's [Material.color].
  ///
  /// Defaults to null and falls back to [Material]'s default.
  final Color backgroundColor;

105
  /// The z-coordinate at which to place this material relative to its parent.
106
  ///
107 108 109
  /// This controls the size of the shadow below the material.
  ///
  /// Defaults to 0. The value is non-negative.
110 111
  final double elevation;

112
  /// The shape of the bottom sheet.
113
  ///
114 115 116 117
  /// Defines the bottom sheet's [Material.shape].
  ///
  /// Defaults to null and falls back to [Material]'s default.
  final ShapeBorder shape;
118

119 120 121 122 123 124 125 126 127 128 129 130 131
  /// {@macro flutter.widgets.Clip}
  ///
  /// Defines the bottom sheet's [Material.clipBehavior].
  ///
  /// Use this property to enable clipping of content when the bottom sheet has
  /// a custom [shape] and the content can extend past this shape. For example,
  /// a bottom sheet with rounded corners and an edge-to-edge [Image] at the
  /// top.
  ///
  /// If this property is null then [ThemeData.bottomSheetTheme.clipBehavior] is
  /// used. If that's null then the behavior will be [Clip.none].
  final Clip clipBehavior;

132
  @override
133
  _BottomSheetState createState() => _BottomSheetState();
134

135 136 137 138 139 140
  /// Creates an [AnimationController] suitable for a
  /// [BottomSheet.animationController].
  ///
  /// This API available as a convenience for a Material compliant bottom sheet
  /// animation. If alternative animation durations are required, a different
  /// animation controller could be provided.
141
  static AnimationController createAnimationController(TickerProvider vsync) {
142
    return AnimationController(
143
      duration: _bottomSheetDuration,
144 145
      debugLabel: 'BottomSheet',
      vsync: vsync,
146 147
    );
  }
148 149 150 151
}

class _BottomSheetState extends State<BottomSheet> {

152
  final GlobalKey _childKey = GlobalKey(debugLabel: 'BottomSheet child');
153 154 155 156 157

  double get _childHeight {
    final RenderBox renderBox = _childKey.currentContext.findRenderObject();
    return renderBox.size.height;
  }
158

159
  bool get _dismissUnderway => widget.animationController.status == AnimationStatus.reverse;
160

161
  void _handleDragUpdate(DragUpdateDetails details) {
162
    assert(widget.enableDrag);
163 164
    if (_dismissUnderway)
      return;
165
    widget.animationController.value -= details.primaryDelta / (_childHeight ?? details.primaryDelta);
166 167
  }

168
  void _handleDragEnd(DragEndDetails details) {
169
    assert(widget.enableDrag);
170 171
    if (_dismissUnderway)
      return;
172
    if (details.velocity.pixelsPerSecond.dy > _minFlingVelocity) {
173
      final double flingVelocity = -details.velocity.pixelsPerSecond.dy / _childHeight;
174
      if (widget.animationController.value > 0.0) {
175
        widget.animationController.fling(velocity: flingVelocity);
176 177
      }
      if (flingVelocity < 0.0) {
178
        widget.onClosing();
179 180
      }
    } else if (widget.animationController.value < _closeProgressThreshold) {
181 182 183
      if (widget.animationController.value > 0.0)
        widget.animationController.fling(velocity: -1.0);
      widget.onClosing();
184
    } else {
185
      widget.animationController.forward();
186 187 188 189 190 191
   }
  }

  bool extentChanged(DraggableScrollableNotification notification) {
    if (notification.extent == notification.minExtent) {
      widget.onClosing();
192
    }
193
    return false;
194 195
  }

196
  @override
197
  Widget build(BuildContext context) {
198 199 200 201
    final BottomSheetThemeData bottomSheetTheme = Theme.of(context).bottomSheetTheme;
    final Color color = widget.backgroundColor ?? bottomSheetTheme.backgroundColor;
    final double elevation = widget.elevation ?? bottomSheetTheme.elevation ?? 0;
    final ShapeBorder shape = widget.shape ?? bottomSheetTheme.shape;
202
    final Clip clipBehavior = widget.clipBehavior ?? bottomSheetTheme.clipBehavior ?? Clip.none;
203

204
    final Widget bottomSheet = Material(
205
      key: _childKey,
206 207 208
      color: color,
      elevation: elevation,
      shape: shape,
209
      clipBehavior: clipBehavior,
210 211 212 213
      child: NotificationListener<DraggableScrollableNotification>(
        onNotification: extentChanged,
        child: widget.builder(context),
      ),
214
    );
215
    return !widget.enableDrag ? bottomSheet : GestureDetector(
216
      onVerticalDragUpdate: _handleDragUpdate,
217
      onVerticalDragEnd: _handleDragEnd,
218
      child: bottomSheet,
219
      excludeFromSemantics: true,
220 221 222 223
    );
  }
}

224
// PERSISTENT BOTTOM SHEETS
225

226
// See scaffold.dart
227 228


229
// MODAL BOTTOM SHEETS
230
class _ModalBottomSheetLayout extends SingleChildLayoutDelegate {
231
  _ModalBottomSheetLayout(this.progress, this.isScrollControlled);
232 233

  final double progress;
234
  final bool isScrollControlled;
235

236
  @override
237
  BoxConstraints getConstraintsForChild(BoxConstraints constraints) {
238
    return BoxConstraints(
239 240 241
      minWidth: constraints.maxWidth,
      maxWidth: constraints.maxWidth,
      minHeight: 0.0,
242 243 244
      maxHeight: isScrollControlled
        ? constraints.maxHeight
        : constraints.maxHeight * 9.0 / 16.0,
245 246 247
    );
  }

248
  @override
249
  Offset getPositionForChild(Size size, Size childSize) {
250
    return Offset(0.0, size.height - childSize.height * progress);
251 252
  }

253
  @override
254 255
  bool shouldRelayout(_ModalBottomSheetLayout oldDelegate) {
    return progress != oldDelegate.progress;
256 257 258
  }
}

259
class _ModalBottomSheet<T> extends StatefulWidget {
260 261 262
  const _ModalBottomSheet({
    Key key,
    this.route,
263 264 265
    this.backgroundColor,
    this.elevation,
    this.shape,
266
    this.clipBehavior,
267 268 269
    this.isScrollControlled = false,
  }) : assert(isScrollControlled != null),
       super(key: key);
270

271
  final _ModalBottomSheetRoute<T> route;
272
  final bool isScrollControlled;
273 274 275
  final Color backgroundColor;
  final double elevation;
  final ShapeBorder shape;
276
  final Clip clipBehavior;
277

278
  @override
279
  _ModalBottomSheetState<T> createState() => _ModalBottomSheetState<T>();
280 281
}

282
class _ModalBottomSheetState<T> extends State<_ModalBottomSheet<T>> {
283
  String _getRouteLabel(MaterialLocalizations localizations) {
284
    switch (Theme.of(context).platform) {
285
      case TargetPlatform.iOS:
286
        return '';
287 288
      case TargetPlatform.android:
      case TargetPlatform.fuchsia:
289
        return localizations.dialogLabel;
290
    }
291 292 293 294 295 296 297 298 299 300
    return null;
  }

  @override
  Widget build(BuildContext context) {
    assert(debugCheckHasMediaQuery(context));
    assert(debugCheckHasMaterialLocalizations(context));
    final MediaQueryData mediaQuery = MediaQuery.of(context);
    final MaterialLocalizations localizations = MaterialLocalizations.of(context);
    final String routeLabel = _getRouteLabel(localizations);
301

302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326
    return AnimatedBuilder(
      animation: widget.route.animation,
      builder: (BuildContext context, Widget child) {
        // Disable the initial animation when accessible navigation is on so
        // that the semantics are added to the tree at the correct time.
        final double animationValue = mediaQuery.accessibleNavigation ? 1.0 : widget.route.animation.value;
        return Semantics(
          scopesRoute: true,
          namesRoute: true,
          label: routeLabel,
          explicitChildNodes: true,
          child: ClipRect(
            child: CustomSingleChildLayout(
              delegate: _ModalBottomSheetLayout(animationValue, widget.isScrollControlled),
              child: BottomSheet(
                animationController: widget.route._animationController,
                onClosing: () {
                  if (widget.route.isCurrent) {
                    Navigator.pop(context);
                  }
                },
                builder: widget.route.builder,
                backgroundColor: widget.backgroundColor,
                elevation: widget.elevation,
                shape: widget.shape,
327
                clipBehavior: widget.clipBehavior,
328 329
              ),
            ),
330 331 332
          ),
        );
      },
333 334 335 336
    );
  }
}

Hixie's avatar
Hixie committed
337 338
class _ModalBottomSheetRoute<T> extends PopupRoute<T> {
  _ModalBottomSheetRoute({
339 340
    this.builder,
    this.theme,
341
    this.barrierLabel,
342
    this.backgroundColor,
343 344
    this.elevation,
    this.shape,
345
    this.clipBehavior,
346
    @required this.isScrollControlled,
347
    RouteSettings settings,
348 349
  }) : assert(isScrollControlled != null),
       super(settings: settings);
350 351

  final WidgetBuilder builder;
352
  final ThemeData theme;
353 354
  final bool isScrollControlled;
  final Color backgroundColor;
355 356
  final double elevation;
  final ShapeBorder shape;
357
  final Clip clipBehavior;
358

359
  @override
360
  Duration get transitionDuration => _bottomSheetDuration;
361 362

  @override
363
  bool get barrierDismissible => true;
364

365 366 367
  @override
  final String barrierLabel;

368
  @override
Hixie's avatar
Hixie committed
369
  Color get barrierColor => Colors.black54;
370

371 372
  AnimationController _animationController;

373

374
  @override
375
  AnimationController createAnimationController() {
376
    assert(_animationController == null);
377
    _animationController = BottomSheet.createAnimationController(navigator.overlay);
378
    return _animationController;
379 380
  }

381
  @override
382
  Widget buildPage(BuildContext context, Animation<double> animation, Animation<double> secondaryAnimation) {
383 384
    // By definition, the bottom sheet is aligned to the bottom of the page
    // and isn't exposed to the top padding of the MediaQuery.
385
    Widget bottomSheet = MediaQuery.removePadding(
386 387
      context: context,
      removeTop: true,
388 389 390 391 392
      child: _ModalBottomSheet<T>(
        route: this,
        backgroundColor: backgroundColor,
        elevation: elevation,
        shape: shape,
393
        clipBehavior: clipBehavior,
394 395
        isScrollControlled: isScrollControlled
      ),
396
    );
397
    if (theme != null)
398
      bottomSheet = Theme(data: theme, child: bottomSheet);
399
    return bottomSheet;
400 401 402
  }
}

403 404 405 406 407 408 409 410
/// Shows a modal material design bottom sheet.
///
/// A modal bottom sheet is an alternative to a menu or a dialog and prevents
/// the user from interacting with the rest of the app.
///
/// A closely related widget is a persistent bottom sheet, which shows
/// information that supplements the primary content of the app without
/// preventing the use from interacting with the app. Persistent bottom sheets
411 412
/// can be created and displayed with the [showBottomSheet] function or the
/// [ScaffoldState.showBottomSheet] method.
413
///
Ian Hickson's avatar
Ian Hickson committed
414 415 416 417 418
/// The `context` argument is used to look up the [Navigator] and [Theme] for
/// the bottom sheet. It is only used when the method is called. Its
/// corresponding widget can be safely removed from the tree before the bottom
/// sheet is closed.
///
419 420 421 422 423 424
/// The `isScrollControlled` parameter specifies whether this is a route for
/// a bottom sheet that will utilize [DraggableScrollableSheet]. If you wish
/// to have a bottom sheet that has a scrollable child such as a [ListView] or
/// a [GridView] and have the bottom sheet be draggable, you should set this
/// parameter to true.
///
425 426 427 428 429
/// The `useRootNavigator` parameter ensures that the root navigator is used to
/// display the [BottomSheet] when set to `true`. This is useful in the case
/// that a modal [BottomSheet] needs to be displayed above all other content
/// but the caller is inside another [Navigator].
///
430
/// Returns a `Future` that resolves to the value (if any) that was passed to
431
/// [Navigator.pop] when the modal bottom sheet was closed.
432 433 434
///
/// See also:
///
435 436
///  * [BottomSheet], which becomes the parent of the widget returned by the
///    function passed as the `builder` argument to [showModalBottomSheet].
437 438
///  * [showBottomSheet] and [ScaffoldState.showBottomSheet], for showing
///    non-modal bottom sheets.
439 440
///  * [DraggableScrollableSheet], which allows you to create a bottom sheet
///    that grows and then becomes scrollable once it reaches its maximum size.
441
///  * <https://material.io/design/components/sheets-bottom.html#modal-bottom-sheet>
442 443 444
Future<T> showModalBottomSheet<T>({
  @required BuildContext context,
  @required WidgetBuilder builder,
445
  Color backgroundColor,
446 447
  double elevation,
  ShapeBorder shape,
448
  Clip clipBehavior,
449
  bool isScrollControlled = false,
450
  bool useRootNavigator = false,
451
}) {
452 453
  assert(context != null);
  assert(builder != null);
454
  assert(isScrollControlled != null);
455
  assert(useRootNavigator != null);
456
  assert(debugCheckHasMediaQuery(context));
457
  assert(debugCheckHasMaterialLocalizations(context));
458

459
  return Navigator.of(context, rootNavigator: useRootNavigator).push(_ModalBottomSheetRoute<T>(
460 461
    builder: builder,
    theme: Theme.of(context, shadowThemeOnly: true),
462
    isScrollControlled: isScrollControlled,
463
    barrierLabel: MaterialLocalizations.of(context).modalBarrierDismissLabel,
464
    backgroundColor: backgroundColor,
465
    elevation: elevation ?? Theme.of(context).bottomSheetTheme.modalElevation,
466
    shape: shape,
467
    clipBehavior: clipBehavior,
468 469
  ));
}
470

471 472
/// Shows a material design bottom sheet in the nearest [Scaffold] ancestor. If
/// you wish to show a persistent bottom sheet, use [Scaffold.bottomSheet].
473
///
474 475 476 477 478 479 480 481 482 483 484 485 486 487 488
/// Returns a controller that can be used to close and otherwise manipulate the
/// bottom sheet.
///
/// To rebuild the bottom sheet (e.g. if it is stateful), call
/// [PersistentBottomSheetController.setState] on the controller returned by
/// this method.
///
/// The new bottom sheet becomes a [LocalHistoryEntry] for the enclosing
/// [ModalRoute] and a back button is added to the appbar of the [Scaffold]
/// that closes the bottom sheet.
///
/// To create a persistent bottom sheet that is not a [LocalHistoryEntry] and
/// does not add a back button to the enclosing Scaffold's appbar, use the
/// [Scaffold.bottomSheet] constructor parameter.
///
489 490 491 492 493 494 495 496 497 498 499
/// A closely related widget is a modal bottom sheet, which is an alternative
/// to a menu or a dialog and prevents the user from interacting with the rest
/// of the app. Modal bottom sheets can be created and displayed with the
/// [showModalBottomSheet] function.
///
/// The `context` argument is used to look up the [Scaffold] for the bottom
/// sheet. It is only used when the method is called. Its corresponding widget
/// can be safely removed from the tree before the bottom sheet is closed.
///
/// See also:
///
500 501
///  * [BottomSheet], which becomes the parent of the widget returned by the
///    `builder`.
502 503 504
///  * [showModalBottomSheet], which can be used to display a modal bottom
///    sheet.
///  * [Scaffold.of], for information about how to obtain the [BuildContext].
505
///  * <https://material.io/design/components/sheets-bottom.html#standard-bottom-sheet>
506 507 508
PersistentBottomSheetController<T> showBottomSheet<T>({
  @required BuildContext context,
  @required WidgetBuilder builder,
509
  Color backgroundColor,
510 511
  double elevation,
  ShapeBorder shape,
512
  Clip clipBehavior,
513 514 515
}) {
  assert(context != null);
  assert(builder != null);
516 517 518 519 520
  assert(debugCheckHasScaffold(context));

  return Scaffold.of(context).showBottomSheet<T>(
    builder,
    backgroundColor: backgroundColor,
521 522
    elevation: elevation,
    shape: shape,
523
    clipBehavior: clipBehavior,
524
  );
525
}