[go_router] Update README.md (#2409)
* Create README.md
Update the go_router README
* Update README.md
* Bump version, update CHANGELOG
diff --git a/packages/go_router/CHANGELOG.md b/packages/go_router/CHANGELOG.md
index 7f59c92..3e73bd1 100644
--- a/packages/go_router/CHANGELOG.md
+++ b/packages/go_router/CHANGELOG.md
@@ -1,3 +1,7 @@
+## 4.2.7
+
+- Update README
+
## 4.2.6
- Fixes rendering issues in the README.
diff --git a/packages/go_router/README.md b/packages/go_router/README.md
index af47513..edd832b 100644
--- a/packages/go_router/README.md
+++ b/packages/go_router/README.md
@@ -1,36 +1,49 @@
-# go_router, A Declarative Routing Package for Flutter
+# go_router
-This package builds on top of the Flutter framework's Router API and provides
-convenient url-based APIs to navigate between different screens. You can
-define your own url patterns, navigating to different url, handle deep and
-dynamic linking, and a number of other navigation-related scenarios.
+A Declarative Routing Package for Flutter.
+
+This package uses the Flutter framework's Router API to provide a
+convenient, url-based API for navigating between different screens. You can
+define URL patterns, navigate using a URL, handle deep links,
+and a number of other navigation-related scenarios.
## Getting Started
Follow the [package install instructions](https://pub.dev/packages/go_router/install),
-and you can start using go_router in your code:
+and you can start using go_router in your app:
```dart
+import 'package:flutter/material.dart';
+import 'package:go_router/go_router.dart';
+
+void main() => runApp(App());
+
class App extends StatelessWidget {
App({Key? key}) : super(key: key);
@override
- Widget build(BuildContext context) => MaterialApp.router(
- routeInformationProvider: _router.routeInformationProvider,
- routeInformationParser: _router.routeInformationParser,
- routerDelegate: _router.routerDelegate,
- title: 'GoRouter Example',
- );
+ Widget build(BuildContext context) {
+ return MaterialApp.router(
+ routeInformationProvider: _router.routeInformationProvider,
+ routeInformationParser: _router.routeInformationParser,
+ routerDelegate: _router.routerDelegate,
+ title: 'GoRouter Example',
+ );
+ }
final GoRouter _router = GoRouter(
routes: <GoRoute>[
GoRoute(
path: '/',
- builder: (BuildContext context, GoRouterState state) => const Page1Screen(),
+ builder: (BuildContext context, GoRouterState state) {
+ return ScreenA();
+ },
),
GoRoute(
- path: '/page2',
- builder: (BuildContext context, GoRouterState state) => const Page2Screen(),
+ path: '/b',
+ builder: (BuildContext context, GoRouterState state) {
+ return ScreenB();
+ },
),
],
);
@@ -39,7 +52,7 @@
## Define Routes
-go_router is governed by a set of routes which are specify as part of the
+go_router is governed by a set of routes which are specified as part of the
[GoRouter](https://pub.dev/documentation/go_router/latest/go_router/GoRouter-class.html)
constructor:
@@ -58,15 +71,17 @@
);
```
-It defined two routes, `/` and `/page2`. Each route path will be matched against
-the location to which the user is navigating. The path will be matched in a
-case-insensitive way, although the case for parameters will be preserved. If
-there are multiple route matches, the <b>first</b> match in the list takes priority
-over the others.
+In the above snippet, two routes are defined, `/` and `/page2`.
+When the URL changes, it is matched against each route path.
+The path is matched in a case-insensitive way, but the case for
+parameters is preserved. If there are multiple route matches,
+the **first match** in the list takes priority over the others.
-In addition to the path, each route will typically have a [builder](https://pub.dev/documentation/go_router/latest/go_router/GoRoute/builder.html)
-function that is responsible for building the `Widget` that is to take up the
-entire screen of the app. The default transition is used between pages
+The [builder](https://pub.dev/documentation/go_router/latest/go_router/GoRoute/builder.html)
+is responsible for building the `Widget` to display on screen.
+Alternatively, you can use `pageBuilder` to customize the transition
+animation when that route becomes active.
+The default transition is used between pages
depending on the app at the top of its widget tree, e.g. the use of `MaterialApp`
will cause go_router to use the `MaterialPage` transitions. Consider using
[pageBuilder](https://pub.dev/documentation/go_router/latest/go_router/GoRoute/pageBuilder.html)
@@ -74,11 +89,15 @@
## Initalization
-Once a [GoRouter](https://pub.dev/documentation/go_router/latest/go_router/GoRouter-class.html)
-object is created, it can be used to initialize `MaterialApp` or `CupertinoApp`.
+Create a [GoRouter](https://pub.dev/documentation/go_router/latest/go_router/GoRouter-class.html)
+object and initialize your `MaterialApp` or `CupertinoApp`:
```dart
-final GoRouter _router = GoRouter(..);
+final GoRouter _router = GoRouter(
+ routes: <GoRoute>[
+ // ...
+ ]
+);
MaterialApp.router(
routeInformationProvider: _router.routeInformationProvider,
@@ -108,16 +127,15 @@
onTap: () => GoRouter.of(context).go('/page2')
```
-go_router also provides a simplified means of navigation using Dart extension
+go_router also provides a more concise way to navigate using Dart extension
methods:
```dart
onTap: () => context.go('/page2')
```
-<br>
-
-### Still not sure how to proceed? 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)
+### Still not sure how to proceed?
+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)
## Migration guides
diff --git a/packages/go_router/pubspec.yaml b/packages/go_router/pubspec.yaml
index bb20820..6f6a2db 100644
--- a/packages/go_router/pubspec.yaml
+++ b/packages/go_router/pubspec.yaml
@@ -1,7 +1,7 @@
name: go_router
description: A declarative router for Flutter based on Navigation 2 supporting
deep linking, data-driven routes and more
-version: 4.2.6
+version: 4.2.7
repository: https://github.com/flutter/packages/tree/main/packages/go_router
issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+go_router%22
