Aprendendo o novo sistema de Navigation e Routing do Flutter
Saiba como as APIs Navigator 2.0 e Router do Flutter oferecem suporte a navegação declarativa, deep links e URLs na web.
Nota: o código de exemplo deste artigo não é null-safe e não é compatível com Dart 3. Para mais informações sobre as melhores práticas atuais de navegação e roteamento no Flutter, acesse a página Navegação e roteamento em docs.flutter.dev.
Este artigo explica como funciona a nova API Navigator e Router do Flutter. Se você acompanha os design docs abertos do Flutter, pode ter visto esses novos recursos chamados de widget Router.
Vamos explorar como essas APIs permitem um controle mais refinado sobre as telas do seu app e como você pode usá-las para interpretar rotas.
Essas novas APIs não são breaking changes, elas simplesmente adicionam uma nova API declarativa. Antes do Navigator 2.0, era difícil empilhar ou desempilhar várias páginas, ou remover uma página abaixo da atual. No entanto, se você estiver satisfeito com o funcionamento atual do
Navigator, pode continuar usando-o do mesmo jeito (de forma imperativa).
O Router oferece a capacidade de tratar rotas vindas da plataforma subjacente e exibir as páginas apropriadas. Neste artigo, o
Router é configurado para interpretar a URL do navegador e exibir a página correta.
Este artigo ajuda você a escolher qual padrão Navigator funciona melhor para o seu app e explica como usar o Navigator 2.0 para interpretar URLs do navegador e ter controle total sobre a pilha de páginas ativas. O exercício deste artigo mostra como criar um app que trata rotas recebidas da plataforma e gerencia as páginas do seu app. O GIF a seguir mostra o app de exemplo em funcionamento:

Navigator 1.0
Se você usa Flutter, provavelmente usa o Navigator e conhece os seguintes conceitos:
-
Navigator— um widget que gerencia uma pilha de objetos Route. -
Route— um objeto gerenciado por umNavigatorque representa uma tela, normalmente implementado por classes comoMaterialPageRoute.
Antes do Navigator 2.0, Routes eram empilhadas e desempilhadas na pilha do Navigator com rotas nomeadas ou rotas anônimas. As próximas seções são um breve resumo dessas duas abordagens.
Rotas anônimas
A maioria dos apps móveis exibe telas umas sobre as outras, como uma pilha. No Flutter, isso é fácil de fazer usando o
Navigator.
MaterialApp e CupertinoApp já usam um Navigator por baixo dos panos. Você pode acessar o navigator usando
Navigator.of() ou exibir uma nova tela usando
Navigator.push(), e voltar para a tela anterior com
Navigator.pop():
import 'package:flutter/material.dart';
void main() {
runApp(Nav2App());
}
class Nav2App extends StatelessWidget {
@override
Widget build(BuildContext context) {
return MaterialApp(
home: HomeScreen(),
);
}
}
class HomeScreen extends StatelessWidget {
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(),
body: Center(
child: FlatButton(
child: Text('View Details'),
onPressed: () {
Navigator.push(
context,
MaterialPageRoute(builder: (context) {
return DetailScreen();
}),
);
},
),
),
);
}
}
class DetailScreen extends StatelessWidget {
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(),
body: Center(
child: FlatButton(
child: Text('Pop!'),
onPressed: () {
Navigator.pop(context);
},
),
),
);
}
}
Quando push() é chamado, o widget DetailScreen é colocado sobre o widget
HomeScreen, assim:

A tela anterior (HomeScreen) continua fazendo parte da árvore de widgets, então qualquer objeto State associado a ela continua existindo enquanto DetailScreen estiver visível.
Rotas nomeadas
O Flutter também oferece suporte a rotas nomeadas, que são definidas no parâmetro routes de MaterialApp
ou CupertinoApp:
import 'package:flutter/material.dart';
void main() {
runApp(Nav2App());
}
class Nav2App extends StatelessWidget {
@override
Widget build(BuildContext context) {
return MaterialApp(
routes: {
'/': (context) => HomeScreen(),
'/details': (context) => DetailScreen(),
},
);
}
}
class HomeScreen extends StatelessWidget {
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(),
body: Center(
child: FlatButton(
child: Text('View Details'),
onPressed: () {
Navigator.pushNamed(
context,
'/details',
);
},
),
),
);
}
}
class DetailScreen extends StatelessWidget {
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(),
body: Center(
child: FlatButton(
child: Text('Pop!'),
onPressed: () {
Navigator.pop(context);
},
),
),
);
}
}
Essas rotas precisam ser predefinidas. Embora você possa passar argumentos para uma rota nomeada, não é possível extrair argumentos da própria rota. Por exemplo, se o app rodar na web, você não consegue extrair o ID de uma rota como
/details/:id.
Rotas nomeadas avançadas com onGenerateRoute
Uma forma mais flexível de lidar com rotas nomeadas é usar onGenerateRoute. Essa API permite tratar todos os caminhos:
onGenerateRoute: (settings) {
// Handle '/'
if (settings.name == '/') {
return MaterialPageRoute(builder: (context) => HomeScreen());
}
// Handle '/details/:id'
var uri = Uri.parse(settings.name);
if (uri.pathSegments.length == 2 &&
uri.pathSegments.first == 'details') {
var id = uri.pathSegments[1];
return MaterialPageRoute(builder: (context) => DetailScreen(id: id));
}
return MaterialPageRoute(builder: (context) => UnknownScreen());
},
Aqui está o exemplo completo:
import 'package:flutter/material.dart';
void main() {
runApp(Nav2App());
}
class Nav2App extends StatelessWidget {
@override
Widget build(BuildContext context) {
return MaterialApp(
onGenerateRoute: (settings) {
// Handle '/'
if (settings.name == '/') {
return MaterialPageRoute(builder: (context) => HomeScreen());
}
// Handle '/details/:id'
var uri = Uri.parse(settings.name);
if (uri.pathSegments.length == 2 &&
uri.pathSegments.first == 'details') {
var id = uri.pathSegments[1];
return MaterialPageRoute(builder: (context) => DetailScreen(id: id));
}
return MaterialPageRoute(builder: (context) => UnknownScreen());
},
);
}
}
class HomeScreen extends StatelessWidget {
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(),
body: Center(
child: FlatButton(
child: Text('View Details'),
onPressed: () {
Navigator.pushNamed(
context,
'/details/1',
);
},
),
),
);
}
}
class DetailScreen extends StatelessWidget {
String id;
DetailScreen({
this.id,
});
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(),
body: Center(
child: Column(
mainAxisAlignment: MainAxisAlignment.center,
children: [
Text('Viewing details for item $id'),
FlatButton(
child: Text('Pop!'),
onPressed: () {
Navigator.pop(context);
},
),
],
),
),
);
}
}
class UnknownScreen extends StatelessWidget {
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(),
body: Center(
child: Text('404!'),
),
);
}
}
Aqui, settings é uma instância de RouteSettings. Os campos name e arguments são os valores fornecidos quando
Navigator.pushNamed
foi chamado, ou o valor definido em initialRoute.
Navigator 2.0
A API do Navigator 2.0 adiciona novas classes ao framework para fazer com que as telas do app sejam uma função do estado do app e para oferecer a capacidade de interpretar rotas vindas da plataforma subjacente (como URLs da web). Aqui está uma visão geral do que há de novo:
-
Page— um objeto imutável usado para definir a pilha de histórico do navigator. -
Router— configura a lista de páginas a serem exibidas pelo Navigator. Normalmente, essa lista muda com base na plataforma subjacente ou quando o estado do app muda. -
RouteInformationParser, que pega aRouteInformationdeRouteInformationProvidere a interpreta em um tipo de dado definido pelo usuário. -
RouterDelegate— define o comportamento específico do app de como oRouterfica sabendo das mudanças no estado do app e como reage a elas. Sua função é escutar aRouteInformationParsere o estado do app e construir oNavigatorcom a lista atual dePages. -
BackButtonDispatcher— repassa os toques no botão voltar para oRouter.
O diagrama a seguir mostra como o RouterDelegate interage com o Router,
RouteInformationParser e o estado do app:

Aqui está um exemplo de como essas peças interagem:
-
Quando a plataforma emite uma nova rota (por exemplo, “books/2”), o
RouteInformationParsera converte em um tipo de dado abstratoTque você define no seu app (por exemplo, uma classe chamadaBooksRoutePath). -
O método
RouterDelegatedosetNewRoutePathé chamado com esse tipo de dado e precisa atualizar o estado da aplicação para refletir a mudança (por exemplo, definindo oselectedBookId) e chamarnotifyListeners. -
Quando
notifyListenersé chamado, ele diz aoRouterpara reconstruir oRouterDelegate(usando o seu métodobuild()) -
RouterDelegate.build()retorna um novoNavigator, cujas páginas agora refletem a mudança no estado do app (por exemplo, oselectedBookId).
Exercício do Navigator 2.0
Esta seção guia você por um exercício usando a API do Navigator 2.0. Terminaremos com um app que consegue ficar sincronizado com a barra de URL e tratar os toques no botão voltar tanto do app quanto do navegador, como mostra o GIF a seguir:

Para acompanhar, mude para o canal master,
crie um novo projeto Flutter com suporte à web e substitua o conteúdo de
lib/main.dart pelo seguinte:
import 'package:flutter/material.dart';
void main() {
runApp(BooksApp());
}
class Book {
final String title;
final String author;
Book(this.title, this.author);
}
class BooksApp extends StatefulWidget {
@override
State<StatefulWidget> createState() => _BooksAppState();
}
class _BooksAppState extends State<BooksApp> {
void initState() {
super.initState();
}
@override
Widget build(BuildContext context) {
return MaterialApp(
title: 'Books App',
home: Navigator(
pages: [
MaterialPage(
key: ValueKey('BooksListPage'),
child: Scaffold(),
)
],
onPopPage: (route, result) => route.didPop(result),
),
);
}
}
Páginas
O Navigator tem um novo argumento pages em seu construtor. Se a lista de objetos Page
mudar, o Navigator atualiza a pilha de rotas para corresponder. Para ver como isso funciona, vamos criar um app que exibe uma lista de livros.
Em _BooksAppState, mantenha dois estados: uma lista de livros e o livro selecionado:
class _BooksAppState extends State<BooksApp> {
// New:
Book _selectedBook;
bool show404 = false;
List<Book> books = [
Book('Left Hand of Darkness', 'Ursula K. Le Guin'),
Book('Too Like the Lightning', 'Ada Palmer'),
Book('Kindred', 'Octavia E. Butler'),
];
// ...
Depois, em _BooksAppState, retorne um Navigator com uma lista de objetos Page
:
@override
Widget build(BuildContext context) {
return MaterialApp(
title: 'Books App',
home: Navigator(
pages: [
MaterialPage(
key: ValueKey('BooksListPage'),
child: BooksListScreen(
books: books,
onTapped: _handleBookTapped,
),
),
],
),
);
}
void _handleBookTapped(Book book) {
setState(() {
_selectedBook = book;
});
}
// ...
class BooksListScreen extends StatelessWidget {
final List<Book> books;
final ValueChanged<Book> onTapped;
BooksListScreen({
@required this.books,
@required this.onTapped,
});
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(),
body: ListView(
children: [
for (var book in books)
ListTile(
title: Text(book.title),
subtitle: Text(book.author),
onTap: () => onTapped(book),
)
],
),
);
}
}
Como este app tem duas telas, uma lista de livros e uma tela mostrando os detalhes, adicione uma segunda página (de detalhes) caso um livro esteja selecionado (usando
collection if):
pages: [
MaterialPage(
key: ValueKey('BooksListPage'),
child: BooksListScreen(
books: books,
onTapped: _handleBookTapped,
),
),
// New:
if (show404)
MaterialPage(key: ValueKey('UnknownPage'), child: UnknownScreen())
else if (_selectedBook != null)
MaterialPage(
key: ValueKey(_selectedBook),
child: BookDetailsScreen(book: _selectedBook))
],
Observe que a key da página é definida pelo valor do objeto book. Isso diz ao Navigator que este objeto MaterialPage é diferente de outro quando o objeto Book é diferente. Sem uma chave única, o framework não consegue determinar quando exibir uma animação de transição entre diferentes
Pages.
Observação: se preferir, você também pode estender Page para personalizar o comportamento. Por exemplo, esta página adiciona uma animação de transição personalizada:
class BookDetailsPage extends Page {
final Book book;
BookDetailsPage({
this.book,
}) : super(key: ValueKey(book));
Route createRoute(BuildContext context) {
return PageRouteBuilder(
settings: this,
pageBuilder: (context, animation, animation2) {
final tween = Tween(begin: Offset(0.0, 1.0), end: Offset.zero);
final curveTween = CurveTween(curve: Curves.easeInOut);
return SlideTransition(
position: animation.drive(curveTween).drive(tween),
child: BookDetailsScreen(
key: ValueKey(book),
book: book,
),
);
},
);
}
}
Por fim, é um erro fornecer um argumento pages
sem fornecer também um callback onPopPage. Essa função é chamada sempre que Navigator.pop() é chamado. Ela deve ser usada para atualizar o estado (que determina a lista de páginas), e deve chamar
didPop na rota para determinar se o pop foi bem-sucedido:
onPopPage: (route, result) {
if (!route.didPop(result)) {
return false;
}
// Update the list of pages by setting _selectedBook to null
setState(() {
_selectedBook = null;
});
return true;
},
É importante verificar se didPop falhou antes de atualizar o estado do app.
Usar setState notifica o framework para chamar o método build(), que retorna uma lista com uma única página quando
_selectedBook é null.
Aqui está o exemplo completo:
import 'package:flutter/material.dart';
void main() {
runApp(BooksApp());
}
class Book {
final String title;
final String author;
Book(this.title, this.author);
}
class BooksApp extends StatefulWidget {
@override
State<StatefulWidget> createState() => _BooksAppState();
}
class _BooksAppState extends State<BooksApp> {
Book _selectedBook;
List<Book> books = [
Book('Left Hand of Darkness', 'Ursula K. Le Guin'),
Book('Too Like the Lightning', 'Ada Palmer'),
Book('Kindred', 'Octavia E. Butler'),
];
@override
Widget build(BuildContext context) {
return MaterialApp(
title: 'Books App',
home: Navigator(
pages: [
MaterialPage(
key: ValueKey('BooksListPage'),
child: BooksListScreen(
books: books,
onTapped: _handleBookTapped,
),
),
if (_selectedBook != null) BookDetailsPage(book: _selectedBook)
],
onPopPage: (route, result) {
if (!route.didPop(result)) {
return false;
}
// Update the list of pages by setting _selectedBook to null
setState(() {
_selectedBook = null;
});
return true;
},
),
);
}
void _handleBookTapped(Book book) {
setState(() {
_selectedBook = book;
});
}
}
class BookDetailsPage extends Page {
final Book book;
BookDetailsPage({
this.book,
}) : super(key: ValueKey(book));
Route createRoute(BuildContext context) {
return MaterialPageRoute(
settings: this,
builder: (BuildContext context) {
return BookDetailsScreen(book: book);
},
);
}
}
class BooksListScreen extends StatelessWidget {
final List<Book> books;
final ValueChanged<Book> onTapped;
BooksListScreen({
@required this.books,
@required this.onTapped,
});
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(),
body: ListView(
children: [
for (var book in books)
ListTile(
title: Text(book.title),
subtitle: Text(book.author),
onTap: () => onTapped(book),
)
],
),
);
}
}
class BookDetailsScreen extends StatelessWidget {
final Book book;
BookDetailsScreen({
@required this.book,
});
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(),
body: Padding(
padding: const EdgeInsets.all(8.0),
child: Column(
crossAxisAlignment: CrossAxisAlignment.start,
children: [
if (book != null) ...[
Text(book.title, style: Theme.of(context).textTheme.headline6),
Text(book.author, style: Theme.of(context).textTheme.subtitle1),
],
],
),
),
);
}
}
Do jeito que está, este app só nos permite definir a pilha de páginas de forma declarativa. Não conseguimos tratar o botão voltar da plataforma, e a URL do navegador não muda enquanto navegamos.
Router
Até agora, o app consegue mostrar páginas diferentes, mas não consegue tratar rotas vindas da plataforma subjacente, por exemplo se o usuário alterar a URL no navegador.
Esta seção mostra como implementar o RouteInformationParser e o RouterDelegate, e atualizar o estado do app. Depois de configurado, o app permanece sincronizado com a URL do navegador.
Tipos de dados
O RouteInformationParser interpreta as informações da rota em um tipo de dado definido pelo usuário, então vamos definir esse tipo primeiro:
class BookRoutePath {
final int id;
final bool isUnknown;
BookRoutePath.home()
: id = null,
isUnknown = false;
BookRoutePath.details(this.id) : isUnknown = false;
BookRoutePath.unknown()
: id = null,
isUnknown = true;
bool get isHomePage => id == null;
bool get isDetailsPage => id != null;
}
Neste app, todas as rotas podem ser representadas usando uma única classe. Em vez disso, você pode optar por usar classes diferentes que implementam uma superclasse, ou gerenciar as informações de rota de outra forma.
RouterDelegate
Em seguida, adicione uma classe que estenda RouterDelegate:
class BookRouterDelegate extends RouterDelegate<BookRoutePath>
with ChangeNotifier, PopNavigatorRouterDelegateMixin<BookRoutePath> {
@override
Widget build(BuildContext context) {
// TODO
throw UnimplementedError();
}
@override
// TODO
GlobalKey<NavigatorState> get navigatorKey => throw UnimplementedError();
@override
Future<void> setNewRoutePath(BookRoutePath configuration) {
// TODO
throw UnimplementedError();
}
}
O tipo genérico definido em RouterDelegate é BookRoutePath, que contém todo o estado necessário para decidir quais páginas mostrar.
Precisaremos mover parte da lógica de _BooksAppState para BookRouterDelegate e criar um
GlobalKey. Neste exemplo, o estado do app fica armazenado diretamente em RouterDelegate, mas também poderia ser separado em outra classe.
class BookRouterDelegate extends RouterDelegate<BookRoutePath>
with ChangeNotifier, PopNavigatorRouterDelegateMixin<BookRoutePath> {
final GlobalKey<NavigatorState> navigatorKey;
Book _selectedBook;
bool show404 = false;
List<Book> books = [
Book('Left Hand of Darkness', 'Ursula K. Le Guin'),
Book('Too Like the Lightning', 'Ada Palmer'),
Book('Kindred', 'Octavia E. Butler'),
];
BookRouterDelegate() : navigatorKey = GlobalKey<NavigatorState>();
// ...
Para mostrar o caminho correto na URL, precisamos retornar um BookRoutePath com base no estado atual do app:
BookRoutePath get currentConfiguration {
if (show404) {
return BookRoutePath.unknown();
}
return _selectedBook == null
? BookRoutePath.home()
: BookRoutePath.details(books.indexOf(_selectedBook));
}
Em seguida, o método build em um RouterDelegate precisa retornar um Navigator:
@override
Widget build(BuildContext context) {
return Navigator(
key: navigatorKey,
pages: [
MaterialPage(
key: ValueKey('BooksListPage'),
child: BooksListScreen(
books: books,
onTapped: _handleBookTapped,
),
),
if (show404)
MaterialPage(key: ValueKey('UnknownPage'), child: UnknownScreen())
else if (_selectedBook != null)
BookDetailsPage(book: _selectedBook)
],
onPopPage: (route, result) {
if (!route.didPop(result)) {
return false;
}
// Update the list of pages by setting _selectedBook to null
_selectedBook = null;
show404 = false;
notifyListeners();
return true;
},
);
}
O callback onPopPage agora usa notifyListeners em vez de setState, já que esta classe agora é um
ChangeNotifier, não um widget. Quando o RouterDelegate notifica seus listeners, o widget
Router também é notificado de que o RouterDelegate's currentConfiguration
mudou e que seu método build precisa ser chamado novamente para construir um novo Navigator.
O método _handleBookTapped também precisa usar notifyListeners em vez de setState:
void _handleBookTapped(Book book) {
_selectedBook = book;
notifyListeners();
}
Quando uma nova rota é empurrada para o app, Router chama setNewRoutePath, o que dá ao nosso app a oportunidade de atualizar o estado do app com base nas mudanças na rota:
@override
Future<void> setNewRoutePath(BookRoutePath path) async {
if (path.isUnknown) {
_selectedBook = null;
show404 = true;
return;
}
if (path.isDetailsPage) {
if (path.id < 0 || path.id > books.length - 1) {
show404 = true;
return;
}
_selectedBook = books[path.id];
} else {
_selectedBook = null;
}
show404 = false;
}
RouteInformationParser
O RouteInformationParser oferece um gancho para interpretar as rotas recebidas (RouteInformation) e convertê-las em um tipo definido pelo usuário (BookRoutePath). Use a classe
Uri para cuidar da interpretação:
class BookRouteInformationParser extends RouteInformationParser<BookRoutePath> {
@override
Future<BookRoutePath> parseRouteInformation(
RouteInformation routeInformation) async {
final uri = Uri.parse(routeInformation.location);
// Handle '/'
if (uri.pathSegments.length == 0) {
return BookRoutePath.home();
}
// Handle '/book/:id'
if (uri.pathSegments.length == 2) {
if (uri.pathSegments[0] != 'book') return BookRoutePath.unknown();
var remaining = uri.pathSegments[1];
var id = int.tryParse(remaining);
if (id == null) return BookRoutePath.unknown();
return BookRoutePath.details(id);
}
// Handle unknown routes
return BookRoutePath.unknown();
}
@override
RouteInformation restoreRouteInformation(BookRoutePath path) {
if (path.isUnknown) {
return RouteInformation(location: '/404');
}
if (path.isHomePage) {
return RouteInformation(location: '/');
}
if (path.isDetailsPage) {
return RouteInformation(location: '/book/${path.id}');
}
return null;
}
}
Esta implementação é específica para este app, não é uma solução geral de interpretação de rotas. Falaremos mais sobre isso depois.
Para usar essas novas classes, usamos o novo construtor MaterialApp.router e passamos nossas implementações personalizadas:
return MaterialApp.router(
title: 'Books App',
routerDelegate: _routerDelegate,
routeInformationParser: _routeInformationParser,
);
Aqui está o exemplo completo:
import 'package:flutter/material.dart';
void main() {
runApp(BooksApp());
}
class Book {
final String title;
final String author;
Book(this.title, this.author);
}
class BooksApp extends StatefulWidget {
@override
State<StatefulWidget> createState() => _BooksAppState();
}
class _BooksAppState extends State<BooksApp> {
BookRouterDelegate _routerDelegate = BookRouterDelegate();
BookRouteInformationParser _routeInformationParser =
BookRouteInformationParser();
@override
Widget build(BuildContext context) {
return MaterialApp.router(
title: 'Books App',
routerDelegate: _routerDelegate,
routeInformationParser: _routeInformationParser,
);
}
}
class BookRouteInformationParser extends RouteInformationParser<BookRoutePath> {
@override
Future<BookRoutePath> parseRouteInformation(
RouteInformation routeInformation) async {
final uri = Uri.parse(routeInformation.location);
// Handle '/'
if (uri.pathSegments.length == 0) {
return BookRoutePath.home();
}
// Handle '/book/:id'
if (uri.pathSegments.length == 2) {
if (uri.pathSegments[0] != 'book') return BookRoutePath.unknown();
var remaining = uri.pathSegments[1];
var id = int.tryParse(remaining);
if (id == null) return BookRoutePath.unknown();
return BookRoutePath.details(id);
}
// Handle unknown routes
return BookRoutePath.unknown();
}
@override
RouteInformation restoreRouteInformation(BookRoutePath path) {
if (path.isUnknown) {
return RouteInformation(location: '/404');
}
if (path.isHomePage) {
return RouteInformation(location: '/');
}
if (path.isDetailsPage) {
return RouteInformation(location: '/book/${path.id}');
}
return null;
}
}
class BookRouterDelegate extends RouterDelegate<BookRoutePath>
with ChangeNotifier, PopNavigatorRouterDelegateMixin<BookRoutePath> {
final GlobalKey<NavigatorState> navigatorKey;
Book _selectedBook;
bool show404 = false;
List<Book> books = [
Book('Left Hand of Darkness', 'Ursula K. Le Guin'),
Book('Too Like the Lightning', 'Ada Palmer'),
Book('Kindred', 'Octavia E. Butler'),
];
BookRouterDelegate() : navigatorKey = GlobalKey<NavigatorState>();
BookRoutePath get currentConfiguration {
if (show404) {
return BookRoutePath.unknown();
}
return _selectedBook == null
? BookRoutePath.home()
: BookRoutePath.details(books.indexOf(_selectedBook));
}
@override
Widget build(BuildContext context) {
return Navigator(
key: navigatorKey,
pages: [
MaterialPage(
key: ValueKey('BooksListPage'),
child: BooksListScreen(
books: books,
onTapped: _handleBookTapped,
),
),
if (show404)
MaterialPage(key: ValueKey('UnknownPage'), child: UnknownScreen())
else if (_selectedBook != null)
BookDetailsPage(book: _selectedBook)
],
onPopPage: (route, result) {
if (!route.didPop(result)) {
return false;
}
// Update the list of pages by setting _selectedBook to null
_selectedBook = null;
show404 = false;
notifyListeners();
return true;
},
);
}
@override
Future<void> setNewRoutePath(BookRoutePath path) async {
if (path.isUnknown) {
_selectedBook = null;
show404 = true;
return;
}
if (path.isDetailsPage) {
if (path.id < 0 || path.id > books.length - 1) {
show404 = true;
return;
}
_selectedBook = books[path.id];
} else {
_selectedBook = null;
}
show404 = false;
}
void _handleBookTapped(Book book) {
_selectedBook = book;
notifyListeners();
}
}
class BookDetailsPage extends Page {
final Book book;
BookDetailsPage({
this.book,
}) : super(key: ValueKey(book));
Route createRoute(BuildContext context) {
return MaterialPageRoute(
settings: this,
builder: (BuildContext context) {
return BookDetailsScreen(book: book);
},
);
}
}
class BookRoutePath {
final int id;
final bool isUnknown;
BookRoutePath.home()
: id = null,
isUnknown = false;
BookRoutePath.details(this.id) : isUnknown = false;
BookRoutePath.unknown()
: id = null,
isUnknown = true;
bool get isHomePage => id == null;
bool get isDetailsPage => id != null;
}
class BooksListScreen extends StatelessWidget {
final List<Book> books;
final ValueChanged<Book> onTapped;
BooksListScreen({
@required this.books,
@required this.onTapped,
});
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(),
body: ListView(
children: [
for (var book in books)
ListTile(
title: Text(book.title),
subtitle: Text(book.author),
onTap: () => onTapped(book),
)
],
),
);
}
}
class BookDetailsScreen extends StatelessWidget {
final Book book;
BookDetailsScreen({
@required this.book,
});
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(),
body: Padding(
padding: const EdgeInsets.all(8.0),
child: Column(
crossAxisAlignment: CrossAxisAlignment.start,
children: [
if (book != null) ...[
Text(book.title, style: Theme.of(context).textTheme.headline6),
Text(book.author, style: Theme.of(context).textTheme.subtitle1),
],
],
),
),
);
}
}
class UnknownScreen extends StatelessWidget {
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(),
body: Center(
child: Text('404!'),
),
);
}
}
Executar este exemplo no Chrome agora mostra as rotas conforme são navegadas e leva à página correta quando a URL é editada manualmente.
TransitionDelegate
Você pode fornecer uma implementação personalizada de TransitionDelegate que personaliza como as rotas aparecem na tela (ou são removidas dela) quando a lista de páginas muda. Se precisar personalizar isso, continue lendo, mas se estiver satisfeito com o comportamento padrão, pode pular esta seção.
Forneça um TransitionDelegate personalizado para um Navigator que defina o comportamento desejado:
// New:
TransitionDelegate transitionDelegate = NoAnimationTransitionDelegate();
child: Navigator(
key: navigatorKey,
// New:
transitionDelegate: transitionDelegate,
Por exemplo, a implementação a seguir desativa todas as animações de transição:
class NoAnimationTransitionDelegate extends TransitionDelegate<void> {
@override
Iterable<RouteTransitionRecord> resolve({
List<RouteTransitionRecord> newPageRouteHistory,
Map<RouteTransitionRecord, RouteTransitionRecord>
locationToExitingPageRoute,
Map<RouteTransitionRecord, List<RouteTransitionRecord>>
pageRouteToPagelessRoutes,
}) {
final results = <RouteTransitionRecord>[];
for (final pageRoute in newPageRouteHistory) {
if (pageRoute.isWaitingForEnteringDecision) {
pageRoute.markForAdd();
}
results.add(pageRoute);
}
for (final exitingPageRoute in locationToExitingPageRoute.values) {
if (exitingPageRoute.isWaitingForExitingDecision) {
exitingPageRoute.markForRemove();
final pagelessRoutes = pageRouteToPagelessRoutes[exitingPageRoute];
if (pagelessRoutes != null) {
for (final pagelessRoute in pagelessRoutes) {
pagelessRoute.markForRemove();
}
}
}
results.add(exitingPageRoute);
}
return results;
}
}
Esta implementação personalizada sobrescreve resolve(), que é responsável por marcar as várias rotas como empurradas, removidas, adicionadas, concluídas ou descartadas:
markForPush— exibe a rota com uma transição animadamarkForAdd— exibe a rota sem transição animada-
markForPop— remove a rota com uma transição animada e a completa com um resultado. “Completar” neste contexto significa que o objetoresulté passado para o callbackonPopPageemAppRouterDelegate. -
markForComplete— remove a rota sem transição e a completa com umresult -
markForRemove— remove a rota sem transição animada e sem completá-la.
Esta classe afeta apenas a API declarativa, e por isso o botão voltar ainda exibe uma animação de transição.
Como este exemplo funciona: Este exemplo analisa tanto as novas rotas quanto as rotas que estão saindo da tela. Ele percorre todos os objetos em
newPageRouteHistory e os marca para serem adicionados sem animação de transição usando markForAdd. Em seguida, percorre os valores do mapa
locationToExitingPageRoute. Se encontrar uma rota marcada como isWaitingForExitingDecision, chama
markForRemove para indicar que a rota deve ser removida sem transição e sem completá-la.
Aqui está o exemplo completo (Gist).
Routers aninhados
Esta demonstração maior mostra como adicionar um Router dentro de outro Router. Muitos apps precisam de rotas para os destinos em um
BottomAppBar e rotas para uma pilha de visualizações acima dele, o que exige dois Navigators. Para isso, o app usa um objeto de estado da aplicação para armazenar o estado de navegação específico do app (o índice do menu selecionado e o objeto
Book selecionado). Este exemplo também mostra como configurar qual Router trata o botão voltar.
Exemplo de router aninhado (Gist)
Próximos passos
Este artigo explorou como usar essas APIs para um app específico, mas elas também podem ser usadas para construir um pacote de API de nível mais alto. Esperamos que você se junte a nós para explorar o que uma API de nível mais alto construída sobre esses recursos pode fazer pelos usuários.