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.
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 |
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.
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).
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.
Cada linha da tabela mostra um trecho de código e o que ele exibe.
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]).