MaterialApp: cos'è e come configurare il widget radice

Cos'è MaterialApp in Flutter?

MaterialApp è un widget wrapper che inizializza Material Design in un'applicazione Flutter. È la radice del Widget Tree e fornisce ai widget figli accesso ai servizi di sistema: navigazione, tema, media query e localizzazione. Senza MaterialApp, l'applicazione non avrà lo stile Material standard e non potrà utilizzare widget come Scaffold, AppBar, FloatingActionButton e BottomNavigationBar.

Cosa aggiunge MaterialApp al Widget Tree

Utilizzando MaterialApp, Flutter aggiunge automaticamente diversi widget chiave alla radice dell'albero: Navigator (stack di schermate per la navigazione), Theme (schema di colori e stili), MediaQuery (informazioni sul dispositivo), Localizations (stringhe localizzate), Directionality (direzione del testo). Questi widget sono implementati come InheritedWidget e sono accessibili tramite BuildContext in qualsiasi punto dell'applicazione.

Utilizzo di base

La configurazione minima di MaterialApp richiede solo il parametro home — il widget visualizzato nella schermata principale. Flutter avvolge automaticamente home in un Scaffold se non lo è già, tramite il meccanismo WidgetsBinding. Quando avvii l'applicazione con runApp(MaterialApp(home: MyHomePage())), Flutter crea un Widget Tree radice con MaterialApp come radice.

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(),
    );
  }
}

In questo esempio, MaterialApp configura il tema di base (chiaro e scuro), il titolo e la schermata principale. Il parametro title viene utilizzato per il titolo della finestra (sul desktop) e per l'accessibilità. I parametri theme e darkTheme definiscono l'aspetto dell'applicazione in diverse modalità.

Struttura e parametri di MaterialApp

MaterialApp accetta oltre 30 parametri, suddivisi in categorie: impostazioni di Material Design, routing, tematizzazione, localizzazione, comportamento degli errori e impostazioni specifiche della piattaforma. Conoscere i parametri chiave consente di configurare l'applicazione in modo flessibile senza scrivere codice aggiuntivo.

Parametri di configurazione principali

Il parametro title imposta il nome dell'applicazione per il titolo della finestra e l'accessibilità. color definisce il colore dell'applicazione per il selettore di attività su Android. debugShowCheckedModeBanner nasconde il banner della modalità di debug nelle build di rilascio. showPerformanceOverlay attiva una sovrapposizione con informazioni sulle prestazioni. supportDarkTheme indica se l'applicazione supporta il tema scuro.

Parametri specifici della piattaforma

MaterialApp fornisce parametri per configurare il comportamento su diverse piattaforme: restorationScopeId per preservare lo stato dell'applicazione al riavvio su Android, scrollBehavior per configurare il comportamento di scorrimento su diversi sistemi operativi, useMaterial3 per abilitare Material 3 (Material You). Material 3 aggiunge colori dinamici, nuovi componenti e stili aggiornati.

Tematizzazione con theme e darkTheme

La tematizzazione è uno dei parametri principali di MaterialApp. Il parametro theme accetta un oggetto ThemeData che definisce la tavolozza dei colori, la tipografia, le forme dei componenti e l'iconografia per il tema chiaro. Il parametro darkTheme è la configurazione equivalente per il tema scuro. Flutter cambia automaticamente tema in base alle impostazioni di sistema del dispositivo.

ThemeData: schema di colori

ThemeData include primarySwatch (colore primario), colorScheme (schema di colori esteso di Material 3), brightness (chiaro o scuro), fontFamily (font predefinito), textTheme (stili di testo), cardTheme, appBarTheme, buttonTheme e dozzine di altri parametri per personalizzare componenti specifici. Usa colorScheme per Material 3 e primarySwatch per Material 2.

Colori dinamici di Material 3

Material 3 (Material You) supporta i colori dinamici, estratti dallo sfondo del dispositivo su Android 12+. Per abilitarli, imposta useMaterial3: true e usa colorScheme.fromSeed o colorScheme.fromImageProvider. I colori dinamici generano automaticamente una tavolozza armoniosa di 5 toni: primary, secondary, tertiary, neutral e neutralVariant.

Accesso al tema nei widget

Qualsiasi widget può accedere al tema corrente tramite Theme.of(context). Theme.of restituisce un oggetto ThemeData da cui puoi ottenere colors, textTheme e altri parametri. Per sottoscrivere i cambiamenti di tema (ad esempio, quando si passa tra modalità chiara e scura), usa il contesto all'interno del metodo build — Flutter ricostruirà automaticamente il widget al cambiamento del tema.

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

In questo esempio, Theme.of(context) ottiene il tema corrente dal MaterialApp più vicino. Il colore di sfondo e lo stile del testo corrispondono automaticamente al tema corrente (chiaro o scuro). Quando il tema cambia, Container e Text verranno ricostruiti con nuovi valori dal ThemeData aggiornato.

Routing e navigazione in MaterialApp

MaterialApp integra Navigator — un navigatore basato su stack che gestisce le transizioni tra le schermate. I parametri initialRoute, routes e onGenerateRoute determinano come Flutter gestisce la navigazione. Navigator.push e Navigator.pushReplacement consentono di cambiare schermata a livello di codice, mentre Navigator.pop consente di tornare indietro.

Route nominate (routes)

Il parametro routes accetta un Map<String, WidgetBuilder>, dove la chiave è il nome della route (stringa) e il valore è una funzione che crea il widget per quella schermata. Le route nominate sono comode per la navigazione statica: '/' (route radice) corrisponde di solito a home, '/settings', '/profile' — altre schermate. Navigator.pushNamed(context, '/settings') naviga alla schermata delle impostazioni.

Generazione di route (onGenerateRoute)

onGenerateRoute è una funzione chiamata quando una route non viene trovata in routes. Accetta RouteSettings e restituisce un MaterialPageRoute. Questo approccio è utile per la navigazione dinamica quando le route dipendono dai dati (ad esempio, /user/42). onGenerateRoute analizza il nome della route, estrae i parametri e crea la schermata appropriata.

Deep link e routing nominato

Per supportare i deep link, usa insieme i parametri onGenerateInitialRoute e onGenerateRoute. I deep link consentono di aprire una schermata specifica dell'applicazione tramite URL (ad esempio, https://example.com/promo). Flutter gestisce i deep link su Android (tramite intent filter) e iOS (tramite universal link) e passa il percorso 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;
  },
)

In questo esempio, onGenerateRoute gestisce route dinamiche come /user/42. Se la route non viene trovata nelle route statiche e non corrisponde al pattern dinamico, Flutter mostra una pagina di errore, personalizzabile tramite onUnknownRoute.

Localizzazione e internazionalizzazione

MaterialApp fornisce supporto integrato per la localizzazione tramite i parametri localizationsDelegates e supportedLocales. LocalizationsDelegates carica le stringhe localizzate, e supportedLocales determina quali lingue supporta l'applicazione. Flutter rileva automaticamente la lingua del dispositivo e carica le risorse localizzate corrispondenti.

Configurazione di supportedLocales e localizationsDelegates

Il parametro supportedLocales accetta un elenco di Locale che l'applicazione supporta: [const Locale('en'), const Locale('ru'), const Locale('de')]. localizationsDelegates è un elenco di delegati che caricano le stringhe localizzate. Per Material Design, aggiungi GlobalMaterialLocalizations.delegate, GlobalWidgetsLocalizations.delegate e GlobalCupertinoLocalizations.delegate.

Localizzazione delle stringhe dell'applicazione

Per localizzare le tue stringhe, usa la classe AppLocalizations, creata tramite flutter_localizations o il pacchetto intl. AppLocalizations fornisce metodi statici per accedere alle stringhe localizzate: AppLocalizations.of(context)!.helloMessage. MaterialApp passa automaticamente Localizations al Widget Tree, rendendole accessibili tramite il contesto.

• flutter_localizations — il pacchetto ufficiale per localizzare i widget Material e le stringhe di sistema.
• intl — il pacchetto per l'internazionalizzazione: formattazione di numeri, date, valute e pluralizzazione.
• File ARB — il formato per memorizzare le stringhe localizzate, utilizzato da flutter_localizations e intl.

MaterialApp vs CupertinoApp vs WidgetsApp

Flutter fornisce tre widget radice per diverse piattaforme: MaterialApp (Material Design per Android e web), CupertinoApp (stile iOS) e WidgetsApp (widget di base senza stile). La scelta del widget radice determina l'aspetto dell'intera applicazione e la disponibilità di componenti specifici della piattaforma.

MaterialApp: la scelta universale

MaterialApp è adatto per la maggior parte delle applicazioni grazie al supporto di Material Design, che ha un aspetto eccellente su Android, web e desktop. Material Design fornisce una ricca libreria di componenti: Scaffold, AppBar, BottomNavigationBar, Drawer, SnackBar, Dialog e molti altri. MaterialApp supporta anche Material 3 con colori dinamici.

CupertinoApp: stile iOS

CupertinoApp utilizza Cupertino Design, che segue le Linee Guida per l'Interfaccia Umana di Apple. Fornisce CupertinoPageScaffold, CupertinoNavigationBar, CupertinoTabBar e altri componenti in stile iOS. Usa CupertinoApp per applicazioni iOS o applicazioni che seguono lo stile Apple su tutte le piattaforme.

WidgetsApp: radice minima

WidgetsApp è il widget radice di base senza stile. Aggiunge Navigator, MediaQuery e Localizations ma non fornisce temi o componenti Material/Cupertino. WidgetsApp è adatto per sistemi di design personalizzati, giochi o applicazioni con stile proprio dove Material o Cupertino sono eccessivi.