Skip to content

Commit 0b62965

Browse files
LukasMirbtLukasMirbt
authored
[go_router] Add state restoration topic to documentation (#9867)
Configuring state restoration with `go_router` is quite tricky and there are several open issues related to state restoration. This PR adds a section in the docs which clearly documents `go_router` state restoration as well as tests that verify the documented behavior. Related issues: flutter/flutter#129165, flutter/flutter#117683 ## Pre-Review Checklist **Note**: The Flutter team is currently trialing the use of [Gemini Code Assist for GitHub](https://developers.google.com/gemini-code-assist/docs/review-github-code). Comments from the `gemini-code-assist` bot should not be taken as authoritative feedback from the Flutter team. If you find its comments useful you can update your code accordingly, but if you are unsure or disagree with the feedback, please feel free to wait for a Flutter team member's review for guidance on which automated comments should be addressed. [^1]: Regular contributors who have demonstrated familiarity with the repository guidelines only need to comment if the PR is not auto-exempted by repo tooling.
1 parent 0a34f71 commit 0b62965

14 files changed

+660
-343
lines changed

‎packages/go_router/CHANGELOG.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
## 16.2.1
2+
3+
- Adds state restoration topic to documentation.
4+
15
## 16.2.0
26

37
- Adds `RelativeGoRouteData` and `TypedRelativeGoRoute`.

‎packages/go_router/README.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,7 @@ See the API documentation for details on the following topics:
3535
- [Type-safe routes](https://pub.dev/documentation/go_router/latest/topics/Type-safe%20routes-topic.html)
3636
- [Named routes](https://pub.dev/documentation/go_router/latest/topics/Named%20routes-topic.html)
3737
- [Error handling](https://pub.dev/documentation/go_router/latest/topics/Error%20handling-topic.html)
38+
- [State restoration](https://pub.dev/documentation/go_router/latest/topics/State%20restoration-topic.html)
3839

3940
## Migration Guides
4041
- [Migrating to 16.0.0](https://flutter.dev/go/go-router-v16-breaking-changes).

‎packages/go_router/dartdoc_options.yaml

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,9 @@ dartdoc:
3333
"Error handling":
3434
markdown: doc/error-handling.md
3535
name: Error handling
36+
"State restoration":
37+
markdown: doc/state-restoration.md
38+
name: State restoration
3639
categoryOrder:
3740
- "Get started"
3841
- "Upgrading"
@@ -45,6 +48,7 @@ dartdoc:
4548
- "Type-safe routes"
4649
- "Named routes"
4750
- "Error handling"
51+
- "State restoration"
4852
showUndocumentedCategories: true
4953
ignore:
5054
- broken-link

‎packages/go_router/doc/state-restoration.md

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
## What is state restoration?
2+
3+
State restoration refers to the process of persisting and restoring serialized state
4+
after the app has been killed by the operating system in the background.
5+
6+
For more information, see [Restore state on Android](https://docs.flutter.dev/platform-integration/android/restore-state-android)
7+
and [Restore state on iOS](https://docs.flutter.dev/platform-integration/ios/restore-state-ios).
8+
9+
> [!NOTE]
10+
> State restoration does not refer to general purpose state persistence.
11+
> For keeping multiple navigation branches in memory at the same time,
12+
> see [StatefulShellRoute](https://pub.dev/documentation/go_router/latest/go_router/StatefulShellRoute-class.html).
13+
14+
## Support
15+
16+
GoRouter fully supports state restoration.
17+
18+
To enable state restoration, a top-level configuration is needed
19+
as well as additional configuration depending on the types of routes used.
20+
21+
## Top-level configuration
22+
23+
Add `restorationScopeId`s to `GoRouter` and `MaterialApp.router`:
24+
25+
```dart
26+
final _router = GoRouter(
27+
restorationScopeId: 'router',
28+
routes: [
29+
...
30+
],
31+
);
32+
```
33+
34+
```dart
35+
class MyApp extends StatelessWidget {
36+
@override
37+
Widget build(BuildContext context) {
38+
return MaterialApp.router(
39+
restorationScopeId: 'app',
40+
routerConfig: _router,
41+
);
42+
}
43+
}
44+
```
45+
46+
## Route-specific configuration
47+
48+
### GoRoute
49+
50+
For a `GoRoute` that uses `pageBuilder`, supply a `restorationId` to the page:
51+
52+
```dart
53+
GoRoute(
54+
pageBuilder: (context, state) {
55+
return MaterialPage(
56+
restorationId: 'detailsPage',
57+
path: '/details',
58+
child: DetailsPage(),
59+
);
60+
},
61+
)
62+
```
63+
64+
For a `GoRoute` that does not use `pageBuilder`, no additional configuration
65+
is needed.
66+
67+
For a runnable example with tests, see the [GoRoute state restoration example](https://github.com/flutter/packages/tree/main/packages/go_router/example/lib/state_restoration/go_route_state_restoration.dart).
68+
69+
### ShellRoute
70+
71+
Add a unique `restorationScopeId` to the `ShellRoute`.
72+
Additionally, add a `pageBuilder` and supply a `restorationId` to the page.
73+
74+
> [!IMPORTANT]
75+
> A `pageBuilder` which returns a page with `restorationId` must be supplied for `ShellRoute` state restoration to work.
76+
77+
For a runnable example with tests, see the [ShellRoute state restoration example](https://github.com/flutter/packages/tree/main/packages/go_router/example/lib/state_restoration/shell_route_state_restoration.dart).
78+
79+
```dart
80+
ShellRoute(
81+
restorationScopeId: 'onboardingShell',
82+
pageBuilder: (context, state, child) {
83+
return MaterialPage(
84+
restorationId: 'onboardingPage',
85+
child: OnboardingScaffold(child: child),
86+
);
87+
},
88+
routes: [
89+
...
90+
],
91+
)
92+
```
93+
94+
### StatefulShellRoute
95+
96+
Add a `restorationScopeId` to the `StatefulShellRoute` and a
97+
`pageBuilder` which returns a page with a `restorationId`.
98+
99+
Additionally, add a `restorationScopeId` to each `StatefulShellBranch`.
100+
101+
> [!IMPORTANT]
102+
> A `pageBuilder` which returns a page with `restorationId` must be supplied for `StatefulShellRoute` state restoration to work.
103+
104+
For a runnable example with tests, see the [StatefulShellRoute state restoration example](https://github.com/flutter/packages/tree/main/packages/go_router/example/lib/state_restoration/stateful_shell_route_state_restoration.dart).
105+
106+
```dart
107+
StatefulShellRoute.indexedStack(
108+
restorationScopeId: 'appShell',
109+
pageBuilder: (context, state, navigationShell) {
110+
return MaterialPage(
111+
restorationId: 'appShellPage',
112+
child: AppShell(navigationShell: navigationShell),
113+
);
114+
},
115+
branches: [
116+
StatefulShellBranch(
117+
restorationScopeId: 'homeBranch',
118+
routes: [
119+
...
120+
],
121+
),
122+
StatefulShellBranch(
123+
restorationScopeId: 'profileBranch',
124+
routes: [
125+
...
126+
],
127+
),
128+
],
129+
)
130+
```

‎packages/go_router/example/lib/others/state_restoration.dart

Lines changed: 0 additions & 101 deletions
This file was deleted.

0 commit comments

Comments
 (0)