MaterialApp: qué es y cómo configurar el widget raíz

¿Qué es MaterialApp en Flutter?

MaterialApp es un widget envoltorio que inicializa Material Design en una aplicación Flutter. Es la raíz del Widget Tree y proporciona a los widgets hijos acceso a servicios del sistema: navegación, tema, consultas de medios y localización. Sin MaterialApp, la aplicación no tendrá el estilo Material estándar y no podrá utilizar widgets como Scaffold, AppBar, FloatingActionButton y BottomNavigationBar.

Qué añade MaterialApp al Widget Tree

Al usar MaterialApp, Flutter agrega automáticamente varios widgets clave a la raíz del árbol: Navigator (pila de pantallas para navegación), Theme (esquema de colores y estilos), MediaQuery (información del dispositivo), Localizations (cadenas localizadas), Directionality (dirección del texto). Estos widgets se implementan como InheritedWidgets y son accesibles a través de BuildContext en cualquier parte de la aplicación.

Uso básico

La configuración mínima de MaterialApp solo requiere el parámetro home — el widget que se muestra en la pantalla principal. Flutter envuelve automáticamente home en un Scaffold si no lo es, mediante el mecanismo WidgetsBinding. Al iniciar la aplicación con runApp(MaterialApp(home: MyHomePage())), Flutter crea un Widget Tree raíz con MaterialApp como raíz.

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: "My Application",
      theme: ThemeData(
        primarySwatch: Colors.blue,
        fontFamily: "Roboto",
      ),
      darkTheme: ThemeData(
        brightness: Brightness.dark,
        primarySwatch: Colors.blue,
      ),
      home: const MyHomePage(),
    );
  }
}

En este ejemplo, MaterialApp configura el tema básico (claro y oscuro), el título y la pantalla principal. El parámetro title se usa para el título de la ventana (en escritorio) y para la accesibilidad. Los parámetros theme y darkTheme definen la apariencia de la aplicación en diferentes modos.

Estructura y parámetros de MaterialApp

MaterialApp acepta más de 30 parámetros, que se dividen en categorías: configuración de Material Design, enrutamiento, tematización, localización, comportamiento de errores y configuración específica de plataforma. Conocer los parámetros clave permite configurar la aplicación de manera flexible sin escribir código adicional.

Parámetros principales de configuración

El parámetro title establece el nombre de la aplicación para el título de la ventana y la accesibilidad. color define el color de la aplicación para el selector de tareas en Android. debugShowCheckedModeBanner oculta el banner de modo depuración en las compilaciones de lanzamiento. showPerformanceOverlay activa una superposición con información de rendimiento. supportDarkTheme indica si la aplicación admite el tema oscuro.

Parámetros específicos de plataforma

MaterialApp proporciona parámetros para configurar el comportamiento en diferentes plataformas: restorationScopeId para preservar el estado de la aplicación al reiniciar en Android, scrollBehavior para configurar el comportamiento del desplazamiento en diferentes SO, useMaterial3 para habilitar Material 3 (Material You). Material 3 añade colores dinámicos, nuevos componentes y estilos actualizados.

Tematización con theme y darkTheme

La tematización es uno de los parámetros principales de MaterialApp. El parámetro theme acepta un objeto ThemeData que define la paleta de colores, la tipografía, las formas de los componentes y la iconografía para el tema claro. El parámetro darkTheme es la configuración equivalente para el tema oscuro. Flutter cambia automáticamente el tema según la configuración del sistema del dispositivo.

ThemeData: esquema de colores

ThemeData incluye primarySwatch (color primario), colorScheme (esquema de colores extendido de Material 3), brightness (claro u oscuro), fontFamily (fuente predeterminada), textTheme (estilos de texto), cardTheme, appBarTheme, buttonTheme y decenas de otros parámetros para personalizar componentes específicos. Usa colorScheme para Material 3 y primarySwatch para Material 2.

Colores dinámicos de Material 3

Material 3 (Material You) soporta colores dinámicos, que se extraen del fondo de pantalla del dispositivo en Android 12+. Para activarlos, establece useMaterial3: true y usa colorScheme.fromSeed o colorScheme.fromImageProvider. Los colores dinámicos generan automáticamente una paleta armoniosa de 5 tonos: primary, secondary, tertiary, neutral y neutralVariant.

Acceso al tema en los widgets

Cualquier widget puede acceder al tema actual a través de Theme.of(context). Theme.of devuelve un objeto ThemeData del que se pueden obtener colores, textTheme y otros parámetros. Para suscribirse a los cambios de tema (por ejemplo, al cambiar entre modo claro y oscuro), usa el contexto dentro del método build — Flutter reconstruirá automáticamente el widget al cambiar el tema.

Container(
  color: Theme.of(context).colorScheme.primary,
  child: Text(
    "Themed text example",
    style: Theme.of(context).textTheme.headlineMedium,
  ),
)

En este ejemplo, Theme.of(context) obtiene el tema actual del MaterialApp más cercano. El color de fondo y el estilo del texto coinciden automáticamente con el tema actual (claro u oscuro). Al cambiar el tema, el Container y el Text se reconstruirán con los nuevos valores del ThemeData actualizado.

Enrutamiento y navegación en MaterialApp

MaterialApp integra Navigator — un navegador basado en pila que gestiona las transiciones entre pantallas. Los parámetros initialRoute, routes y onGenerateRoute determinan cómo Flutter maneja la navegación. Navigator.push y Navigator.pushReplacement permiten cambiar de pantalla programáticamente, mientras que Navigator.pop permite volver atrás.

Rutas con nombre (routes)

El parámetro routes acepta un Map<String, WidgetBuilder>, donde la clave es el nombre de la ruta (cadena) y el valor es una función que crea el widget para esa pantalla. Las rutas con nombre son convenientes para la navegación estática: '/' (ruta raíz) generalmente corresponde a home, '/settings', '/profile' — otras pantallas. Navigator.pushNamed(context, '/settings') navega a la pantalla de configuración.

Generación de rutas (onGenerateRoute)

onGenerateRoute es una función que se llama cuando no se encuentra una ruta en routes. Acepta RouteSettings y devuelve un MaterialPageRoute. Este enfoque es útil para la navegación dinámica cuando las rutas dependen de datos (por ejemplo, /user/42). onGenerateRoute analiza el nombre de la ruta, extrae los parámetros y crea la pantalla correspondiente.

Enlaces profundos y enrutamiento con nombre

Para soportar enlaces profundos (deep links), usa los parámetros onGenerateInitialRoute y onGenerateRoute juntos. Los enlaces profundos permiten abrir una pantalla específica de la aplicación mediante una URL (por ejemplo, https://example.com/promo). Flutter maneja los enlaces profundos en Android (a través de intent filters) y en iOS (a través de universal links) y pasa la ruta a onGenerateRoute.

MaterialApp(
  initialRoute: "/",
  routes: {
    "/": (context) => const HomePage(),
    "/settings": (context) => const SettingsPage(),
  },
  onGenerateRoute: (settings) {
    if (settings.name?.startsWith("/user/") == true) {
      final userId = settings.name!.split("/").last;
      return MaterialPageRoute(
        builder: (_) => UserPage(userId: userId),
      );
    }
    return null;
  },
)

En este ejemplo, onGenerateRoute maneja rutas dinámicas como /user/42. Si la ruta no se encuentra en las rutas estáticas y no coincide con el patrón dinámico, Flutter muestra una página de error, que se puede personalizar mediante onUnknownRoute.

Localización e internacionalización

MaterialApp proporciona soporte integrado de localización mediante los parámetros localizationsDelegates y supportedLocales. LocalizationsDelegates carga las cadenas localizadas, y supportedLocales determina qué idiomas soporta la aplicación. Flutter detecta automáticamente el idioma del dispositivo y carga los recursos localizados correspondientes.

Configuración de supportedLocales y localizationsDelegates

El parámetro supportedLocales acepta una lista de Locales que la aplicación soporta: [const Locale('en'), const Locale('ru'), const Locale('de')]. localizationsDelegates es una lista de delegados que cargan las cadenas localizadas. Para Material Design, añade GlobalMaterialLocalizations.delegate, GlobalWidgetsLocalizations.delegate y GlobalCupertinoLocalizations.delegate.

Localización de las cadenas de la aplicación

Para localizar tus propias cadenas, usa la clase AppLocalizations, creada mediante flutter_localizations o el paquete intl. AppLocalizations proporciona métodos estáticos para acceder a las cadenas localizadas: AppLocalizations.of(context)!.helloMessage. MaterialApp pasa automáticamente Localizations al Widget Tree, haciéndolas accesibles a través del contexto.

• flutter_localizations — el paquete oficial para localizar widgets de Material y cadenas del sistema.
• intl — el paquete para internacionalización: formato de números, fechas, monedas y pluralización.
• Archivos ARB — el formato para almacenar cadenas localizadas, utilizado por flutter_localizations e intl.

MaterialApp vs CupertinoApp vs WidgetsApp

Flutter proporciona tres widgets raíz para diferentes plataformas: MaterialApp (Material Design para Android y web), CupertinoApp (estilo iOS) y WidgetsApp (widget básico sin estilo). La elección del widget raíz determina la apariencia de toda la aplicación y la disponibilidad de componentes específicos de la plataforma.

MaterialApp: la elección universal

MaterialApp es adecuado para la mayoría de las aplicaciones gracias al soporte de Material Design, que se ve genial en Android, web y escritorio. Material Design proporciona una rica biblioteca de componentes: Scaffold, AppBar, BottomNavigationBar, Drawer, SnackBar, Dialog y muchos más. MaterialApp también soporta Material 3 con colores dinámicos.

CupertinoApp: estilo iOS

CupertinoApp utiliza Cupertino Design, que sigue las Guías de Interfaz Humana de Apple. Proporciona CupertinoPageScaffold, CupertinoNavigationBar, CupertinoTabBar y otros componentes con estilo iOS. Usa CupertinoApp para aplicaciones iOS o aplicaciones que siguen el estilo de Apple en todas las plataformas.

WidgetsApp: raíz mínima

WidgetsApp es el widget raíz básico sin estilo. Añade Navigator, MediaQuery y Localizations, pero no proporciona temas ni componentes Material/Cupertino. WidgetsApp es adecuado para sistemas de diseño personalizados, juegos o aplicaciones con estilo propio donde Material o Cupertino son excesivos.