flexible_space_bar.dart 15.5 KB
Newer Older
Ian Hickson's avatar
Ian Hickson committed
1
// Copyright 2014 The Flutter Authors. All rights reserved.
2 3 4 5
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

import 'dart:math' as math;
6
import 'dart:ui' as ui;
7 8 9

import 'package:flutter/widgets.dart';

10
import 'colors.dart';
11 12 13
import 'constants.dart';
import 'theme.dart';

14
/// The collapsing effect while the space bar collapses from its full size.
15 16 17 18 19 20 21 22 23 24 25
enum CollapseMode {
  /// The background widget will scroll in a parallax fashion.
  parallax,

  /// The background widget pin in place until it reaches the min extent.
  pin,

  /// The background widget will act as normal with no collapsing effect.
  none,
}

26 27 28 29 30 31 32 33 34 35 36 37 38 39
/// The stretching effect while the space bar stretches beyond its full size.
enum StretchMode {
  /// The background widget will expand to fill the extra space.
  zoomBackground,

  /// The background will blur using a [ImageFilter.blur] effect.
  blurBackground,

  /// The title will fade away as the user over-scrolls.
  fadeTitle,
}

/// The part of a material design [AppBar] that expands, collapses, and
/// stretches.
40
///
41 42
/// {@youtube 560 315 https://www.youtube.com/watch?v=mSc7qFzxHDw}
///
43
/// Most commonly used in the [SliverAppBar.flexibleSpace] field, a flexible
44 45
/// space bar expands and contracts as the app scrolls so that the [AppBar]
/// reaches from the top of the app to the top of the scrolling contents of the
46 47 48 49
/// app. When using [SliverAppBar.flexibleSpace], the [SliverAppBar.expandedHeight]
/// must be large enough to accommodate the [SliverAppBar.flexibleSpace] widget.
///
/// Furthermore is included functionality for stretch behavior. When
50 51
/// [SliverAppBar.stretch] is true, and your [ScrollPhysics] allow for
/// overscroll, this space will stretch with the overscroll.
52
///
53 54 55
/// The widget that sizes the [AppBar] must wrap it in the widget returned by
/// [FlexibleSpaceBar.createSettings], to convey sizing information down to the
/// [FlexibleSpaceBar].
56
///
57
/// {@tool dartpad}
58 59 60 61 62 63 64
/// This sample application demonstrates the different features of the
/// [FlexibleSpaceBar] when used in a [SliverAppBar]. This app bar is configured
/// to stretch into the overscroll space, and uses the
/// [FlexibleSpaceBar.stretchModes] to apply `fadeTitle`, `blurBackground` and
/// `zoomBackground`. The app bar also makes use of [CollapseMode.parallax] by
/// default.
///
65
/// ** See code in examples/api/lib/material/flexible_space_bar/flexible_space_bar.0.dart **
66 67
/// {@end-tool}
///
68
/// See also:
Ian Hickson's avatar
Ian Hickson committed
69
///
70 71
///  * [SliverAppBar], which implements the expanding and contracting.
///  * [AppBar], which is used by [SliverAppBar].
72
///  * <https://material.io/design/components/app-bars-top.html#behavior>
73
class FlexibleSpaceBar extends StatefulWidget {
74 75
  /// Creates a flexible space bar.
  ///
76
  /// Most commonly used in the [AppBar.flexibleSpace] field.
77
  const FlexibleSpaceBar({
78
    Key? key,
79 80
    this.title,
    this.background,
81
    this.centerTitle,
82
    this.titlePadding,
83
    this.collapseMode = CollapseMode.parallax,
84
    this.stretchModes = const <StretchMode>[StretchMode.zoomBackground],
85
    this.expandedTitleScale = 1.5,
86
  }) : assert(collapseMode != null),
87
       assert(expandedTitleScale >= 1),
88
       super(key: key);
89

90 91 92
  /// The primary contents of the flexible space bar when expanded.
  ///
  /// Typically a [Text] widget.
93
  final Widget? title;
94 95 96

  /// Shown behind the [title] when expanded.
  ///
97
  /// Typically an [Image] widget with [Image.fit] set to [BoxFit.cover].
98
  final Widget? background;
99

100 101
  /// Whether the title should be centered.
  ///
102
  /// By default this property is true if the current target platform
103
  /// is [TargetPlatform.iOS] or [TargetPlatform.macOS], false otherwise.
104
  final bool? centerTitle;
105

106 107 108 109 110
  /// Collapse effect while scrolling.
  ///
  /// Defaults to [CollapseMode.parallax].
  final CollapseMode collapseMode;

111
  /// Stretch effect while over-scrolling.
112 113 114 115
  ///
  /// Defaults to include [StretchMode.zoomBackground].
  final List<StretchMode> stretchModes;

116 117 118 119 120 121 122 123 124
  /// Defines how far the [title] is inset from either the widget's
  /// bottom-left or its center.
  ///
  /// Typically this property is used to adjust how far the title is
  /// is inset from the bottom-left and it is specified along with
  /// [centerTitle] false.
  ///
  /// By default the value of this property is
  /// `EdgeInsetsDirectional.only(start: 72, bottom: 16)` if the title is
125
  /// not centered, `EdgeInsetsDirectional.only(start: 0, bottom: 16)` otherwise.
126
  final EdgeInsetsGeometry? titlePadding;
127

128 129 130 131 132 133 134 135
  /// Defines how much the title is scaled when the FlexibleSpaceBar is expanded
  /// due to the user scrolling downwards. The title is scaled uniformly on the
  /// x and y axes while maintaining its bottom-left position (bottom-center if
  /// [centerTitle] is true).
  ///
  /// Defaults to 1.5 and must be greater than 1.
  final double expandedTitleScale;

136 137 138 139
  /// Wraps a widget that contains an [AppBar] to convey sizing information down
  /// to the [FlexibleSpaceBar].
  ///
  /// Used by [Scaffold] and [SliverAppBar].
140 141 142 143 144 145 146
  ///
  /// `toolbarOpacity` affects how transparent the text within the toolbar
  /// appears. `minExtent` sets the minimum height of the resulting
  /// [FlexibleSpaceBar] when fully collapsed. `maxExtent` sets the maximum
  /// height of the resulting [FlexibleSpaceBar] when fully expanded.
  /// `currentExtent` sets the scale of the [FlexibleSpaceBar.background] and
  /// [FlexibleSpaceBar.title] widgets of [FlexibleSpaceBar] upon
147
  /// initialization. `scrolledUnder` is true if the [FlexibleSpaceBar]
148 149
  /// overlaps the app's primary scrollable, false if it does not, and null
  /// if the caller has not determined as much.
150 151
  /// See also:
  ///
152 153
  ///  * [FlexibleSpaceBarSettings] which creates a settings object that can be
  ///    used to specify these settings to a [FlexibleSpaceBar].
154
  static Widget createSettings({
155 156 157
    double? toolbarOpacity,
    double? minExtent,
    double? maxExtent,
158
    bool? isScrolledUnder,
159 160
    required double currentExtent,
    required Widget child,
161 162
  }) {
    assert(currentExtent != null);
163
    return FlexibleSpaceBarSettings(
164 165 166
      toolbarOpacity: toolbarOpacity ?? 1.0,
      minExtent: minExtent ?? currentExtent,
      maxExtent: maxExtent ?? currentExtent,
167
      isScrolledUnder: isScrolledUnder,
168 169 170 171 172
      currentExtent: currentExtent,
      child: child,
    );
  }

173
  @override
174
  State<FlexibleSpaceBar> createState() => _FlexibleSpaceBarState();
175 176 177
}

class _FlexibleSpaceBarState extends State<FlexibleSpaceBar> {
178
  bool _getEffectiveCenterTitle(ThemeData theme) {
179
    if (widget.centerTitle != null)
180
      return widget.centerTitle!;
181 182 183
    assert(theme.platform != null);
    switch (theme.platform) {
      case TargetPlatform.android:
184
      case TargetPlatform.fuchsia:
185 186
      case TargetPlatform.linux:
      case TargetPlatform.windows:
187 188
        return false;
      case TargetPlatform.iOS:
189
      case TargetPlatform.macOS:
190 191 192 193
        return true;
    }
  }

194
  Alignment _getTitleAlignment(bool effectiveCenterTitle) {
195
    if (effectiveCenterTitle)
196
      return Alignment.bottomCenter;
197
    final TextDirection textDirection = Directionality.of(context);
198 199 200
    assert(textDirection != null);
    switch (textDirection) {
      case TextDirection.rtl:
201
        return Alignment.bottomRight;
202
      case TextDirection.ltr:
203
        return Alignment.bottomLeft;
204 205 206
    }
  }

207
  double _getCollapsePadding(double t, FlexibleSpaceBarSettings settings) {
208 209 210 211 212 213 214
    switch (widget.collapseMode) {
      case CollapseMode.pin:
        return -(settings.maxExtent - settings.currentExtent);
      case CollapseMode.none:
        return 0.0;
      case CollapseMode.parallax:
        final double deltaExtent = settings.maxExtent - settings.minExtent;
215
        return -Tween<double>(begin: 0.0, end: deltaExtent / 4.0).transform(t);
216 217 218
    }
  }

219 220
  @override
  Widget build(BuildContext context) {
221 222
    return LayoutBuilder(
      builder: (BuildContext context, BoxConstraints constraints) {
223
        final FlexibleSpaceBarSettings settings = context.dependOnInheritedWidgetOfExactType<FlexibleSpaceBarSettings>()!;
224 225 226 227
        assert(
          settings != null,
          'A FlexibleSpaceBar must be wrapped in the widget returned by FlexibleSpaceBar.createSettings().',
        );
228

229
        final List<Widget> children = <Widget>[];
230

231 232 233 234
        final double deltaExtent = settings.maxExtent - settings.minExtent;

        // 0.0 -> Expanded
        // 1.0 -> Collapsed to toolbar
235
        final double t = (1.0 - (settings.currentExtent - settings.minExtent) / deltaExtent).clamp(0.0, 1.0);
236 237 238 239 240 241

        // background
        if (widget.background != null) {
          final double fadeStart = math.max(0.0, 1.0 - kToolbarHeight / deltaExtent);
          const double fadeEnd = 1.0;
          assert(fadeStart <= fadeEnd);
242 243 244 245 246
          // If the min and max extent are the same, the app bar cannot collapse
          // and the content should be visible, so opacity = 1.
          final double opacity = settings.maxExtent == settings.minExtent
              ? 1.0
              : 1.0 - Interval(fadeStart, fadeEnd).transform(t);
247
          double height = settings.maxExtent;
248

249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276
          // StretchMode.zoomBackground
          if (widget.stretchModes.contains(StretchMode.zoomBackground) &&
            constraints.maxHeight > height) {
            height = constraints.maxHeight;
          }
          children.add(Positioned(
            top: _getCollapsePadding(t, settings),
            left: 0.0,
            right: 0.0,
            height: height,
            child: Opacity(
              // IOS is relying on this semantics node to correctly traverse
              // through the app bar when it is collapsed.
              alwaysIncludeSemantics: true,
              opacity: opacity,
              child: widget.background,
            ),
          ));

          // StretchMode.blurBackground
          if (widget.stretchModes.contains(StretchMode.blurBackground) &&
            constraints.maxHeight > settings.maxExtent) {
            final double blurAmount = (constraints.maxHeight - settings.maxExtent) / 10;
            children.add(Positioned.fill(
              child: BackdropFilter(
                filter: ui.ImageFilter.blur(
                  sigmaX: blurAmount,
                  sigmaY: blurAmount,
277
                ),
278 279 280
                child: Container(
                  color: Colors.transparent,
                ),
281
              ),
282
            ));
283 284
          }
        }
285

286 287
        // title
        if (widget.title != null) {
288
          final ThemeData theme = Theme.of(context);
289

290
          Widget? title;
291 292
          switch (theme.platform) {
            case TargetPlatform.iOS:
293
            case TargetPlatform.macOS:
294 295 296
              title = widget.title;
              break;
            case TargetPlatform.android:
297 298 299
            case TargetPlatform.fuchsia:
            case TargetPlatform.linux:
            case TargetPlatform.windows:
300 301 302 303
              title = Semantics(
                namesRoute: true,
                child: widget.title,
              );
304
              break;
305 306 307 308 309 310
          }

          // StretchMode.fadeTitle
          if (widget.stretchModes.contains(StretchMode.fadeTitle) &&
            constraints.maxHeight > settings.maxExtent) {
            final double stretchOpacity = 1 -
311
              (((constraints.maxHeight - settings.maxExtent) / 100).clamp(0.0, 1.0));
312 313 314 315 316 317 318 319
            title = Opacity(
              opacity: stretchOpacity,
              child: title,
            );
          }

          final double opacity = settings.toolbarOpacity;
          if (opacity > 0.0) {
320
            TextStyle titleStyle = theme.primaryTextTheme.headline6!;
321
            titleStyle = titleStyle.copyWith(
322
              color: titleStyle.color!.withOpacity(opacity),
323 324 325 326 327 328 329
            );
            final bool effectiveCenterTitle = _getEffectiveCenterTitle(theme);
            final EdgeInsetsGeometry padding = widget.titlePadding ??
              EdgeInsetsDirectional.only(
                start: effectiveCenterTitle ? 0.0 : 72.0,
                bottom: 16.0,
              );
330
            final double scaleValue = Tween<double>(begin: widget.expandedTitleScale, end: 1.0).transform(t);
331 332 333 334 335 336 337 338 339 340 341 342
            final Matrix4 scaleTransform = Matrix4.identity()
              ..scale(scaleValue, scaleValue, 1.0);
            final Alignment titleAlignment = _getTitleAlignment(effectiveCenterTitle);
            children.add(Container(
              padding: padding,
              child: Transform(
                alignment: titleAlignment,
                transform: scaleTransform,
                child: Align(
                  alignment: titleAlignment,
                  child: DefaultTextStyle(
                    style: titleStyle,
343 344 345 346 347 348 349
                    child: LayoutBuilder(
                      builder: (BuildContext context, BoxConstraints constraints) {
                        return Container(
                          width: constraints.maxWidth / scaleValue,
                          alignment: titleAlignment,
                          child: title,
                        );
350
                      },
351
                    ),
352 353 354 355 356 357 358 359
                  ),
                ),
              ),
            ));
          }
        }

        return ClipRect(child: Stack(children: children));
360
      },
361
    );
362
  }
363 364
}

365 366 367 368
/// Provides sizing and opacity information to a [FlexibleSpaceBar].
///
/// See also:
///
369
///  * [FlexibleSpaceBar] which creates a flexible space bar.
370 371 372 373 374
class FlexibleSpaceBarSettings extends InheritedWidget {
  /// Creates a Flexible Space Bar Settings widget.
  ///
  /// Used by [Scaffold] and [SliverAppBar]. [child] must have a
  /// [FlexibleSpaceBar] widget in its tree for the settings to take affect.
375 376 377
  ///
  /// The required [toolbarOpacity], [minExtent], [maxExtent], [currentExtent],
  /// and [child] parameters must not be null.
378
  const FlexibleSpaceBarSettings({
379 380 381 382 383 384
    Key? key,
    required this.toolbarOpacity,
    required this.minExtent,
    required this.maxExtent,
    required this.currentExtent,
    required Widget child,
385
    this.isScrolledUnder,
386 387 388 389 390 391 392 393
  }) : assert(toolbarOpacity != null),
       assert(minExtent != null && minExtent >= 0),
       assert(maxExtent != null && maxExtent >= 0),
       assert(currentExtent != null && currentExtent >= 0),
       assert(toolbarOpacity >= 0.0),
       assert(minExtent <= maxExtent),
       assert(minExtent <= currentExtent),
       assert(currentExtent <= maxExtent),
394
       super(key: key, child: child);
395

396
  /// Affects how transparent the text within the toolbar appears.
397
  final double toolbarOpacity;
398 399

  /// Minimum height of the resulting [FlexibleSpaceBar] when fully collapsed.
400
  final double minExtent;
401 402

  /// Maximum height of the resulting [FlexibleSpaceBar] when fully expanded.
403
  final double maxExtent;
404 405 406 407

  /// If the [FlexibleSpaceBar.title] or the [FlexibleSpaceBar.background] is
  /// not null, then this value is used to calculate the relative scale of
  /// these elements upon initialization.
408
  final double currentExtent;
409

410 411 412 413 414 415 416 417 418 419 420
  /// True if the FlexibleSpaceBar overlaps the primary scrollable's contents.
  ///
  /// This value is used by the [AppBar] to resolve
  /// [AppBar.backgroundColor] against [MaterialState.scrolledUnder],
  /// i.e.  to enable apps to specify different colors when content
  /// has been scrolled up and behind the app bar.
  ///
  /// Null if the caller hasn't determined if the FlexibleSpaceBar
  /// overlaps the primary scrollable's contents.
  final bool? isScrolledUnder;

421
  @override
422
  bool updateShouldNotify(FlexibleSpaceBarSettings oldWidget) {
423 424 425
    return toolbarOpacity != oldWidget.toolbarOpacity
        || minExtent != oldWidget.minExtent
        || maxExtent != oldWidget.maxExtent
426 427
        || currentExtent != oldWidget.currentExtent
        || isScrolledUnder != oldWidget.isScrolledUnder;
428
  }
429
}