Navigator: cos'è, gestione degli schermi in Flutter

Cos'è Navigator in Flutter

Navigator è un widget che gestisce una pila di oggetti Route, implementando la navigazione tra schermate in un'applicazione Flutter. Ogni chiamata a push inserisce un nuovo Route in cima alla pila, pop rimuove il Route superiore e torna alla schermata precedente. MaterialApp crea automaticamente un Navigator per l'intera applicazione, rendendolo accessibile tramite Navigator.of(context).

A differenza di StatefulWidget, dove la sostituzione del contenuto avviene tramite setState all'interno di un singolo widget, Navigator opera con schermate complete che hanno un proprio ciclo di vita. Ogni Route nella pila è uno stato isolato con il proprio BuildContext, prevenendo perdite di memoria e semplificando la gestione delle dipendenze. Quando viene chiamato pop, il Route inutilizzato viene distrutto, liberando risorse.

Secondo la Guida alla navigazione Flutter (2026), Navigator si è evoluto da un'API imperativa (Navigator 1.0) a una dichiarativa (Navigator 2.0). Navigator 1.0 utilizza i metodi push/pop direttamente, il che è conveniente per scenari semplici. Navigator 2.0 (Router) è adatto per applicazioni con collegamenti profondi, navigazione adattiva e routing web.

Come funziona Navigator internamente

Internamente, Navigator utilizza Overlay — un widget speciale che visualizza i Routes uno sopra l'altro. Ogni Route crea la propria posizione nell'Overlay con un indice z corrispondente alla sua profondità nella pila. Questo spiega perché quando si chiama push, la nuova schermata si anima sopra quella precedente, e quando si chiama pop, la schermata precedente è già pronta per la visualizzazione: non è stata distrutta ma è rimasta nell'Overlay sotto la nuova schermata.

Per le animazioni di transizione, Navigator utilizza PageTransitionsTheme, che può essere sovrascritto in ThemeData. Le animazioni specifiche della piattaforma vengono impostate tramite CupertinoPageRoute per iOS (scorrimento da destra) e MaterialPageRoute per Android (scorrimento dal basso). Navigator seleziona automaticamente l'animazione corretta quando si utilizza PlatformRoute.

Metodi di Navigator: push, pop e pushReplacement

Navigator fornisce un insieme di metodi per gestire la pila di Routes. Ogni metodo risolve un compito di navigazione specifico — da una semplice transizione alla sostituzione completa della cronologia delle schermate. Esaminiamo i metodi principali con esempi di utilizzo.

Push e Pop: operazioni di base

Il metodo push prende un Route e restituisce un Future con il risultato passato durante pop. Ciò consente di ricevere dati dalla schermata verso cui si è navigato. Ad esempio, una schermata di selezione data può restituire un DateTime tramite Navigator.pop(context, selectedDate). Il metodo pop senza argomenti restituisce null, con un argomento — passa il valore alla schermata chiamante.

PushReplacement: sostituzione della schermata

pushReplacement sostituisce il Route corrente con uno nuovo, rimuovendo il route corrente dalla pila. Questo è fondamentale per scenari in cui l'utente non deve poter tornare alla schermata precedente. Un esempio tipico — la schermata di login: dopo il login riuscito, la schermata corrente viene sostituita dalla schermata principale e il pulsante Indietro non torna al modulo di login.

Route nominate e onGenerateRoute

Navigator supporta la navigazione per route nominate tramite il metodo pushNamed. Invece di creare un Route direttamente, lo sviluppatore specifica un identificatore di stringa e Navigator crea automaticamente il Route in base alla configurazione in MaterialApp. Questo semplifica il codice e centralizza la definizione delle route in un unico punto.

Le route nominate vengono definite tramite la proprietà routes in MaterialApp, dove ogni chiave è una stringa di percorso e il valore è una funzione che restituisce un Widget. Per route dinamiche (con parametri), si utilizza onGenerateRoute — un callback che riceve RouteSettings e restituisce un Route. Ciò consente di passare argomenti tramite il parametro arguments e implementare la navigazione profonda.

Secondo il Flutter Cookbook (2026), il passaggio di argomenti tramite pushNamed viene effettuato con il parametro arguments: Object?. La schermata ricevente estrae gli argomenti tramite ModalRoute.of(context)!.settings.arguments, fornendo un trasferimento dati type-safe senza variabili globali o InheritedWidget.

Gestione delle route sconosciute

La proprietà onUnknownRoute in MaterialApp gestisce i casi in cui pushNamed viene chiamato con una route inesistente. Questo è utile per mostrare una schermata 404 o reindirizzare alla pagina principale. In combinazione con onGenerateRoute, garantisce una copertura completa di tutti i possibili scenari di navigazione.

Navigator 2.0 e navigazione dichiarativa con Router

Navigator 2.0 (noto anche come API Router) è un approccio dichiarativo alla navigazione introdotto in Flutter 2.0. A differenza del Navigator 1.0 imperativo, dove lo sviluppatore chiama push/pop, Router gestisce la navigazione tramite lo stato, sincronizzando automaticamente l'URL del browser con la schermata corrente. Questo è particolarmente importante per applicazioni web e versioni desktop.

L'architettura di Navigator 2.0 è composta da tre componenti chiave: RouteInformationParser analizza l'URL in una configurazione di route, RouterDelegate trasforma la configurazione in un elenco di Routes e BackButtonDispatcher gestisce il pulsante Indietro di sistema. Questa architettura rende la navigazione completamente prevedibile e testabile.

Per semplificare il lavoro con Navigator 2.0, esistono pacchetti wrapper: go_router (raccomandato da Google), auto_route e beamer. go_router fornisce un DSL dichiarativo per definire route con supporto per navigazione annidata, reindirizzamenti e collegamenti profondi senza implementare manualmente RouterDelegate. Secondo pub.dev (2026), go_router è utilizzato nel 35% dei nuovi progetti Flutter che preferiscono un approccio dichiarativo.

Esempio di navigazione in un'applicazione Flutter

Consideriamo un esempio di Navigator con route nominate e passaggio di dati tra schermate. Il codice mostra una schermata di elenco prodotti, la transizione verso una schermata di dettaglio e il ritorno con un risultato.

// Route configuration in 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(),
    );
  },
)

// Navigation with data passing
final result = await Navigator.pushNamed(
  context,
  '/product',
  arguments: 'product_42',
);

// Getting data on the receiving screen
final args = ModalRoute.of(context)!.settings.arguments as String;

// Replace screen after login
Navigator.pushReplacementNamed(context, '/home');

// Clear stack to main screen
Navigator.pushNamedAndRemoveUntil(
  context,
  '/home',
  (route) => false,
);

Nell'esempio, Navigator.pushNamed passa l'ID del prodotto alla schermata di dettaglio. Al ritorno tramite Navigator.pop(context, updatedProduct), la schermata chiamante riceve i dati aggiornati nella variabile result. pushReplacementNamed sostituisce la schermata corrente dopo l'autorizzazione, e pushNamedAndRemoveUntil con la condizione (route) => false pulisce completamente la pila, impedendo la navigazione di ritorno verso schermate precedenti.