MaterialApp: що це та як налаштувати кореневий віджет

Що таке MaterialApp у Flutter?

MaterialApp — це віджет-обгортка, який ініціалізує Material Design у програмі Flutter. Він є коренем Widget Tree та надає дочірнім віджетам доступ до системних сервісів: навігації, теми, медіа-запитів та локалізації. Без MaterialApp програма не матиме стандартного стилю Material і не зможе використовувати такі віджети, як Scaffold, AppBar, FloatingActionButton та BottomNavigationBar.

Що MaterialApp додає до Widget Tree

При використанні MaterialApp Flutter автоматично додає кілька ключових віджетів у корінь дерева: Navigator (стек екранів для навігації), Theme (колірна схема та стилі), MediaQuery (інформація про пристрій), Localizations (локалізовані рядки), Directionality (напрямок тексту). Ці віджети реалізовані як InheritedWidget і доступні через BuildContext у будь-якому місці програми.

Базове використання

Мінімальна конфігурація MaterialApp потребує лише параметра home — віджета, який відображається на головному екрані. Flutter автоматично обгортає home у Scaffold, якщо він не є Scaffold, через механізм WidgetsBinding. При запуску програми з runApp(MaterialApp(home: MyHomePage())) Flutter створює кореневий Widget Tree з MaterialApp як коренем.

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

У цьому прикладі MaterialApp налаштовує базову тему (світлу та темну), заголовок і головний екран. Параметр title використовується для заголовка вікна (на робочому столі) та для доступності. Параметри theme та darkTheme визначають зовнішній вигляд програми в різних режимах.

Структура та параметри MaterialApp

MaterialApp приймає понад 30 параметрів, які поділяються на категорії: налаштування Material Design, маршрутизація, тематизація, локалізація, поведінка при помилках та налаштування для конкретних платформ. Знання ключових параметрів дозволяє гнучко налаштувати програму без написання додаткового коду.

Основні параметри конфігурації

Параметр title задає назву програми для заголовка вікна та доступності. color визначає колір програми для перемикача завдань на Android. debugShowCheckedModeBanner приховує банер режиму налагодження в релізній збірці. showPerformanceOverlay вмикає накладення з інформацією про продуктивність. supportDarkTheme вказує, чи підтримує програма темну тему.

Параметри для конкретних платформ

MaterialApp надає параметри для налаштування поведінки на різних платформах: restorationScopeId для збереження стану програми при перезапуску на Android, scrollBehavior для налаштування поведінки прокрутки на різних ОС, useMaterial3 для ввімкнення Material 3 (Material You). Material 3 додає динамічні кольори, нові компоненти та оновлені стилі.

Тематизація через theme та darkTheme

Тематизація — один із головних параметрів MaterialApp. Параметр theme приймає об'єкт ThemeData, який визначає кольорову палітру, типографіку, форми компонентів та іконографію для світлої теми. Параметр darkTheme — аналогічна конфігурація для темної теми. Flutter автоматично перемикає тему залежно від системних налаштувань пристрою.

ThemeData: колірна схема

ThemeData включає primarySwatch (основний колір), colorScheme (розширена колірна схема Material 3), brightness (світла або темна), fontFamily (шрифт за замовчуванням), textTheme (стилі тексту), cardTheme, appBarTheme, buttonTheme та десятки інших параметрів для налаштування конкретних компонентів. Використовуйте colorScheme для Material 3 та primarySwatch для Material 2.

Динамічні кольори Material 3

Material 3 (Material You) підтримує динамічні кольори, які витягуються з шпалер пристрою на Android 12+. Для ввімкнення встановіть useMaterial3: true та використовуйте colorScheme.fromSeed або colorScheme.fromImageProvider. Динамічні кольори автоматично генерують гармонійну палітру з 5 тонів: primary, secondary, tertiary, neutral та neutralVariant.

Доступ до теми у віджетах

Будь-який віджет може отримати доступ до поточної теми через Theme.of(context). Theme.of повертає ThemeData, з якого можна отримати colors, textTheme та інші параметри. Для підписки на зміни теми (наприклад, при перемиканні між світлою та темною) використовуйте контекст всередині методу build — Flutter автоматично перебудує віджет при зміні теми.

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

У цьому прикладі Theme.of(context) отримує поточну тему з найближчого MaterialApp. Колір фону та стиль тексту автоматично відповідають поточній темі (світлій або темній). При перемиканні теми Container та Text перебудуються з новими значеннями з оновленого ThemeData.

Маршрутизація та навігація в MaterialApp

MaterialApp інтегрує Navigator — стековий навігатор, який керує переходами між екранами. Параметри initialRoute, routes та onGenerateRoute визначають, як Flutter обробляє навігацію. Navigator.push та Navigator.pushReplacement дозволяють перемикати екрани програмно, а Navigator.pop — повертатися назад.

Іменовані маршрути (routes)

Параметр routes приймає Map<String, WidgetBuilder>, де ключ — ім'я маршруту (рядок), а значення — функція, яка створює віджет для екрана. Іменовані маршрути зручні для статичної навігації: '/' (кореневий маршрут) зазвичай відповідає home, '/settings', '/profile' — інші екрани. Navigator.pushNamed(context, '/settings') переходить на екран налаштувань.

Генерація маршрутів (onGenerateRoute)

onGenerateRoute — це функція, яка викликається, коли маршрут не знайдено в routes. Вона приймає RouteSettings і повертає MaterialPageRoute. Цей підхід корисний для динамічної навігації, коли маршрути залежать від даних (наприклад, /user/42). onGenerateRoute розбирає ім'я маршруту, витягує параметри та створює відповідний екран.

Глибокі посилання та іменована маршрутизація

Для підтримки глибоких посилань (deep links) використовуйте параметри onGenerateInitialRoute та onGenerateRoute разом. Глибокі посилання дозволяють відкривати певний екран програми за URL (наприклад, https://example.com/promo). Flutter обробляє глибокі посилання на Android (через intent filters) та iOS (через universal links) і передає шлях у 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;
  },
)

У цьому прикладі onGenerateRoute обробляє динамічні маршрути виду /user/42. Якщо маршрут не знайдено в статичній routes і не відповідає динамічному шаблону, Flutter відображає сторінку помилки, яку можна налаштувати через onUnknownRoute.

Локалізація та інтернаціоналізація

MaterialApp надає вбудовану підтримку локалізації через параметри localizationsDelegates та supportedLocales. LocalizationsDelegates завантажують локалізовані рядки, а supportedLocales визначає, які мови підтримує програма. Flutter автоматично визначає мову пристрою та завантажує відповідні локалізовані ресурси.

Налаштування supportedLocales та localizationsDelegates

Параметр supportedLocales приймає список Locale, які підтримує програма: [const Locale('en'), const Locale('ru'), const Locale('de')]. localizationsDelegates — список делегатів, які завантажують локалізовані рядки. Для Material Design додайте GlobalMaterialLocalizations.delegate, GlobalWidgetsLocalizations.delegate та GlobalCupertinoLocalizations.delegate.

Локалізація рядків програми

Для локалізації власних рядків використовуйте клас AppLocalizations, створений через flutter_localizations або пакет intl. AppLocalizations надає статичні методи для доступу до локалізованих рядків: AppLocalizations.of(context)!.helloMessage. MaterialApp автоматично передає Localizations у Widget Tree, роблячи їх доступними через контекст.

• flutter_localizations — офіційний пакет для локалізації Material-віджетів та системних рядків.
• intl — пакет для інтернаціоналізації: форматування чисел, дат, валют та плюралізація.
• ARB файли — формат зберігання локалізованих рядків, який використовується flutter_localizations та intl.

MaterialApp vs CupertinoApp vs WidgetsApp

Flutter надає три кореневих віджети для різних платформ: MaterialApp (Material Design для Android та вебу), CupertinoApp (iOS-стиль) та WidgetsApp (базовий віджет без стилізації). Вибір кореневого віджета визначає зовнішній вигляд всієї програми та доступність платформенних компонентів.

MaterialApp: універсальний вибір

MaterialApp підходить для більшості програм завдяки підтримці Material Design, який чудово виглядає на Android, вебі та робочому столі. Material Design надає багату бібліотеку компонентів: Scaffold, AppBar, BottomNavigationBar, Drawer, SnackBar, Dialog та багато інших. MaterialApp також підтримує Material 3 з динамічними кольорами.

CupertinoApp: iOS-стиль

CupertinoApp використовує Cupertino Design, який відповідає рекомендаціям Human Interface Guidelines від Apple. Він надає CupertinoPageScaffold, CupertinoNavigationBar, CupertinoTabBar та інші iOS-стилізовані компоненти. Використовуйте CupertinoApp для iOS-програм або програм, які дотримуються стилю Apple на всіх платформах.

WidgetsApp: мінімальний корінь

WidgetsApp — це базовий кореневий віджет без стилізації. Він додає Navigator, MediaQuery та Localizations, але не надає тем або компонентів Material/Cupertino. WidgetsApp підходить для кастомних дизайн-систем, ігор або програм із власною стилізацією, де Material або Cupertino є надмірними.