Skip to content

3. Primeiros passos com Flutter

3.1. Exemplo 01: a estrutura de um aplicativo Flutter

3.1.1. O projeto

Um projeto [Flutter] é criado com o comando [flutter create]:

flutter create --org fr.stahe --platforms=android,web,windows my_application
  • [--org fr.stahe]: o prefixo do ID do aplicativo, invertido como um nome de domínio. O aplicativo [Android] se chamará [fr.stahe.my_application]; dois aplicativos instalados no mesmo celular devem ter IDs diferentes;
  • [--platforms=...]: as plataformas de destino. Para cada uma delas, o [flutter create] cria uma pasta ([android/], [web/], [windows/] e também [ios/], [macos/], [linux/] se solicitadas): um pequeno projeto específico da plataforma que apenas inicia o motor do [Flutter] e carrega o aplicativo nele. Raramente fazemos alterações nele (o nome do aplicativo, o ícone e as permissões);
  • [my_application]: o nome do projeto, que também é o nome do pacote [Dart]: letras minúsculas, números e sublinhados.

O comando gera um aplicativo completo e pronto para executar (um contador). O projeto de exemplo foi criado da mesma forma e, em seguida, sua pasta [lib/] foi preenchida manualmente para reunir vinte e cinco aplicativos em um único projeto: assim, eles compartilham os mesmos pacotes, que são baixados uma única vez.

3.1.2. O arquivo pubspec.yaml

O arquivo [pubspec.yaml] descreve o projeto: seu nome, a versão exigida do [Dart], os pacotes usados e os arquivos incluídos no aplicativo. O dos exemplos:

# ==========================================================================
# pubspec.yaml - a descrição do projeto de exemplos
# --------------------------------------------------------------------------
# Um único projeto Flutter para os 25 exemplos: cada um tem sua pasta em
# lib/ e seu próprio ponto de entrada (main.dart), informado ao comando
# flutter run com a opção -t (target):
#
#     flutter run -t lib/ex05_controlled_fields/main.dart
#
# As bibliotecas (os "pacotes") são baixadas do pub.dev pelo comando
# flutter pub get (executado automaticamente por flutter run).
# ==========================================================================

name: examples_flutter
description: The 25 small examples of the course Step-by-step introduction to the Flutter framework.
# sem publicação no pub.dev: isto é um aplicativo, não uma biblioteca
publish_to: none
version: 1.0.0

environment:
  # a versão exigida da linguagem Dart
  sdk: ^3.12.0

dependencies:
  flutter:
    sdk: flutter
  # endereços "limpos" na web (exemplo 17)
  flutter_web_plugins:
    sdk: flutter
  # os textos do próprio Flutter (botões de diálogo, calendário...)
  # em inglês e em francês (exemplos 05, 21)
  flutter_localizations:
    sdk: flutter
  # datas e números formatados de acordo com o idioma (exemplos 09, 21)
  intl: any
  # o roteador (exemplos 17, 18)
  go_router: ^16.2.0
  # um estado compartilhado por todo o aplicativo (exemplos 20, 24, 25)
  provider: ^6.1.5
  # um pequeno dicionário chave -> valor, mantido no dispositivo (exemplos 20, 21, 23)
  shared_preferences: ^2.5.3
  # requisições HTTP (exemplos 22 a 25)
  http: ^1.5.0
  # exibição de imagens SVG (exemplo 03, captcha dos exemplos 22 a 25)
  flutter_svg: ^2.2.1

dev_dependencies:
  # os testes (e as capturas de tela do curso, veja test/captures)
  flutter_test:
    sdk: flutter
  # as regras de estilo recomendadas pela equipe do Flutter (veja analysis_options.yaml)
  flutter_lints: ^6.0.0

flutter:
  # os ícones do Material Design (Icons.add, Icons.delete...)
  uses-material-design: true
  # os arquivos distribuídos COM o aplicativo: são lidos pelo caminho
  assets:
    - assets/
    - assets/i18n/
  # uma fonte monoespaçada (para exibir JSON), distribuída com o aplicativo
  fonts:
    - family: RobotoMono
      fonts:
        - asset: assets/fonts/RobotoMono-Regular.ttf
        - asset: assets/fonts/RobotoMono-Bold.ttf
          weight: 700
  • Linhas 14–18: o nome do projeto (que também é o nome do pacote — os arquivos do projeto são importados por meio de [package:examples_flutter/...]), sua descrição e sua versão. [publish_to: none]: este projeto não é uma biblioteca; ele nunca será publicado no [pub.dev];
  • linhas 20–22: a versão exigida da linguagem [Dart]. O prefixo [^] aceita qualquer versão mais recente dentro da mesma versão principal (3.12, 3.13… mas não 4.0);
  • linhas 24–45: os pacotes exigidos pelo aplicativo. Alguns vêm do próprio SDK do [Flutter] ([sdk: flutter]): [flutter] (o framework), [flutter_localizations] (os textos do [Flutter] traduzidos para cada idioma), [flutter_web_plugins] (uma configuração específica para web). Os demais são baixados do pub.dev, o repositório de pacotes [Dart]: sua finalidade é explicada nos comentários, e cada um será demonstrado no exemplo que o utiliza. [intl: any]: qualquer versão (o [flutter_localizations] impõe a sua);
  • linhas 47–52: pacotes usados apenas no desenvolvimento e não incluídos no aplicativo distribuído: [flutter_test] (testes) e [flutter_lints] (regras de estilo do analisador);
  • linhas 54–67: a configuração específica do [Flutter]:
    • [uses-material-design: true]: o aplicativo usa a fonte de ícones do [Material Design] ([Icons.add], [Icons.delete]...);
    • [assets]: os arquivos incluídos no aplicativo (imagens, dicionários etc.), que são lidos pelo seu caminho. Ao especificar uma pasta ([assets/]), todos os arquivos que ela contém são entregues diretamente;
    • [fonts]: uma fonte incluída no aplicativo; a [Roboto Mono], uma fonte monoespaçada, é usada para exibir JSON. A fonte padrão do [Material Design], a [Roboto], é a fonte do sistema [Android]: não é necessário incluí-la.

As versões dos pacotes seguem a mesma convenção do [npm]: [^16.2.0] aceita qualquer versão 16.x.y a partir de 16.2.0. O comando [flutter pub get] baixa os pacotes e grava as versões exatas selecionadas no arquivo [pubspec.lock]. Ele é executado automaticamente pelo [flutter run] quando o [pubspec.yaml] foi alterado; o [VS Code] também o executa assim que esse arquivo é salvo. Para adicionar um pacote, em vez de editar o arquivo manualmente, você pode digitar [flutter pub add go_router]: o comando adiciona a linha com a versão mais recente do pacote.

3.1.3. O arquivo analysis_options.yaml

O analisador do [Dart] verifica o código enquanto você digita: o [VS Code] sublinha os erros em vermelho e os avisos em amarelo ou azul. Você também pode executá-lo para o projeto inteiro com [flutter analyze]. Suas regras:

# ==========================================================================
# analysis_options.yaml - as regras do analisador de código Dart
# --------------------------------------------------------------------------
# O analisador verifica o código enquanto ele é digitado (o VS Code sublinha os
# erros) e por meio do comando flutter analyze. Partimos das regras
# recomendadas pela equipe do Flutter (pacote flutter_lints)...
# ==========================================================================

include: package:flutter_lints/flutter.yaml

analyzer:
  language:
    # ... tornadas mais rígidas: nenhuma conversão implícita de um tipo dynamic
    strict-casts: true
    strict-raw-types: true

linter:
  rules:
    # aspas simples em todo lugar, como nos exemplos do curso
    prefer_single_quotes: true
    # "final" para uma variável local que nunca é reatribuída
    prefer_final_locals: true
    # strings muito longas são permitidas (textos dos exemplos)
    lines_longer_than_80_chars: false
  • linha 9: as regras recomendadas pela equipe do [Flutter] (pacote [flutter_lints]): um widget deve ter um construtor [const] sempre que possível, um controller deve ser liberado etc.;
  • Linhas 14–15: tipagem mais estrita. [Dart] é uma linguagem de tipagem estática, mas tem um tipo [dynamic] (“qualquer coisa”): o JSON decodificado, por exemplo, é composto de [dynamic]. O [strict-casts] proíbe a conversão implícita para outro tipo: é preciso escrevê-la explicitamente ([json['lastName'] as String]), e qualquer erro ocorre ali e fica visível;
  • Linhas 20–24: algumas regras de estilo: use aspas simples para strings (aspas duplas se a string contiver um apóstrofo: ["it's"]) e [final] para variáveis que nunca são reatribuídas.

3.1.4. O ponto de entrada: main.dart

Todo programa tem um arquivo chamado [main.dart], que contém a função [main] — o ponto de entrada de qualquer programa [Dart]. O do Exemplo 01:

// =========================================================================
// lib/ex01_first_application/main.dart - um primeiro aplicativo
// -------------------------------------------------------------------------
// Tudo, em um aplicativo Flutter, é um WIDGET: um objeto que descreve
// um pedaço da tela (um texto, um botão, uma margem, uma coluna...).
// Os widgets são aninhados uns nos outros e formam uma ÁRVORE.
// Um widget tem um método build(), que RETORNA os widgets que
// o compõem. O Flutter chama build() para produzir a tela; ele
// O CHAMA DE NOVO a cada vez que o estado do widget muda (setState), e
// atualiza a tela com o novo resultado.
// =========================================================================

import 'package:flutter/material.dart';

// dados "comuns", fora dos widgets: nunca mudam
const title = 'Welcome to Flutter';
const languages = ['Dart', 'Flutter', 'Material Design'];

// "12:05:09": a hora atual, em dois dígitos
String currentTime() {
  final d = DateTime.now();
  String twoDigits(int n) => n.toString().padLeft(2, '0');
  return '${twoDigits(d.hour)}:${twoDigits(d.minute)}:${twoDigits(d.second)}';
}

// o ponto de entrada de todo programa Dart
void main() {
  // runApp: o Flutter assume a tela e exibe nela o widget RAIZ
  runApp(const Application());
}

// o widget raiz: ele configura o aplicativo (título, tema, primeira tela).
// StatelessWidget: um widget SEM estado, inteiramente descrito por seus parâmetros
class Application extends StatelessWidget {
  const Application({super.key});

  @override
  Widget build(BuildContext context) {
    // MaterialApp: um aplicativo com as cores e o comportamento do
    // Material Design, a linguagem visual do Google
    return MaterialApp(
      title: 'Example 01',
      // sem o banner "DEBUG" no canto da tela
      debugShowCheckedModeBanner: false,
      // as cores de todo o aplicativo, derivadas de uma cor base
      theme: ThemeData(colorSchemeSeed: Colors.indigo),
      home: const HomePage(),
    );
  }
}

// um widget COM estado: ele vem em duas partes, o widget propriamente dito (que nunca
// muda) e um objeto State (que guarda os dados que mudam)
class HomePage extends StatefulWidget {
  const HomePage({super.key});

  @override
  State<HomePage> createState() => _HomePageState();
}

// o "_": esta classe é PRIVADA, invisível fora deste arquivo
class _HomePageState extends State<HomePage> {
  // o ESTADO: campos simples do objeto State
  int _counter = 0;
  String _time = currentTime();

  // a função chamada pelo botão
  void _increment() {
    // setState: o estado é modificado DENTRO da função passada a setState;
    // o Flutter então chama build() de novo para atualizar a tela. Nunca
    // modificamos a tela diretamente
    setState(() {
      _counter++;
      _time = currentTime();
    });
  }

  @override
  Widget build(BuildContext context) {
    // Scaffold: a estrutura de uma tela Material (barra superior, corpo...)
    return Scaffold(
      appBar: AppBar(title: const Text('Example 01 - a first application')),
      // Padding: uma margem ao redor do seu filho
      body: Padding(
        padding: const EdgeInsets.all(16),
        // Column: filhos dispostos um abaixo do outro
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.start,
          children: [
            Text(title, style: Theme.of(context).textTheme.headlineSmall),
            const SizedBox(height: 12),
            const Text(
              'This screen is produced by Flutter, from the main function '
              'and the Application and HomePage widgets.',
            ),
            const SizedBox(height: 8),
            // ${expression} insere o valor de uma expressão em uma string
            Text('It is written in ${languages.join(', ')} (${languages.length} languages).'),
            const SizedBox(height: 16),
            // onPressed: a função a chamar quando o botão é pressionado (veja o exemplo 04)
            FilledButton(onPressed: _increment, child: const Text('Click me')),
            const SizedBox(height: 16),
            Text(
              'You clicked $_counter times (last click: $_time).',
              style: const TextStyle(fontWeight: FontWeight.bold, color: Color(0xFF087EA4)),
            ),
          ],
        ),
      ),
    );
  }
}

Vamos começar pelo fim: o programa.

  • Linha 13: a biblioteca [Material] do [Flutter]: todos os widgets do [Material Design], a linguagem visual do [Google] (botões, campos de entrada, barras, janelas etc.). Ela importa o restante do próprio [Flutter];
  • linhas 16–17: dois valores de dados comuns, declarados fora dos widgets: eles nunca mudam. [const]: uma constante conhecida em tempo de compilação;
  • linhas 20–23: uma função comum que retorna a hora atual no formato “12:05:09”. Ela contém uma pequena função própria, [twoDigits], escrita em uma única linha com [=>];
  • linhas 27–29: a função [main], chamada na inicialização. [runApp] inicia o [Flutter]: ele assume o controle da tela e exibe o widget que lhe é fornecido — a raiz do aplicativo.

O widget raiz, [Application]:

  • Linha 34: um widget é uma classe. Esta classe herda de [StatelessWidget], um widget sem estado: o que ele exibe depende exclusivamente de seus parâmetros e nunca muda por conta própria;
  • Linha 29: seu construtor. [{super.key}]: um parâmetro nomeado opcional repassado à classe pai. Todo widget tem um: a “chave” que o identifica (veja o Exemplo 04). O construtor é [const]: [Application()] pode ser uma constante que o [Flutter] nunca precisa reconstruir;
  • Linhas 38–47: o método [build], o núcleo de um widget. Ele retorna os widgets que o compõem. [@override]: ele sobrescreve o método [build] da classe pai. O parâmetro [context] é a posição do widget na árvore de widgets: ele serve para recuperar o que seus ancestrais fornecem (o tema, por exemplo, linha 90);
  • linhas 41–47: [MaterialApp] é o widget que transforma uma árvore de widgets em um aplicativo [Material]: um título ([title], o nome do aplicativo na lista de aplicativos recentes do celular ou na aba do navegador), um tema ([theme]) e uma tela inicial ([home]). [debugShowCheckedModeBanner: false] remove o banner “DEBUG” que um aplicativo em desenvolvimento exibe em um canto. [ThemeData(colorSchemeSeed: Colors.indigo)]: todas as cores do aplicativo (botões, barras, campos etc.) derivam de uma única cor base, de acordo com as regras do [Material Design] 3.

A primeira tela, [HomePage], tem dados que mudam: é um widget com estado.

  • Linhas 54–58: um [StatefulWidget] é composto de duas partes. O widget em si, como qualquer widget, nunca muda (seus campos seriam [final]); sua única tarefa é criar, por meio de [createState], um objeto [State], que por sua vez contém os dados que mudam. O [Flutter] cria esse objeto uma só vez e o mantém enquanto o widget permanecer no mesmo lugar da árvore;
  • linha 62: o objeto [State]. Seu nome começa com um sublinhado: em [Dart], tudo que começa com [_] é privado e invisível fora do arquivo;
  • linhas 64–65: o estado: campos simples do objeto [State];
  • linhas 68–75: o método chamado pelo botão. Ele não afeta a tela: ele altera o estado dentro da função passada a [setState]. [setState] executa essa função e, em seguida, notifica o [Flutter] de que o estado mudou: o [Flutter] chamará [build], comparará a nova árvore de widgets com a antiga e redesenhará o que mudou;
  • linhas 79–105: o [build] da tela:
    • [Scaffold] (“andaime”) é a estrutura de uma tela [Material]: uma barra superior ([appBar]), um corpo ([body]) e, se solicitados, uma barra inferior, um botão flutuante e um menu lateral;
    • [AppBar]: a barra superior; seu título é um widget ([Text]), como quase tudo no [Flutter];
    • [Padding]: uma margem ao redor de seu único filho, [child]. [EdgeInsets.all(16)]: 16 pontos de cada lado (um “ponto” lógico, independente da densidade da tela: aproximadamente 2,6 pixels no celular mostrado nas capturas de tela);
    • [Column]: seus filhos, [children], dispostos um abaixo do outro. [crossAxisAlignment: CrossAxisAlignment.start]: alinhados à esquerda (o eixo “transversal” de uma coluna é o eixo horizontal);
    • [Text]: texto. Seu estilo pode ser derivado do tema: [Theme.of(context).textTheme.headlineSmall] é o estilo para “títulos pequenos”;
    • [SizedBox]: uma caixa vazia com uma altura especificada — um espaço entre dois widgets;
    • linha 98: [${expression}] insere o valor de uma expressão em uma string; [$_counter] basta para uma variável simples (linha 104);
    • linha 101: um botão. [onPressed] recebe a função a ser chamada quando o botão é pressionado. Especificamos a própria função, sem parênteses: [onPressed: _increment()] a chamaria imediatamente, durante a construção da tela;
    • linhas 104–105: texto que depende do estado. Quando o estado muda, [build] é chamado e esse texto muda.

Duas observações sobre [Dart]:

  • quase todos os argumentos de widgets são parâmetros nomeados ([title: ...], [child: ...]): a árvore de widgets se lê como uma descrição, e a ordem dos argumentos não importa. Um parâmetro nomeado é opcional, a menos que seja declarado como [required];
  • a palavra-chave [const] antes de um widget ([const SizedBox(height: 12)]) o cria de uma vez por todas em tempo de compilação. O [Flutter] passa então a saber que ele nunca muda e não perde tempo comparando-o. O analisador sinaliza qualquer [const] omitido; o [VS Code] sabe adicioná-los sozinho.

A árvore de widgets da tela, como exibida pela ferramenta [Flutter DevTools] (inspetor de widgets):

Application
└── MaterialApp
    └── HomePage
        └── Scaffold
            ├── AppBar
            │   └── Text
            └── Padding
                └── Column
                    ├── Text          (the title)
                    ├── SizedBox
                    ├── Text
                    ├── SizedBox
                    ├── Text
                    ├── SizedBox
                    ├── FilledButton
                    │   └── Text
                    ├── SizedBox
                    └── Text          (the counter)

Em um aplicativo [Flutter], você escreve muito pouco código de “implementação” e muito código “descritivo”: a tela é uma árvore de widgets, cada um configurado por seus parâmetros. É o mesmo conceito do JSX do [React], mas sem uma linguagem de template: a árvore é escrita em [Dart].

3.1.5. Execução

No console aberto na pasta [examples_flutter], com o emulador [Android] em execução:

flutter run -d emulator-5554 -t lib/ex01_first_application/main.dart

O console exibe:

Launching lib/ex01_first_application/main.dart on sdk gphone16k x86 64 in debug mode...
Running Gradle task 'assembleDebug'...                             24,1s
√ Built build\app\outputs\flutter-apk\app-debug.apk
Installing build\app\outputs\flutter-apk\app-debug.apk...          1 523ms
Syncing files to device sdk gphone16k x86 64...                       88ms

Flutter run key commands.
r Hot reload.
R Hot restart.
h List all available interactive commands.
d Detach (terminate "flutter run" but leave application running).
c Clear the screen
q Quit (terminate the application on the device).

A Dart VM Service on sdk gphone16k x86 64 is available at: http://127.0.0.1:54321/...
The Flutter DevTools debugger and profiler on sdk gphone16k x86 64 is available at: http://127.0.0.1:9101?uri=...

Na primeira vez, a compilação do aplicativo [Android] (com a ferramenta [Gradle]) leva um ou dois minutos; as compilações seguintes levam apenas alguns segundos. O aplicativo é instalado no emulador e iniciado. À esquerda, a tela de inicialização; à direita, depois de pressionar o botão duas vezes:

Dois experimentos para fazer:

  • Altere o texto do título em [main.dart], salve o arquivo e digite `r` no console (ou simplesmente salve o arquivo no [VS Code]): a tela é atualizada em um segundo, e o contador mantém seu valor. Isso é um “hot reload”: o novo código é injetado no aplicativo em execução; o [Flutter] chama [build], mas os objetos [State] são preservados. R (“hot restart”) reinicia o aplicativo a partir de [main]: o contador volta a 0;
  • Inicie o mesmo aplicativo no navegador: [flutter run -d chrome -t lib/ex01_first_application/main.dart]. É a mesma tela, renderizada pelo mesmo motor; só muda o tamanho da janela. Com [-d windows], é um aplicativo [Windows].

3.2. Exemplo 02: o estado e os valores calculados

O estado é o núcleo do [Flutter], assim como é para o [React]. Este exemplo calcula o preço com impostos (IVA) de um item:

// =========================================================================
// lib/ex02_state/main.dart - o estado e os valores calculados
// -------------------------------------------------------------------------
// Uma pequena calculadora de preços com IVA:
//   - o ESTADO: os campos do objeto State; alterá-los DENTRO de setState()
//     faz build() executar de novo, o que produz a tela com os novos valores;
//   - um valor CALCULADO a partir do estado NÃO é estado: é um
//     "getter" (ou uma variável local de build), recalculado a cada chamada
//     de build(). Está sempre atualizado, sem nada para sincronizar;
//   - um dado que depende dos valores SUCESSIVOS do estado (o histórico
//     dos totais) é atualizado onde o estado muda: em setState;
//   - o título do aplicativo (aba do navegador, lista de aplicativos
//     recentes do celular) também é um widget, Title:
//     ele acompanha o estado como o resto da tela.
// =========================================================================

import 'package:flutter/material.dart';
import 'package:intl/intl.dart';

// um formatador de valores em euros, à moda americana (€1,234.50), veja o exemplo 09
final euros = NumberFormat.currency(locale: 'en_US', symbol: '€');

void main() {
  runApp(
    MaterialApp(
      debugShowCheckedModeBanner: false,
      theme: ThemeData(colorSchemeSeed: Colors.indigo),
      home: const CalculatorPage(),
    ),
  );
}

class CalculatorPage extends StatefulWidget {
  const CalculatorPage({super.key});

  @override
  State<CalculatorPage> createState() => _CalculatorPageState();
}

class _CalculatorPageState extends State<CalculatorPage> {
  // o estado
  String _label = 'Pen';
  double _priceExclVat = 2.5;
  int _quantity = 1;
  double _vatRate = 20; // em %
  // o histórico das últimas 5 alterações do total com IVA
  final List<String> _history = [];

  // um controller dá acesso ao TEXTO de um campo de entrada: precisamos de um
  // aqui para devolvê-lo ao valor inicial (Reset). O exemplo 05
  // os estuda em detalhe
  final _labelField = TextEditingController(text: 'Pen');
  final _priceField = TextEditingController(text: '2.5');

  // valores CALCULADOS: getters, recalculados a cada leitura
  double get _totalExclVat => _quantity * _priceExclVat;
  double get _vatAmount => _totalExclVat * _vatRate / 100;
  double get _totalInclVat => _totalExclVat + _vatAmount;

  // TODAS as alterações do estado passam por este método: ele anota o
  // total com IVA antes da alteração, aplica a alteração e completa
  // o histórico se o total mudou
  void _change(void Function() change) {
    final oldTotal = _totalInclVat;
    setState(() {
      change();
      if (_totalInclVat != oldTotal) {
        _history.insert(0, '${euros.format(oldTotal)} -> ${euros.format(_totalInclVat)}');
        if (_history.length > 5) {
          _history.removeLast();
        }
      }
    });
  }

  // trocar o item redefine a quantidade para 1: fazemos isso onde sabemos
  // POR QUE o estado muda
  void _changeLabel(String newValue) {
    _change(() {
      _label = newValue;
      _quantity = 1;
    });
  }

  void _reset() {
    _change(() {
      _label = 'Pen';
      _priceExclVat = 2.5;
      _quantity = 1;
      _vatRate = 20;
    });
    _labelField.text = 'Pen';
    _priceField.text = '2.5';
  }

  // o objeto State desaparece (saímos da tela): os controllers são liberados
  @override
  void dispose() {
    _labelField.dispose();
    _priceField.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    final totalStyle = Theme.of(context).textTheme.titleMedium!.copyWith(fontWeight: FontWeight.bold);

    // Title: o título do aplicativo ACOMPANHA o estado, como todo o resto
    return Title(
      title: 'Incl. VAT: ${euros.format(_totalInclVat)}',
      color: Colors.indigo,
      child: Scaffold(
        appBar: AppBar(title: const Text('Example 02 - the state')),
        // ListView: uma coluna que rola se ultrapassar a altura da tela
        body: ListView(
          padding: const EdgeInsets.all(16),
          children: [
            Card(
              child: Padding(
                padding: const EdgeInsets.all(16),
                child: Column(
                  children: [
                    // onChanged: chamado a cada tecla digitada, com o novo texto
                    TextField(
                      controller: _labelField,
                      decoration: const InputDecoration(labelText: 'Item'),
                      onChanged: _changeLabel,
                    ),
                    TextField(
                      controller: _priceField,
                      decoration: const InputDecoration(labelText: 'Unit price excl. VAT'),
                      // o teclado numérico do celular, com o ponto decimal
                      keyboardType: const TextInputType.numberWithOptions(decimal: true),
                      // tryParse: null se o texto não for um número; a vírgula também é aceita
                      onChanged: (text) => _change(() => _priceExclVat = double.tryParse(text.replaceAll(',', '.')) ?? 0),
                    ),
                    const SizedBox(height: 12),
                    Row(
                      children: [
                        const Expanded(child: Text('Quantity (back to 1 if the item changes)')),
                        IconButton(
                          icon: const Icon(Icons.remove),
                          // null: o botão fica desabilitado
                          onPressed: _quantity > 0 ? () => _change(() => _quantity--) : null,
                        ),
                        Text('$_quantity', style: totalStyle),
                        IconButton(icon: const Icon(Icons.add), onPressed: () => _change(() => _quantity++)),
                      ],
                    ),
                    const SizedBox(height: 8),
                    // botões dos quais apenas UM é selecionado: a alíquota do IVA
                    SegmentedButton<double>(
                      segments: const [
                        ButtonSegment(value: 5.5, label: Text('5.5%')),
                        ButtonSegment(value: 10, label: Text('10%')),
                        ButtonSegment(value: 20, label: Text('20%')),
                      ],
                      selected: {_vatRate},
                      onSelectionChanged: (choice) => _change(() => _vatRate = choice.first),
                    ),
                    const SizedBox(height: 12),
                    OutlinedButton(onPressed: _reset, child: const Text('Reset')),
                  ],
                ),
              ),
            ),
            Card(
              child: Padding(
                padding: const EdgeInsets.all(16),
                child: Column(
                  crossAxisAlignment: CrossAxisAlignment.start,
                  children: [
                    Text('$_quantity x $_label', style: Theme.of(context).textTheme.titleLarge),
                    const Divider(),
                    _line('Total excl. VAT', euros.format(_totalExclVat)),
                    _line('VAT ($_vatRate%)', euros.format(_vatAmount)),
                    _line('Total incl. VAT', euros.format(_totalInclVat), style: totalStyle),
                  ],
                ),
              ),
            ),
            Card(
              child: Padding(
                padding: const EdgeInsets.all(16),
                child: Column(
                  crossAxisAlignment: CrossAxisAlignment.start,
                  children: [
                    Text('History of the total incl. VAT', style: Theme.of(context).textTheme.titleSmall),
                    // uma linha de texto por elemento do histórico (veja o exemplo 03)
                    for (final line in _history) Text('• $line'),
                  ],
                ),
              ),
            ),
          ],
        ),
      ),
    );
  }

  // uma linha "rótulo ....... valor": um método que produz widgets
  Widget _line(String label, String amount, {TextStyle? style}) {
    return Padding(
      padding: const EdgeInsets.symmetric(vertical: 4),
      child: Row(
        children: [
          Expanded(child: Text(label, style: style)),
          Text(amount, style: style),
        ],
      ),
    );
  }
}
  • Linha 21: um formatador de valores no estilo do inglês dos EUA (€1,234.50), criado de uma vez por todas fora dos widgets, usando o pacote [intl] (veja o Exemplo 09). [final]: uma variável atribuída uma única vez, mas cujo valor só é conhecido em tempo de execução (ao contrário de [const]);
  • linhas 23–28: o programa; desta vez, o [MaterialApp] é escrito diretamente em [main]. É assim que a maioria dos exemplos começará;
  • linhas 42–45: quatro dados de estado, campos simples, com os tipos: [String], [double], [int]. Em [Dart], [int] e [double], há dois tipos distintos de números;
  • linha 47: o histórico das últimas cinco alterações do total, uma lista. O campo é [final]: a lista nunca será substituída; ela será modificada (adições, remoções);
  • Linhas 52–53: dois controllers de campos de entrada. Um campo de entrada do [Flutter] armazena seu texto em um controller, que é criado e atribuído a ele: o texto pode então ser lido ou alterado a partir do código (botão Reiniciar). O Exemplo 05 trata disso em detalhes;
  • linhas 56–58: três valores calculados a partir do estado. Eles NÃO são campos de estado; são getters — métodos sem parênteses que são usados como campos ([_totalInclVat]). Eles são recalculados a cada leitura, de modo que estão sempre atualizados. É a mesma regra que já vimos com o [React]: armazenamos no estado apenas o que não podemos calcular; todo o resto é calculado;
  • Linhas 63–73: o histórico dos totais com IVA depende dos valores sucessivos do total, o que um getter não consegue expressar. Por isso, TODAS as alterações de estado passam pelo método [_change], que recebe como parâmetro a alteração a ser feita (uma função sem parâmetros nem valor de retorno, do tipo [void Function()]): ele registra o total antes da alteração, aplica a alteração em `[setState]`, compara com o total depois da alteração e atualiza o histórico se houve mudança. Este é o lugar natural para esse cálculo: onde o estado muda, e não em `[build]` (que deve apenas descrever a tela);
  • linhas 78–81: alterar o item redefine a quantidade para 1. Isso é feito no método que trata a alteração do campo, onde sabemos por que o estado está mudando;
  • linhas 85–93: várias alterações de estado dentro de um único [setState]: [build] será chamado apenas uma vez. Em seguida, os controllers recebem seu texto inicial: os campos o exibem imediatamente;
  • linhas 98–101: [dispose] é chamado quando o objeto [State] desaparece definitivamente (a tela é encerrada). Aqui, os objetos criados — neste caso, os controllers — são liberados. O Exemplo 13 ilustrará o ciclo de vida de um objeto [State].

O método [build]:

  • linha 106: um estilo de texto, calculado com base no tema — o estilo de título de tamanho médio ([titleMedium]), em negrito. [copyWith] cria uma cópia de um objeto com propriedades modificadas: é uma convenção do [Flutter] que veremos com frequência. [!] informa ao [Dart] que o valor não é [null] (o tipo de [titleMedium] é [TextStyle?], um estilo ou [null]);
  • Linhas 109–111: o widget [Title] fornece o título do aplicativo: na web, é o título da aba do navegador; no [Android], é o nome exibido na lista de aplicativos recentes. Enquanto o [React] usava um efeito ([useEffect]) para modificar [document.title] depois de exibido, o [Flutter] não exige nada de especial: o título é um widget, descrito pelo [build] como o resto da tela, e é atualizado automaticamente junto com o estado;
  • linha 115: [ListView] é uma coluna que rola quando excede a altura da tela. Em um celular, é quase sempre disso que se precisa: um [Column] alto demais seria cortado (e o [Flutter] exibiria uma faixa amarela e preta, indicando um “overflow”);
  • linhas 124–127: um campo de entrada ([TextField]): seu controller, seu rótulo ([decoration: InputDecoration(labelText: ...)]) e [onChanged], a função chamada a cada tecla digitada, junto com o novo texto;
  • linhas 130–135: o preço. [keyboardType] seleciona o teclado do celular: neste caso, o teclado numérico, incluindo a vírgula. O texto digitado é convertido em número por [double.tryParse], que retorna [null] se o texto não for um número ([?? 0]: neste caso, 0). A vírgula francesa é aceita substituindo-a por um ponto;
  • linhas 138–147: a quantidade, com dois botões, “–” e “+”. [Row] coloca seus filhos lado a lado; [Expanded] dá ao seu filho toda a largura restante. [IconButton]: um botão que é apenas um ícone. [onPressed: null] desabilita um botão: o valor não pode ficar abaixo de 0;
  • linhas 152–159: a alíquota do IVA, três botões “segmentados”, dos quais apenas um é selecionado. [selected] recebe um conjunto de valores ([{_vatRate}]: um [Set] com um elemento), [onSelectionChanged] o novo conjunto selecionado;
  • linhas 173–177: os resultados: três linhas geradas pelo método [_line];
  • linha 190: uma linha de texto por elemento do histórico, gerada por um laço [for] escrito dentro da lista de filhos (veja o Exemplo 03);
  • linhas 202–208: um método que cria widgets. [{TextStyle? style}]: um parâmetro nomeado opcional cujo valor padrão é [null] se não for fornecido. Dividir um [build] em métodos o torna mais legível; o Exemplo 10 mostrará que muitas vezes é melhor transformá-los em widgets de verdade.

Modificamos o preço, a quantidade e a alíquota e, depois, o item:

Cada vez que o total com IVA muda, uma linha é adicionada ao histórico. Alterar o item redefine a quantidade para 1 (à direita).

A diferença em relação ao [React] está em um detalhe: o [React] reflete o comportamento do componente, que recria suas variáveis a cada vez; o estado deve, portanto, ser armazenado separadamente, por meio de [useState]. No [Flutter], o estado reside em um objeto ([State]), criado uma vez e mantido: são os seus campos, e o [build] é apenas um de seus métodos. Portanto, não precisamos de hooks nem de suas regras (como não chamá-los dentro de uma condição ou gerenciar suas dependências). A regra de ouro continua a mesma: só modificamos o estado em [setState], e o [build] simplesmente descreve a tela com base no estado.

3.3. Exemplo 03: escrevendo uma árvore de widgets

Não há linguagem de template no [Flutter]: a tela é escrita em [Dart]. Para condições e laços, o [Dart] oferece ferramentas para criar listas de filhos. Este exemplo exibe uma lista de médicos que pode ser filtrada:

// =========================================================================
// lib/ex03_widgets/main.dart - escrevendo uma árvore de widgets
// -------------------------------------------------------------------------
// O Flutter não tem linguagem de template (nem HTML, nem JSX): as
// telas são escritas em Dart, com construtores de widgets aninhados.
// Para condições e laços, o Dart oferece ferramentas feitas para
// construir LISTAS de filhos (children: [...]):
//   - if (condição) widget          : um filho que só EXISTE se a
//                                      condição for verdadeira ("collection if");
//   - if (c) widgetA else widgetB    : um OU o outro;
//   - condição ? widgetA : widgetB  : o mesmo, em uma expressão;
//   - for (final x in lista) widget   : um filho por elemento da lista
//                                      ("collection for");
//   - ...outraLista                   : os elementos de outra lista,
//                                      inseridos neste ponto ("spread");
//   - switch (valor) { padrão => ... } : um valor entre vários.
// E tudo o que vem antes do return de build() é código comum.
// =========================================================================

import 'package:flutter/material.dart';
import 'package:flutter_svg/flutter_svg.dart';

// uma "enumeração": os únicos valores possíveis de uma especialidade
enum Specialty { generalPractitioner, pediatrician, cardiologist }

// uma classe de dados: seus campos são final, um objeto Doctor nunca
// muda. O construtor "const" permite criar constantes dela
class Doctor {
  final int id;
  final String title;
  final String firstName;
  final String lastName;
  final Specialty specialty;
  final bool available;

  const Doctor(this.id, this.title, this.firstName, this.lastName, this.specialty, this.available);
}

const doctors = [
  Doctor(1, 'Mme', 'Marie', 'PELISSIER', Specialty.generalPractitioner, true),
  Doctor(2, 'Mr', 'Paul', 'TATOU', Specialty.pediatrician, false),
  Doctor(3, 'Melle', 'Sophie', 'DUPONT', Specialty.cardiologist, true),
];

// "um valor entre vários, dependendo de um valor": uma EXPRESSÃO switch.
// O compilador verifica se todos os casos da enumeração são tratados
String label(Specialty s) => switch (s) {
  Specialty.generalPractitioner => 'general practitioner',
  Specialty.pediatrician => 'pediatrician',
  Specialty.cardiologist => 'cardiologist',
};

Icon icon(Specialty s) => switch (s) {
  Specialty.pediatrician => const Icon(Icons.child_care, color: Colors.orange),
  Specialty.cardiologist => const Icon(Icons.favorite, color: Colors.red),
  _ => const Icon(Icons.medical_services, color: Colors.teal), // "_": todos os outros casos
};

void main() {
  runApp(
    MaterialApp(
      debugShowCheckedModeBanner: false,
      theme: ThemeData(colorSchemeSeed: Colors.indigo),
      home: const DoctorsPage(),
    ),
  );
}

class DoctorsPage extends StatefulWidget {
  const DoctorsPage({super.key});

  @override
  State<DoctorsPage> createState() => _DoctorsPageState();
}

class _DoctorsPageState extends State<DoctorsPage> {
  String _filter = ''; // o texto procurado
  bool _onlyAvailable = false;
  bool _showHelp = true;

  @override
  Widget build(BuildContext context) {
    // a lista exibida: uma variável comum, recalculada a cada build()
    final text = _filter.trim().toLowerCase();
    final displayed = doctors
        .where(
          (m) =>
              (!_onlyAvailable || m.available) &&
              '${m.firstName} ${m.lastName} ${label(m.specialty)}'.toLowerCase().contains(text),
        )
        .toList();

    // "um dos três blocos": é calculado ANTES do return, com ifs
    final Widget content;
    if (doctors.isEmpty) {
      content = const Text('No doctor.');
    } else if (displayed.isEmpty) {
      content = Text('No doctor matches "$_filter".', style: const TextStyle(color: Colors.deepOrange));
    } else {
      content = Column(
        children: [
          // um filho por médico: "collection for", com sua posição (indexada)
          for (final (i, m) in displayed.indexed)
            // Opacity: os médicos indisponíveis ficam esmaecidos
            Opacity(
              opacity: m.available ? 1 : 0.5,
              // ListTile: uma linha de lista Material (ícone, título, subtítulo, trailing)
              child: ListTile(
                leading: CircleAvatar(child: Text('${i + 1}')),
                title: Text('${m.title} ${m.firstName} ${m.lastName}'),
                // Wrap: como uma Row, mas que quebra para a linha seguinte quando falta espaço
                subtitle: Wrap(
                  spacing: 6,
                  crossAxisAlignment: WrapCrossAlignment.center,
                  children: [icon(m.specialty), Text(label(m.specialty))],
                ),
                trailing: Chip(
                  label: Text(m.available ? 'available' : 'unavailable'),
                  // uma cor escolhida por uma expressão condicional
                  backgroundColor: m.available ? Colors.green.shade100 : Colors.grey.shade300,
                ),
              ),
            ),
        ],
      );
    }

    return Scaffold(
      appBar: AppBar(
        // uma imagem SVG distribuída com o aplicativo (pasta assets/, veja pubspec.yaml)
        leading: Padding(padding: const EdgeInsets.all(12), child: SvgPicture.asset('assets/doctor.svg')),
        title: const Text('Example 03 - the widgets'),
      ),
      body: ListView(
        padding: const EdgeInsets.all(16),
        children: [
          TextField(
            decoration: const InputDecoration(hintText: 'search...', prefixIcon: Icon(Icons.search)),
            onChanged: (value) => setState(() => _filter = value),
          ),
          // SwitchListTile: um interruptor, com seu rótulo
          SwitchListTile(
            title: const Text('available only'),
            value: _onlyAvailable,
            onChanged: (value) => setState(() => _onlyAvailable = value),
          ),
          Align(
            alignment: Alignment.centerLeft,
            child: TextButton(
              onPressed: () => setState(() => _showHelp = !_showHelp),
              child: Text(_showHelp ? 'Hide help' : 'Show help'),
            ),
          ),
          // "collection if": este widget só EXISTE se _showHelp for true
          if (_showHelp)
            Card(
              color: Colors.lightBlue.shade50,
              child: const Padding(
                padding: EdgeInsets.all(12),
                child: Text('Type a name or a specialty. The unavailable doctors are grayed out.'),
              ),
            ),
          content,
          const SizedBox(height: 12),
          // um estilo CALCULADO: o tamanho do texto depende do número de médicos exibidos
          Text(
            '${displayed.length} doctor(s) displayed - the size of this text depends on it.',
            style: TextStyle(fontSize: 12 + displayed.length * 2.0),
          ),
        ],
      ),
    );
  }
}
  • linha 24: uma enumeração: os únicos três valores possíveis para uma especialidade ([Specialty.pediatrician]...);
  • linhas 28–36: uma classe de dados. Seus campos são [final]: um [Doctor] nunca muda. O construtor [Doctor(this.id, this.title, ...)] atribui diretamente seus argumentos aos campos de mesmo nome. Ele é [const]: é possível criar médicos constantes (linha 39);
  • linhas 47–50: “um valor entre vários, dependendo de um valor”: uma [switch] expressão (não uma instrução), que tem um valor. Cada caso é escrito como [pattern => value]. Para uma enumeração, o compilador verifica se todos os casos são tratados: adicionar uma especialidade sem completar este [switch] resultaria em um erro de compilação;
  • linhas 53–56: o mesmo princípio se aplica à seleção de um ícone; o padrão [_] significa “todos os outros casos”. Os ícones do [Material Design] são constantes da classe [Icons];
  • linhas 77–79: o estado da tela.

O método [build]:

  • linhas 84–91: a lista exibida: uma variável recalculada a cada chamada de [build]. [where] mantém os elementos que satisfazem uma condição; [toList()] converte o resultado em uma lista;
  • linhas 94–100: um entre três valores possíveis, selecionado com [if] antes de [return]. Um widget é um valor como qualquer outro: pode ser armazenado em uma variável. [final Widget content;] declara a variável sem inicializá-la: o compilador verifica se cada ramificação atribui um valor a ela exatamente uma vez;
  • linhas 103–117: a lista. Um `[for]` escrito em uma lista literal (`[children: [ ... ]]`) adiciona um elemento a ela a cada iteração do laço: é um “collection for”. [displayed.indexed] retorna tuplas (posição, médico), que [(i, m)] “desempacota” em duas variáveis;
  • linha 106: [Opacity] torna seu filho parcialmente transparente: os médicos indisponíveis aparecem acinzentados. O valor é calculado pelo operador [? :];
  • linhas 108–112: [ListTile] é o item de lista do [Material Design]: um elemento de cabeçalho ([leading], aqui um disco mostrando a posição), um título, um subtítulo e um elemento final ([trailing]). Todos eles são widgets: quaisquer widgets. O subtítulo é um [Wrap]: um [Row] que quebra para a linha seguinte quando não há espaço suficiente (em um celular, o ícone e a especialidade nem sempre caberiam ao lado do rótulo “disponível”);
  • Linhas 117–120: um “marcador” ([Chip]), cujo texto e cor dependem do médico. [Colors.green.shade100]: um tom claro de verde.

[return]:

  • linha 131: uma imagem SVG, incluída no aplicativo (pasta [assets/], declarada em [pubspec.yaml]). O [Flutter] não consegue renderizar SVG por conta própria: o pacote [flutter_svg] fornece o widget [SvgPicture]. Para uma imagem PNG ou JPEG, o [Flutter] tem o widget [Image.asset];
  • Linhas 138–139: o campo de busca. [hintText] é o texto acinzentado exibido enquanto o campo estiver vazio; [prefixIcon] é um ícone à esquerda. Desta vez, sem controller: só precisamos do valor digitado, recebido por [onChanged];
  • linhas 142–145: um interruptor, com seu rótulo: um item de lista em que você toca para alternar;
  • linha 150: uma função anônima, escrita diretamente dentro do parâmetro: ela alterna o estado;
  • linhas 155–160: um “if collection”: o cartão de ajuda existe somente se [_showHelp] for verdadeiro. Não existe widget “oculto”: quando a condição é falsa, a lista de filhos tem um item a menos;
  • linha 163: o conteúdo selecionado anteriormente;
  • linhas 167–168: um estilo calculado: o tamanho do texto depende do número de médicos exibidos.

Para resumir as ferramentas do [Dart] que substituem, dentro de uma lista de filhos, o que outros frameworks escrevem em seus templates:

Em Dart
Função
if (condition) widget
um filho que só existe se a condição for verdadeira
if (c) widgetA else widgetB
um ou outro
condition? widgetA : widgetB
um ou outro, em uma expressão
for (final x in list) widget
um filho por elemento da lista
...otherList
os elementos de outra lista, inseridos neste ponto
...[widgetA, widgetB]
vários filhos de uma vez (geralmente depois de uma instrução `if`)
switch (value) { pattern => widget }
um filho entre vários, com base em um valor

Na inicialização; depois de digitar “gen” e ocultar a ajuda; depois, com “xyz”:

3.4. Exemplo 04: eventos

Um widget interativo recebe funções como parâmetros para serem chamadas quando algo acontece; elas costumam ser chamadas de “callbacks”. Este exemplo gerencia uma lista de tarefas:

// =========================================================================
// lib/ex04_events/main.dart - reagindo às ações do usuário
// -------------------------------------------------------------------------
// Um widget interativo recebe como parâmetros as FUNÇÕES a chamar quando
// algo acontece ("callbacks"):
//   - onPressed: f                  : f é chamada em um toque (botões);
//   - onPressed: () => remove(t)    : uma função anônima, para passar seus
//                                     próprios argumentos;
//   - onChanged, onSubmitted...     : a função recebe um dado (o
//                                     texto, a caixa marcada...);
//   - GestureDetector               : adiciona gestos (toque, toque longo,
//                                     toque duplo, arrastar...) a
//                                     QUALQUER widget;
//   - Dismissible                   : deslizar uma linha para removê-la,
//                                     o gesto típico de um celular.
// Para agir sobre um campo de entrada a partir do código (ler ou limpar seu
// texto, dar-lhe o foco), associamos a ele um CONTROLLER e um FocusNode.
// =========================================================================

import 'package:flutter/material.dart';
import 'package:flutter/services.dart';

class Task {
  final int id;
  final String label;
  bool done;

  Task(this.id, this.label, {this.done = false});
}

void main() {
  runApp(
    MaterialApp(
      debugShowCheckedModeBanner: false,
      theme: ThemeData(colorSchemeSeed: Colors.indigo),
      home: const TasksPage(),
    ),
  );
}

class TasksPage extends StatefulWidget {
  const TasksPage({super.key});

  @override
  State<TasksPage> createState() => _TasksPageState();
}

class _TasksPageState extends State<TasksPage> {
  final List<Task> _tasks = [
    Task(1, 'Install Flutter', done: true),
    Task(2, 'Read the chapter on events'),
  ];
  final List<String> _log = [];
  // o controller do campo: seu texto (leitura, escrita);
  // o FocusNode: seu foco (o cursor e o teclado do celular)
  final _field = TextEditingController();
  final _focus = FocusNode();
  // um campo do objeto State que NÃO é exibido: modificá-lo
  // não exige setState
  int _nextId = 3;

  @override
  void dispose() {
    _field.dispose();
    _focus.dispose();
    super.dispose();
  }

  void _trace(String message) {
    final t = TimeOfDay.now();
    _log.insert(0, '${t.format(context)} $message');
  }

  // chamado pelo botão E pela tecla Enter do teclado (onSubmitted)
  void _add() {
    final label = _field.text.trim();
    if (label.isEmpty) {
      return;
    }
    setState(() {
      _tasks.add(Task(_nextId++, label));
      _trace('added "$label"');
    });
    _field.clear();
    // o foco volta ao campo: a próxima tarefa pode ser digitada
    _focus.requestFocus();
  }

  void _toggle(Task task, bool done) {
    setState(() {
      task.done = done;
      _trace('"${task.label}": ${done ? 'done' : 'to do'}');
    });
  }

  void _remove(Task task, String how) {
    setState(() {
      _tasks.remove(task);
      _trace('removed "${task.label}" ($how)');
    });
  }

  // os detalhes de um toque: sua posição, relativa ao widget tocado
  void _position(TapDownDetails details) {
    final p = details.localPosition;
    setState(() => _trace('tap at (${p.dx.round()}, ${p.dy.round()})'));
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Example 04 - the events')),
      body: ListView(
        padding: const EdgeInsets.all(16),
        children: [
          Row(
            children: [
              Expanded(
                // CallbackShortcuts: atalhos de teclado (um teclado
                // físico: computador, emulador, tablet); Esc limpa o campo
                child: CallbackShortcuts(
                  bindings: {const SingleActivator(LogicalKeyboardKey.escape): _field.clear},
                  child: TextField(
                    controller: _field,
                    focusNode: _focus,
                    decoration: const InputDecoration(hintText: 'new task (Esc to clear)'),
                    // a tecla "Enter" do teclado do celular
                    textInputAction: TextInputAction.done,
                    onSubmitted: (_) => _add(),
                  ),
                ),
              ),
              const SizedBox(width: 8),
              FilledButton(onPressed: _add, child: const Text('Add')),
            ],
          ),
          const SizedBox(height: 12),
          for (final t in _tasks)
            // Dismissible: deslizar a linha para a esquerda a remove.
            // key: a IDENTIDADE da linha, para que o Flutter saiba qual
            // desapareceu (veja a explicação no curso)
            Dismissible(
              key: ValueKey(t.id),
              direction: DismissDirection.endToStart,
              background: Container(
                color: Colors.red.shade100,
                alignment: Alignment.centerRight,
                padding: const EdgeInsets.only(right: 16),
                child: const Icon(Icons.delete),
              ),
              onDismissed: (_) => _remove(t, 'swipe'),
              child: CheckboxListTile(
                // a caixa fica À ESQUERDA, como em uma lista de tarefas
                controlAffinity: ListTileControlAffinity.leading,
                value: t.done,
                // a caixa passa seu novo valor (bool?, daí o "!")
                onChanged: (checked) => _toggle(t, checked!),
                title: Text(
                  t.label,
                  style: t.done ? const TextStyle(decoration: TextDecoration.lineThrough, color: Colors.grey) : null,
                ),
                // uma função anônima: a tarefa DESTA linha como argumento
                secondary: IconButton(
                  icon: const Icon(Icons.delete_outline, color: Colors.red),
                  onPressed: () => _remove(t, 'button'),
                ),
              ),
            ),
          const SizedBox(height: 12),
          // GestureDetector: qualquer widget passa a ser sensível a gestos
          GestureDetector(
            onTapDown: _position,
            onDoubleTap: () => setState(() => _trace('double tap')),
            onLongPress: () => setState(() => _trace('long press')),
            child: Container(
              height: 80,
              alignment: Alignment.center,
              decoration: BoxDecoration(color: const Color(0xFFE7F5FF), borderRadius: BorderRadius.circular(8)),
              child: const Text('Touch this area (tap, double tap, long press)'),
            ),
          ),
          const SizedBox(height: 16),
          Text('Log', style: Theme.of(context).textTheme.titleSmall),
          for (final line in _log) Text(line, style: const TextStyle(fontSize: 12)),
        ],
      ),
    );
  }
}
  • linhas 23–28: uma tarefa. [done] não é [final]: vamos modificá-lo. [{this.done = false}]: um parâmetro nomeado opcional, com seu valor padrão;
  • linhas 49–53: o estado: a lista de tarefas e um registro de eventos;
  • linhas 56–57: para manipular o campo de entrada a partir do código, dois objetos são associados a ele: um controller ([TextEditingController]), que dá acesso ao seu texto, e um [FocusNode], que dá acesso ao seu foco (o cursor piscante e o teclado do celular, que abre quando um campo tem o foco);
  • Linha 60: um campo do objeto [State] que não é exibido: modificá-lo não exige um [setState]. É o que o [React] chama de “referência” ([useRef]); no [Flutter], é um campo comum;
  • linhas 63–66: o controller e o [FocusNode] são liberados quando a tela desaparece;
  • linhas 69–71: uma linha adicional no topo do registro. [TimeOfDay] é a hora do dia do [Flutter]; [format(context)] a formata de acordo com as convenções do idioma do aplicativo;
  • linhas 75–86: adição de uma tarefa, disparada pelo botão E pela tecla Enter do teclado. Lemos o texto no controller ([_field.text]), adicionamos a tarefa (em [setState]), limpamos o campo ([_field.clear()]) e devolvemos o foco a ele ([_focus.requestFocus()]): agora é possível digitar a próxima tarefa;
  • Linhas 89–92: marcar ou desmarcar uma tarefa: modificamos o próprio objeto [Task], em [setState]. Ao contrário do [React], não há necessidade de criar uma nova lista: o [setState] notifica o [Flutter] de que o estado mudou, independentemente de como ele mudou;
  • linhas 96–99: exclusão, seja pelo botão ou por deslizamento (veja abaixo);
  • Linhas 104–106: a função chamada quando a área inferior é tocada. Ela recebe os detalhes do evento: neste caso, [localPosition], a posição do dedo em relação ao widget tocado.

O método [build]:

  • Linhas 121–122: [CallbackShortcuts] associa atalhos de teclado a funções para um teclado físico (computador, emulador, tablet com teclado): a tecla Esc limpa o campo. [{ key: function }] é um [Map] literal;
  • Linhas 124–129: o campo de entrada, vinculado ao seu controller e ao seu [FocusNode]. [textInputAction] seleciona a tecla “Enter” do teclado do celular; [onSubmitted] é chamado quando ela é pressionada, junto com o texto (que não é usado: o parâmetro se chama [_], por convenção);
  • linha 134: o botão chama o mesmo método;
  • linhas 138–151: uma linha por tarefa, em um [Dismissible]: um widget que você desliza com o dedo para removê-lo, o gesto típico de uma lista em um celular. [direction]: somente para a esquerda; [background]: o que aparece abaixo da linha durante o deslizamento (um ícone de lixeira sobre fundo vermelho); [onDismissed]: a função chamada quando a linha é deslizada para fora da tela;
  • linha 143: a chave do [Dismissible]. Quando uma lista de widgets muda, o [Flutter] compara a lista antiga com a nova para determinar quais widgets manter: sem uma chave, ele os associa pela posição (o primeiro ao primeiro, o segundo ao segundo e assim por diante). Se a primeira tarefa desaparecer, a segunda tomaria seu lugar… com o estado da primeira. Uma chave dá a cada widget uma identidade: o [Flutter] passa então a associar os widgets por suas chaves. A chave deve ser única entre os irmãos e estável: o identificador da tarefa, e não sua posição. Um [Dismissible] exige uma chave;
  • linhas 152–157: um item de lista com uma caixa de seleção. [controlAffinity] coloca a caixa de seleção à esquerda. [onChanged] recebe o novo valor da caixa de seleção, do tipo [bool?] (uma caixa de seleção pode ter um terceiro estado, “indeterminado”): [!] indica que ele não é [null];
  • linha 160: o estilo do rótulo depende da tarefa: tachado e cinza se estiver concluída, o estilo padrão ([null]) caso contrário;
  • linhas 163–165: um botão de “lixeira”. A função anônima [() => _remove(t, 'button')] permite que argumentos sejam passados: a tarefa desta linha;
  • Linhas 171–174: [GestureDetector] torna qualquer widget sensível a gestos: toque ([onTap], [onTapDown]...), toque duplo, toque longo, deslizamento, pinça... Aqui, uma simples caixa colorida ([Container]) responde a três gestos;
  • linhas 175–178: [Container] é uma caixa, na qual se especificam margem, fundo, borda, tamanho e alinhamento. [decoration] descreve seu fundo: uma cor, cantos arredondados. [Color(0xFFE7F5FF)]: uma cor especificada por seu código ARGB (opacidade FF, depois vermelho, verde, azul);
  • linha 184: o registro.

Adicione uma tarefa, marque a segunda, toque na área inferior; depois, arraste a primeira tarefa para a esquerda (no meio, durante o arrasto; à direita, depois que a linha é removida):

No [React], os eventos do navegador ([click], [keydown]...) são os mesmos para todos os elementos; no [Flutter], cada widget interativo declara os seus, com parâmetros tipados ([onPressed], [onChanged], [onSubmitted]...), e o [GestureDetector] adiciona gestos aos que não têm nenhum. O editor, que conhece os parâmetros de cada widget, os sugere enquanto você digita.

3.5. Exemplo 05: todos os tipos de campo

Este exemplo usa o formulário do Exemplo 05 do curso de [React], com os campos de entrada do [Flutter]: caixas de texto, botões de opção, caixas de seleção, listas suspensas, listas com marcadores, controles deslizantes e calendários.

// =========================================================================
// lib/ex05_controlled_fields/main.dart - todos os tipos de campos
// -------------------------------------------------------------------------
// Um campo CONTROLADO exibe um valor do estado e notifica o widget de
// cada alteração (onChanged), que atualiza o estado: o estado é a
// única fonte da verdade. Modificar o estado (a partir do código) modifica o campo.
// O que onChanged passa depende do campo:
//   - TextField (com um controller)    -> o texto (String);
//   - Checkbox, Switch                 -> bool? / bool;
//   - Radio (em um RadioGroup)          -> o valor do botão escolhido;
//   - DropdownButton                   -> o valor do item escolhido;
//   - FilterChip                       -> bool: o chip está selecionado?
//   - Slider                           -> double;
//   - showDatePicker (um diálogo)      -> um Future<DateTime?>.
// O TextField é um caso especial: ele guarda seu texto em um
// TextEditingController, que criamos, lemos (controller.text),
// modificamos... e liberamos (dispose).
// Mesma forma do exemplo 05 do curso de React; tudo acontece no
// celular, sem servidor.
// =========================================================================

import 'dart:convert';

import 'package:flutter/material.dart';
import 'package:flutter_localizations/flutter_localizations.dart';

const titles = ['Mr', 'Mme', 'Melle'];
const hobbies = ['sport', 'music', 'reading', 'cinema'];
const countries = {'fr': 'France', 'be': 'Belgium', 'ch': 'Switzerland'};
const languages = {'fr': 'French', 'en': 'English', 'es': 'Spanish'};

void main() {
  runApp(
    MaterialApp(
      debugShowCheckedModeBanner: false,
      theme: ThemeData(colorSchemeSeed: Colors.indigo),
      // os textos do próprio Flutter (calendário, botões OK / CANCEL) em
      // inglês (veja o exemplo 21)
      locale: const Locale('en'),
      supportedLocales: const [Locale('en'), Locale('fr')],
      localizationsDelegates: GlobalMaterialLocalizations.delegates,
      home: const FormPage(),
    ),
  );
}

class FormPage extends StatefulWidget {
  const FormPage({super.key});

  @override
  State<FormPage> createState() => _FormPageState();
}

class _FormPageState extends State<FormPage> {
  // um estado por campo do formulário
  String _title = 'Mme';
  final _name = TextEditingController();
  final _age = TextEditingController(text: '30');
  String _presentation = '';
  bool _newsletter = false;
  final Set<String> _hobbies = {'reading'}; // um SET: sem duplicatas
  String _country = 'fr';
  final Set<String> _languages = {};
  DateTime? _birthDate; // null: ainda não escolhido
  double _satisfaction = 3;
  String? _sent;

  @override
  void initState() {
    super.initState();
    // um controller NOTIFICA seus ouvintes a cada alteração do texto:
    // a tela é redesenhada (o modelo exibido ao vivo)
    _name.addListener(_redraw);
    _age.addListener(_redraw);
  }

  void _redraw() => setState(() {});

  @override
  void dispose() {
    _name.dispose();
    _age.dispose();
    super.dispose();
  }

  // "2026-10-05": o formato de data da API do RdvMedecins
  String? get _birthDateText => _birthDate?.toIso8601String().substring(0, 10);

  // todos os valores, reunidos em um objeto (o que seria enviado a um servidor)
  Map<String, Object?> get _model => {
    'title': _title,
    'name': _name.text.trim(),
    'age': int.tryParse(_age.text), // null se o campo estiver vazio
    'presentation': _presentation,
    'newsletter': _newsletter,
    'hobbies': _hobbies.toList(),
    'country': _country,
    'languages': _languages.toList(),
    'birthDate': _birthDateText,
    'satisfaction': _satisfaction.round(),
  };

  // a data de nascimento: um diálogo de calendário. showDatePicker retorna
  // um Future, a data escolhida (ou null: diálogo fechado sem escolha)
  Future<void> _chooseBirthDate() async {
    final choice = await showDatePicker(
      context: context,
      initialDate: _birthDate ?? DateTime(2000, 1, 1),
      firstDate: DateTime(1900),
      lastDate: DateTime.now(),
    );
    if (choice != null) {
      setState(() => _birthDate = choice);
    }
  }

  // o estado modificado PELO CÓDIGO: os campos acompanham
  void _example() {
    setState(() {
      _title = 'Mr';
      _name.text = 'MARTIN';
      _age.text = '42';
      _hobbies
        ..clear()
        ..addAll(['sport', 'cinema']);
      _country = 'be';
    });
  }

  void _send() {
    // JsonEncoder.withIndent: JSON indentado; jsonEncode: em uma linha
    setState(() => _sent = jsonEncode(_model));
  }

  @override
  Widget build(BuildContext context) {
    final titleStyle = Theme.of(context).textTheme.titleSmall;
    return Scaffold(
      appBar: AppBar(title: const Text('Example 05 - the controlled fields')),
      body: ListView(
        padding: const EdgeInsets.all(16),
        children: [
          Text('Title', style: titleStyle),
          // RadioGroup: o valor escolhido (groupValue) e a função chamada
          // quando um dos botões Radio que ele contém é escolhido
          RadioGroup<String>(
            groupValue: _title,
            onChanged: (value) => setState(() => _title = value!),
            child: Row(
              children: [
                for (final t in titles) ...[Radio<String>(value: t), Text(t), const SizedBox(width: 12)],
              ],
            ),
          ),
          Row(
            children: [
              Expanded(
                flex: 2,
                child: TextField(
                  controller: _name,
                  decoration: const InputDecoration(labelText: 'Name'),
                ),
              ),
              const SizedBox(width: 12),
              Expanded(
                child: TextField(
                  controller: _age,
                  decoration: const InputDecoration(labelText: 'Age'),
                  keyboardType: TextInputType.number,
                ),
              ),
            ],
          ),
          const SizedBox(height: 8),
          // Focus: notifica quando seu filho GANHA ou PERDE o foco. O campo
          // não está ligado ao estado a cada tecla: seu texto só é lido ao
          // sair do campo (como onBlur em HTML)
          Focus(
            onFocusChange: (hasFocus) {
              if (!hasFocus) setState(() {});
            },
            child: TextFormField(
              initialValue: _presentation,
              maxLines: 2,
              decoration: const InputDecoration(labelText: 'Presentation (updated when leaving the field)'),
              onChanged: (text) => _presentation = text, // SEM setState: nada é redesenhado
            ),
          ),
          // uma única caixa: true / false
          CheckboxListTile(
            contentPadding: EdgeInsets.zero,
            controlAffinity: ListTileControlAffinity.leading,
            title: const Text('Receive the newsletter'),
            value: _newsletter,
            onChanged: (checked) => setState(() => _newsletter = checked!),
          ),
          Text('Hobbies', style: titleStyle),
          // vários chips para UM conjunto: o valor é adicionado ou removido
          Wrap(
            spacing: 8,
            children: [
              for (final l in hobbies)
                FilterChip(
                  label: Text(l),
                  selected: _hobbies.contains(l),
                  onSelected: (selected) => setState(() => selected ? _hobbies.add(l) : _hobbies.remove(l)),
                ),
            ],
          ),
          const SizedBox(height: 8),
          Row(
            children: [
              Text('Country', style: titleStyle),
              const SizedBox(width: 16),
              // uma lista suspensa: value indica qual item está escolhido
              DropdownButton<String>(
                value: _country,
                items: [
                  for (final MapEntry(key: code, value: name) in countries.entries)
                    DropdownMenuItem(value: code, child: Text(name)),
                ],
                onChanged: (code) => setState(() => _country = code!),
              ),
            ],
          ),
          Text('Spoken languages', style: titleStyle),
          Wrap(
            spacing: 8,
            children: [
              for (final MapEntry(key: code, value: name) in languages.entries)
                FilterChip(
                  label: Text(name),
                  selected: _languages.contains(code),
                  onSelected: (selected) => setState(() => selected ? _languages.add(code) : _languages.remove(code)),
                ),
            ],
          ),
          const SizedBox(height: 8),
          Row(
            children: [
              Text('Satisfaction: ${_satisfaction.round()} / 5', style: titleStyle),
              Expanded(
                // um controle deslizante: 5 marcas, de 1 a 5
                child: Slider(
                  value: _satisfaction,
                  min: 1,
                  max: 5,
                  divisions: 4,
                  onChanged: (v) => setState(() => _satisfaction = v),
                ),
              ),
            ],
          ),
          ListTile(
            contentPadding: EdgeInsets.zero,
            leading: const Icon(Icons.cake),
            title: const Text('Date of birth'),
            subtitle: Text(_birthDateText ?? 'not chosen'),
            trailing: OutlinedButton(onPressed: _chooseBirthDate, child: const Text('Choose')),
          ),
          const SizedBox(height: 8),
          // Wrap: os botões quebram para a linha seguinte em uma tela estreita
          Wrap(
            spacing: 8,
            runSpacing: 8,
            children: [
              FilledButton(onPressed: _send, child: const Text('Send')),
              OutlinedButton(onPressed: _example, child: const Text('Fill from the code')),
            ],
          ),
          const SizedBox(height: 16),
          Text('The model, live', style: titleStyle),
          Container(
            padding: const EdgeInsets.all(8),
            color: Colors.grey.shade100,
            // JsonEncoder.withIndent('  '): o JSON, indentado com 2 espaços
            child: Text(
              const JsonEncoder.withIndent('  ').convert(_model),
              style: const TextStyle(fontFamily: 'RobotoMono', fontSize: 12),
            ),
          ),
          // um bloco que só existe após um envio; ...[ ] insere VÁRIOS widgets
          if (_sent != null) ...[
            const SizedBox(height: 8),
            Text('Last send', style: titleStyle),
            Container(
              padding: const EdgeInsets.all(8),
              color: Colors.green.shade50,
              child: Text(_sent!, style: const TextStyle(fontFamily: 'RobotoMono', fontSize: 12)),
            ),
          ],
        ],
      ),
    );
  }
}

Um campo controlado exibe um valor do estado e notifica o widget de qualquer alteração ([onChanged]), que atualiza o estado: o estado é a única fonte de verdade. Isso vale para todos os campos do [Flutter]... exceto as caixas de texto, que armazenam seu texto em um controller.

  • Linhas 39–41: o texto do próprio [Flutter] (os dias e meses do calendário, os botões “OK” e “CANCEL” de suas janelas) está em inglês por padrão. Declaramos os idiomas do aplicativo ([supportedLocales]), o idioma selecionado ([locale]) e os “delegates” que fornecem as traduções do [Flutter], no pacote [flutter_localizations]. O Exemplo 21 voltará a isso;
  • linhas 56–66: um estado por campo. [final _name = TextEditingController()]: para um campo de texto, o estado é o próprio controller; [Set<String>]: um conjunto (sem duplicatas) de hobbies e idiomas; [DateTime? _birthDate]: uma data, ou [null] até que uma seja selecionada;
  • linhas 69–74: [initState] é chamado uma vez, quando o objeto [State] é criado (veja o Exemplo 13). Um controller notifica seus ouvintes ([addListener]) a cada alteração de seu texto: a tela é redesenhada para que o modelo exibido na parte inferior acompanhe a digitação. [setState(() {})]: não é preciso alterar nada, apenas redesenhar;
  • linha 87: a data no formato da API do [RdvMedecins], “2026-10-05”. [_birthDate?.toIso8601String()]: o operador [?.] chama o método somente se [_birthDate] não for [null] (caso contrário, o resultado é [null]);
  • linhas 90–100: todos os valores, reunidos em um [Map] (que seria enviado a um servidor). [int.tryParse(_age.text)]: a idade, ou [null] se o campo não for um número;
  • linhas 105–113: a data de nascimento é selecionada em uma janela de calendário. [showDatePicker] abre a janela e retorna um [Future]: a data selecionada, mais tarde, quando o usuário fechar a janela (ou [null] se a fechou sem fazer uma seleção). O método é [async]: [await] espera o [Future] terminar sem bloquear o aplicativo. Esse mecanismo é usado sempre que é preciso esperar (por uma janela, por um servidor);
  • linhas 118–126: o estado modificado pelo código: os campos o acompanham. Para uma caixa de texto, escrevemos em seu controller. [..clear()..addAll([...])]: a “cascata” do [Dart], várias chamadas de método no mesmo objeto;
  • linha 132: [jsonEncode] (de [dart:convert]) cria o JSON a partir de um [Map].

Os campos em [build]:

  • linhas 146–151: botões de opção. [RadioGroup] contém o valor selecionado ([groupValue]) e a função chamada quando outro valor é selecionado ([onChanged]); ele contém os botões [Radio], cada um com seu próprio valor. [...[a, b, c]] insere vários widgets de uma vez: para cada título, um botão, seu rótulo e um espaço;
  • linhas 160–169: dois campos de texto lado a lado, em um [Row]. [Expanded(flex: 2, ...)]: o nome ocupa o dobro do espaço da idade. O teclado do campo de idade é numérico;
  • Linhas 178–186: um campo não controlado: [TextFormField] pode receber um valor inicial ([initialValue]) em vez de um controller e gerenciar seu próprio texto. O texto é atualizado a cada tecla digitada, SEM [setState]: nada é redesenhado. O widget [Focus] avisa quando seu filho ganha ou perde o foco ([onFocusChange]): o redesenho só ocorre quando se sai do campo. Isso equivale ao evento [blur] do HTML;
  • linhas 190–195: uma única caixa de seleção e seu rótulo;
  • linhas 199–206: múltipla escolha para UM conjunto: caixas de seleção para escolher ([FilterChip]). Cada chip é selecionado se o conjunto contém seu valor; tocar nele adiciona ou remove o valor. [Wrap] coloca seus filhos lado a lado e quebra para a linha seguinte quando não há mais espaço;
  • linhas 216–222: uma lista suspensa. [value] indica qual item está selecionado; [items] lista os itens, cada um com seu valor e seu widget. [for (final MapEntry(key: code, value: name) in countries.entries)] percorre as entradas do [Map] [countries] “desempacotando” cada uma em duas variáveis, [code] e [name];
  • linhas 230–234: idiomas falados, também listados com chips. (No [Flutter], não existe lista de múltipla escolha: chips ou caixas de seleção cumprem essa função);
  • linhas 244–249: um controle deslizante, de 1 a 5, em quatro intervalos ([divisions]). Seu valor é um [double];
  • linhas 254–259: a data de nascimento e o botão que abre o calendário;
  • linhas 278–279: o modelo, ao vivo: seu JSON, indentado com dois espaços, na fonte monoespaçada incluída no aplicativo;
  • linhas 283–289: um bloco que só aparece depois que uma mensagem é enviada: [if] seguido de [...[ ]] insere vários widgets, ou nenhum.

Você escolhe o título, um nome, hobbies e um idioma; depois abre o calendário; depois envia:

A tabela a seguir resume o que cada campo transmite à sua função correspondente, [onChanged]:

Campo
Valor transmitido
TextField, TextFormField
String (texto); ou o controller é lido
Checkbox, CheckboxListTile
bool? (marcada, desmarcada ou indeterminada)
Switch, SwitchListTile
bool
Radio (em um RadioGroup)
o valor do botão selecionado (T?)
DropdownButton<T>
o valor do elemento selecionado (T?)
FilterChip
bool: o chip está selecionado?
SegmentedButton<T>
Set<T>: os valores selecionados
Slider
double
showDatePicker
Future<DateTime?>: a data selecionada, mais tarde

3.6. Exemplo 06: um formulário, um objeto, um reducer

O exemplo 05 tinha um campo de estado para cada campo do formulário. Para um formulário real, preferimos um objeto que contém todos os valores — o modelo — e descrevemos suas mudanças em uma única função, o reducer: [reducer(currentState, action) -> newState]. É isso que o hook [useReducer] faz no [React]; no [Flutter], não há nada a importar: [Dart] fornece tudo o que é necessário.

// =========================================================================
// lib/ex06_reducer/main.dart - um formulário, um objeto, um reducer
// -------------------------------------------------------------------------
// O exemplo 05 tinha um campo de estado por campo do formulário. Para um
// formulário de verdade, preferimos UM objeto que guarda todos os valores, o
// MODELO (aqui um objeto Profile, não modificável), e descrevemos suas
// alterações em uma única função, o REDUCER:
//
//     reducer(currentState, action) -> newState
//
// O widget não modifica mais o estado: ele DESCREVE o que aconteceu, com um objeto
// ProfileAction (Edit(Field.lastName, 'Dupont'), Leave(Field.lastName)...), e
// o reducer deduz dele o novo estado. Toda a lógica fica em um só
// lugar, em uma função PURA (mesma entrada, mesma saída, sem efeito
// colateral), fácil de testar.
// O Dart se presta bem a isso: uma classe "sealed" lista todas as ações
// possíveis, e um switch sobre uma ação é verificado pelo compilador
// (um caso esquecido é um erro).
//
// O estado também guarda, para cada campo, se ele foi "tocado" (deixado pelo
// menos uma vez); a partir disso deduzimos se ele está "modificado" (seu valor difere do
// valor inicial) e se está desabilitado.
// =========================================================================

import 'dart:convert';

import 'package:flutter/material.dart';

// o nome de cada campo do formulário
enum Field { title, firstName, lastName, age, newsletter, email, country, birthDate, presentation }

// os dados do formulário: um objeto NÃO MODIFICÁVEL (todos os seus campos são
// final). Para "modificá-lo", construímos um novo (copyWith)
class Profile {
  final String title;
  final String firstName;
  final String lastName;
  final int age;
  final bool newsletter;
  final String email;
  final String country;
  final String birthDate;
  final String presentation;

  const Profile({
    required this.title,
    required this.firstName,
    required this.lastName,
    required this.age,
    required this.newsletter,
    required this.email,
    required this.country,
    required this.birthDate,
    required this.presentation,
  });

  // uma cópia, na qual alguns campos são alterados (os outros são mantidos);
  // "??": o novo valor se for fornecido, senão o antigo
  Profile copyWith({
    String? title,
    String? firstName,
    String? lastName,
    int? age,
    bool? newsletter,
    String? email,
    String? country,
    String? birthDate,
    String? presentation,
  }) {
    return Profile(
      title: title ?? this.title,
      firstName: firstName ?? this.firstName,
      lastName: lastName ?? this.lastName,
      age: age ?? this.age,
      newsletter: newsletter ?? this.newsletter,
      email: email ?? this.email,
      country: country ?? this.country,
      birthDate: birthDate ?? this.birthDate,
      presentation: presentation ?? this.presentation,
    );
  }

  // o valor de um campo, designado pelo seu nome
  Object value(Field c) => switch (c) {
    Field.title => title,
    Field.firstName => firstName,
    Field.lastName => lastName,
    Field.age => age,
    Field.newsletter => newsletter,
    Field.email => email,
    Field.country => country,
    Field.birthDate => birthDate,
    Field.presentation => presentation,
  };

  // uma cópia na qual UM campo, designado pelo seu nome, tem um novo valor
  Profile withField(Field c, Object v) => switch (c) {
    Field.title => copyWith(title: v as String),
    Field.firstName => copyWith(firstName: v as String),
    Field.lastName => copyWith(lastName: v as String),
    Field.age => copyWith(age: v as int),
    Field.newsletter => copyWith(newsletter: v as bool),
    Field.email => copyWith(email: v as String),
    Field.country => copyWith(country: v as String),
    Field.birthDate => copyWith(birthDate: v as String),
    Field.presentation => copyWith(presentation: v as String),
  };

  Map<String, Object> toJson() => {for (final c in Field.values) c.name: value(c)};
}

const initial = Profile(
  title: 'Mme',
  firstName: 'Marie',
  lastName: 'PELISSIER',
  age: 30,
  newsletter: false,
  email: '',
  country: 'fr',
  birthDate: '',
  presentation: '',
);

// o estado completo: os valores e os campos já deixados
class ProfileState {
  final Profile values;
  final Set<Field> touched;

  const ProfileState(this.values, this.touched);
}

// as ações possíveis. "sealed": não há outras além das
// deste arquivo, o compilador sabe disso
sealed class ProfileAction {
  const ProfileAction();
}

class Edit extends ProfileAction {
  final Field field;
  final Object value;
  const Edit(this.field, this.value);
}

class Leave extends ProfileAction {
  final Field field;
  const Leave(this.field);
}

class Uppercase extends ProfileAction {
  const Uppercase();
}

class Reset extends ProfileAction {
  const Reset();
}

// o reducer: ele NUNCA modifica o estado que recebe, retorna um novo.
// O switch "desestrutura" cada ação: Edit(:final field, ...) lê
// seus campos em variáveis de mesmo nome
ProfileState reducer(ProfileState state, ProfileAction action) => switch (action) {
  Edit(:final field, :final value) => ProfileState(state.values.withField(field, value), state.touched),
  Leave(:final field) => ProfileState(state.values, {...state.touched, field}),
  Uppercase() => ProfileState(
    state.values.copyWith(firstName: state.values.firstName.toUpperCase(), lastName: state.values.lastName.toUpperCase()),
    state.touched,
  ),
  Reset() => const ProfileState(initial, {}),
};

const titles = ['Mr', 'Mme', 'Melle'];
const trackedFields = [Field.firstName, Field.lastName, Field.age, Field.email];
// os campos de texto: cada um terá seu controller
const textFields = [Field.firstName, Field.lastName, Field.email, Field.presentation];

void main() {
  runApp(
    MaterialApp(
      debugShowCheckedModeBanner: false,
      theme: ThemeData(colorSchemeSeed: Colors.indigo),
      home: const ProfilePage(),
    ),
  );
}

class ProfilePage extends StatefulWidget {
  const ProfilePage({super.key});

  @override
  State<ProfilePage> createState() => _ProfilePageState();
}

class _ProfilePageState extends State<ProfilePage> {
  ProfileState _state = const ProfileState(initial, {});
  // um controller por campo de texto; um "map": Field -> controller
  final _controllers = {for (final c in textFields) c: TextEditingController(text: initial.value(c) as String)};

  @override
  void dispose() {
    for (final c in _controllers.values) {
      c.dispose();
    }
    super.dispose();
  }

  // A ÚNICA maneira de mudar o estado: descrever o que aconteceu
  void _dispatch(ProfileAction action) {
    setState(() => _state = reducer(_state, action));
    // o reducer pode ter alterado um texto (Uppercase, Reset): os
    // campos de entrada devem mostrá-lo
    for (final MapEntry(key: field, value: controller) in _controllers.entries) {
      final value = _state.values.value(field) as String;
      if (controller.text != value) {
        controller.text = value;
      }
    }
  }

  Profile get _v => _state.values;

  // valores DEDUZIDOS do estado
  bool _modified(Field c) => _v.value(c) != initial.value(c);
  bool _disabled(Field c) => c == Field.email && !_v.newsletter; // o e-mail exige a newsletter
  bool get _formModified => Field.values.any(_modified);

  // um campo de texto ligado ao modelo: um método que o constrói
  Widget _field(Field field, String label, {int lines = 1}) {
    // Focus: sabemos quando o campo é DEIXADO (ele perde o foco)
    return Focus(
      onFocusChange: (hasFocus) {
        if (!hasFocus) _dispatch(Leave(field));
      },
      child: TextField(
        controller: _controllers[field],
        enabled: !_disabled(field),
        maxLines: lines,
        decoration: InputDecoration(labelText: label),
        onChanged: (text) => _dispatch(Edit(field, text)),
      ),
    );
  }

  @override
  Widget build(BuildContext context) {
    final titleStyle = Theme.of(context).textTheme.titleSmall;
    return Scaffold(
      appBar: AppBar(title: const Text('Example 06 - a reducer')),
      body: ListView(
        padding: const EdgeInsets.all(16),
        children: [
          RadioGroup<String>(
            groupValue: _v.title,
            onChanged: (t) => _dispatch(Edit(Field.title, t!)),
            child: Row(
              children: [
                for (final t in titles) ...[Radio<String>(value: t), Text(t), const SizedBox(width: 12)],
              ],
            ),
          ),
          Row(
            children: [
              Expanded(child: _field(Field.firstName, 'First name')),
              const SizedBox(width: 12),
              Expanded(child: _field(Field.lastName, 'Last name')),
            ],
          ),
          Row(
            children: [
              Text('Age: ${_v.age}', style: titleStyle),
              Expanded(
                child: Slider(
                  value: _v.age.toDouble(),
                  max: 120,
                  divisions: 120,
                  onChanged: (a) => _dispatch(Edit(Field.age, a.round())),
                  // o controle deslizante é solto: o campo foi "deixado"
                  onChangeEnd: (_) => _dispatch(const Leave(Field.age)),
                ),
              ),
            ],
          ),
          SwitchListTile(
            contentPadding: EdgeInsets.zero,
            title: const Text('Receive the newsletter'),
            value: _v.newsletter,
            onChanged: (yes) => _dispatch(Edit(Field.newsletter, yes)),
          ),
          _field(Field.email, 'E-mail (if newsletter)'),
          const SizedBox(height: 8),
          DropdownButton<String>(
            value: _v.country,
            items: const [
              DropdownMenuItem(value: 'fr', child: Text('France')),
              DropdownMenuItem(value: 'be', child: Text('Belgium')),
              DropdownMenuItem(value: 'ch', child: Text('Switzerland')),
            ],
            onChanged: (p) => _dispatch(Edit(Field.country, p!)),
          ),
          _field(Field.presentation, 'Presentation', lines: 2),
          const SizedBox(height: 12),
          Wrap(
            spacing: 8,
            children: [
              OutlinedButton(onPressed: () => _dispatch(const Uppercase()), child: const Text('Name in upper case')),
              OutlinedButton(onPressed: () => _dispatch(const Reset()), child: const Text('Reset')),
            ],
          ),
          const SizedBox(height: 16),
          Text('The model, live', style: titleStyle),
          Container(
            padding: const EdgeInsets.all(8),
            color: Colors.grey.shade100,
            child: Text(
              const JsonEncoder.withIndent('  ').convert(_v.toJson()),
              style: const TextStyle(fontFamily: 'RobotoMono', fontSize: 12),
            ),
          ),
          const SizedBox(height: 16),
          Text('The state of the fields', style: titleStyle),
          // DataTable: uma tabela, com suas colunas e suas linhas
          DataTable(
            columnSpacing: 16,
            headingRowHeight: 36,
            dataRowMinHeight: 28,
            dataRowMaxHeight: 32,
            columns: const [
              DataColumn(label: Text('field')),
              DataColumn(label: Text('touched')),
              DataColumn(label: Text('modified')),
              DataColumn(label: Text('disabled')),
            ],
            rows: [
              for (final c in trackedFields)
                DataRow(
                  cells: [
                    DataCell(Text(c.name)),
                    DataCell(Text('${_state.touched.contains(c)}')),
                    DataCell(Text('${_modified(c)}')),
                    DataCell(Text('${_disabled(c)}')),
                  ],
                ),
            ],
          ),
          const SizedBox(height: 8),
          Text.rich(
            TextSpan(
              children: [
                const TextSpan(text: 'form modified: '),
                TextSpan(
                  text: '$_formModified',
                  style: const TextStyle(fontWeight: FontWeight.bold),
                ),
              ],
            ),
          ),
        ],
      ),
    );
  }
}

O modelo:

  • linha 30: o nome de cada campo do formulário;
  • linhas 34–43: os dados do formulário: um objeto não editável, cujos campos são todos [final];
  • linhas 45–54: um construtor com parâmetros nomeados, todos obrigatórios ([required]);
  • linhas 59–79: para “modificar” um objeto não editável, cria-se uma cópia na qual alguns campos são alterados: é o método [copyWith], uma variação do [Flutter] (que encontramos com [TextStyle]). Cada parâmetro é opcional ([String? title]: uma string ou [null]); [title ?? this.title]: o novo valor, se fornecido, ou o antigo, caso contrário;
  • linhas 84–93: o valor de um campo designado pelo seu nome: uma expressão [switch] sobre a enumeração;
  • linhas 97–106: uma cópia na qual UM campo, designado pelo seu nome, tem um novo valor. [v as String]: o valor recebido (do tipo [Object], que pode ser qualquer coisa) é convertido em string; se não fosse uma string, resultaria em um erro de execução;
  • linha 109: um [Map] “nome do campo -> valor”, criado por um [for] dentro de um literal [Map]. [c.name]: o nome de um valor da enumeração (“firstName”);
  • linhas 112–121: os valores iniciais;
  • linhas 125–129: o estado completo: os valores e todos os campos que já foram processados (“tocados”).

As ações e o reducer:

  • linhas 134–154: as ações possíveis: uma classe selada ([sealed]) e suas quatro subclasses. [sealed] informa ao compilador que não há outras subclasses além das deste arquivo. Uma ação descreve o que aconteceu: [Edit(Field.lastName, 'Dupont')], [Leave(Field.lastName)]...;
  • linhas 160–167: o reducer. É uma função pura: mesma entrada, mesma saída, sem efeitos colaterais; ele nunca modifica o estado recebido, mas devolve um novo. O [switch] se aplica à ação, e cada case é um padrão que testa seu tipo: [Edit(:final field, :final value)] verifica que a ação é um [Edit] e guarda seus campos [field] e [value] em variáveis de mesmo nome. Como a classe é selada, o compilador verifica que as quatro ações são tratadas; adicionar uma quinta sem completar o reducer resultaria em um erro de compilação;
  • linha 162: um novo conjunto, composto pelos elementos do conjunto antigo ([...state.touched]) e pelo campo que está sendo abandonado.

A tela:

  • linha 193: o estado da tela: UM campo, o objeto [ProfileState];
  • linha 195: um controller de campo de texto, em um [Map] criado por um [for];
  • Linhas 206–213: o ÚNICO método para alterar o estado: descrever o que aconteceu. [_dispatch] (o nome que o [React] lhe dá) calcula o novo estado usando o reducer, dentro de [setState]. Em seguida, como o reducer pode ter modificado algum texto (Uppercase, Reset), os valores são copiados para os controllers que ainda não os têm;
  • linhas 221–223: valores derivados do estado: um campo é modificado se seu valor difere do valor inicial; o e-mail fica desabilitado sem a newsletter; o formulário é modificado se algum de seus campos for modificado ([any]). [Field.values]: a lista dos valores da enumeração;
  • linhas 226–237: um método que cria um campo de texto vinculado ao modelo: seu controller, seu estado desabilitado ([enabled]) e duas ações: [Edit] a cada tecla digitada, [Leave] quando perde o foco;
  • No [build], cada campo descreve suas mudanças por meio de uma ação: [_dispatch(Edit(Field.title, t!))], [_dispatch(const Uppercase())]...;
  • linhas 320–338: uma tabela ([DataTable]), com suas colunas e linhas: o status de cada campo acompanhado;
  • linhas 344–349: um texto composto por várias seções com estilos diferentes: [Text.rich] e seus [TextSpan].

Alteramos o nome, saímos do campo e assinamos a newsletter; depois colocamos o nome em maiúsculas:

Toda a lógica do formulário está contida no reducer — uma função de poucas linhas, sem nenhum widget — que pode ser testada isoladamente. Os widgets agora simplesmente exibem o estado e descrevem o que está acontecendo.

3.7. Exemplo 07: validando um formulário manualmente

Uma função pura, [validate(account)], devolve os erros dos campos; ela é chamada toda vez que [build] é executado, de modo que os erros estão sempre atualizados. Eles não são exibidos imediatamente (um formulário vazio coberto de vermelho é desagradável), apenas para um campo que já foi abandonado. Enviar o formulário exibe todos os erros.

// =========================================================================
// lib/ex07_validation/main.dart - validando um formulário, à mão
// -------------------------------------------------------------------------
// Uma função PURA, validate(account), retorna os erros dos campos; nós a
// chamamos a cada build(), então os erros estão sempre atualizados.
// Não os mostramos de imediato (um formulário vazio coberto de vermelho é
// desagradável): apenas para um campo já deixado ("touched"). O envio
// marca todos os campos como tocados e só age se o formulário
// for válido. Um TextField exibe um erro abaixo do campo, em vermelho,
// quando recebe um texto de erro: InputDecoration(errorText: ...).
//
// As mesmas regras do servidor RdvMedecins (formulário "Criar uma conta").
// ATENÇÃO: esta validação é apenas uma COMODIDADE para o usuário (uma
// resposta imediata, sem ida e volta ao servidor). Ela não protege
// nada: qualquer pessoa pode enviar ao servidor uma requisição montada
// à mão (curl...). O servidor portanto SEMPRE valida tudo de novo (veja o exemplo 25).
// =========================================================================

import 'package:flutter/material.dart';

enum Field { title, firstName, lastName, login, password, confirmation }

// um "record": um pequeno grupo de valores nomeados, sem precisar escrever uma classe
typedef Account = ({String title, String firstName, String lastName, String login, String password, String confirmation});

const titles = ['Mr', 'Mme', 'Melle'];
final loginFormat = RegExp(r'^[a-z0-9._-]{1,30}$');
const passwordMin = 6;

// as regras: uma função pura, que depende apenas do seu argumento.
// Ela retorna, para cada campo com erro, sua mensagem
Map<Field, String> validate(Account c) {
  final errors = <Field, String>{};
  if (!titles.contains(c.title)) errors[Field.title] = 'Choose a title from the list.';
  if (c.firstName.trim().isEmpty) {
    errors[Field.firstName] = 'The first name is required.';
  } else if (c.firstName.length > 20) {
    errors[Field.firstName] = 'The first name must not exceed 20 characters.';
  }
  if (c.lastName.trim().isEmpty) {
    errors[Field.lastName] = 'The last name is required.';
  } else if (c.lastName.length > 20) {
    errors[Field.lastName] = 'The last name must not exceed 20 characters.';
  }
  if (c.login.isEmpty) {
    errors[Field.login] = 'The login is required.';
  } else if (!loginFormat.hasMatch(c.login)) {
    errors[Field.login] = 'Unaccented lower-case letters, digits, dot, hyphen, underscore.';
  }
  if (c.password.isEmpty) {
    errors[Field.password] = 'The password is required.';
  } else if (c.password.length < passwordMin) {
    errors[Field.password] = 'At least $passwordMin characters.';
  }
  // uma regra que compara DOIS campos
  if (c.confirmation != c.password) {
    errors[Field.confirmation] = 'The confirmation does not match the password.';
  }
  return errors;
}

void main() {
  runApp(
    MaterialApp(
      debugShowCheckedModeBanner: false,
      theme: ThemeData(colorSchemeSeed: Colors.indigo),
      home: const AccountPage(),
    ),
  );
}

class AccountPage extends StatefulWidget {
  const AccountPage({super.key});

  @override
  State<AccountPage> createState() => _AccountPageState();
}

class _AccountPageState extends State<AccountPage> {
  String _title = 'Mr';
  // um controller por campo de texto
  final _texts = {
    for (final c in [Field.firstName, Field.lastName, Field.login, Field.password, Field.confirmation])
      c: TextEditingController(),
  };
  final Set<Field> _touched = {};
  bool _submitAttempted = false;
  bool _success = false;

  @override
  void dispose() {
    for (final c in _texts.values) {
      c.dispose();
    }
    super.dispose();
  }

  // a conta, como digitada: um record construído sob demanda
  Account get _account => (
    title: _title,
    firstName: _texts[Field.firstName]!.text,
    lastName: _texts[Field.lastName]!.text,
    login: _texts[Field.login]!.text,
    password: _texts[Field.password]!.text,
    confirmation: _texts[Field.confirmation]!.text,
  );

  void _send() {
    setState(() {
      _submitAttempted = true;
      _touched.addAll(Field.values); // todos os erros aparecem
      // aqui, a conta seria enviada ao servidor (veja o exemplo 25)
      _success = validate(_account).isEmpty;
    });
  }

  @override
  Widget build(BuildContext context) {
    // os erros: recalculados a cada build(), nunca guardados no estado
    final errors = validate(_account);

    // o erro a EXIBIR para um campo: somente se ele foi tocado
    String? error(Field c) => _touched.contains(c) ? errors[c] : null;

    // um campo de texto: rótulo, erro e uma marca de verificação verde se foi tocado e é válido
    Widget field(Field c, String label, {bool secret = false}) {
      final valid = _touched.contains(c) && !errors.containsKey(c);
      return Focus(
        onFocusChange: (hasFocus) {
          if (!hasFocus) setState(() => _touched.add(c));
        },
        child: TextField(
          controller: _texts[c],
          obscureText: secret, // os caracteres ficam ocultos
          decoration: InputDecoration(
            labelText: label,
            errorText: error(c),
            // o erro pode ocupar duas linhas
            errorMaxLines: 2,
            suffixIcon: valid ? const Icon(Icons.check_circle, color: Colors.green) : null,
          ),
          onChanged: (_) => setState(() => _success = false),
        ),
      );
    }

    return Scaffold(
      appBar: AppBar(title: const Text('Example 07 - the validation')),
      body: ListView(
        padding: const EdgeInsets.all(16),
        children: [
          DropdownButton<String>(
            value: _title,
            items: [for (final t in titles) DropdownMenuItem(value: t, child: Text(t))],
            onChanged: (t) => setState(() => _title = t!),
          ),
          field(Field.firstName, 'First name'),
          field(Field.lastName, 'Last name'),
          field(Field.login, 'Login'),
          field(Field.password, 'Password', secret: true),
          field(Field.confirmation, 'Confirmation', secret: true),
          const SizedBox(height: 16),
          FilledButton(onPressed: _send, child: const Text('Create the account')),
          const SizedBox(height: 12),
          if (_submitAttempted && errors.isNotEmpty)
            _Message('The form contains ${errors.length} error(s).', color: Colors.red.shade50),
          if (_success)
            _Message('Valid form: it could be sent to the server.', color: Colors.green.shade50),
        ],
      ),
    );
  }
}

// um pequeno widget privado: uma mensagem sobre um fundo colorido
class _Message extends StatelessWidget {
  final String text;
  final Color color;

  const _Message(this.text, {required this.color});

  @override
  Widget build(BuildContext context) {
    return Container(
      padding: const EdgeInsets.all(12),
      decoration: BoxDecoration(color: color, borderRadius: BorderRadius.circular(8)),
      child: Text(text),
    );
  }
}
  • linha 24: a conta informada é um record: um pequeno grupo de valores nomeados, sem nenhuma classe para escrever. [typedef] lhe atribui um nome. Um record é escrito como [(title: 'Mr', firstName: 'Marie', ...)] e lido como [account.firstName];
  • linhas 27–28: uma expressão regular (o formato de um login) e uma constante: as mesmas regras do servidor [RdvMedecins];
  • linhas 32–59: as regras: uma função pura que depende apenas de seu argumento e devolve um [Map] “campo com erro → mensagem”. A última regra compara DOIS campos: a confirmação e a senha;
  • linhas 82–84: um validador por campo de texto;
  • linha 86: os campos que já foram abandonados;
  • linhas 99–105: a conta, como informada: um record gerado sob demanda a partir dos validadores. [_texts[Field.firstName]!]: o acesso a um [Map] devolve um valor ou [null] (a chave pode não existir); o [!] confirma que ela está presente;
  • linhas 108–113: o envio marca todos os campos como tocados (os erros aparecem) e só então age, se o formulário for válido;
  • linha 120: no [build], os erros são recalculados a cada vez; nunca são armazenados no estado;
  • linha 123: uma função local: o erro a exibir para um campo, somente se ele tiver sido tocado;
  • Linhas 126–142: uma função local que cria um campo. [InputDecoration] sabe exibir um erro: [errorText]. Quando não é [null], o campo é contornado de vermelho e a mensagem é exibida abaixo dele (em no máximo duas linhas: [errorMaxLines]). [suffixIcon]: um ícone à direita do campo — neste caso, um visto verde para um campo preenchido e válido. [obscureText] oculta os caracteres de uma senha;
  • linhas 165–168: mensagens de fim de formulário;
  • linhas 176–187: um pequeno widget privado, para evitar repetir duas vezes a mesma caixa colorida.

Preencha alguns campos e envie; depois corrija tudo e envie novamente:

ATENÇÃO: esta validação é apenas uma comodidade para o usuário — uma resposta imediata, sem ida e volta com o servidor. Ela não protege nada: qualquer pessoa pode enviar ao servidor uma requisição montada manualmente ([curl]…), e o código de um aplicativo móvel pode ser modificado. O servidor, portanto, sempre revalida tudo (veja o exemplo 25).

3.8. Exemplo 08: formulários do Flutter, Form e FormField

O formulário do exemplo 07, escrito com as ferramentas fornecidas pelo próprio [Flutter] . Enquanto o [React] exige uma biblioteca ([React Hook Form]), o [Flutter] tem seus próprios widgets de formulário:

// =========================================================================
// lib/ex08_form/main.dart - os formulários do Flutter: Form e FormField
// -------------------------------------------------------------------------
// O formulário do exemplo 07, escrito com as ferramentas de formulário que
// o próprio Flutter fornece:
//   - Form: um widget que AGRUPA campos de formulário (FormField);
//     ele é acessado por uma "global key", GlobalKey<FormState>;
//   - TextFormField, DropdownButtonFormField...: campos que sabem
//     se validar sozinhos. Seu parâmetro validator é uma função:
//         (value) -> null se o valor estiver correto, senão a mensagem de erro;
//   - autovalidateMode: QUANDO validar (aqui, assim que o usuário
//     modificou o campo, depois a cada tecla);
//   - form.validate(): valida TODOS os campos, exibe seus
//     erros e retorna true se tudo estiver correto;
//   - form.save(): chama o onSaved de cada campo, que guarda seu
//     valor onde quisermos.
// Os campos NÃO são controlados: cada um guarda seu valor, o Form apenas o
// lê na validação e no momento de salvar.
// =========================================================================

import 'dart:convert';

import 'package:flutter/material.dart';

const titles = ['Mr', 'Mme', 'Melle'];

void main() {
  runApp(
    MaterialApp(
      debugShowCheckedModeBanner: false,
      theme: ThemeData(colorSchemeSeed: Colors.indigo),
      home: const AccountPage(),
    ),
  );
}

class AccountPage extends StatefulWidget {
  const AccountPage({super.key});

  @override
  State<AccountPage> createState() => _AccountPageState();
}

class _AccountPageState extends State<AccountPage> {
  // a chave que dá acesso ao estado do formulário (validate, save, reset)
  final _formKey = GlobalKey<FormState>();
  // a chave de UM campo: para validar de novo a confirmação quando a senha muda
  final _confirmationKey = GlobalKey<FormFieldState<String>>();
  // a senha é lida na regra da confirmação: um controller
  final _password = TextEditingController();
  // os valores guardados pelos callbacks onSaved
  final Map<String, String> _account = {};
  // null: nenhum envio ainda; '': envio recusado; senão, o JSON enviado
  String? _sent;

  @override
  void dispose() {
    _password.dispose();
    super.dispose();
  }

  void _create() {
    final form = _formKey.currentState!;
    if (!form.validate()) {
      setState(() => _sent = '');
      return;
    }
    form.save(); // cada onSaved guarda seu valor em _account
    setState(() => _sent = jsonEncode(_account));
  }

  // FÁBRICAS de regras: cada uma retorna uma função de validação
  FormFieldValidator<String> _required(String message) =>
      (v) => (v == null || v.trim().isEmpty) ? message : null;

  FormFieldValidator<String> _maximum(int max, FormFieldValidator<String> other) =>
      (v) => other(v) ?? (v!.length > max ? 'At most $max characters.' : null);

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Example 08 - Form and FormField')),
      body: Form(
        key: _formKey,
        child: ListView(
          padding: const EdgeInsets.all(16),
          children: [
            // initialValue: o valor inicial; o campo então gerencia o seu próprio
            DropdownButtonFormField<String>(
              initialValue: 'Mr',
              decoration: const InputDecoration(labelText: 'Title'),
              items: [for (final t in titles) DropdownMenuItem(value: t, child: Text(t))],
              onChanged: (_) {},
              onSaved: (t) => _account['title'] = t!,
            ),
            TextFormField(
              decoration: const InputDecoration(labelText: 'First name'),
              autovalidateMode: AutovalidateMode.onUserInteraction,
              validator: _maximum(20, _required('The first name is required.')),
              onSaved: (v) => _account['firstName'] = v!.trim(),
            ),
            TextFormField(
              decoration: const InputDecoration(labelText: 'Last name'),
              autovalidateMode: AutovalidateMode.onUserInteraction,
              validator: _maximum(20, _required('The last name is required.')),
              onSaved: (v) => _account['lastName'] = v!.trim(),
            ),
            TextFormField(
              decoration: const InputDecoration(labelText: 'Login', errorMaxLines: 2),
              autovalidateMode: AutovalidateMode.onUserInteraction,
              // uma regra escrita diretamente: uma função anônima
              validator: (v) {
                if (v == null || v.isEmpty) return 'The login is required.';
                if (!RegExp(r'^[a-z0-9._-]{1,30}$').hasMatch(v)) {
                  return 'Unaccented lower-case letters, digits, dot, hyphen, underscore.';
                }
                return null;
              },
              onSaved: (v) => _account['login'] = v!,
            ),
            TextFormField(
              controller: _password,
              obscureText: true,
              decoration: const InputDecoration(labelText: 'Password'),
              autovalidateMode: AutovalidateMode.onUserInteraction,
              validator: (v) {
                if (v == null || v.isEmpty) return 'The password is required.';
                return v.length < 6 ? 'At least 6 characters.' : null;
              },
              // a senha muda: a confirmação é validada de novo
              // (se já foi digitada)
              onChanged: (_) {
                final confirmation = _confirmationKey.currentState!;
                if (confirmation.value?.isNotEmpty ?? false) confirmation.validate();
              },
              onSaved: (v) => _account['password'] = v!,
            ),
            TextFormField(
              key: _confirmationKey,
              obscureText: true,
              decoration: const InputDecoration(labelText: 'Confirmation', errorMaxLines: 2),
              autovalidateMode: AutovalidateMode.onUserInteraction,
              // uma regra que lê OUTRO campo
              validator: (v) => v == _password.text ? null : 'The confirmation does not match the password.',
            ),
            const SizedBox(height: 16),
            FilledButton(onPressed: _create, child: const Text('Create the account')),
            const SizedBox(height: 12),
            if (_sent != null)
              Container(
                padding: const EdgeInsets.all(12),
                decoration: BoxDecoration(
                  color: _sent!.isEmpty ? Colors.red.shade50 : Colors.green.shade50,
                  borderRadius: BorderRadius.circular(8),
                ),
                child: Text(_sent!.isEmpty ? 'Invalid form.' : 'Valid form: $_sent'),
              ),
          ],
        ),
      ),
    );
  }
}
  • Linha 46: um formulário chamado [Form] contém campos de formulário. Para interagir com ele a partir do código (validar, salvar), atribuímos a ele uma chave global, [GlobalKey]: um objeto que dá acesso ao estado de um widget na árvore ([_formKey.currentState]);
  • linha 48: a chave de UM campo, para que ele possa ser revalidado isoladamente;
  • linha 50: um controller para a senha: a regra de confirmação precisa lê-lo;
  • linha 52: os valores armazenados no envio;
  • linhas 62–69: [validate()] valida todos os campos do formulário, exibe os eventuais erros e devolve [true] se tudo estiver correto. [save()] chama então a função [onSaved] de cada campo, que define seu valor;
  • Linhas 73–77: geradores de regras. Uma regra de validação ([FormFieldValidator]) é uma função que recebe o valor do campo e devolve [null] se ele for válido; caso contrário, devolve a mensagem de erro. [_required('...')] cria uma regra; [_maximum(20, other)] cria uma regra que aplica primeiro a regra [other]e depois a sua própria ([??]: se a primeira não encontrar nada);
  • linha 83: o formulário e sua chave;
  • linhas 89–94: uma lista suspensa que também é um campo de formulário. [initialValue]: seu valor inicial; depois disso, o campo gerencia seu próprio valor;
  • linhas 96–100: um [TextFormField] é um [TextField] que também é um campo de formulário: ele tem uma regra ([validator]), uma função de salvamento ([onSaved]) e um modo de validação automática: [AutovalidateMode.onUserInteraction] valida o campo assim que o usuário o modifica e, depois, a cada tecla digitada;
  • linhas 112–117: uma regra escrita diretamente, com dois testes;
  • linhas 132–134: quando a senha muda, a confirmação é revalidada por meio da chave do campo, se já tiver sido preenchida;
  • linha 144: uma regra que lê OUTRO campo.

Digite alguns valores incorretos e envie; depois corrija-os:

Qual dos dois métodos escolher? [Form] e [TextFormField] bastam para um formulário cujas regras são escritas no aplicativo. Mas, neste curso, as regras do servidor prevalecem: o estudo de caso não tem regras no aplicativo e exibe o erro devolvido pelo servidor sob cada campo (exemplo 25). É o método usado no exemplo 07, que trata dos campos e de seus erros.

3.9. Exemplo 09: formatando valores

Cada linha da tabela mostra um trecho de código e o que ele exibe.

3.9.1. Funções de formatação

O [Flutter] não tem mecanismo de formatação embutido (os “pipes” do [Angular]): no [build], chamamos funções padrão, guardadas em um arquivo e testáveis separadamente:

// =========================================================================
// lib/ex09_formatting/formatting.dart - funções de formatação "caseiras"
// -------------------------------------------------------------------------
// O Flutter não tem mecanismo próprio de formatação (o Angular tem seus
// "pipes"): em build(), chamamos FUNÇÕES comuns, guardadas
// em um arquivo e testáveis isoladamente:
//     timeRange(slot)           -> "8:00 - 8:20"
//     timeRange(slot, Part.start) -> "8:00"
// O Dart também permite ACRESCENTAR métodos a um tipo existente, com uma
// "extension": 'marie pelissier'.capitalized -> 'Marie Pelissier'.
// Para datas, números e valores monetários, o pacote intl conhece as
// convenções de cada idioma (veja main.dart).
// =========================================================================

// um horário, como descrito pela API do RdvMedecins
class Slot {
  final int startHour;
  final int startMinute;
  final int endHour;
  final int endMinute;

  const Slot(this.startHour, this.startMinute, this.endHour, this.endMinute);
}

enum Part { all, start, end }

// "8:05" em vez de "8:5"
String _time(int h, int m) => '$h:${m.toString().padLeft(2, '0')}';

// um parâmetro OPCIONAL, com seu valor padrão: [Part part = Part.all]
String timeRange(Slot c, [Part part = Part.all]) => switch (part) {
  Part.start => _time(c.startHour, c.startMinute),
  Part.end => _time(c.endHour, c.endMinute),
  Part.all => '${_time(c.startHour, c.startMinute)} - ${_time(c.endHour, c.endMinute)}',
};

// uma EXTENSION do tipo String: novos métodos para TODAS as strings
extension Formatting on String {
  // "marie pelissier" -> "Marie Pelissier"; \p{L}: uma letra, acentuada ou não
  String get capitalized => replaceAllMapped(
    RegExp(r'\p{L}+', unicode: true),
    (m) => m[0]![0].toUpperCase() + m[0]!.substring(1).toLowerCase(),
  );

  // "Marie PELISSIER" -> "MP"
  String get initials =>
      split(RegExp(r'\s+')).where((word) => word.isNotEmpty).map((word) => word[0].toUpperCase()).join();
}

// "2026-10-05" (o formato da API do RdvMedecins) -> uma data
DateTime toDate(String day) => DateTime.parse(day);
  • linhas 16–22: um horário, como descrito na API [RdvMedecins]: horas e minutos, como números;
  • linha 28: “8:05” em vez de “8:5”: [padLeft(2, '0')] completa com zeros à esquerda;
  • linhas 31–34: uma função com um parâmetro posicional opcional (entre colchetes), junto com seu valor padrão: [timeRange(c)] ou [timeRange(c, Part.start)];
  • linhas 38–47: uma extensão: ela adiciona métodos (neste caso, getters) ao tipo [String], a TODAS as strings: ['marie pelissier'.capitalized]. Este é um recurso especial do [Dart], muito útil para formatação. [replaceAllMapped] substitui cada palavra (uma sequência de letras, acentuadas ou não: [\p{L}+] com [unicode: true]) pelo valor de retorno da função;
  • linha 51: “2026-10-05” (o formato da API) -> uma data ([DateTime]).

3.9.2. A tela

// =========================================================================
// lib/ex09_formatting/main.dart - formatando valores
// -------------------------------------------------------------------------
// Cada linha da tabela mostra um trecho de código e o que ele exibe.
// Os formatadores do pacote intl (DateFormat, NumberFormat) são criados
// uma vez por todas, fora dos widgets: construí-los custa mais do que
// usá-los.
// Os nomes dos dias e dos meses de cada idioma não são carregados
// por padrão: initializeDateFormatting() os carrega, ANTES de runApp.
// =========================================================================

import 'dart:convert';

import 'package:flutter/material.dart';
import 'package:intl/date_symbol_data_local.dart';
import 'package:intl/intl.dart';

import 'formatting.dart';

// datas: formatos "prontos" (yMMMd, yMMMMEEEEd, Hms...), ou um padrão
final shortDate = DateFormat.yMMMd('en_US');
final fullDate = DateFormat.yMMMMEEEEd('en_US');
final timeOnly = DateFormat.Hms('en_US');
final frenchDay = DateFormat.yMMMMd('fr_FR');
final pattern = DateFormat('MM/dd/yyyy HH:mm', 'en_US');
// números e valores monetários
final euros = NumberFormat.currency(locale: 'en_US', symbol: '€');
final integer = NumberFormat.decimalPattern('en_US');
final percent = NumberFormat.decimalPercentPattern(locale: 'en_US', decimalDigits: 1);

const day = '2026-10-05'; // uma data no formato da API do RdvMedecins
const price = 1234.5;
const rate = 0.055;
const name = 'marie pelissier';
const doctor = {'title': 'Mme', 'firstName': 'Marie', 'lastName': 'PELISSIER'};
const languages = ['Dart', 'Flutter', 'Kotlin', 'Swift', 'SQL'];
const slots = [Slot(8, 0, 8, 20), Slot(8, 20, 8, 40), Slot(14, 5, 14, 25)];

// main pode ser ASSÍNCRONO: esperamos os idiomas serem carregados
Future<void> main() async {
  await initializeDateFormatting('fr_FR');
  await initializeDateFormatting('en_US');
  runApp(
    MaterialApp(
      debugShowCheckedModeBanner: false,
      theme: ThemeData(colorSchemeSeed: Colors.indigo),
      home: const FormattingPage(),
    ),
  );
}

class FormattingPage extends StatefulWidget {
  const FormattingPage({super.key});

  @override
  State<FormattingPage> createState() => _FormattingPageState();
}

class _FormattingPageState extends State<FormattingPage> {
  DateTime _now = DateTime.now();

  @override
  Widget build(BuildContext context) {
    // (código exibido, valor): uma linha da tabela, como um "record"
    final rows = <(String, String)>[
      ('shortDate.format(now)', shortDate.format(_now)),
      ('fullDate.format(now)', fullDate.format(_now)),
      ('timeOnly.format(now)', timeOnly.format(_now)),
      ('pattern.format(now)', pattern.format(_now)),
      ('fullDate.format(toDate(day))', fullDate.format(toDate(day))),
      ('frenchDay.format(toDate(day))', frenchDay.format(toDate(day))),
      ('now.toString()', _now.toString()),
      ('euros.format(price)', euros.format(price)),
      ('integer.format(price)', integer.format(price)),
      ('price.toStringAsFixed(1)', price.toStringAsFixed(1)),
      ('percent.format(rate)', percent.format(rate)),
      ('name.toUpperCase()', name.toUpperCase()),
      ('name.capitalized', name.capitalized),
      ("'RDV'.toLowerCase()", 'RDV'.toLowerCase()),
      ("languages.take(3).join(', ')", languages.take(3).join(', ')),
      ('jsonEncode(doctor)', jsonEncode(doctor)),
      // duas transformações em sequência: o resultado da primeira vai para a segunda
      ('name.capitalized.initials', name.capitalized.initials),
    ];

    const codeStyle = TextStyle(fontFamily: 'RobotoMono', fontSize: 11, color: Color(0xFFC7254E));
    return Scaffold(
      appBar: AppBar(title: const Text('Example 09 - the formatting')),
      body: ListView(
        padding: const EdgeInsets.all(12),
        children: [
          // Table: uma tabela simples; a primeira coluna ocupa 55% da largura
          Table(
            columnWidths: const {0: FractionColumnWidth(0.55)},
            border: TableBorder(horizontalInside: BorderSide(color: Colors.grey.shade300)),
            children: [
              const TableRow(
                children: [
                  Padding(
                    padding: EdgeInsets.all(4),
                    child: Text('In the code', style: TextStyle(fontWeight: FontWeight.bold)),
                  ),
                  Padding(
                    padding: EdgeInsets.all(4),
                    child: Text('Displayed', style: TextStyle(fontWeight: FontWeight.bold)),
                  ),
                ],
              ),
              // um record pode ser "desestruturado": (code, value)
              for (final (code, value) in rows)
                TableRow(
                  children: [
                    Padding(
                      padding: const EdgeInsets.all(4),
                      child: Text(code, style: codeStyle),
                    ),
                    Padding(padding: const EdgeInsets.all(4), child: Text(value)),
                  ],
                ),
            ],
          ),
          const SizedBox(height: 16),
          Text('Iterating over the entries of a Map', style: Theme.of(context).textTheme.titleSmall),
          for (final MapEntry(:key, :value) in doctor.entries) Text('$key = $value'),
          const SizedBox(height: 16),
          Text('A home-made function: timeRange', style: Theme.of(context).textTheme.titleSmall),
          for (final c in slots) Text('${timeRange(c)} (start: ${timeRange(c, Part.start)})'),
          const SizedBox(height: 16),
          Align(
            alignment: Alignment.centerLeft,
            child: OutlinedButton(
              onPressed: () => setState(() => _now = DateTime.now()),
              child: const Text('Refresh the time'),
            ),
          ),
        ],
      ),
    );
  }
}
  • linhas 21–25: formatadores de data do pacote [intl]. [DateFormat] contém formatos “predefinidos”, identificados pelas partes a exibir: [yMMMd] (ano, mês abreviado, dia), [yMMMMEEEEd] (mais o dia da semana por extenso), [Hms] (horas, minutos, segundos)... Também é possível especificar um padrão: ['MM/dd/yyyy HH:mm']. O segundo parâmetro é o idioma;
  • linhas 27–29: formatadores de números: valores monetários, inteiros, porcentagens;
  • linhas 40–42: os nomes dos dias e dos meses de cada idioma não são carregados por padrão: [initializeDateFormatting] os carrega, antes de [runApp]. [main] pode ser assíncrona;
  • linhas 65–83: a tabela: uma lista de records posicionais [(code, value)], sem nomes de campos;
  • linhas 93–111: [Table] desenha uma tabela simples. [columnWidths]: a primeira coluna ocupa 55% da largura; [border]: linhas entre as linhas da tabela. [for (final (code, value) in rows)] decompõe cada record;
  • linha 124: percorrer as entradas de um [Map]: [:key] é um atalho para [key: key];
  • linha 127: a função personalizada.

Para datas, números e valores monetários, [intl] tem a mesma finalidade que a API [Intl] dos navegadores web: ele entende as convenções de cada idioma (separadores, nomes dos meses, ordem dos componentes). A tabela usa as convenções do inglês dos EUA (€1,234.50, “month day, year”); observe que, em francês, um espaço fino não separável separa os milhares (1 234,50 €), e a ordem é “dia mês ano” (a linha [frenchDay]).