Skip to content

Commit 13fd74b

Browse files
stuartmorganstuartmorgan
authored
Merge branch 'flutter:main' into pigeon-test-harness-consolidation-ios
2 parents 0e9a556 + 77c9fea commit 13fd74b

File tree

166 files changed

+1424
-2961
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

166 files changed

+1424
-2961
lines changed

‎.github/workflows/scorecards-analysis.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,6 @@ jobs:
4949

5050
# Upload the results to GitHub's code scanning dashboard.
5151
- name: "Upload to code-scanning"
52-
uses: github/codeql-action/upload-sarif@807578363a7869ca324a79039e6db9c843e0e100 # v1.0.26
52+
uses: github/codeql-action/upload-sarif@4238421316c33d73aeea2801274dd286f157c2bb # v1.0.26
5353
with:
5454
sarif_file: results.sarif

‎packages/go_router/CHANGELOG.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
## 5.1.7
2+
3+
- Adds documentation using dartdoc topics
4+
15
## 5.1.6
26

37
- Fixes crashes when multiple `GoRoute`s use the same `parentNavigatorKey` in a route subtree.

‎packages/go_router/README.md‎

Lines changed: 45 additions & 225 deletions
Original file line numberDiff line numberDiff line change
@@ -1,235 +1,55 @@
11
# go_router
2-
3-
A Declarative Routing Package for Flutter.
4-
5-
This package uses the Flutter framework's Router API to provide a
2+
A declarative routing package for Flutter that uses the Router API to provide a
63
convenient, url-based API for navigating between different screens. You can
7-
define URL patterns, navigate using a URL, handle deep links,
8-
and a number of other navigation-related scenarios.
9-
10-
## Getting Started
11-
12-
Follow the [package install instructions](https://pub.dev/packages/go_router/install),
13-
and you can start using go_router in your app:
14-
15-
```dart
16-
import 'package:flutter/material.dart';
17-
import 'package:go_router/go_router.dart';
18-
19-
void main() => runApp(App());
20-
21-
class App extends StatelessWidget {
22-
App({Key? key}) : super(key: key);
23-
24-
@override
25-
Widget build(BuildContext context) {
26-
return MaterialApp.router(
27-
routerConfig: _router,
28-
title: 'GoRouter Example',
29-
);
30-
}
31-
32-
final GoRouter _router = GoRouter(
33-
routes: <GoRoute>[
34-
GoRoute(
35-
path: '/',
36-
builder: (BuildContext context, GoRouterState state) {
37-
return ScreenA();
38-
},
39-
),
40-
GoRoute(
41-
path: '/b',
42-
builder: (BuildContext context, GoRouterState state) {
43-
return ScreenB();
44-
},
45-
),
46-
],
47-
);
48-
}
49-
```
50-
51-
## Define Routes
52-
53-
go_router is governed by a set of routes which are specified as part of the
54-
[GoRouter](https://pub.dev/documentation/go_router/latest/go_router/GoRouter-class.html)
55-
constructor:
56-
57-
```dart
58-
GoRouter(
59-
routes: [
60-
GoRoute(
61-
path: '/',
62-
builder: (context, state) => const Page1Screen(),
63-
),
64-
GoRoute(
65-
path: '/page2',
66-
builder: (context, state) => const Page2Screen(),
67-
),
68-
],
69-
);
70-
```
71-
72-
In the above snippet, two routes are defined, `/` and `/page2`.
73-
When the URL changes, it is matched against each route path.
74-
The path is matched in a case-insensitive way, but the case for
75-
parameters is preserved. If there are multiple route matches,
76-
the **first match** in the list takes priority over the others.
77-
78-
The [builder](https://pub.dev/documentation/go_router/latest/go_router/GoRoute/builder.html)
79-
is responsible for building the `Widget` to display on screen.
80-
Alternatively, you can use `pageBuilder` to customize the transition
81-
animation when that route becomes active.
82-
The default transition is used between pages
83-
depending on the app at the top of its widget tree, e.g. the use of `MaterialApp`
84-
will cause go_router to use the `MaterialPage` transitions. Consider using
85-
[pageBuilder](https://pub.dev/documentation/go_router/latest/go_router/GoRoute/pageBuilder.html)
86-
for custom `Page` class.
87-
88-
## Initialization
89-
90-
Create a [GoRouter](https://pub.dev/documentation/go_router/latest/go_router/GoRouter-class.html)
91-
object and initialize your `MaterialApp` or `CupertinoApp`:
92-
93-
```dart
94-
final GoRouter _router = GoRouter(
95-
routes: <GoRoute>[
96-
// ...
97-
]
98-
);
99-
100-
MaterialApp.router(
101-
routerConfig: _router,
102-
);
103-
```
104-
105-
## Error handling
106-
107-
By default, go_router comes with default error screens for both `MaterialApp` and
108-
`CupertinoApp` as well as a default error screen in the case that none is used.
109-
Once can also replace the default error screen by using the [errorBuilder](https://pub.dev/documentation/go_router/latest/go_router/GoRouter/GoRouter.html):
110-
111-
```dart
112-
GoRouter(
113-
...
114-
errorBuilder: (context, state) => ErrorScreen(state.error),
115-
);
116-
```
117-
118-
## Redirection
119-
120-
You can use redirection to prevent the user from visiting a specific page. In
121-
go_router, redirection can be asynchronous.
122-
123-
```dart
124-
GoRouter(
125-
...
126-
redirect: (context, state) async {
127-
if (await LoginService.of(context).isLoggedIn) {
128-
// No redirect is required if the user is already logged in.
129-
return null;
130-
}
131-
return '/login';
132-
},
133-
);
134-
```
135-
136-
If the code depends on [BuildContext](https://api.flutter.dev/flutter/widgets/BuildContext-class.html)
137-
through the [dependOnInheritedWidgetOfExactType](https://api.flutter.dev/flutter/widgets/BuildContext/dependOnInheritedWidgetOfExactType.html)
138-
(which is how `of` methods are usually implemented), the redirect will be called every time the [InheritedWidget](https://api.flutter.dev/flutter/widgets/InheritedWidget-class.html)
139-
updated.
140-
141-
### Top-level redirect
142-
143-
The [GoRouter.redirect](https://pub.dev/documentation/go_router/latest/go_router/GoRouter-class.html)
144-
is always called for every navigation regardless of which GoRoute was matched. The
145-
top-level redirect always takes priority over route-level redirect.
146-
147-
### Route-level redirect
148-
149-
If the top-level redirect does not redirect to a different location,
150-
the [GoRoute.redirect](https://pub.dev/documentation/go_router/latest/go_router/GoRoute/redirect.html)
151-
is then called if the route has matched the GoRoute. If there are multiple
152-
GoRoute matches, e.g. GoRoute with sub-routes, the parent route redirect takes
153-
priority over sub-routes' redirect.
154-
155-
## Navigation
156-
157-
To navigate between routes, use the [GoRouter.go](https://pub.dev/documentation/go_router/latest/go_router/GoRouter/go.html) method:
158-
159-
```dart
160-
onTap: () => GoRouter.of(context).go('/page2')
161-
```
162-
163-
go_router also provides a more concise way to navigate using Dart extension
164-
methods:
165-
166-
```dart
167-
onTap: () => context.go('/page2')
168-
```
169-
170-
## Nested Navigation
171-
172-
The `ShellRoute` route type provides a way to wrap all sub-routes with a UI shell.
173-
Under the hood, GoRouter places a Navigator in the widget tree, which is used
174-
to display matching sub-routes:
175-
176-
```dart
177-
final _router = GoRouter(
178-
routes: [
179-
ShellRoute(
180-
builder: (context, state, child) {
181-
return AppScaffold(child: child);
182-
},
183-
routes: <RouteBase>[
184-
GoRoute(
185-
path: '/albums',
186-
builder: (context, state) {
187-
return HomeScreen();
188-
},
189-
routes: <RouteBase>[
190-
/// The details screen to display stacked on the inner Navigator.
191-
GoRoute(
192-
path: 'song/:songId',
193-
builder: (BuildContext context, GoRouterState state) {
194-
return const DetailsScreen(label: 'A');
195-
},
196-
),
197-
],
198-
),
199-
],
200-
),
201-
],
202-
);
203-
```
204-
205-
For more details, see the
206-
[ShellRoute](https://pub.dev/documentation/go_router/latest/go_router/ShellRoute-class.html)
207-
API documentation. For a complete
208-
example, see the
209-
[ShellRoute sample](https://github.com/flutter/packages/tree/main/packages/go_router/example/lib/shell_route.dart)
210-
in the example/ directory.
211-
212-
### Still not sure how to proceed?
213-
See [examples](https://github.com/flutter/packages/tree/main/packages/go_router/example) for complete runnable examples or visit [API documentation](https://pub.dev/documentation/go_router/latest/go_router/go_router-library.html)
214-
4+
define URL patterns, navigate using a URL, handle deep links, and a number of
5+
other navigation-related scenarios.
6+
7+
## Features
8+
GoRouter has a number of features to make navigation straightforward:
9+
10+
- Parsing path and query parameters using a template syntax (for example, "user/:id')
11+
- Displaying multiple screens for a destination (sub-routes)
12+
- Redirection support - you can re-route the user to a different URL based on
13+
application state, for example to a sign-in when the user is not
14+
authenticated
15+
- Support for multiple Navigators via
16+
[ShellRoute](https://pub.dev/documentation/go_router/ShellRoute-class.html) -
17+
you can display an inner Navigator that displays its own pages based on the
18+
matched route. For example, to display a BottomNavigationBar that stays
19+
visible at the bottom of the
20+
screen
21+
- Support for both Material and Cupertino apps
22+
- Backwards-compatibility with Navigator API
23+
24+
## Documentation
25+
See the API documentation for details on the following topics:
26+
27+
- [Getting started](https://pub.dev/documentation/go_router/latest/topics/Get%20started-topic.html)
28+
- [Upgrade an existing app](https://pub.dev/documentation/go_router/latest/topics/Upgrading-topic.html)
29+
- [Configuration](https://pub.dev/documentation/go_router/latest/topics/Configuration-topic.html)
30+
- [Navigation](https://pub.dev/documentation/go_router/latest/topics/Navigation-topic.html)
31+
- [Redirection](https://pub.dev/documentation/go_router/latest/topics/Redirection-topic.html)
32+
- [Web](https://pub.dev/documentation/go_router/latest/topics/Web-topic.html)
33+
- [Deep linking](https://pub.dev/documentation/go_router/latest/topics/Deep%20linking-topic.html)
34+
- [Transition animations](https://pub.dev/documentation/go_router/latest/topics/Transition%20animations-topic.html)
35+
- [Type-safe routes](https://pub.dev/documentation/go_router/latest/topics/Type-safe%20routes-topic.html)
36+
- [Named routes](https://pub.dev/documentation/go_router/latest/topics/Named%20routes-topic.html)
37+
- [Logging](https://pub.dev/documentation/go_router/latest/topics/Logging-topic.html)
38+
- [Error handling](https://pub.dev/documentation/go_router/latest/topics/Error%20handling-topic.html)
21539

21640
## Migration guides
217-
218-
- [Migrating to 2.0](https://flutter.dev/go/go-router-v2-breaking-changes)
219-
- [Migrating to 2.5](https://flutter.dev/go/go-router-v2-5-breaking-changes)
220-
- [Migrating to 3.0](https://flutter.dev/go/go-router-v3-breaking-changes)
221-
- [Migrating to 4.0](https://flutter.dev/go/go-router-v4-breaking-changes)
222-
- [Migrating to 5.0](https://flutter.dev/go/go-router-v5-breaking-changes)
22341
- [Migrating to 5.1.2](https://flutter.dev/go/go-router-v5-1-2-breaking-changes)
42+
- [Migrating to 5.0](https://flutter.dev/go/go-router-v5-breaking-changes)
43+
- [Migrating to 4.0](https://flutter.dev/go/go-router-v4-breaking-changes)
44+
- [Migrating to 3.0](https://flutter.dev/go/go-router-v3-breaking-changes)
45+
- [Migrating to 2.5](https://flutter.dev/go/go-router-v2-5-breaking-changes)
46+
- [Migrating to 2.0](https://flutter.dev/go/go-router-v2-breaking-changes)
22447

22548
## Changelog
226-
227-
See the [Changelog](https://github.com/flutter/packages/blob/main/packages/go_router/CHANGELOG.md)
49+
See the
50+
[Changelog](https://github.com/flutter/packages/blob/main/packages/go_router/CHANGELOG.md)
22851
for a list of new features and breaking changes.
22952

23053
## Roadmap
231-
232-
See the [github project](https://github.com/orgs/flutter/projects/17/) for our current priority.
233-
234-
235-
54+
See the [GitHub project](https://github.com/orgs/flutter/projects/17/) for a
55+
prioritized list of feature requests and known issues.

‎packages/go_router/dartdoc_options.yaml‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
dartdoc:
2+
categories:
3+
"Get started":
4+
markdown: doc/get-started.md
5+
name: Get started
6+
"Upgrading":
7+
markdown: doc/upgrading.md
8+
name: Upgrade an existing app
9+
"Configuration":
10+
markdown: doc/configuration.md
11+
name: Configuration
12+
"Navigation":
13+
markdown: doc/navigation.md
14+
name: Navigation
15+
"Redirection":
16+
markdown: doc/redirection.md
17+
name: Redirection
18+
"Web":
19+
markdown: doc/web.md
20+
name: Web
21+
"Deep linking":
22+
markdown: doc/deep-linking.md
23+
name: Deep linking
24+
"Transition animations":
25+
markdown: doc/transition-animations.md
26+
name: Transition animations
27+
"Type-safe routes":
28+
markdown: doc/type-safe-routes.md
29+
name: Type-safe routes
30+
"Named routes":
31+
markdown: doc/named-routes.md
32+
name: Type-safe routes
33+
"Error handling":
34+
markdown: doc/error-handling.md
35+
name: Error handling
36+
categoryOrder:
37+
- "Get started"
38+
- "Upgrading"
39+
- "Configuration"
40+
- "Navigation"
41+
- "Redirection"
42+
- "Web"
43+
- "Deep linking"
44+
- "Transition animations"
45+
- "Type-safe routes"
46+
- "Named routes"
47+
- "Error handling"
48+
showUndocumentedCategories: true
49+
ignore:
50+
- broken-link
51+
- missing-from-search-index

0 commit comments

Comments
 (0)