MaterialApp: o que é e como configurar o widget raiz

O que é MaterialApp no Flutter?

MaterialApp é um widget wrapper que inicializa o Material Design numa aplicação Flutter. É a raiz da Widget Tree e fornece aos widgets filhos acesso a serviços do sistema: navegação, tema, media queries e localização. Sem MaterialApp, a aplicação não terá o estilo Material padrão e não poderá usar widgets como Scaffold, AppBar, FloatingActionButton e BottomNavigationBar.

O que o MaterialApp adiciona à Widget Tree

Ao usar MaterialApp, o Flutter adiciona automaticamente vários widgets-chave à raiz da árvore: Navigator (pilha de ecrãs para navegação), Theme (esquema de cores e estilos), MediaQuery (informação do dispositivo), Localizations (strings localizadas), Directionality (direção do texto). Estes widgets são implementados como InheritedWidgets e são acessíveis através de BuildContext em qualquer parte da aplicação.

Uso básico

A configuração mínima do MaterialApp requer apenas o parâmetro home — o widget exibido no ecrã principal. O Flutter envolve automaticamente home num Scaffold se este ainda não for um Scaffold, através do mecanismo WidgetsBinding. Quando inicia a aplicação com runApp(MaterialApp(home: MyHomePage())), o Flutter cria uma Widget Tree raiz com MaterialApp como raiz.

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

Neste exemplo, o MaterialApp configura o tema básico (claro e escuro), título e ecrã principal. O parâmetro title é usado para o título da janela (no desktop) e para acessibilidade. Os parâmetros theme e darkTheme definem a aparência da aplicação em diferentes modos.

Estrutura e parâmetros do MaterialApp

MaterialApp aceita mais de 30 parâmetros, que se dividem em categorias: configurações de Material Design, roteamento, tematização, localização, comportamento de erros e configurações específicas de plataforma. Conhecer os parâmetros-chave permite configurar a aplicação de forma flexível sem escrever código adicional.

Parâmetros principais de configuração

O parâmetro title define o nome da aplicação para o título da janela e acessibilidade. color define a cor da aplicação para o alternador de tarefas no Android. debugShowCheckedModeBanner oculta o banner de modo de depuração em builds de lançamento. showPerformanceOverlay ativa uma sobreposição com informações de desempenho. supportDarkTheme indica se a aplicação suporta o tema escuro.

Parâmetros específicos de plataforma

MaterialApp fornece parâmetros para configurar o comportamento em diferentes plataformas: restorationScopeId para preservar o estado da aplicação ao reiniciar no Android, scrollBehavior para configurar o comportamento de scroll em diferentes SO, useMaterial3 para ativar o Material 3 (Material You). O Material 3 adiciona cores dinâmicas, novos componentes e estilos atualizados.

Tematização com theme e darkTheme

A tematização é um dos principais parâmetros do MaterialApp. O parâmetro theme aceita um objeto ThemeData que define a paleta de cores, tipografia, formas de componentes e iconografia para o tema claro. O parâmetro darkTheme é a configuração equivalente para o tema escuro. O Flutter alterna automaticamente o tema com base nas definições do sistema do dispositivo.

ThemeData: esquema de cores

ThemeData inclui primarySwatch (cor primária), colorScheme (esquema de cores estendido do Material 3), brightness (claro ou escuro), fontFamily (fonte padrão), textTheme (estilos de texto), cardTheme, appBarTheme, buttonTheme e dezenas de outros parâmetros para personalizar componentes específicos. Use colorScheme para Material 3 e primarySwatch para Material 2.

Cores dinâmicas do Material 3

O Material 3 (Material You) suporta cores dinâmicas, extraídas do papel de parede do dispositivo no Android 12+. Para ativar, defina useMaterial3: true e use colorScheme.fromSeed ou colorScheme.fromImageProvider. As cores dinâmicas geram automaticamente uma paleta harmoniosa de 5 tons: primary, secondary, tertiary, neutral e neutralVariant.

Acesso ao tema nos widgets

Qualquer widget pode aceder ao tema atual através de Theme.of(context). Theme.of devolve um objeto ThemeData do qual pode obter colors, textTheme e outros parâmetros. Para subscrever alterações de tema (por exemplo, ao alternar entre modo claro e escuro), use o contexto dentro do método build — o Flutter reconstruirá automaticamente o widget quando o tema mudar.

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

Neste exemplo, Theme.of(context) obtém o tema atual do MaterialApp mais próximo. A cor de fundo e o estilo de texto correspondem automaticamente ao tema atual (claro ou escuro). Ao alternar o tema, o Container e o Text serão reconstruídos com novos valores do ThemeData atualizado.

Roteamento e navegação no MaterialApp

MaterialApp integra o Navigator — um navegador baseado em pilha que gerencia as transições entre ecrãs. Os parâmetros initialRoute, routes e onGenerateRoute determinam como o Flutter lida com a navegação. Navigator.push e Navigator.pushReplacement permitem alternar ecrãs programaticamente, enquanto Navigator.pop permite voltar atrás.

Rotas nomeadas (routes)

O parâmetro routes aceita um Map<String, WidgetBuilder>, onde a chave é o nome da rota (string) e o valor é uma função que cria o widget para esse ecrã. As rotas nomeadas são convenientes para navegação estática: '/' (rota raiz) geralmente corresponde a home, '/settings', '/profile' — outros ecrãs. Navigator.pushNamed(context, '/settings') navega para o ecrã de definições.

Geração de rotas (onGenerateRoute)

onGenerateRoute é uma função chamada quando uma rota não é encontrada em routes. Aceita RouteSettings e devolve um MaterialPageRoute. Esta abordagem é útil para navegação dinâmica quando as rotas dependem de dados (por exemplo, /user/42). onGenerateRoute analisa o nome da rota, extrai parâmetros e cria o ecrã apropriado.

Links profundos e roteamento nomeado

Para suportar links profundos (deep links), use os parâmetros onGenerateInitialRoute e onGenerateRoute juntos. Os links profundos permitem abrir um ecrã específico da aplicação através de um URL (por exemplo, https://example.com/promo). O Flutter lida com links profundos no Android (através de intent filters) e no iOS (através de universal links) e passa o caminho para 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;
  },
)

Neste exemplo, onGenerateRoute lida com rotas dinâmicas como /user/42. Se a rota não for encontrada nas rotas estáticas e não corresponder ao padrão dinâmico, o Flutter exibe uma página de erro, que pode ser personalizada através de onUnknownRoute.

Localização e internacionalização

MaterialApp fornece suporte integrado de localização através dos parâmetros localizationsDelegates e supportedLocales. LocalizationsDelegates carregam as strings localizadas, e supportedLocales determina quais idiomas a aplicação suporta. O Flutter deteta automaticamente o idioma do dispositivo e carrega os recursos localizados correspondentes.

Configurar supportedLocales e localizationsDelegates

O parâmetro supportedLocales aceita uma lista de Locales que a aplicação suporta: [const Locale('en'), const Locale('ru'), const Locale('de')]. localizationsDelegates é uma lista de delegados que carregam as strings localizadas. Para Material Design, adicione GlobalMaterialLocalizations.delegate, GlobalWidgetsLocalizations.delegate e GlobalCupertinoLocalizations.delegate.

Localizar as strings da aplicação

Para localizar as suas próprias strings, use a classe AppLocalizations, criada através de flutter_localizations ou do pacote intl. AppLocalizations fornece métodos estáticos para aceder às strings localizadas: AppLocalizations.of(context)!.helloMessage. O MaterialApp passa automaticamente Localizations para a Widget Tree, tornando-as acessíveis através do contexto.

• flutter_localizations — o pacote oficial para localizar widgets Material e strings do sistema.
• intl — o pacote para internacionalização: formatação de números, datas, moedas e pluralização.
• Ficheiros ARB — o formato para armazenar strings localizadas, usado por flutter_localizations e intl.

MaterialApp vs CupertinoApp vs WidgetsApp

O Flutter fornece três widgets raiz para diferentes plataformas: MaterialApp (Material Design para Android e web), CupertinoApp (estilo iOS) e WidgetsApp (widget básico sem estilo). A escolha do widget raiz determina a aparência de toda a aplicação e a disponibilidade de componentes específicos da plataforma.

MaterialApp: a escolha universal

MaterialApp é adequado para a maioria das aplicações graças ao suporte do Material Design, que tem ótimo aspeto no Android, web e desktop. O Material Design oferece uma biblioteca rica de componentes: Scaffold, AppBar, BottomNavigationBar, Drawer, SnackBar, Dialog e muitos outros. O MaterialApp também suporta Material 3 com cores dinâmicas.

CupertinoApp: estilo iOS

CupertinoApp usa o Cupertino Design, que segue as Diretrizes de Interface Humana da Apple. Fornece CupertinoPageScaffold, CupertinoNavigationBar, CupertinoTabBar e outros componentes com estilo iOS. Use CupertinoApp para aplicações iOS ou aplicações que seguem o estilo Apple em todas as plataformas.

WidgetsApp: raiz mínima

WidgetsApp é o widget raiz básico sem estilo. Adiciona Navigator, MediaQuery e Localizations, mas não fornece temas ou componentes Material/Cupertino. WidgetsApp é adequado para sistemas de design personalizados, jogos ou aplicações com estilo próprio onde Material ou Cupertino são excessivos.