Navigator: qué es, gestión de pantallas en Flutter

Qué es Navigator en Flutter

Navigator es un widget que gestiona una pila de objetos Route, implementando la navegación entre pantallas en una aplicación Flutter. Cada llamada a push coloca un nuevo Route en la cima de la pila, pop elimina el Route superior y regresa a la pantalla anterior. MaterialApp crea automáticamente un Navigator para toda la aplicación, haciéndolo accesible mediante Navigator.of(context).

A diferencia de StatefulWidget, donde la sustitución de contenido ocurre mediante setState dentro de un solo widget, Navigator opera con pantallas completas que tienen su propio ciclo de vida. Cada Route en la pila es un estado aislado con su propio BuildContext, lo que evita fugas de memoria y simplifica la gestión de dependencias. Cuando se llama a pop, el Route no utilizado se destruye, liberando recursos.

Según la Guía de navegación de Flutter (2026), Navigator ha evolucionado desde una API imperativa (Navigator 1.0) hasta una declarativa (Navigator 2.0). Navigator 1.0 utiliza métodos push/pop directamente, lo que es conveniente para escenarios simples. Navigator 2.0 (Router) es adecuado para aplicaciones con enlaces profundos, navegación adaptable y enrutamiento web.

Cómo funciona Navigator internamente

Internamente, Navigator utiliza Overlay, un widget especial que muestra los Routes uno sobre otro. Cada Route crea su propia posición en el Overlay con un z-index correspondiente a su profundidad en la pila. Esto explica por qué al llamar a push, la nueva pantalla se anima sobre la anterior, y al llamar a pop, la pantalla anterior ya está lista para mostrarse: no fue destruida sino que permaneció en el Overlay debajo de la nueva.

Para las animaciones de transición, Navigator utiliza PageTransitionsTheme, que se puede sobrescribir en ThemeData. Las animaciones específicas de la plataforma se configuran mediante CupertinoPageRoute para iOS (deslizar desde la derecha) y MaterialPageRoute para Android (deslizar desde abajo). Navigator selecciona automáticamente la animación correcta al usar PlatformRoute.

Métodos de Navigator: push, pop y pushReplacement

Navigator proporciona un conjunto de métodos para gestionar la pila de Routes. Cada método resuelve una tarea de navegación específica, desde una transición simple hasta el reemplazo completo del historial de pantallas. Revisemos los métodos principales con ejemplos de uso.

Push y Pop: operaciones básicas

El método push toma un Route y devuelve un Future con el resultado pasado durante pop. Esto permite recibir datos desde la pantalla a la que se navegó. Por ejemplo, una pantalla de selección de fecha puede devolver un DateTime mediante Navigator.pop(context, selectedDate). El método pop sin argumentos devuelve null, con un argumento — pasa el valor a la pantalla que llama.

PushReplacement: reemplazo de pantalla

pushReplacement reemplaza el Route actual por uno nuevo, eliminando el route actual de la pila. Esto es crítico para escenarios donde el usuario no debe poder volver a la pantalla anterior. Un ejemplo típico es la pantalla de inicio de sesión: después de un inicio exitoso, la pantalla actual se reemplaza por la principal, y el botón Atrás no regresa al formulario de inicio de sesión.

Rutas nombradas y onGenerateRoute

Navigator admite la navegación por rutas nombradas mediante el método pushNamed. En lugar de crear un Route directamente, el desarrollador especifica un identificador de cadena, y Navigator crea el Route automáticamente según la configuración en MaterialApp. Esto simplifica el código y centraliza la definición de rutas en un solo lugar.

Las rutas nombradas se definen mediante la propiedad routes en MaterialApp, donde cada clave es una cadena de ruta y el valor es una función que devuelve un Widget. Para rutas dinámicas (con parámetros), se utiliza onGenerateRoute, un callback que recibe RouteSettings y devuelve un Route. Esto permite pasar argumentos mediante el parámetro arguments e implementar navegación profunda.

Según el Cookbook de Flutter (2026), el paso de argumentos mediante pushNamed se realiza con el parámetro arguments: Object?. La pantalla receptora extrae los argumentos mediante ModalRoute.of(context)!.settings.arguments, proporcionando una transferencia de datos con seguridad de tipos sin variables globales ni InheritedWidget.

Manejo de rutas desconocidas

La propiedad onUnknownRoute en MaterialApp maneja los casos en que se llama a pushNamed con una ruta inexistente. Esto es útil para mostrar una pantalla 404 o redirigir a la página principal. En combinación con onGenerateRoute, garantiza una cobertura completa de todos los escenarios de navegación posibles.

Navigator 2.0 y navegación declarativa con Router

Navigator 2.0 (también conocido como API Router) es un enfoque declarativo de navegación introducido en Flutter 2.0. A diferencia del Navigator 1.0 imperativo, donde el desarrollador llama a push/pop, Router gestiona la navegación mediante el estado, sincronizando automáticamente la URL del navegador con la pantalla actual. Esto es especialmente importante para aplicaciones web y versiones de escritorio.

La arquitectura de Navigator 2.0 consta de tres componentes clave: RouteInformationParser analiza la URL en una configuración de ruta, RouterDelegate transforma la configuración en una lista de Routes, y BackButtonDispatcher maneja el botón Atrás del sistema. Esta arquitectura hace que la navegación sea completamente predecible y comprobable.

Para simplificar el trabajo con Navigator 2.0, existen paquetes envoltorio: go_router (recomendado por Google), auto_route y beamer. go_router proporciona un DSL declarativo para definir rutas con soporte para navegación anidada, redirecciones y enlaces profundos sin implementar manualmente RouterDelegate. Según pub.dev (2026), go_router se utiliza en el 35% de los nuevos proyectos Flutter que prefieren un enfoque declarativo.

Ejemplo de navegación en una aplicación Flutter

Consideremos un ejemplo de Navigator con rutas nombradas y paso de datos entre pantallas. El código demuestra una pantalla de lista de productos, la transición a una pantalla de detalle y el retorno con un resultado.

// 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,
);

En el ejemplo, Navigator.pushNamed pasa el ID del producto a la pantalla de detalle. Al regresar mediante Navigator.pop(context, updatedProduct), la pantalla que llama recibe los datos actualizados en la variable result. pushReplacementNamed reemplaza la pantalla actual después de la autorización, y pushNamedAndRemoveUntil con la condición (route) => false limpia completamente la pila, evitando la navegación de regreso a pantallas anteriores.