Description

SliverAppBar.stretch

This PR introduces the ability to configure a stretch effect for a SliverAppBar when using ScrollPhysics that allow overscroll. (i.e. iOS's BouncingScrollPhysics).
This configuration also allows you to specify an amount of overscroll offset that will trigger a given callback function. The default triggering offset distance is 100.0.
This stretch features works with all of the SliverAppBar configurations - floating, pinned, snap, and default scrolling persistent headers all work with stretch.

FlexibleSpaceBar

Potential follow-up on this would be to add something along the lines of a stretchMode to FlexibleSpaceBar, similar to the collapseMode that is already provided.
The SliverAppBar changes alone would leave the FlexibleSpaceBar in a weird state when using the stretch feature, so I have added support here as well.
This support comes in the form of StretchModes, modeled after the CollapseModes that are already a part of FlexibleSpaceBar. Currently being added here are zoomBackground, blurBackground, and fadeTitle, all of which are in use in the animation below. Providing at least the zoomBackground stretch mode seems prudent since without it an app bar will stretch outside of the background. These stretch modes do not interfere with any of the collapse modes.

Code snippet behind this animation:

import 'package:flutter/material.dart';

void main() {
  runApp(
    MaterialApp(
      home: Scaffold(
        body: CustomScrollView(
          physics: BouncingScrollPhysics(),
          slivers: <Widget>[
            SliverAppBar(
              stretch: true,
              onStretchTrigger: () {print('hello!');},
              expandedHeight: 300.0,
              flexibleSpace: FlexibleSpaceBar(
                stretchModes: <StretchMode>[
                  StretchMode.zoomBackground,
                  StretchMode.blurBackground,
                  StretchMode.fadeTitle,
                ],
                centerTitle: true,
                title: const Text('Horizons'),
                background: Stack(
                  fit: StackFit.expand,
                  children: [
                    Image.network(
                      'https://images.unsplash.com/photo-1503803548695-c2a7b4a5b875?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=1350&q=80',
                      fit: BoxFit.cover,
                    ),
                    const DecoratedBox(
                      decoration: BoxDecoration(
                        gradient: LinearGradient(
                          begin: Alignment(0.0, 0.5),
                          end: Alignment(0.0, 0.0),
                          colors: <Color>[Color(0x60000000), Color(0x00000000)],
                        ),
                      ),
                    ),
                  ],
                ),
              ),
            ),
            SliverList(
              delegate: SliverChildListDelegate([
                ListTile(
                  leading: Icon(Icons.wb_sunny),
                  title: Text('Sunday'),
                  subtitle: Text('sunny, h: 80, l: 65'),
                ),
                ListTile(
                  leading: Icon(Icons.wb_sunny),
                  title: Text('Monday'),
                  subtitle: Text('sunny, h: 80, l: 65'),
                ),
                // ListTiles++
              ]
            ),
          ),
        ],
      ),
    )
  ));
}

More Custom Stretching!

While the stretch modes introduced here may not cover every possible stretch behavior, the changes to SliverAppBar alone make it much easier to implement your own custom behavior for stretching, as the proper constraints will be passed down from the SliverPersistentHeader to any of its children when stretch is true. For example, the Pesto demo of Flutter Gallery automatically adheres to the stretch, using a LayoutBuilder instead of a FlexibleSpaceBar. Shown here:

A follow-up PR will add animated illustrations to go along with sample code.

Related Issues

Fixes #27373

Tests

I added the following tests:

• FlexibleSpaceBar stretch mode default zoomBackground
• FlexibleSpaceBar stretch mode blurBackground
• FlexibleSpaceBar stretch mode fadeTitle
• FlexibleSpaceBar stretch mode ignored for non-overscroll physics
• SliverAppBar - Stretch
  • fills overscroll
  • does not stretch without overscroll physics
  • default trigger offset
  • custom trigger offset
  • stretch callback not triggered without overscroll physics
  • asserts stretch != null
  • asserts reasonable trigger offset
• SliverAppBar - Stretch, Pinned
  • fills overscroll
  • does not fill overscroll without proper physics
• SliverAppBar - Stretch, Floating
  • fills overscroll
  • does not fill overscroll without proper physics
• SliverAppBar - Stretch, Floating, Pinned
  • fills overscroll
  • does not fill overscroll without proper physics

Checklist

Before you create this PR confirm that it meets all requirements listed below by checking the relevant checkboxes ([x]). This will ensure a smooth and quick review process.

• I read the Contributor Guide and followed the process outlined there for submitting PRs.
• I signed the CLA.
• I read and followed the Flutter Style Guide, including Features we expect every widget to implement.
• I updated/added relevant documentation (doc comments with ///).
• All existing and new tests are passing.
• The analyzer (flutter analyze --flutter-repo) does not report any problems on my PR.
• I am willing to follow-up on review comments in a timely manner.

Breaking Change

Does your PR require Flutter developers to manually update their apps to accommodate your change?

• No, this is not a breaking change.