firka/flutter
3
0
Fork 1
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

CupertinoSheetRoute (#157568)

Browse Source 
Fixes #42560

### Updated 12/04/24

Adds a CupertinoSheetRoute which displays an iOS style sheet, while
giving the previous route a delegated transition to sync up correctly.

There's a lot of sample files in this draft showing different use cases
for the sake of reviewing the PR. We'll want to probably go down to
about two before this PR lands.

**TODO in this PR**

- [x] Write actual documentation
- [x] Write tests

**TODO in a feature branch, and will be merged with this PR**

- [ ] Add swipe down to dismiss

**TODO in a follow up PR**

- [ ] Stretching on swipe up
- [ ] Add a fullscreen version
- [x] Dark mode theming

How it currently compares, with the simple case and nested navigation:
| Flutter  | Native|
| ------------- | ------------- |
|
![Flutter-Simple](https://github.com/user-attachments/assets/2a1f277e-91c9-48e0-b894-5fad71ef6a21)
|![Native-Simple](https://github.com/user-attachments/assets/6960252a-f762-4ad8-8d68-5c3d7cf8d4e7)
|
|
![Flutter-Nested](https://github.com/user-attachments/assets/bacb3e35-9d11-4113-9331-75daaded67e7)
|
![Native-stacked](https://github.com/user-attachments/assets/70ccbbbb-24c2-40b5-b838-4f8412828b9b)
|

Update:

![Flutter-Status-Bar](https://github.com/user-attachments/assets/c738cc5c-7176-4df2-9422-6b3fa608c943)
Now the status bar will transition from dark to light text so that it's
visible after the transition.

`cupertino_sheet.0.dart` has an example of what it looks like to do a
simple case. It's fairly straightforward.

`cupertino_sheet.1.dart` shows one with nested navigation. It's
necessary to add a `Navigator` if showing page navigation within the
sheet is wanted. I'm thinking adding an API option that auto sets this
up may be needed as there are some pitfalls.

`cupertino_sheet.2.dart` functionally does the same as above but uses
the `showCupertinoSheet` to reduce boilerplate.

## Pre-launch Checklist

- [x] I read the [Contributor Guide] and followed the process outlined
there for submitting PRs.
- [x] I read the [Tree Hygiene] wiki page, which explains my
responsibilities.
- [x] I read and followed the [Flutter Style Guide], including [Features
we expect every widget to implement].
- [x] I signed the [CLA].
- [x] I listed at least one issue that this PR fixes in the description
above.
- [x] I updated/added relevant documentation (doc comments with `///`).
- [x] I added new tests to check the change I am making, or this PR is
[test-exempt].
- [x] I followed the [breaking change policy] and added [Data Driven
Fixes] where supported.
- [ ] All existing and new tests are passing.

If you need help, consider asking for advice on the #hackers-new channel
on [Discord].

<!-- Links -->
[Contributor Guide]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#overview
[Tree Hygiene]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md
[test-exempt]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#tests
[Flutter Style Guide]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md
[Features we expect every widget to implement]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md#features-we-expect-every-widget-to-implement
[CLA]: https://cla.developers.google.com/
[flutter/tests]: https://github.com/flutter/tests
[breaking change policy]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#handling-breaking-changes
[Discord]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Chat.md
[Data Driven Fixes]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Data-driven-Fixes.md
This commit is contained in:
Mitchell Goodwin
2025-01-10 15:01:08 -08:00
committed by GitHub
parent 9e211cabbd
commit 50f7120de5
9 changed files with 2180 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

86
examples/api/lib/cupertino/sheet/cupertino_sheet.0.dart Normal file
View File

@@ -0,0 +1,86 @@
// Copyright 2014 The Flutter 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 'package:flutter/cupertino.dart';
/// Flutter code sample for [CupertinoSheetRoute].
void main() {
runApp(const CupertinoSheetApp());
}
class CupertinoSheetApp extends StatelessWidget {
const CupertinoSheetApp({super.key});
@override
Widget build(BuildContext context) {
return const CupertinoApp(title: 'Cupertino Sheet', home: HomePage());
}
}
class HomePage extends StatelessWidget {
const HomePage({super.key});
@override
Widget build(BuildContext context) {
return CupertinoPageScaffold(
navigationBar: const CupertinoNavigationBar(
middle: Text('Sheet Example'),
automaticBackgroundVisibility: false,
),
child: Center(
child: Column(
mainAxisAlignment: MainAxisAlignment.center,
children: <Widget>[
CupertinoButton.filled(
onPressed: () {
Navigator.of(context).push(
CupertinoSheetRoute<void>(
builder: (BuildContext context) => const _SheetScaffold(),
),
);
},
child: const Text('Open Bottom Sheet'),
),
],
),
),
);
}
}
class _SheetScaffold extends StatelessWidget {
const _SheetScaffold();
@override
Widget build(BuildContext context) {
return CupertinoPageScaffold(
child: Center(
child: Column(
mainAxisAlignment: MainAxisAlignment.center,
children: <Widget>[
const Text('CupertinoSheetRoute'),
CupertinoButton.filled(
onPressed: () {
Navigator.of(context).maybePop();
},
child: const Text('Go Back'),
),
const Text('You can also close this sheet by dragging downwards'),
CupertinoButton.filled(
onPressed: () {
Navigator.of(context).push(
CupertinoSheetRoute<void>(
builder: (BuildContext context) => const _SheetScaffold(),
),
);
},
child: const Text('Push Another Sheet'),
),
],
),
),
);
}
}

120
examples/api/lib/cupertino/sheet/cupertino_sheet.1.dart Normal file
View File

@@ -0,0 +1,120 @@
// Copyright 2014 The Flutter 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 'package:flutter/cupertino.dart';
/// Flutter code sample for [showCupertinoSheet].
void main() {
runApp(const CupertinoSheetApp());
}
class CupertinoSheetApp extends StatelessWidget {
const CupertinoSheetApp({super.key});
@override
Widget build(BuildContext context) {
return const CupertinoApp(title: 'Cupertino Sheet', home: HomePage());
}
}
class HomePage extends StatelessWidget {
const HomePage({super.key});
@override
Widget build(BuildContext context) {
return CupertinoPageScaffold(
navigationBar: const CupertinoNavigationBar(
middle: Text('Sheet Example'),
automaticBackgroundVisibility: false,
),
child: Center(
child: Column(
mainAxisAlignment: MainAxisAlignment.center,
children: <Widget>[
CupertinoButton.filled(
onPressed: () {
showCupertinoSheet<void>(
context: context,
useNestedNavigation: true,
pageBuilder: (BuildContext context) => const _SheetScaffold(),
);
},
child: const Text('Open Bottom Sheet'),
),
],
),
),
);
}
}
class _SheetScaffold extends StatelessWidget {
const _SheetScaffold();
@override
Widget build(BuildContext context) {
return const CupertinoPageScaffold(child: _SheetBody(title: 'CupertinoSheetRoute'));
}
}
class _SheetBody extends StatelessWidget {
const _SheetBody({required this.title});
final String title;
@override
Widget build(BuildContext context) {
return Center(
child: Column(
mainAxisAlignment: MainAxisAlignment.center,
children: <Widget>[
Text(title),
CupertinoButton.filled(
onPressed: () {
Navigator.of(context).pop();
},
child: const Text('Go Back'),
),
CupertinoButton.filled(
onPressed: () {
CupertinoSheetRoute.popSheet(context);
},
child: const Text('Pop Whole Sheet'),
),
CupertinoButton.filled(
onPressed: () {
Navigator.of(context).push(
CupertinoPageRoute<void>(builder: (BuildContext context) => const _SheetNextPage()),
);
},
child: const Text('Push Nested Page'),
),
CupertinoButton.filled(
onPressed: () {
showCupertinoSheet<void>(
context: context,
useNestedNavigation: true,
pageBuilder: (BuildContext context) => const _SheetScaffold(),
);
},
child: const Text('Push Another Sheet'),
),
],
),
);
}
}
class _SheetNextPage extends StatelessWidget {
const _SheetNextPage();
@override
Widget build(BuildContext context) {
return const CupertinoPageScaffold(
backgroundColor: CupertinoColors.activeOrange,
child: _SheetBody(title: 'Next Page'),
);
}
}

278
examples/api/lib/cupertino/sheet/cupertino_sheet.2.dart Normal file
View File

@@ -0,0 +1,278 @@
// Copyright 2014 The Flutter 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 'package:flutter/cupertino.dart';
/// Flutter code sample for [CupertinoSheetRoute] with restorable state and nested navigation.
void main() => runApp(const RestorableSheetExampleApp());
class RestorableSheetExampleApp extends StatelessWidget {
const RestorableSheetExampleApp({super.key});
@override
Widget build(BuildContext context) {
return const CupertinoApp(
restorationScopeId: 'sheet-app',
title: 'Restorable Sheet',
home: RestorableSheet(restorationId: 'sheet'),
);
}
}
class RestorableSheet extends StatefulWidget {
const RestorableSheet({super.key, this.restorationId});
final String? restorationId;
@override
State<RestorableSheet> createState() => _RestorableSheetState();
}
@pragma('vm:entry-point')
class _RestorableSheetState extends State<RestorableSheet> with RestorationMixin {
final RestorableInt _counter = RestorableInt(0);
late RestorableRouteFuture<int?> _restorableSheetRouteFuture;
@override
void initState() {
super.initState();
_restorableSheetRouteFuture = RestorableRouteFuture<int?>(
onComplete: _changeCounter,
onPresent: (NavigatorState navigator, Object? arguments) {
return navigator.restorablePush(_counterSheetBuilder, arguments: _counter.value);
},
);
}
@override
String? get restorationId => widget.restorationId;
@override
void restoreState(RestorationBucket? oldBucket, bool initialRestore) {
registerForRestoration(_counter, 'count');
registerForRestoration(_restorableSheetRouteFuture, 'sheet_route_future');
}
@override
void dispose() {
_counter.dispose();
super.dispose();
}
@pragma('vm:entry-point')
static Route<void> _counterSheetBuilder(BuildContext context, Object? arguments) {
return CupertinoSheetRoute<int?>(
builder: (BuildContext context) {
return Navigator(
restorationScopeId: 'nested-nav',
onGenerateRoute: (RouteSettings settings) {
return CupertinoPageRoute<void>(
settings: settings,
builder: (BuildContext context) {
return PopScope(
canPop: settings.name != '/',
onPopInvokedWithResult: (bool didPop, Object? result) {
if (didPop) {
return;
}
Navigator.of(context).pop();
},
child: CounterSheetScaffold(counter: arguments! as int),
);
},
);
},
);
},
);
}
void _changeCounter(int? newCounter) {
if (newCounter != null) {
setState(() {
_counter.value = newCounter;
});
}
}
@override
Widget build(BuildContext context) {
return CupertinoPageScaffold(
navigationBar: const CupertinoNavigationBar(
middle: Text('Sheet Example'),
automaticBackgroundVisibility: false,
),
child: Center(
child: Column(
mainAxisAlignment: MainAxisAlignment.center,
children: <Widget>[
const Text('Counter current value:'),
Text('${_counter.value}'),
CupertinoButton(
child: const Text('Open Sheet'),
onPressed: () {
_restorableSheetRouteFuture.present();
},
),
],
),
),
);
}
}
class CounterSheetScaffold extends StatefulWidget {
const CounterSheetScaffold({super.key, required this.counter});
final int counter;
@override
State<CounterSheetScaffold> createState() => _CounterSheetScaffoldState();
}
class _CounterSheetScaffoldState extends State<CounterSheetScaffold> with RestorationMixin {
late RestorableInt _counter;
late RestorableRouteFuture<int?> _multiplicationRouteFuture;
@override
void initState() {
super.initState();
_counter = RestorableInt(widget.counter);
_multiplicationRouteFuture = RestorableRouteFuture<int?>(
onComplete: _changeCounter,
onPresent: (NavigatorState navigator, Object? arguments) {
return navigator.restorablePush(_multiplicationRouteBuilder, arguments: _counter.value);
},
);
}
@pragma('vm:entry-point')
static Route<void> _multiplicationRouteBuilder(BuildContext context, Object? arguments) {
return CupertinoPageRoute<int?>(
settings: const RouteSettings(name: '/multiplication'),
builder: (BuildContext context) {
return MultiplicationPage(counter: arguments! as int);
},
);
}
void _changeCounter(int? newCounter) {
if (newCounter != null) {
setState(() {
_counter.value = newCounter;
});
}
}
@override
String? get restorationId => 'sheet_scaffold';
@override
void restoreState(RestorationBucket? oldBucket, bool initialRestore) {
registerForRestoration(_counter, 'sheet_counter');
registerForRestoration(_multiplicationRouteFuture, 'multiplication_route');
if (!_counter.enabled) {
_counter = RestorableInt(widget.counter);
}
}
@override
void dispose() {
_counter.dispose();
_multiplicationRouteFuture.dispose();
super.dispose();
}
@override
Widget build(BuildContext context) {
return CupertinoPageScaffold(
child: Center(
child: Column(
mainAxisAlignment: MainAxisAlignment.center,
children: <Widget>[
Text('Current Count: ${_counter.value}'),
Row(
mainAxisAlignment: MainAxisAlignment.center,
children: <Widget>[
CupertinoButton(
onPressed: () {
setState(() => _counter.value = _counter.value - 1);
},
child: const Text('Decrease'),
),
CupertinoButton(
onPressed: () {
setState(() => _counter.value = _counter.value + 1);
},
child: const Text('Increase'),
),
],
),
CupertinoButton(
onPressed: () => _multiplicationRouteFuture.present(),
child: const Text('Go to Multiplication Page'),
),
CupertinoButton(
onPressed: () => Navigator.of(context, rootNavigator: true).pop(_counter.value),
child: const Text('Pop Sheet'),
),
],
),
),
);
}
}
class MultiplicationPage extends StatefulWidget {
const MultiplicationPage({super.key, required this.counter});
final int counter;
@override
State<MultiplicationPage> createState() => _MultiplicationPageState();
}
class _MultiplicationPageState extends State<MultiplicationPage> with RestorationMixin {
late final RestorableInt _counter = RestorableInt(widget.counter);
@override
String? get restorationId => 'multiplication_page';
@override
void restoreState(RestorationBucket? oldBucket, bool initialRestore) {
registerForRestoration(_counter, 'multi_counter');
}
@override
void dispose() {
_counter.dispose();
super.dispose();
}
@override
Widget build(BuildContext context) {
return CupertinoPageScaffold(
child: Center(
child: Column(
mainAxisAlignment: MainAxisAlignment.center,
children: <Widget>[
const Text('Current Count'),
Text(_counter.value.toString()),
CupertinoButton(
onPressed: () {
setState(() => _counter.value = _counter.value * 2);
},
child: const Text('Double it'),
),
CupertinoButton(
onPressed: () => Navigator.pop(context, _counter.value),
child: const Text('Pass it on to the last sheet'),
),
],
),
),
);
}
}

24
examples/api/test/cupertino/sheet/cupertino_sheet.0_test.dart Normal file
View File

@@ -0,0 +1,24 @@
// Copyright 2014 The Flutter 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 'package:flutter/cupertino.dart';
import 'package:flutter_api_samples/cupertino/sheet/cupertino_sheet.0.dart' as example;
import 'package:flutter_test/flutter_test.dart';
void main() {
testWidgets('Tap on button displays cupertino sheet', (WidgetTester tester) async {
await tester.pumpWidget(const example.CupertinoSheetApp());
final Finder dialogTitle = find.text('CupertinoSheetRoute');
expect(dialogTitle, findsNothing);
await tester.tap(find.byType(CupertinoButton));
await tester.pumpAndSettle();
expect(dialogTitle, findsOneWidget);
await tester.tap(find.text('Go Back'));
await tester.pumpAndSettle();
expect(dialogTitle, findsNothing);
});
}

44
examples/api/test/cupertino/sheet/cupertino_sheet.1_test.dart Normal file
View File

@@ -0,0 +1,44 @@
// Copyright 2014 The Flutter 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 'package:flutter/cupertino.dart';
import 'package:flutter_api_samples/cupertino/sheet/cupertino_sheet.1.dart' as example;
import 'package:flutter_test/flutter_test.dart';
void main() {
testWidgets('Tap on button displays cupertino sheet', (WidgetTester tester) async {
await tester.pumpWidget(const example.CupertinoSheetApp());
final Finder dialogTitle = find.text('CupertinoSheetRoute');
final Finder nextPageTitle = find.text('Next Page');
expect(dialogTitle, findsNothing);
expect(nextPageTitle, findsNothing);
await tester.tap(find.byType(CupertinoButton));
await tester.pumpAndSettle();
expect(dialogTitle, findsOneWidget);
expect(nextPageTitle, findsNothing);
await tester.tap(find.text('Push Nested Page'));
await tester.pumpAndSettle();
expect(dialogTitle, findsNothing);
expect(nextPageTitle, findsOneWidget);
await tester.tap(find.text('Push Another Sheet'));
await tester.pumpAndSettle();
// Both titles are on the screen, though one is covered by the second sheet.
expect(dialogTitle, findsOneWidget);
expect(nextPageTitle, findsOneWidget);
await tester.tap(find.text('Pop Whole Sheet').last);
await tester.pumpAndSettle();
expect(dialogTitle, findsNothing);
expect(nextPageTitle, findsOneWidget);
await tester.tap(find.text('Pop Whole Sheet'));
await tester.pumpAndSettle();
expect(dialogTitle, findsNothing);
expect(nextPageTitle, findsNothing);
});
}

47
examples/api/test/cupertino/sheet/cupertino_sheet.2_test.dart Normal file
View File

@@ -0,0 +1,47 @@
// Copyright 2014 The Flutter 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 'package:flutter/cupertino.dart';
import 'package:flutter_api_samples/cupertino/sheet/cupertino_sheet.2.dart' as example;
import 'package:flutter_test/flutter_test.dart';
void main() {
testWidgets('Tap on button displays cupertino sheet', (WidgetTester tester) async {
await tester.pumpWidget(const example.RestorableSheetExampleApp());
final Finder dialogTitle = find.text('Current Count: 0');
expect(dialogTitle, findsNothing);
await tester.tap(find.byType(CupertinoButton));
await tester.pumpAndSettle();
expect(dialogTitle, findsOneWidget);
await tester.tap(find.text('Pop Sheet'));
await tester.pumpAndSettle();
expect(dialogTitle, findsNothing);
});
testWidgets('State restoration keeps the counter at the right value', (
WidgetTester tester,
) async {
await tester.pumpWidget(const example.RestorableSheetExampleApp());
await tester.tap(find.byType(CupertinoButton));
await tester.pumpAndSettle();
expect(find.text('Current Count: 0'), findsOneWidget);
await tester.tap(find.text('Increase'));
await tester.pumpAndSettle();
await tester.tap(find.text('Increase'));
await tester.pumpAndSettle();
expect(find.text('Current Count: 2'), findsOneWidget);
await tester.restartAndRestore();
expect(find.text('Current Count: 2'), findsOneWidget);
});
}