Saltar al contenido principal

Aserciones más estrictas en el Navigator y el ámbito del controlador de Hero

Se añadieron aserciones adicionales para garantizar que un ámbito de controlador de hero solo pueda suscribirse a un navigator a la vez.

Resumen

#

El framework lanza un error de aserción (assertion error) cuando detecta que hay múltiples navigators registrados con un único ámbito de controlador de hero.

Contexto

#

El ámbito de controlador de hero aloja un controlador de hero para su subárbol de widgets. El controlador de hero solo puede admitir un navigator a la vez. Anteriormente, no había ninguna aserción para garantizar eso.

Descripción del cambio

#

Si el código comienza a lanzar errores de aserción después de este cambio, significa que el código ya estaba roto incluso antes de este cambio. Es posible que se registren múltiples navigators bajo el mismo ámbito de controlador de hero, y estos no pueden activar animaciones de hero cuando cambia su ruta. Este cambio solo sacó a la luz este problema.

Guía de migración

#

Una aplicación de ejemplo que comienza a lanzar excepciones.

dart 
import 'package:flutter/material.dart';
​
void main() {
  runApp(
    MaterialApp(
      builder: (BuildContext context, Widget child) {
        // Builds two parallel navigators. This throws
        // error because both of navigators are under the same
        // hero controller scope created by MaterialApp.
        return Stack(
          children: <Widget>[
            Navigator(
              onGenerateRoute: (RouteSettings settings) {
                return MaterialPageRoute<void>(
                  settings: settings,
                  builder: (BuildContext context) {
                    return const Text('first Navigator');
                  }
                );
              },
            ),
            Navigator(
              onGenerateRoute: (RouteSettings settings) {
                return MaterialPageRoute<void>(
                  settings: settings,
                  builder: (BuildContext context) {
                    return const Text('Second Navigator');
                  }
                );
              },
            ),
          ],
        );
      }
    )
  );
}

Puedes corregir esta aplicación introduciendo tus propios ámbitos de controlador de hero.

dart 
import 'package:flutter/material.dart';
​
void main() {
  runApp(
    MaterialApp(
      builder: (BuildContext context, Widget child) {
        // Builds two parallel navigators.
        return Stack(
          children: <Widget>[
            HeroControllerScope(
              controller: MaterialApp.createMaterialHeroController(),
              child: Navigator(
                onGenerateRoute: (RouteSettings settings) {
                  return MaterialPageRoute<void>(
                    settings: settings,
                    builder: (BuildContext context) {
                      return const Text('first Navigator');
                    }
                  );
                },
              ),
            ),
            HeroControllerScope(
              controller: MaterialApp.createMaterialHeroController(),
              child: Navigator(
                onGenerateRoute: (RouteSettings settings) {
                  return MaterialPageRoute<void>(
                    settings: settings,
                    builder: (BuildContext context) {
                      return const Text('second Navigator');
                    }
                  );
                },
              ),
            ),
          ],
        );
      }
    )
  );
}

Timeline

#

Introducido en la versión: 1.20.0
En el lanzamiento estable: 1.20

Referencias

#

Documentación de la API:

Problema relevante:

PR relevante:

A menos que se indique lo contrario, la documentación de este sitio refleja Flutter 3.44.0. Página actualizada por última vez el 2026-05-05. Ver código fuente oreportar un problema.