Navigator: zarządzanie ekranami we Flutter

Czym jest Navigator we Flutter

Navigator — to widget zarządzający stosem obiektów Route, który implementuje nawigację ekranową w aplikacji Flutter. Każde wywołanie push umieszcza nowy Route na szczycie stosu, pop usuwa górny Route i wraca do poprzedniego ekranu. MaterialApp automatycznie tworzy Navigator dla całej aplikacji, udostępniając go przez Navigator.of(context).

W przeciwieństwie do StatefulWidget, gdzie zmiana zawartości odbywa się przez setState wewnątrz jednego widgeta, Navigator operuje na całych ekranach z własnym cyklem życia. Każdy Route w stosie to izolowany stan z własnym BuildContext, co zapobiega wyciekom pamięci i upraszcza zarządzanie zależnościami. Przy wywołaniu pop nieużywany Route jest niszczony, zwalniając zasoby.

Według Flutter Navigation Guide (2026), Navigator przeszedł ewolucję od imperatywnego API (Navigator 1.0) do deklaratywnego (Navigator 2.0). Navigator 1.0 używa metod push/pop bezpośrednio, co jest wygodne w prostych scenariuszach. Navigator 2.0 (Router) nadaje się do aplikacji z głębokimi linkami, adaptacyjną nawigacją i routingiem webowym.

Jak Navigator działa pod maską

Wewnątrz Navigator używa Overlay — specjalnego widgeta, który wyświetla Route jeden nad drugim. Każdy Route tworzy własną pozycję w Overlay z indeksem Z odpowiadającym głębokości w stosie. To wyjaśnia, dlaczego przy push nowy ekran jest animowany nad poprzednim, a przy pop — poprzedni ekran jest już gotowy do wyświetlenia: nie został zniszczony, tylko pozostał w Overlay poniżej nowego.

Do animacji przejść Navigator używa PageTransitionsTheme, które można nadpisać w ThemeData. Animacje platformowe są ustawiane przez CupertinoPageRoute dla iOS (przesunięcie z prawej) i MaterialPageRoute dla Androida (przesunięcie z dołu). Navigator automatycznie wybiera właściwą animację przy użyciu PlatformRoute.

Metody Navigator: push, pop i pushReplacement

Navigator udostępnia zestaw metod do zarządzania stosem Route. Każda metoda rozwiązuje konkretne zadanie nawigacji — od prostego przejścia do całkowitej zamiany historii ekranów. Przyjrzyjmy się głównym metodom z przykładami użycia.

Push i Pop: podstawowe operacje

Metoda push przyjmuje Route i zwraca Future z wynikiem przekazanym przy pop. Umożliwia to odbieranie danych z ekranu, do którego przeszliśmy. Na przykład ekran wyboru daty może zwrócić DateTime przez Navigator.pop(context, selectedDate). Metoda pop bez argumentu zwraca null, z argumentem — przekazuje wartość do wywołującego ekranu.

PushReplacement: zamiana ekranu

pushReplacement zastępuje bieżącą Route nową, usuwając bieżącą ze stosu. Jest to kluczowe w scenariuszach, gdzie użytkownik nie powinien wracać do poprzedniego ekranu. Typowy przykład — ekran logowania: po pomyślnym zalogowaniu bieżący ekran jest zastępowany głównym, a przycisk „Wstecz” nie wraca do formularza logowania.

Nazwane trasy i onGenerateRoute

Navigator obsługuje nawigację po nazwanych trasach przez metodę pushNamed. Zamiast bezpośredniego tworzenia Route, programista podaje identyfikator tekstowy, a Navigator tworzy Route automatycznie na podstawie konfiguracji w MaterialApp. Upraszcza to kod i centralizuje definicję tras w jednym miejscu.

Nazwane trasy definiuje się przez właściwość routes w MaterialApp, gdzie każdy klucz to ścieżka tekstowa, a wartość to funkcja zwracająca Widget. Dla dynamicznych tras (z parametrami) używa się onGenerateRoute — callbacka, który otrzymuje RouteSettings i zwraca Route. Umożliwia to przekazywanie argumentów przez arguments i realizację głębokiej nawigacji.

Według Flutter Cookbook (2026), przekazywanie argumentów przez pushNamed odbywa się za pomocą parametru arguments: Object?. Ekran odbierający pobiera argumenty przez ModalRoute.of(context)!.settings.arguments, co zapewnia bezpieczne typowo przekazywanie danych bez globalnych zmiennych lub InheritedWidget.

Obsługa nieznanych tras

Właściwość onUnknownRoute w MaterialApp obsługuje przypadki, gdy pushNamed jest wywołany z nieistniejącą trasą. Jest to przydatne do wyświetlania ekranu 404 lub przekierowania na stronę główną. W połączeniu z onGenerateRoute zapewnia pełne pokrycie wszystkich możliwych scenariuszy nawigacyjnych.

Navigator 2.0 i deklaratywna nawigacja Router

Navigator 2.0 (znany również jako Router API) — to deklaratywne podejście do nawigacji, wprowadzone we Flutter 2.0. W przeciwieństwie do imperatywnego Navigator 1.0, gdzie programista wywołuje push/pop, Router zarządza nawigacją przez stan, automatycznie synchronizując URL przeglądarki z bieżącym ekranem. Jest to szczególnie ważne dla aplikacji webowych i wersji desktopowych.

Architektura Navigator 2.0 składa się z trzech kluczowych komponentów: RouteInformationParser parsuje URL do konfiguracji trasy, RouterDelegate przekształca konfigurację na listę Route, a BackButtonDispatcher obsługuje systemowy przycisk „Wstecz”. Taka architektura czyni nawigację w pełni przewidywalną i testowalną.

Dla uproszczenia pracy z Navigator 2.0 istnieją pakiety-opakowania: go_router (zalecany przez Google), auto_route i beamer. go_router udostępnia deklaratywny DSL do definiowania tras z obsługą nawigacji zagnieżdżonej, przekierowań i głębokich linków bez ręcznej implementacji RouterDelegate. Według pub.dev (2026), go_router jest używany w 35% nowych projektów Flutter preferujących podejście deklaratywne.

Przykład nawigacji w aplikacji Flutter

Przyjrzyjmy się przykładowi Navigator z nazwanymi trasami i przekazywaniem danych między ekranami. Kod demonstruje ekran listy produktów, przejście do ekranu szczegółów i powrót z wynikiem.

// Konfiguracja tras w MaterialApp
MaterialApp(
  initialRoute: '/',
  onGenerateRoute: (RouteSettings settings) {
    if (settings.name == '/') {
      return MaterialPageRoute(
        builder: (context) => const ProductListPage(),
      );
    }
    if (settings.name == '/product') {
      final productId = settings.arguments as String;
      return MaterialPageRoute(
        builder: (context) => ProductDetailPage(productId: productId),
      );
    }
    return MaterialPageRoute(
      builder: (context) => const NotFoundPage(),
    );
  },
)

// Nawigacja z przekazywaniem danych
final result = await Navigator.pushNamed(
  context,
  '/product',
  arguments: 'product_42',
);

// Pobieranie danych na ekranie odbierającym
final args = ModalRoute.of(context)!.settings.arguments as String;

// Zastąp ekran po logowaniu
Navigator.pushReplacementNamed(context, '/home');

// Wyczyść stos do ekranu głównego
Navigator.pushNamedAndRemoveUntil(
  context,
  '/home',
  (route) => false,
);

W przykładzie Navigator.pushNamed przekazuje identyfikator produktu do ekranu szczegółów. Przy powrocie przez Navigator.pop(context, updatedProduct) wywołujący ekran otrzymuje zaktualizowane dane w zmiennej result. pushReplacementNamed zastępuje bieżący ekran po autoryzacji, a pushNamedAndRemoveUntil z warunkiem (route) => false całkowicie czyści stos, zapobiegając powrotowi do poprzednich ekranów.