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:

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 um Navigator que representa uma tela, normalmente implementado por classes como MaterialPageRoute.

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():

dart
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:

dart
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:

dart
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:

dart
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.

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 a RouteInformation de RouteInformationProvider e a interpreta em um tipo de dado definido pelo usuário.

  • RouterDelegate — define o comportamento específico do app de como o Router fica sabendo das mudanças no estado do app e como reage a elas. Sua função é escutar a RouteInformationParser e o estado do app e construir o Navigator com a lista atual de Pages.

  • BackButtonDispatcher — repassa os toques no botão voltar para o Router.

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:

  1. Quando a plataforma emite uma nova rota (por exemplo, “books/2”), o RouteInformationParser a converte em um tipo de dado abstrato T que você define no seu app (por exemplo, uma classe chamada BooksRoutePath).

  2. O método RouterDelegate do setNewRoutePath é chamado com esse tipo de dado e precisa atualizar o estado da aplicação para refletir a mudança (por exemplo, definindo o selectedBookId) e chamar notifyListeners.

  3. Quando notifyListeners é chamado, ele diz ao Router para reconstruir o RouterDelegate (usando o seu método build())

  4. RouterDelegate.build() retorna um novo Navigator, cujas páginas agora refletem a mudança no estado do app (por exemplo, o selectedBookId).

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:

dart
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:

dart
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 :

dart
@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):

dart
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:

dart
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:

dart
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:

dart
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:

dart
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:

dart
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.

dart
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:

dart
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:

dart
@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:

dart
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:

dart
@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:

dart
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:

dart
return MaterialApp.router(
  title: 'Books App',
  routerDelegate: _routerDelegate,
  routeInformationParser: _routeInformationParser,
);

Aqui está o exemplo completo:

dart
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:

dart
// 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:

dart
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 animada

  • markForAdd — 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 objeto result é passado para o callback onPopPage em AppRouterDelegate.

  • markForComplete — remove a rota sem transição e a completa com um result

  • 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.

Mais do Flutter