Since its inception, Flutter has provided a straightforward, imperative navigation model known as Navigator 1.0. For many applications with simple, linear user flows, methods like Navigator.push() and Navigator.pop() were sufficient. Developers could easily push new screens onto a stack and pop them off. However, as applications grew in complexity and Flutter's reach expanded to the web, the limitations of this imperative approach became increasingly apparent. Managing deep links, synchronizing the browser's URL bar, handling the back button consistently, and orchestrating complex nested navigation flows became challenging, often requiring custom workarounds.
In response to these challenges, the Flutter team introduced a fundamentally different approach: a declarative navigation system, commonly referred to as Navigator 2.0. This isn't just an update; it's a complete paradigm shift. Instead of telling the framework *how* to navigate (e.g., "push this screen"), developers now declare *what* the navigation stack should look like based on the current application state. This state-driven philosophy grants developers unprecedented control and makes navigation a predictable function of the app's data, solving the core issues that plagued the older system.
This article provides a comprehensive exploration of the Navigator 2.0 API. We will dissect its core components, contrast its declarative nature with the imperative past, walk through a practical implementation, and discuss advanced patterns to build robust, scalable, and web-friendly Flutter applications.
The Paradigm Shift: Imperative vs. Declarative Routing
To truly appreciate Navigator 2.0, one must first understand the fundamental difference between imperative and declarative programming. This distinction is at the heart of the new API's design and purpose.
Navigator 1.0: The Imperative Approach
The original Navigator API is imperative. You issue direct commands to manipulate the navigation stack. Think of it as giving step-by-step instructions:
- "Go to the settings screen." (
Navigator.pushNamed(context, '/settings')) - "Add the detail screen on top of the current screen." (
Navigator.push(context, MaterialPageRoute(...))) - "Go back to the previous screen." (
Navigator.pop(context))
This model is intuitive for simple cases. However, it has a significant drawback: the navigation stack becomes its own source of state, separate from your application's business logic. This separation can lead to inconsistencies. For example, what happens if a user is logged out while on a profile page? You must imperatively find and remove all authenticated screens from the stack. What if a user receives a deep link to /orders/123? You need to manually construct the entire stack (e.g., Home -> Orders List -> Order Details) to provide a coherent user experience. This logic becomes tangled and difficult to manage.
// Imperative navigation in Navigator 1.0
void _showDetails() {
Navigator.push(
context,
MaterialPageRoute(builder: (context) => const DetailScreen()),
);
}
void _goBack() {
Navigator.pop(context);
}
Navigator 2.0: The Declarative Revolution
Navigator 2.0 flips the model on its head. It is declarative. You don't issue commands. Instead, you describe the desired state of the navigation stack as a direct result of your application's state. The framework then reconciles the current UI with your declared stack.
Imagine your application state is represented by an object:
class AppState {
bool isLoggedIn;
int? selectedItemId;
bool show404;
}
Your navigation logic becomes a function that maps this state to a list of pages:
List<Page> buildPagesFromState(AppState state) {
final pages = [
MaterialPage(key: ValueKey('HomePage'), child: HomeScreen()),
];
if (state.isLoggedIn && state.selectedItemId != null) {
pages.add(
MaterialPage(
key: ValueKey('ItemDetailsPage-${state.selectedItemId}'),
child: ItemDetailsScreen(itemId: state.selectedItemId!),
),
);
} else if (state.show404) {
pages.add(
MaterialPage(key: ValueKey('404Page'), child: UnknownScreen()),
);
}
return pages;
}
When you want to navigate, you don't call Navigator.push(). You simply modify the application state (e.g., set `selectedItemId = 123`) and notify the framework. Flutter automatically rebuilds the page list and animates the transition between the old and new stacks. This makes the navigation history a direct, predictable reflection of your app's state, solving the problems of deep linking, state synchronization, and complex conditional flows in one elegant stroke.
The Core Architecture of Navigator 2.0
The declarative API is built upon a set of interconnected classes that work together to translate application state into a visible navigation stack and synchronize it with the platform's URL. Understanding the role of each component is key to mastering Navigator 2.0.
1. Page
A Page is an immutable object that describes the configuration for a Route (the actual object that manages the widget, animations, and overlays in the navigation stack). It's a blueprint, not the final product. The key takeaway is that you build a `List
- `MaterialPage` / `CupertinoPage`: These are the most common implementations, providing platform-adaptive transitions (slide-up for iOS, fade for Android).
- `key`: Providing a `ValueKey` is crucial. It helps Flutter identify which page corresponds to which piece of data, preventing widgets from losing their state during rebuilds. For example, `ValueKey('book-${book.id}')` ensures the correct screen is maintained.
- `child`: The widget to be displayed on this page.
2. Router
The Router widget is the lynchpin of the new system. You no longer use `MaterialApp` directly, but rather its `MaterialApp.router` constructor. This constructor requires a `routerDelegate` and a `routeInformationParser`.
The `Router` widget's primary job is to listen to its delegate (`RouterDelegate`) and build a `Navigator` widget based on the list of pages provided. It also interfaces with the underlying platform routing mechanism (like the browser's history API) to report route changes.
3. RouteInformationParser
This class acts as a bidirectional translator between platform-specific route information (like a URL string) and a data type you define for your app's navigation state. It has two essential methods:
parseRouteInformation: This method is called when the platform reports a new route (e.g., the user types `/books/123` into the browser's address bar). Its job is to take the incomingRouteInformation(which contains the URL) and convert it into a custom data class that your `RouterDelegate` can understand. For `/books/123`, it might produce `AppRoutePath.details(123)`.restoreRouteInformation: This method does the opposite. When your `RouterDelegate` reports its current configuration (e.g., the user is viewing book 123), this method converts that configuration back intoRouteInformationso the platform can update the URL in the browser bar.
4. RouterDelegate
The `RouterDelegate` is the heart and soul of your navigation logic. It is the central authority that holds, listens to, and modifies your application's navigation state. It connects all the other pieces.
Key Responsibilities:
- Listening to App State: It should listen to your state management solution (a `ChangeNotifier`, `Stream`, `Bloc`, etc.) for changes that affect navigation.
- Building the Navigator: Its `build()` method is called by the `Router` widget. Here, you must construct a `Navigator` widget, providing it with the `List
` that represents the current state. - Updating State from Parser: Its `setNewRoutePath()` method is called by the framework when the `RouteInformationParser` has successfully parsed a new route. The delegate is responsible for updating its internal state based on this new path.
- Reporting State to Parser: The `currentConfiguration` getter must return the current route path, which the `RouteInformationParser` uses to update the browser URL via `restoreRouteInformation`.
- Handling Pop Events: By using the `PopNavigatorRouterDelegateMixin`, it can easily handle back button presses from the `Navigator`. The `popRoute` method is called, allowing you to update your state accordingly (e.g., set `selectedItemId = null`).
Typically, your `RouterDelegate` will extend `ChangeNotifier`, so it can call `notifyListeners()` whenever its state changes, triggering the `Router` to rebuild the navigator stack.
// The main app widget wiring everything together
class MyApp extends StatelessWidget {
@override
Widget build(BuildContext context) {
return MaterialApp.router(
title: 'Navigator 2.0 Example',
// The delegate that builds the navigator from app state
routerDelegate: MyRouterDelegate(),
// The parser that converts URLs to app state and back
routeInformationParser: MyRouteInformationParser(),
);
}
}
A Practical Example: A Master-Detail Book App
Let's solidify these concepts by building a simple app that shows a list of books. Tapping a book opens a detail screen. We want this to work on the web with clean URLs like `/` for the list and `/book/1` for a specific book.
Step 1: Define the Navigation State and Path
First, we define a simple class to represent our navigation path. This is the data structure that the parser and delegate will communicate with.
// Represents the parsed route information
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 && !isUnknown;
bool get isDetailsPage => id != null;
}
Step 2: Implement the `RouteInformationParser`
This class will handle parsing URL strings into our `BookRoutePath` object and vice versa.
class BookRouteInformationParser extends RouteInformationParser<BookRoutePath> {
@override
Future<BookRoutePath> parseRouteInformation(RouteInformation routeInformation) async {
final uri = Uri.parse(routeInformation.location ?? '');
// Handle '/'
if (uri.pathSegments.isEmpty) {
return BookRoutePath.home();
}
// Handle '/book/:id'
if (uri.pathSegments.length == 2 && uri.pathSegments[0] == 'book') {
final idString = uri.pathSegments[1];
final id = int.tryParse(idString);
if (id != null) {
return BookRoutePath.details(id);
}
}
// Handle unknown routes
return BookRoutePath.unknown();
}
@override
RouteInformation? restoreRouteInformation(BookRoutePath path) {
if (path.isUnknown) {
return const RouteInformation(location: '/404');
}
if (path.isHomePage) {
return const RouteInformation(location: '/');
}
if (path.isDetailsPage) {
return RouteInformation(location: '/book/${path.id}');
}
return null;
}
}
Step 3: Implement the `RouterDelegate`
This is the core logic. It holds the state (`_selectedBookId`, `_show404`), builds the page stack, and handles user actions.
class BookRouterDelegate extends RouterDelegate<BookRoutePath>
with ChangeNotifier, PopNavigatorRouterDelegateMixin<BookRoutePath> {
@override
final GlobalKey<NavigatorState> navigatorKey;
int? _selectedBookId;
bool _show404 = false;
// Dummy data for our app
final List<Book> books = [
Book('Stranger in a Strange Land', 'Robert A. Heinlein', 1),
Book('The Foundation', 'Isaac Asimov', 2),
Book('Fahrenheit 451', 'Ray Bradbury', 3),
];
BookRouterDelegate() : navigatorKey = GlobalKey<NavigatorState>();
@override
BookRoutePath get currentConfiguration {
if (_show404) {
return BookRoutePath.unknown();
}
return _selectedBookId == null
? BookRoutePath.home()
: BookRoutePath.details(_selectedBookId);
}
@override
Widget build(BuildContext context) {
return Navigator(
key: navigatorKey,
pages: [
MaterialPage(
key: const ValueKey('BooksListScreen'),
child: BooksListScreen(
books: books,
onTapped: _handleBookTapped,
),
),
if (_show404)
const MaterialPage(key: ValueKey('UnknownScreen'), child: UnknownScreen())
else if (_selectedBookId != null)
MaterialPage(
key: ValueKey('BookDetails-$_selectedBookId'),
child: BookDetailsScreen(book: books.firstWhere((b) => b.id == _selectedBookId)),
)
],
onPopPage: (route, result) {
if (!route.didPop(result)) {
return false;
}
// Handle pop when a detail screen is visible
_selectedBookId = null;
_show404 = false;
notifyListeners();
return true;
},
);
}
@override
Future<void> setNewRoutePath(BookRoutePath path) async {
if (path.isUnknown) {
_show404 = true;
_selectedBookId = null;
return;
}
if (path.isDetailsPage) {
if (books.any((b) => b.id == path.id)) {
_selectedBookId = path.id;
_show404 = false;
} else {
_show404 = true;
_selectedBookId = null;
}
} else {
_selectedBookId = null;
_show404 = false;
}
// No need to call notifyListeners() here, as this method is called by the
// framework which will trigger a rebuild.
}
void _handleBookTapped(Book book) {
_selectedBookId = book.id;
notifyListeners(); // Crucial! This tells the Router to rebuild.
}
}
Step 4: Create the UI Screens
Finally, we create the simple screens that are referenced by the delegate. The important part is the callback (`onTapped`) which allows the screen to communicate user intent back to the `RouterDelegate` to change the state.
// books_list_screen.dart
class BooksListScreen extends StatelessWidget {
final List<Book> books;
final ValueChanged<Book> onTapped;
const BooksListScreen({required this.books, required this.onTapped, Key? key}) : super(key: key);
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(title: const Text('Book Library')),
body: ListView(
children: [
for (var book in books)
ListTile(
title: Text(book.title),
subtitle: Text(book.author),
onTap: () => onTapped(book),
),
],
),
);
}
}
// book_details_screen.dart
class BookDetailsScreen extends StatelessWidget {
final Book book;
const BookDetailsScreen({required this.book, Key? key}) : super(key: key);
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(title: Text(book.title)),
body: Padding(
padding: const EdgeInsets.all(16.0),
child: Center(
child: Text('Details for "${book.title}" by ${book.author}.'),
),
),
);
}
}
With these pieces in place, we have a fully functioning navigation system. User taps update the state in the delegate, which calls `notifyListeners()`, rebuilding the `Navigator` with the new page stack. Direct URL changes are parsed, updating the delegate's state, which also rebuilds the stack. The flow is robust, predictable, and entirely driven by a single source of truth: the state within the `RouterDelegate`.
Advanced Concepts and Best Practices
While the above example covers the fundamentals, real-world applications often require more sophisticated patterns.
Integrating with State Management Solutions
The `RouterDelegate` should not be the primary owner of your application's state. Its role is to be a specialized controller for *navigation state*. Best practice is to have the delegate listen to your main state management solution (Provider, Riverpod, BLoC, etc.) and translate that state into a navigation stack.
For example, using `Provider`, your `RouterDelegate`'s constructor could take an `AppState` object and add a listener to it. When the `AppState` changes, the delegate calls `notifyListeners()` on itself to trigger a rebuild.
Nested Navigation
Navigator 2.0 excels at nested navigation, a common pattern in apps with a `BottomNavigationBar` or tab views where each tab maintains its own navigation history. The solution is to place a `Router` widget inside each tab's view. Each of these nested routers will have its own `RouterDelegate`, managing only the state relevant to that specific tab. The parent `RouterDelegate` would manage switching between the main tabs.
Simplifying with Packages
The verbosity and boilerplate of implementing Navigator 2.0 from scratch can be daunting. Recognizing this, the community has developed excellent packages that provide simpler, more opinionated APIs on top of Navigator 2.0, hiding much of the complexity.
- go_router: A popular choice that uses a URL-based approach. You define your routes as a map of URL patterns to builders (e.g., `'/family/:fid'`). It handles all the parsing and delegate implementation for you, making it feel closer to traditional web routing frameworks.
- auto_route: A code-generation based solution. You annotate your page widgets, and a build runner generates all the necessary routing code, providing a type-safe and less error-prone API.
- Beamer: A powerful library that focuses on `BeamState` and `BeamLocation` concepts to manage complex navigation and deep-linking scenarios with a high degree of control.
These packages are not a replacement for understanding the underlying API. They are powerful abstractions. Knowing how `RouterDelegate` and `RouteInformationParser` work will help you debug issues and leverage these packages to their full potential.
Configuring URL Strategy for Web
For Flutter web applications, the URL in the browser bar is critical. By default, Flutter uses a hash-based strategy (e.g., `myapp.com/#/book/1`). To get clean URLs (`myapp.com/book/1`), you need to configure a path-based strategy. This is a simple, one-line change in your `main.dart` file before `runApp()` is called.
import 'package:flutter_web_plugins/url_strategy.dart';
void main() {
// Use PathUrlStrategy for clean URLs.
usePathUrlStrategy();
runApp(const MyApp());
}
Remember that using the path strategy requires server-side configuration. Your web server must be configured to serve your `index.html` for any incoming path, allowing the Flutter app to handle the routing on the client side.
Conclusion: Embracing the Declarative Future
Flutter's Navigator 2.0 represents a significant evolution in how we think about routing and application architecture. It moves away from scattered, imperative commands and towards a centralized, declarative model where the UI is a direct and predictable function of the application's state. While the initial learning curve can be steep due to the number of new concepts, the payoff is immense. It provides a robust, scalable, and testable foundation for complex applications, especially those targeting the web.
For very simple apps with only a few linear screens, the original Navigator 1.0 API might still suffice. However, for any application with aspirations of complex user flows, deep linking, nested navigation, or first-class web support, investing the time to master the declarative Router API is not just recommended—it's essential for building modern, maintainable Flutter applications.
0 개의 댓글:
Post a Comment