Anatomia de um projeto Flutter e primeira app

No fim desta aula consegues

• Explicar para que serve cada pasta de um projeto Flutter e o que nunca se commita.
• Ler e alterar um pubspec.yaml: dependências, versões com ^, assets, e o papel do pubspec.lock.
• Distinguir os modos debug, profile e release e escolher o certo para cada situação.
• Descrever a cadeia main → runApp → MaterialApp → Scaffold → widgets.
• Construir um ecrã com Text, Icon, Image, Container e Padding, e adicionar um package do pub.dev.

O que flutter create gera

Para os testes: o código da app está em lib/; android/ e ios/ são projetos nativos gerados que o Flutter embrulha.

O que se commita e o que não

• O flutter create já gera um .gitignore correto. Não o apagues.
• Nunca no repositório: build/ (binários, centenas de MB), .dart_tool/ (cache do compilador), .idea/ e *.iml (IDE), android/local.properties (caminhos do teu portátil).
• Sempre no repositório: lib/, test/, pubspec.yaml, pubspec.lock, analysis_options.yaml, as pastas nativas, assets/.
• pubspec.lock commita-se em apps (todos compilam com as mesmas versões) e não se commita em packages publicados.
• Segredos (chaves de API, key.properties da assinatura) nunca entram no git. Voltamos a isto numa aula mais à frente.

pubspec.yaml

name: tempo_acores
description: Previsão meteorológica para os Açores.
publish_to: 'none'
version: 1.0.0+1                # versionName + versionCode (class 31)

environment:
  sdk: ^3.11.0

dependencies:                   # ships inside the app
  flutter:
    sdk: flutter
  google_fonts: ^8.2.1
  intl: ^0.20.3

dev_dependencies:               # development and tests only
  flutter_test:
    sdk: flutter
  flutter_lints: ^6.0.0

flutter:
  uses-material-design: true
  assets:
    - assets/img/

pubspec.yaml: o que interessa

• dependencies entram no binário final; dev_dependencies (lints, testes, geradores de código) não.
• ^6.2.1 significa "qualquer 6.x.y a partir de 6.2.1, mas não 7". É o semver: a versão major muda quando a API parte compatibilidade.
• flutter pub get resolve e descarrega; flutter pub add nome acrescenta ao pubspec e faz o get; flutter pub upgrade sobe para as versões mais recentes permitidas; flutter pub outdated mostra o que está atrasado.
• pubspec.lock fixa a versão exata que foi resolvida. Com ele, tu e os colegas compilam exatamente o mesmo código.
• A secção flutter: declara assets e fontes. Uma imagem que não esteja aqui não existe para a app.

Para os testes: ^1.2.3 aceita até <2.0.0; o pubspec.lock fixa versões exatas.

Modos de compilação

Uma app que parece lenta em debug pode ser perfeitamente rápida em release. O contrário nunca acontece.

Para os testes: debug usa JIT e permite hot reload; release usa AOT e é o único modo que se distribui.

A linha de comandos

O VS Code e o Android Studio chamam exatamente estes comandos por baixo dos botões.

DevTools

• Um conjunto de ferramentas no browser, ligado à app em debug ou profile. Com flutter run aparece um link no terminal; no VS Code, comando "Flutter: Open DevTools".
• Widget Inspector: a árvore de widgets ao vivo. "Select widget mode" deixa tocar no ecrã e ver que widget é. O Layout Explorer mostra as constraints (amanhã).
• Performance: gráfico de frames; cada barra acima da linha dos 16 ms é jank. Mostra rebuilds a mais.
• Network: todos os pedidos HTTP com headers, corpo e tempos. Vais usar quando a app falar com a API.
• Memory e Logging: fugas de memória e a saída de debugPrint.

Para os testes: o inspector é para layout, o separador Performance é para jank, e nenhum dos dois funciona em release.

Anatomia de uma app

• main() é a porta de entrada. Chama runApp(widget), que liga o widget à raiz do ecrã e arranca o motor.
• MaterialApp é a raiz de quase todas as apps: define tema, rotas, localização e título. Há um por app.
• Scaffold é a estrutura de um ecrã: appBar em cima, body no meio, floatingActionButton, drawer, bottomNavigationBar. Há um por ecrã.
• Dentro do body, os teus widgets: texto, ícones, imagens, listas, cartões.
• Cada ecrã do Gmail ou do Spotify segue exatamente esta estrutura: barra em cima, conteúdo, navegação em baixo.

Para os testes: um MaterialApp por app, um Scaffold por ecrã, e runApp só se chama uma vez.

O primeiro repositório da UC

git clone https://github.com/Tiago-Rocha/pdm-aula-05.git
cd pdm-aula-05/starter
flutter pub get

Todos os repositórios das aulas têm a mesma forma: starter/ é o projeto por onde começas, com TODOs numerados no código e testes a falhar em test/; solucao/ é o estado final, para comparares no fim, não antes.

1. Clona. Abre a pasta starter/ no VS Code. Ctrl+Shift+P → Flutter: Select Device → o teu Android. Depois F5: corre a configuração "Tempo Açores (debug)" que já vem no projeto. A app tem de aparecer no teu telemóvel com um texto no centro.
2. Abre lib/main.dart no VS Code e procura TODO 1.
3. Corre flutter test uma vez: vê os testes vermelhos. O objetivo da aula é pô-los verdes.

1. Ler o main.dart em conjunto

import 'package:flutter/material.dart';

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

class WeatherApp extends StatelessWidget {
  const WeatherApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Tempo Açores',
      theme: ThemeData(colorSchemeSeed: Colors.teal, useMaterial3: true),
      home: Scaffold(
        appBar: AppBar(title: const Text('Tempo Açores')),
        body: const Center(
          child: Text('TODO 1: substitui por um cartão'),
        ),
      ),
    );
  }
}

1. main.dart: o que interessa

• import 'package:flutter/material.dart' traz o Material Design inteiro. Quase todos os ficheiros de UI começam assim.
• WeatherApp é um StatelessWidget: não tem estado próprio, só descreve. O build devolve a árvore.
• colorSchemeSeed gera uma paleta Material 3 inteira a partir de uma cor. Muda para Colors.deepOrange e faz hot reload.
• const à frente de um widget diz ao Flutter que aquela subárvore nunca muda: pode reutilizá-la em vez de reconstruir. Usa sempre que o compilador deixar.
• Center centra o filho; Text desenha texto. São os dois widgets mais simples que existem.

2. Widgets básicos

Column(
  mainAxisSize: MainAxisSize.min,
  children: [
    Text(
      'Ponta Delgada',
      style: Theme.of(context).textTheme.headlineSmall,   // theme size, not fixed
    ),
    const SizedBox(height: 8),                            // blank space
    const Icon(Icons.wb_sunny, size: 48, color: Colors.orange),
    Image.asset('assets/img/sao_miguel.jpg', height: 120, fit: BoxFit.cover),
    Padding(
      padding: const EdgeInsets.all(12),
      child: Container(
        padding: const EdgeInsets.symmetric(horizontal: 16, vertical: 8),
        decoration: BoxDecoration(
          color: Colors.teal.shade50,
          border: Border.all(color: Colors.teal),
          borderRadius: BorderRadius.circular(12),
        ),
        child: const Text('21 °C'),
      ),
    ),
  ],
)

2. Widgets básicos: o que interessa

• Text com style do textTheme respeita o tema e o tamanho de letra do utilizador. Evita fontSize: 24 fixo.
• Icon usa os ícones Material incluídos (Icons.*). Não precisas de descarregar nada.
• Image.asset lê um ficheiro declarado em pubspec.yaml na secção assets:. Se te esqueceres, erro em runtime, não em compilação.
• Container junta cor, padding, borda, raio e tamanho num só widget. Padding e SizedBox são versões leves para quando só precisas de espaço.
• Column empilha filhos na vertical; amanhã vemos layout a fundo.

3. O cartão da localidade

class LocationCard extends StatelessWidget {
  const LocationCard({super.key, required this.name, required this.temperature});

  final String name;
  final double temperature;

  @override
  Widget build(BuildContext context) {
    final textTheme = Theme.of(context).textTheme;
    return Card(
      child: Padding(
        padding: const EdgeInsets.all(16),
        child: Row(
          children: [
            const Icon(Icons.wb_sunny, size: 40, color: Colors.orange),
            const SizedBox(width: 16),
            Text(name, style: textTheme.titleLarge),
            const Spacer(),
            Text('${temperature.round()} °C', style: textTheme.headlineMedium),
          ],
        ),
      ),
    );
  }
}

3. O cartão: o que interessa

• Um widget próprio é uma classe com campos final, construtor const com parâmetros nomeados e um build. É exatamente o modelo de dados que escreveste no DartPad com um método a mais.
• Usa-se como qualquer outro: const LocationCard(name: 'Horta', temperature: 19.4). O const só é possível porque o construtor é const e os argumentos são literais.
• Card dá elevação e cantos redondos do tema. Row põe os filhos lado a lado; Spacer empurra o resto para a direita.
• Um ficheiro por widget quando passa de 20 linhas. O main.dart importa com import 'location_card.dart';.

4. Hot reload e hot restart na prática

1. Com a app a correr, muda Colors.teal para Colors.indigo e guarda o ficheiro: o VS Code faz hot reload ao guardar. A cor muda, o resto fica igual. Isto é hot reload: código novo, estado antigo.
2. Muda a temperatura de um cartão e faz hot reload. Muda. O build foi chamado outra vez com o código novo.
3. Muda o main() para runApp(const OutraApp()) (cria uma OutraApp que só tem um Text). Hot reload não chega: o main só corre no arranque. Hot restart: o botão ↻ da barra de depuração.
4. Acrescenta uma imagem nova a assets/img/ e ao pubspec.yaml. Nem guardar nem o botão ↻ chegam: pára a app (■) e F5 outra vez.

Para os testes: hot reload mantém o estado e volta a chamar build; hot restart reinicia a app; mudar o pubspec.yaml exige um novo flutter run.

5. Adicionar um package

flutter pub add google_fonts

import 'package:google_fonts/google_fonts.dart';

// inside MaterialApp
theme: ThemeData(
  colorSchemeSeed: Colors.teal,
  useMaterial3: true,
  textTheme: GoogleFonts.interTextTheme(),   // the whole app now uses Inter
),

• pub add escreve no pubspec.yaml, faz o pub get e atualiza o pubspec.lock. Depois de uma dependência nova, pára a app (■) e F5 outra vez.
• Antes de adicionar um package, olha para o pub.dev: pontos, popularidade, data da última versão, se suporta as plataformas que precisas. Aprofundamos numa aula mais à frente.
• Alternativa: intl com DateFormat('EEEE, d MMMM').format(DateTime.now()). Para datas em português precisa de initializeDateFormatting('pt_PT'); vemos numa aula mais à frente.

Até amanhã