MaterialApp — co to jest, konfiguracja i rola widżetu głównego

Czym jest MaterialApp we Flutterze?

MaterialApp — to widżet-opakowanie, który inicjalizuje Material Design w aplikacji Flutter. Jest korzeniem Widget Tree i zapewnia widżetom potomnym dostęp do usług systemowych: nawigacji, motywów, zapytań medialnych i lokalizacji. Bez MaterialApp aplikacja nie będzie mieć standardowego stylu Material i nie będzie mogła używać takich widżetów jak Scaffold, AppBar, FloatingActionButton i BottomNavigationBar.

Co MaterialApp dodaje do Widget Tree

Podczas używania MaterialApp Flutter automatycznie dodaje kilka kluczowych widżetów do korzenia drzewa: Navigator (stos ekranów do nawigacji), Theme (schemat kolorów i style), MediaQuery (informacje o urządzeniu), Localizations (zlokalizowane ciągi znaków), Directionality (kierunek tekstu). Te widżety są zaimplementowane jako InheritedWidget i są dostępne przez BuildContext w dowolnym miejscu aplikacji.

Podstawowe użycie

Minimalna konfiguracja MaterialApp wymaga tylko parametru home — widżetu wyświetlanego na głównym ekranie. Flutter automatycznie owija home w Scaffold, jeśli nie jest on Scaffold, przez mechanizm WidgetsBinding. Przy uruchomieniu aplikacji z runApp(MaterialApp(home: MyHomePage())) Flutter tworzy główne Widget Tree z MaterialApp jako korzeniem.

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

W tym przykładzie MaterialApp konfiguruje podstawowy motyw (jasny i ciemny), tytuł i główny ekran. Parametr title jest używany do tytułu okna (na desktopie) i dla accessibility. Parametry theme i darkTheme określają wygląd aplikacji w różnych trybach.

Struktura i parametry MaterialApp

MaterialApp przyjmuje ponad 30 parametrów, które dzielą się na kategorie: ustawienia Material Design, routing, motywacja, lokalizacja, zachowanie przy błędach i ustawienia dla konkretnych platform. Znajomość kluczowych parametrów pozwala elastycznie skonfigurować aplikację bez pisania dodatkowego kodu.

Główne parametry konfiguracji

Parametr title ustawia nazwę aplikacji dla tytułu okna i accessibility. color określa kolor aplikacji dla przełącznika zadań na Androidzie. debugShowCheckedModeBanner ukrywa baner trybu debugowania w wydaniu produkcyjnym. showPerformanceOverlay włącza nakładkę z informacjami o wydajności. supportDarkTheme wskazuje, czy aplikacja obsługuje ciemny motyw.

Parametry dla konkretnych platform

MaterialApp udostępnia parametry do konfiguracji zachowania na różnych platformach: restorationScopeId do zapisywania stanu aplikacji przy restarcie na Androidzie, scrollBehavior do konfiguracji zachowania przewijania na różnych systemach operacyjnych, useMaterial3 do włączenia Material 3 (Material You). Material 3 dodaje dynamiczne kolory, nowe komponenty i zaktualizowane style.

Motywacja przez theme i darkTheme

Motywacja — jeden z głównych parametrów MaterialApp. Parametr theme przyjmuje obiekt ThemeData, który określa paletę kolorów, typografię, kształty komponentów i ikonografię dla jasnego motywu. Parametr darkTheme — analogiczna konfiguracja dla ciemnego motywu. Flutter automatycznie przełącza motyw w zależności od ustawień systemowych urządzenia.

ThemeData: schemat kolorów

ThemeData zawiera primarySwatch (kolor główny), colorScheme (rozszerzony schemat kolorów Material 3), brightness (jasny lub ciemny), fontFamily (domyślna czcionka), textTheme (style tekstu), cardTheme, appBarTheme, buttonTheme i dziesiątki innych parametrów do konfiguracji konkretnych komponentów. Używaj colorScheme dla Material 3 i primarySwatch dla Material 2.

Dynamiczne kolory Material 3

Material 3 (Material You) obsługuje dynamiczne kolory, które są pobierane z tapety urządzenia na Androidzie 12+. Aby włączyć, ustaw useMaterial3: true i używaj colorScheme.fromSeed lub colorScheme.fromImageProvider. Dynamiczne kolory automatycznie generują harmonijną paletę z 5 tonów: primary, secondary, tertiary, neutral i neutralVariant.

Dostęp do motywu w widżetach

Każdy widżet może uzyskać dostęp do bieżącego motywu przez Theme.of(context). Theme.of zwraca ThemeData, z którego można pobrać colors, textTheme i inne parametry. Aby subskrybować zmiany motywu (np. przy przełączaniu między jasnym a ciemnym), używaj kontekstu wewnątrz metody build — Flutter automatycznie przebuduje widżet przy zmianie motywu.

Container(
  color: Theme.of(context).colorScheme.primary,
  child: Text(
    "Przykładowy tekst z motywem",
    style: Theme.of(context).textTheme.headlineMedium,
  ),
)

W tym przykładzie Theme.of(context) pobiera bieżący motyw z najbliższego MaterialApp. Kolor tła i styl tekstu automatycznie odpowiadają bieżącemu motywowi (jasnemu lub ciemnemu). Przy przełączaniu motywu Container i Text przebudują się z nowymi wartościami z zaktualizowanego ThemeData.

Routing i nawigacja w MaterialApp

MaterialApp integruje Navigator — nawigator stosowy, który zarządza przejściami między ekranami. Parametry initialRoute, routes i onGenerateRoute określają, jak Flutter obsługuje nawigację. Navigator.push i Navigator.pushReplacement pozwalają programowo przełączać ekrany, a Navigator.pop — wracać do poprzedniego.

Nazwane trasy (routes)

Parametr routes przyjmuje Map, gdzie klucz to nazwa trasy (ciąg znaków), a wartość to funkcja tworząca widżet dla ekranu. Nazwane trasy są wygodne dla statycznej nawigacji: '/' (trasa główna) zwykle odpowiada home, '/settings', '/profile' — inne ekrany. Navigator.pushNamed(context, '/settings') przechodzi do ekranu ustawień.

Generowanie tras (onGenerateRoute)

onGenerateRoute — to funkcja wywoływana, gdy trasa nie zostanie znaleziona w routes. Przyjmuje RouteSettings i zwraca MaterialPageRoute. To podejście jest przydatne do dynamicznej nawigacji, gdy trasy zależą od danych (np. /user/42). onGenerateRoute analizuje nazwę trasy, wyodrębnia parametry i tworzy odpowiedni ekran.

Głębokie linki i named routing

Do obsługi głębokich linków (deep links) używaj parametrów onGenerateInitialRoute i onGenerateRoute razem. Głębokie linki pozwalają otwierać określony ekran aplikacji przez URL (np. https://example.com/promo). Flutter obsługuje głębokie linki na Androidzie (przez intent filters) i iOS (przez universal links) i przekazuje ścieżkę do 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;
  },
)

W tym przykładzie onGenerateRoute obsługuje dynamiczne trasy w formacie /user/42. Jeśli trasa nie zostanie znaleziona w statycznej routes i nie pasuje do dynamicznego wzorca, Flutter wyświetla stronę błędu, którą można skonfigurować przez onUnknownRoute.

Lokalizacja i internacjonalizacja

MaterialApp zapewnia wbudowaną obsługę lokalizacji przez parametry localizationsDelegates i supportedLocales. LocalizationsDelegates ładują zlokalizowane ciągi znaków, a supportedLocales określa, które języki obsługuje aplikacja. Flutter automatycznie wykrywa język urządzenia i ładuje odpowiednie zlokalizowane zasoby.

Konfiguracja supportedLocales i localizationsDelegates

Parametr supportedLocales przyjmuje listę Locale obsługiwanych przez aplikację: [const Locale('en'), const Locale('ru'), const Locale('de')]. localizationsDelegates — lista delegatów ładujących zlokalizowane ciągi znaków. Dla Material Design dodaj GlobalMaterialLocalizations.delegate, GlobalWidgetsLocalizations.delegate i GlobalCupertinoLocalizations.delegate.

Lokalizacja ciągów aplikacji

Do lokalizacji własnych ciągów używaj klasy AppLocalizations utworzonej przez flutter_localizations lub pakiet intl. AppLocalizations udostępnia statyczne metody dostępu do zlokalizowanych ciągów: AppLocalizations.of(context)!.helloMessage. MaterialApp automatycznie przekazuje Localizations do Widget Tree, czyniąc je dostępnymi przez kontekst.

• flutter_localizations — oficjalny pakiet do lokalizacji widżetów Material i ciągów systemowych.
• intl — pakiet do internacjonalizacji: formatowanie liczb, dat, walut i pluralizacja.
• ARB pliki — format przechowywania zlokalizowanych ciągów używany przez flutter_localizations i intl.

MaterialApp vs CupertinoApp vs WidgetsApp

Flutter udostępnia trzy główne widżety dla różnych platform: MaterialApp (Material Design dla Androida i sieci), CupertinoApp (styl iOS) i WidgetsApp (podstawowy widżet bez stylizacji). Wybór głównego widżetu określa wygląd całej aplikacji i dostępność komponentów platformy.

MaterialApp: uniwersalny wybór

MaterialApp nadaje się dla większości aplikacji dzięki obsłudze Material Design, który dobrze wygląda na Androidzie, w sieci i na desktopie. Material Design zapewnia bogatą bibliotekę komponentów: Scaffold, AppBar, BottomNavigationBar, Drawer, SnackBar, Dialog i wiele innych. MaterialApp obsługuje również Material 3 z dynamicznymi kolorami.

CupertinoApp: styl iOS

CupertinoApp używa Cupertino Design zgodnego z Human Interface Guidelines od Apple. Udostępnia CupertinoPageScaffold, CupertinoNavigationBar, CupertinoTabBar i inne komponenty w stylu iOS. Używaj CupertinoApp dla aplikacji iOS lub aplikacji stosujących styl Apple na wszystkich platformach.

WidgetsApp: minimalny korzeń

WidgetsApp — to podstawowy widżet główny bez stylizacji. Dodaje Navigator, MediaQuery i Localizations, ale nie udostępnia motywów ani komponentów Material/Cupertino. WidgetsApp nadaje się dla niestandardowych systemów projektowych, gier lub aplikacji z własną stylizacją, gdzie Material lub Cupertino jest zbędny.