Skip to content

4. Widgets

Escrever seus próprios widgets está no cerne do trabalho com o [Flutter]: uma tela bem escrita é composta de pequenos widgets, cada um com seus parâmetros, seu [build] e, se necessário, seu estado. Este capítulo mostra como eles se comunicam entre si (parâmetros, funções), como são montados (composição), como funcionam (ciclo de vida), como compartilham dados sem repassá-los de um a outro (dados herdados) e como reutilizar comportamento.

4.1. Exemplo 10: widgets e seus parâmetros

4.1.1. Tipo de dados

O pai e o filho compartilham uma classe, definida em seu próprio arquivo:

// o tipo de dado compartilhado pelo pai (DoctorsPage) e pelo filho (DoctorCard)
class Doctor {
  final int id;
  final String title;
  final String firstName;
  final String lastName;
  final String specialty;
  final bool available;

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

  // uma cópia na qual apenas a disponibilidade muda
  Doctor withAvailability(bool d) =>
      Doctor(id: id, title: title, firstName: firstName, lastName: lastName, specialty: specialty, available: d);
}
  • linhas 10–16: um construtor com parâmetros nomeados, todos obrigatórios: [Doctor(id: 1, title: 'Mme', ...)]. Parâmetros nomeados tornam a chamada legível, e sua ordem não importa;
  • linhas 20–21: uma cópia em que apenas a disponibilidade muda (o próprio objeto nunca muda).

4.1.2. O filho

// =========================================================================
// lib/ex10_widget_parameters/doctor_card.dart - um widget FILHO
// -------------------------------------------------------------------------
// Ele recebe seus dados do pai por meio dos PARÂMETROS do seu
// construtor, guardados em campos final. Seu tipo é verificado em
// tempo de compilação: DoctorCard(doctor: 42) seria recusado.
//   - required: o pai DEVE fornecer este parâmetro;
//   - this.compact = false: um parâmetro opcional, com seu valor padrão.
//
// Regra de ouro: um widget NUNCA MODIFICA seus parâmetros (eles são final).
// Os dados descem do pai para o filho; para pedir uma
// alteração, o filho chama uma função que o pai lhe passou
// (veja o exemplo 11). Quando o pai altera seus dados, ele RECONSTRÓI seus
// filhos com novos parâmetros.
// =========================================================================

import 'package:flutter/material.dart';

import 'doctor.dart';

// o "estilo" do card: constantes PRIVADAS deste arquivo (o "_").
// Nenhum outro widget pode vê-las, nem ser incomodado por elas
const _initialsColor = Color(0xFF087EA4);
const _initialsStyle = TextStyle(color: Colors.white, fontWeight: FontWeight.bold);

class DoctorCard extends StatelessWidget {
  final Doctor doctor;
  final int rank;
  final bool compact;

  // const: se todos os parâmetros são constantes, o widget também é
  // (o Flutter então nem precisa reconstruí-lo)
  const DoctorCard({super.key, required this.doctor, required this.rank, this.compact = false});

  @override
  Widget build(BuildContext context) {
    // um valor calculado a partir dos parâmetros
    final initials = '${doctor.firstName[0]}${doctor.lastName[0]}';

    return Card(
      // uma borda verde para um médico disponível
      shape: RoundedRectangleBorder(
        borderRadius: BorderRadius.circular(12),
        side: doctor.available ? const BorderSide(color: Colors.green, width: 2) : BorderSide.none,
      ),
      child: Padding(
        padding: const EdgeInsets.all(12),
        child: Row(
          children: [
            CircleAvatar(
              backgroundColor: _initialsColor,
              child: Text(initials, style: _initialsStyle),
            ),
            const SizedBox(width: 12),
            // Expanded: o texto ocupa toda a largura restante
            Expanded(
              child: Column(
                crossAxisAlignment: CrossAxisAlignment.start,
                children: [
                  Text(
                    '$rank. ${doctor.title} ${doctor.firstName} ${doctor.lastName}',
                    style: Theme.of(context).textTheme.titleMedium,
                  ),
                  if (!compact) Text(doctor.specialty, style: const TextStyle(color: Colors.grey)),
                ],
              ),
            ),
          ],
        ),
      ),
    );
  }
}
  • linhas 23–24: o “estilo” do card: constantes privadas a este arquivo (o “_”). Nenhum outro arquivo pode vê-las nem ser afetado por elas. É o equivalente, no [Flutter], dos “módulos CSS” do [React]: não há folha de estilo global; o estilo de um widget fica embutido em seu código;
  • linhas 27–29: os parâmetros do widget, guardados em campos [final];
  • linha 33: o construtor. [required this.doctor]: um parâmetro obrigatório, guardado diretamente no campo; [this.compact = false]: um parâmetro opcional, com seu valor padrão. O construtor é [const]: se todos os argumentos forem constantes, o card também será constante;
  • linha 38: um valor calculado a partir dos parâmetros;
  • linhas 42–44: a forma do card ([Card]): cantos arredondados e uma borda verde se o médico estiver disponível ([BorderSide.none] caso contrário);
  • linhas 50–52: um disco colorido com as iniciais;
  • linha 64: a especialidade só é exibida na visualização não compacta.

Regra de ouro: um widget nunca modifica seus próprios parâmetros (eles são [final]; aliás, o compilador proíbe isso). Os dados fluem do pai para o filho; para solicitar uma mudança, o filho chama uma função que o pai lhe passou (exemplo 11). Quando o pai muda seus dados, ele reconstrói seus filhos com novos parâmetros.

4.1.3. O pai

// =========================================================================
// lib/ex10_widget_parameters/main.dart - o widget PAI
// -------------------------------------------------------------------------
// Ele importa o widget DoctorCard e o usa, quantas vezes for
// necessário, como qualquer widget do Flutter: um widget é um pedaço
// de interface REUTILIZÁVEL, com seus próprios parâmetros, seu build() e
// seu estilo. Escrever seus próprios widgets é o coração do trabalho com o
// Flutter: uma tela bem escrita é feita de pequenos widgets.
// =========================================================================

import 'package:flutter/material.dart';

import 'doctor_card.dart';
import 'doctor.dart';

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> {
  List<Doctor> _doctors = const [
    Doctor(id: 1, title: 'Mme', firstName: 'Marie', lastName: 'PELISSIER', specialty: 'general practitioner', available: true),
    Doctor(id: 2, title: 'Mr', firstName: 'Paul', lastName: 'TATOU', specialty: 'pediatrician', available: false),
    Doctor(id: 3, title: 'Melle', firstName: 'Sophie', lastName: 'DUPONT', specialty: 'general practitioner', available: true),
  ];
  bool _compact = false;

  // o pai altera SEUS dados: o Flutter chama seu build() de novo, que
  // reconstrói os filhos com seus novos parâmetros
  void _toggleAvailability() {
    setState(() {
      _doctors = [for (final m in _doctors) m.withAvailability(!m.available)];
    });
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Example 10 - the widgets and their parameters')),
      body: ListView(
        padding: const EdgeInsets.all(16),
        children: [
          SwitchListTile(
            contentPadding: EdgeInsets.zero,
            title: const Text('compact display'),
            value: _compact,
            onChanged: (v) => setState(() => _compact = v),
          ),
          Align(
            alignment: Alignment.centerLeft,
            child: OutlinedButton(onPressed: _toggleAvailability, child: const Text('Toggle the availabilities')),
          ),
          const SizedBox(height: 8),
          for (final (i, m) in _doctors.indexed)
            // cada card recebe SEUS parâmetros
            DoctorCard(key: ValueKey(m.id), doctor: m, rank: i + 1, compact: _compact),
          const SizedBox(height: 16),
          const Text(
            'The same card, in its compact version, by setting the parameter:',
            style: TextStyle(color: Colors.grey),
          ),
          SizedBox(width: 260, child: DoctorCard(doctor: _doctors[0], rank: 1, compact: true)),
        ],
      ),
    );
  }
}
  • linhas 34–39: o estado do pai: a lista de médicos (uma lista constante, que será substituída por outra) e a exibição compacta;
  • linhas 43–45: o pai altera SEUS dados para uma nova lista formada por cópias dos médicos. [Flutter] chama seu [build], que reconstrói os cards com seus novos parâmetros;
  • linha 69: um card por médico, com SEUS parâmetros. O widget [DoctorCard] é usado exatamente como um widget do [Flutter];
  • linha 75: o mesmo card, em versão compacta, em uma caixa de 260 pontos de largura.

Inicialmente, depois na visualização compacta, a disponibilidade é invertida:

Um método que cria widgets (como [_line] do exemplo 02) ou um widget de verdade ([DoctorCard])? O widget de verdade é quase sempre preferível: ele tem um nome, seus parâmetros são tipados e documentados, pode ser reutilizado em outro lugar e o [Flutter] pode evitar reconstruí-lo (se ele for [const], ou se seus parâmetros não mudaram).

4.2. Exemplo 11: o filho notifica o pai

Os dados descem por parâmetros; as informações sobem de volta por funções passadas como parâmetros.

4.2.1. “Eventos” do filho

// =========================================================================
// lib/ex11_lifting_state_up/counter.dart
// -------------------------------------------------------------------------
// Um filho que NOTIFICA seu pai: o pai lhe passa FUNÇÕES como
// parâmetros (por convenção, seus nomes começam com "on"), e o filho
// as chama quando algo acontece:
//     Counter(label: 'Coffees', max: 3, onIncrement: ..., onLimit: ...)
// Os tipos dessas funções têm nomes prontos no Flutter:
//   - ValueChanged<int> : uma função que recebe um int e não retorna nada;
//   - VoidCallback      : uma função sem parâmetros, que não retorna nada.
// =========================================================================

import 'package:flutter/material.dart';

class Counter extends StatefulWidget {
  final String label;
  final int max;
  final ValueChanged<int> onIncrement; // com o novo valor
  final VoidCallback onLimit; // sem dados

  const Counter({
    super.key,
    required this.label,
    required this.max,
    required this.onIncrement,
    required this.onLimit,
  });

  @override
  State<Counter> createState() => _CounterState();
}

class _CounterState extends State<Counter> {
  // o estado ESPECÍFICO deste contador: cada Counter tem o seu
  int _value = 0;

  void _plus() {
    // widget: no objeto State, dá acesso aos parâmetros do widget
    if (_value >= widget.max) {
      widget.onLimit();
      return;
    }
    setState(() => _value++);
    // o pai é NOTIFICADO e recebe o novo valor
    widget.onIncrement(_value);
  }

  @override
  Widget build(BuildContext context) {
    return Row(
      children: [
        SizedBox(width: 110, child: Text(widget.label)),
        OutlinedButton(onPressed: _plus, child: const Text('+1')),
        const SizedBox(width: 12),
        Chip(label: Text('$_value / ${widget.max}')),
      ],
    );
  }
}
  • linhas 18–19: dois parâmetros que são funções, as quais o contador chamará. [ValueChanged<int>] é o tipo de uma função que recebe um [int] e não devolve nada; [VoidCallback] é o tipo de uma função sem parâmetros. Por convenção, seus nomes começam com “on”, como [onPressed] ou [onChanged] nos widgets do [Flutter];
  • linha 35: o estado ESPECÍFICO deste contador: cada [Counter] tem o seu;
  • linhas 37–45: dentro do objeto [State], [widget] dá acesso aos parâmetros do widget: [widget.max], [widget.onLimit]... Se o máximo for ultrapassado, o contador notifica seu pai ([widget.onLimit()]); caso contrário, altera seu estado e depois notifica o pai transmitindo o novo valor. Ao contrário do [React], o estado é atualizado imediatamente: [_value] já tem seu novo valor quando ele é transmitido.

4.2.2. Um widget controlado

// =========================================================================
// lib/ex11_lifting_state_up/labeled_text_field.dart - um widget CONTROLADO
// -------------------------------------------------------------------------
// Um campo de formulário "caseiro" (rótulo + campo + ajuda + contador de
// caracteres) que é usado como um campo controlado:
//     LabeledTextField(value: _name, onChanged: (v) => setState(() => _name = v), ...)
// O valor pertence ao PAI, que o passa (value) e que é
// notificado a cada tecla (onChanged). Quem decide é o pai.
//
// Uma dificuldade específica do Flutter: um TextField guarda seu texto em um
// controller, que precisa sobreviver às reconstruções. O widget portanto tem um
// estado (o controller)... que ele deve manter ATUALIZADO quando o pai altera
// o valor (botão "Clear"): esse é o papel de didUpdateWidget.
// =========================================================================

import 'package:flutter/material.dart';

class LabeledTextField extends StatefulWidget {
  final String value;
  final ValueChanged<String> onChanged;
  final String label;
  final int max;
  final String help;

  const LabeledTextField({
    super.key,
    required this.value,
    required this.onChanged,
    required this.label,
    required this.max,
    this.help = '',
  });

  @override
  State<LabeledTextField> createState() => _LabeledTextFieldState();
}

class _LabeledTextFieldState extends State<LabeledTextField> {
  // late: o campo será inicializado mais tarde (em initState), antes de qualquer uso
  late final TextEditingController _controller;

  @override
  void initState() {
    super.initState();
    _controller = TextEditingController(text: widget.value);
  }

  // chamado quando o PAI reconstrói este widget com novos parâmetros;
  // oldWidget: o widget anterior, para comparar
  @override
  void didUpdateWidget(LabeledTextField oldWidget) {
    super.didUpdateWidget(oldWidget);
    if (widget.value != _controller.text) {
      _controller.text = widget.value; // o pai alterou o valor por conta própria
    }
  }

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

  @override
  Widget build(BuildContext context) {
    final full = widget.value.length == widget.max;
    return TextField(
      controller: _controller,
      maxLength: widget.max, // o campo recusa os caracteres excedentes
      decoration: InputDecoration(
        labelText: widget.label,
        helperText: widget.help,
        // a borda fica vermelha quando o campo está cheio
        errorText: full ? 'Maximum length reached' : null,
      ),
      onChanged: widget.onChanged, // a função do pai, passada como está
    );
  }
}

Um campo de formulário “personalizado” (rótulo + campo + tooltip + contador de caracteres) que funciona como um campo controlado: o valor pertence ao pai, que o passa ao campo ([value]) e é notificado a cada tecla digitada ([onChanged]).

  • Linha 40: [late]: este campo será inicializado mais tarde (em [initState]), mas antes de ser usado. O [Dart] verifica isso em tempo de execução;
  • Linhas 43–45: o controller começa com o valor do pai;
  • linhas 51–54: este é o desafio específico do [Flutter]: um [TextField] guarda seu texto em um controller, que deve sobreviver às reconstruções da página. O widget, portanto, tem um estado (o controller)... que ele deve manter atualizado quando o próprio pai altera o valor (botão Limpar). [didUpdateWidget] é chamado toda vez que o pai reconstrói este widget com novos parâmetros; ele recebe o widget antigo para comparação. Se o valor do pai for diferente do texto do campo, ele é copiado;
  • linha 69: o campo rejeita os caracteres excedentes e exibe um contador (“12/20”);
  • linha 72: uma tooltip aparece abaixo do campo;
  • linha 74: a borda fica vermelha quando o campo está cheio;
  • linha 76: a função do pai, passada como está ao [TextField].

4.2.3. O pai

// =========================================================================
// lib/ex11_lifting_state_up/main.dart - o pai escuta seus filhos
// -------------------------------------------------------------------------
// Os dados descem (parâmetros); a informação sobe por meio de
// funções passadas como parâmetros:
//   1. "eventos" do filho: onIncrement, onLimit;
//   2. um widget controlado: value + onChanged, como um Checkbox. O estado
//      continua sendo propriedade do pai, que pode modificá-lo por conta própria (Clear).
// =========================================================================

import 'package:flutter/material.dart';

import 'labeled_text_field.dart';
import 'counter.dart';

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

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

  @override
  State<ParentPage> createState() => _ParentPageState();
}

class _ParentPageState extends State<ParentPage> {
  int _total = 0;
  String _message = '';
  String _firstName = 'Marie';
  String _lastName = 'PELISSIER';

  // a função chamada por um contador: ela recebe o valor que o contador passa
  void _onIncrement(String label, int value) {
    setState(() {
      _total++;
      _message = '$label is now $value';
    });
  }

  void _clear() {
    setState(() {
      _firstName = '';
      _lastName = '';
    });
  }

  @override
  Widget build(BuildContext context) {
    final titleStyle = Theme.of(context).textTheme.titleSmall;
    return Scaffold(
      appBar: AppBar(title: const Text('Example 11 - the child notifies its parent')),
      body: ListView(
        padding: const EdgeInsets.all(16),
        children: [
          Card(
            child: Padding(
              padding: const EdgeInsets.all(12),
              child: Column(
                crossAxisAlignment: CrossAxisAlignment.start,
                children: [
                  Text('1. Functions called by the children', style: titleStyle),
                  Counter(
                    label: 'Coffees',
                    max: 3,
                    onIncrement: (v) => _onIncrement('Coffees', v),
                    onLimit: () => setState(() => _message = 'No more than 3 coffees!'),
                  ),
                  Counter(
                    label: 'Glasses of water',
                    max: 8,
                    onIncrement: (v) => _onIncrement('Glasses of water', v),
                    onLimit: () => setState(() => _message = 'Enough drinking.'),
                  ),
                  const SizedBox(height: 8),
                  Text('Total of the clicks: $_total - $_message', style: const TextStyle(fontStyle: FontStyle.italic)),
                ],
              ),
            ),
          ),
          Card(
            child: Padding(
              padding: const EdgeInsets.all(12),
              child: Column(
                crossAxisAlignment: CrossAxisAlignment.start,
                children: [
                  Text('2. Controlled widgets', style: titleStyle),
                  LabeledTextField(
                    value: _firstName,
                    onChanged: (v) => setState(() => _firstName = v),
                    label: 'First name',
                    max: 20,
                    help: 'Required',
                  ),
                  LabeledTextField(
                    value: _lastName,
                    onChanged: (v) => setState(() => _lastName = v),
                    label: 'Last name',
                    max: 20,
                    help: 'Upper-cased when displayed',
                  ),
                  const SizedBox(height: 8),
                  Text.rich(
                    TextSpan(
                      children: [
                        const TextSpan(text: "Parent's data: "),
                        TextSpan(
                          text: '$_firstName ${_lastName.toUpperCase()}',
                          style: const TextStyle(fontWeight: FontWeight.bold),
                        ),
                      ],
                    ),
                  ),
                  const SizedBox(height: 8),
                  OutlinedButton(onPressed: _clear, child: const Text('Clear (from the parent)')),
                ],
              ),
            ),
          ),
        ],
      ),
    );
  }
}
  • linhas 40–43: a função chamada por um contador; ela recebe o valor passado pelo contador;
  • linhas 69–73: um contador e as funções que ele chamará. [(v) => _onIncrement('Coffees', v)]: uma função anônima que soma seu próprio argumento (o rótulo);
  • linhas 94–99: um campo controlado: seu valor e a função que altera o estado do pai;
  • linha 114: os dados do pai, que acompanham o que é digitado;
  • linha 121: o pai altera o valor por conta própria: os campos são limpos (por meio de seu [didUpdateWidget]).

Pressione o primeiro contador quatro vezes, o segundo uma vez e digite o nome; depois limpe os campos a partir do pai:

4.3. Exemplo 12: composição

4.3.1. Um card

Os parâmetros de um widget transmitem dados… mas também conteúdo: um widget é um valor como outro qualquer, que pode ser passado a outro widget. O [Flutter] usa isso em toda parte: o [child] de um [Padding], o [title] de um [AppBar], o [body] de um [Scaffold].

// =========================================================================
// lib/ex12_composition/info_card.dart - um TEMPLATE reutilizável
// -------------------------------------------------------------------------
// Os parâmetros de um widget passam DADOS... mas também
// CONTEÚDO: um widget é um valor como outro qualquer, que pode ser passado a
// outro widget, que o coloca onde quiser. O Flutter usa isso em todo lugar:
// o filho de um Padding, o título de uma AppBar, o corpo de um Scaffold...
//   - child: por convenção, o conteúdo "principal";
//   - header, footer: outros lugares (alguns "slots"), fornecidos pelo
//     pai; o header tem um conteúdo padrão, o footer é opcional.
// O card define a moldura (borda, cabeçalho, rodapé), o pai fornece o que
// vai dentro.
// =========================================================================

import 'package:flutter/material.dart';

class InfoCard extends StatelessWidget {
  final Color? color; // "?": opcional (null por padrão)
  final Widget header;
  final Widget? footer;
  final Widget child;

  const InfoCard({super.key, this.color, this.header = const Text('Untitled'), this.footer, required this.child});

  @override
  Widget build(BuildContext context) {
    final background = color ?? Colors.grey.shade300;
    return Card(
      // clipBehavior: o cabeçalho colorido acompanha os cantos arredondados do card
      clipBehavior: Clip.antiAlias,
      shape: RoundedRectangleBorder(
        borderRadius: BorderRadius.circular(8),
        side: BorderSide(color: background),
      ),
      child: Column(
        crossAxisAlignment: CrossAxisAlignment.stretch,
        children: [
          Container(
            color: background,
            padding: const EdgeInsets.all(10),
            // DefaultTextStyle: o estilo de TODOS os textos do cabeçalho,
            // seja qual for o widget fornecido pelo pai
            child: DefaultTextStyle.merge(
              style: TextStyle(color: color == null ? Colors.black : Colors.white, fontWeight: FontWeight.bold),
              child: header,
            ),
          ),
          Padding(padding: const EdgeInsets.all(10), child: child),
          // nenhum rodapé fornecido: nenhum rodapé
          if (footer != null)
            Container(
              color: Colors.grey.shade100,
              padding: const EdgeInsets.all(8),
              child: DefaultTextStyle.merge(
                style: const TextStyle(color: Colors.grey, fontSize: 12),
                child: footer!,
              ),
            ),
        ],
      ),
    );
  }
}
  • linhas 18–21: parâmetros: uma cor opcional ([Color?]) e três slots para conteúdo: [header], [footer] (opcional), e [child], o conteúdo principal;
  • linha 23: o cabeçalho tem um conteúdo padrão: um widget constante;
  • linha 27: a cor do cabeçalho: a fornecida ou cinza-claro;
  • linha 30: o cabeçalho colorido é recortado para acompanhar os cantos arredondados do card;
  • linhas 43–45: [DefaultTextStyle] define o estilo de TODO o texto de sua subárvore, qualquer que seja o widget fornecido pelo pai: o cabeçalho é em negrito, branco sobre um fundo colorido;
  • linha 48: o conteúdo principal, fornecido pelo pai;
  • linhas 50–58: nenhum rodapé fornecido; nenhum rodapé. [footer!]: neste ramo, [footer] não é [null] (o compilador não consegue inferir isso para um campo, daí o [!]).

4.3.2. Uma tabela genérica

// =========================================================================
// lib/ex12_composition/simple_table.dart - uma tabela GENÉRICA
// -------------------------------------------------------------------------
// SimpleTable<T> é um widget genérico: ele exibe linhas de qualquer
// tipo T. Sabe percorrer as linhas, mas não como exibir UMA
// linha: o pai lhe diz, passando-lhe uma FUNÇÃO,
// cells(row, index), que retorna os widgets das células.
// É o princípio dos "builders" do Flutter (ListView.builder,
// FutureBuilder...): o conteúdo fornecido pelo pai usa dados
// que pertencem ao filho (a linha, sua posição).
// =========================================================================

import 'package:flutter/material.dart';

// o tipo de uma função que constrói as células de uma linha
typedef CellsBuilder<T> = List<Widget> Function(T row, int index);

class SimpleTable<T> extends StatelessWidget {
  final List<T> rows;
  final List<String> columns;
  final CellsBuilder<T> cells;
  final Widget empty; // exibido quando não há nenhuma linha

  const SimpleTable({
    super.key,
    required this.rows,
    required this.columns,
    required this.cells,
    this.empty = const Text('No data.'),
  });

  // uma célula: uma pequena margem ao redor do seu conteúdo
  static Widget _cell(Widget content) => Padding(padding: const EdgeInsets.all(6), child: content);

  @override
  Widget build(BuildContext context) {
    if (rows.isEmpty) {
      return Column(
        crossAxisAlignment: CrossAxisAlignment.start,
        children: [
          Text(columns.join('   '), style: const TextStyle(fontWeight: FontWeight.bold)),
          const Divider(),
          DefaultTextStyle.merge(
            style: const TextStyle(color: Colors.grey),
            child: empty,
          ),
        ],
      );
    }
    return Table(
      defaultVerticalAlignment: TableCellVerticalAlignment.middle,
      border: TableBorder(horizontalInside: BorderSide(color: Colors.grey.shade300)),
      children: [
        TableRow(
          children: [for (final c in columns) _cell(Text(c, style: const TextStyle(fontWeight: FontWeight.bold)))],
        ),
        for (final (i, row) in rows.indexed)
          // as células DESTA linha, construídas pela função do pai
          TableRow(children: [for (final c in cells(row, i)) _cell(c)]),
      ],
    );
  }
}
  • linha 16: o tipo de uma função que recebe uma linha (do tipo [T]) e seu índice, e devolve os widgets de suas células;
  • linha 18: um widget genérico: ele exibe linhas de qualquer tipo ([T]). Ele sabe percorrer as linhas, mas não sabe exibir UMA linha; o pai lhe diz como, passando-lhe a função [cells]. Este é o princípio dos “builders” do [Flutter] ([ListView.builder], [FutureBuilder]...): o conteúdo é fornecido pelo pai, mas usa dados que pertencem ao filho (a linha, seu índice). O [React] chama isso de “render prop”;
  • linha 33: um método [static], que não usa nenhum campo do widget;
  • linhas 37–45: nenhuma linha: os cabeçalhos das colunas e o conteúdo [empty], fornecido pelo pai;
  • linhas 50–59: a tabela: uma linha de cabeçalhos, seguida de uma linha para cada item, cujas células são geradas pela função do pai.

4.3.3. O pai

// =========================================================================
// lib/ex12_composition/main.dart - usando os templates InfoCard e SimpleTable
// =========================================================================

import 'package:flutter/material.dart';

import 'info_card.dart';
import 'simple_table.dart';

// um slot: um record nomeado (sem precisar escrever uma classe)
typedef Slot = ({int id, String timeRange, String? patient});

const slots = <Slot>[
  (id: 1, timeRange: '8:00 - 8:20', patient: null),
  (id: 2, timeRange: '8:20 - 8:40', patient: 'Mme Alice DURAND'),
  (id: 3, timeRange: '8:40 - 9:00', patient: null),
];

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

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

  @override
  Widget build(BuildContext context) {
    final free = slots.where((c) => c.patient == null).length;

    return Scaffold(
      appBar: AppBar(title: const Text('Example 12 - the composition')),
      body: ListView(
        padding: const EdgeInsets.all(16),
        children: [
          // header e footer: widgets passados como parâmetros; child: o conteúdo
          InfoCard(
            color: Colors.indigo,
            header: const Row(
              children: [
                Icon(Icons.event, color: Colors.white),
                SizedBox(width: 8),
                // Expanded: o texto ocupa o espaço restante (e quebra linha)
                Expanded(child: Text('Schedule of Mme PELISSIER')),
              ],
            ),
            footer: Text('$free free slot(s)'),
            // SimpleTable<Slot>: T é inferido a partir do tipo das linhas
            child: SimpleTable(
              rows: slots,
              columns: const ['#', 'Slot', 'Status'],
              // a função que constrói as células de UMA linha;
              // c recebe a linha, i sua posição
              cells: (c, i) => [
                Text('${i + 1}'),
                Text(c.timeRange),
                c.patient != null
                    ? Chip(label: Text(c.patient!), visualDensity: VisualDensity.compact)
                    : Chip(
                        label: const Text('Free'),
                        backgroundColor: Colors.green.shade100,
                        visualDensity: VisualDensity.compact,
                      ),
              ],
            ),
          ),
          const InfoCard(
            color: Colors.green,
            header: Text('A card without a footer'),
            child: Text('The footer is not provided: the card does not display it.'),
          ),
          // nenhum cabeçalho fornecido: o conteúdo padrão, "Untitled"
          InfoCard(
            child: SimpleTable<({int id, String name})>(
              rows: const [],
              columns: const ['Name'],
              cells: (p, _) => [Text(p.name)],
              empty: const Text('Nobody for now.'),
            ),
          ),
        ],
      ),
    );
  }
}
  • linha 11: um slot, na forma de um record nomeado;
  • linhas 42–52: um card: sua cor, um cabeçalho (uma linha: um ícone e um texto), um rodapé;
  • linhas 54–66: seu conteúdo: uma tabela de slots. [T] é derivado do tipo de [rows]: é um [SimpleTable<Slot>]. A função [cells] recebe um horário ([c]) e seu índice ([i]) e devolve três widgets;
  • linhas 72–75: um card sem rodapé;
  • linhas 79–83: um card sem cabeçalho (o conteúdo padrão, “Untitled”); sua tabela está vazia. [SimpleTable<({int id, String name})>]: o tipo [T] é especificado explicitamente, porque [rows: const []] não permite inferi-lo.

Image

O card define a moldura (borda, cabeçalho, rodapé); o pai fornece o conteúdo que fica dentro dela. É assim que os próprios widgets do [Flutter] são construídos: [Scaffold] define a estrutura de uma tela e recebe a barra superior, o corpo e o botão flutuante.

4.4. Exemplo 13: o ciclo de vida de um widget

4.4.1. Um relógio

// =========================================================================
// lib/ex13_lifecycle/clock.dart - um widget que inicia e para
// -------------------------------------------------------------------------
// A vida do objeto State de um StatefulWidget:
//   1. initState()              : ele acabou de ser criado, o widget está prestes a
//                                 aparecer. O que deve ser iniciado é iniciado aqui;
//   2. didChangeDependencies()  : logo depois, e depois a cada vez que um dado herdado
//                                 que ele lê muda (veja o exemplo 14);
//   3. build()                  : quantas vezes for necessário;
//   4. didUpdateWidget(old)     : o pai o reconstruiu com novos
//                                 parâmetros;
//   5. dispose()                : o widget desaparece de vez. O que
//                                 foi iniciado é PARADO aqui.
// Um relógio dispara um timer (Timer.periodic) quando aparece...
// e deve obrigatoriamente pará-lo quando desaparece: senão o
// timer continuaria rodando à toa e chamaria setState()
// em um objeto morto (um erro).
// =========================================================================

import 'dart:async';

import 'package:flutter/material.dart';

String currentTime() => DateTime.now().toString().substring(11, 19); // "12:05:09"

class Clock extends StatefulWidget {
  final ValueChanged<String> onLog;
  final Color color;

  const Clock({super.key, required this.onLog, this.color = Colors.indigo});

  @override
  State<Clock> createState() => _ClockState();
}

class _ClockState extends State<Clock> {
  String _time = currentTime();
  // late: inicializado em initState
  late final Timer _timer;

  // notificando o pai... DEPOIS da construção da tela atual: não
  // modificamos o estado de um widget (o pai) enquanto ele está sendo construído
  void _log(String message) {
    WidgetsBinding.instance.addPostFrameCallback((_) => widget.onLog(message));
  }

  @override
  void initState() {
    super.initState(); // sempre primeiro
    _log('Clock: initState - starting the timer');
    _timer = Timer.periodic(const Duration(seconds: 1), (_) {
      setState(() => _time = currentTime());
    });
  }

  @override
  void didUpdateWidget(Clock oldWidget) {
    super.didUpdateWidget(oldWidget);
    if (oldWidget.color != widget.color) {
      _log('Clock: didUpdateWidget - new color');
    }
  }

  @override
  void dispose() {
    _timer.cancel(); // a LIMPEZA
    _log('Clock: dispose - timer stopped');
    super.dispose(); // sempre por último
  }

  @override
  Widget build(BuildContext context) {
    return Text(
      _time,
      style: TextStyle(fontSize: 40, fontFamily: 'RobotoMono', color: widget.color),
    );
  }
}

O ciclo de vida do objeto [State] dentro de um [StatefulWidget]:

Método
Quando?
initState()
O objeto acabou de ser criado; o widget vai aparecer. É aqui que se inicia tudo o que precisa ser iniciado (timer, assinatura etc.)
didChangeDependencies()
Logo após initState e, depois, sempre que qualquer dado herdado que ele leia mudar (veja o exemplo 14)
build()
quantas vezes for necessário
didUpdateWidget(old)
o pai o reconstruiu com novos parâmetros
dispose()
o widget desaparece definitivamente. Tudo o que foi iniciado ali é interrompido
  • linhas 37–39: o estado: a hora exibida e um timer ([Timer], da biblioteca [dart:async]);
  • linhas 43–44: o relógio notifica seu pai a cada etapa de seu ciclo de vida. Mas ele o faz durante [initState] ou [dispose] — ou seja, enquanto o [Flutter] está construindo a tela: o pai não pode modificar seu estado nesse momento ([setState] causaria um erro). [addPostFrameCallback] adia a chamada para depois que o quadro atual terminar de ser renderizado;
  • linhas 48–52: [super.initState()] primeiro, sempre. Em seguida, um timer periódico é iniciado: sua função é chamada a cada segundo e atualiza a hora;
  • linhas 57–60: o pai redesenhou o relógio com outra cor: isso é registrado;
  • linhas 65–68: limpeza: interrompemos o timer. Caso contrário, ele continuaria a executar inutilmente e chamaria [setState] em um objeto morto, resultando em um erro (“setState() called after dispose()”) e em um vazamento de memória. [super.dispose()] vem sempre por último.

4.4.2. O pai

// =========================================================================
// lib/ex13_lifecycle/main.dart
// -------------------------------------------------------------------------
//   - if (_withClock) Clock(...): marcar / desmarcar a caixa faz
//     o widget aparecer / desaparecer (initState, depois dispose, veja
//     clock.dart); mudar sua cor o reconstrói (didUpdateWidget);
//   - autofocus: um campo de entrada que recebe o foco assim que aparece
//     (o teclado do celular abre);
//   - o título do aplicativo acompanha a entrada (widget Title);
//   - AppLifecycleListener: a vida do próprio APLICATIVO. Em um
//     celular, ele vai para segundo plano (outro aplicativo é aberto,
//     a tela se apaga), depois volta: podemos reagir a isso (salvar,
//     parar um timer...).
// =========================================================================

import 'package:flutter/material.dart';

import 'clock.dart';

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

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

  @override
  State<LifecyclePage> createState() => _LifecyclePageState();
}

class _LifecyclePageState extends State<LifecyclePage> {
  bool _withClock = true;
  bool _red = false;
  final List<String> _log = [];
  String _search = '';
  bool _showSearch = false;
  late final AppLifecycleListener _listener;

  void _trace(String message) {
    // o relógio pode notificar DEPOIS que a tela desapareceu (fechamento do aplicativo)
    if (!mounted) return;
    setState(() => _log.add('${currentTime()} $message'));
  }

  @override
  void initState() {
    super.initState();
    // o aplicativo muda de estado: resumed (em primeiro plano), inactive,
    // hidden, paused (em segundo plano)...
    _listener = AppLifecycleListener(onStateChange: (state) => _trace('Application: ${state.name}'));
  }

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

  @override
  Widget build(BuildContext context) {
    return Title(
      title: _search.isEmpty ? 'Example 13' : 'Search: $_search',
      color: Colors.indigo,
      child: Scaffold(
        appBar: AppBar(title: const Text('Example 13 - the lifecycle')),
        body: ListView(
          padding: const EdgeInsets.all(16),
          children: [
            Card(
              child: Padding(
                padding: const EdgeInsets.all(12),
                child: Column(
                  crossAxisAlignment: CrossAxisAlignment.start,
                  children: [
                    CheckboxListTile(
                      contentPadding: EdgeInsets.zero,
                      controlAffinity: ListTileControlAffinity.leading,
                      title: const Text('show the clock'),
                      value: _withClock,
                      onChanged: (v) => setState(() => _withClock = v!),
                    ),
                    CheckboxListTile(
                      contentPadding: EdgeInsets.zero,
                      controlAffinity: ListTileControlAffinity.leading,
                      title: const Text('in red'),
                      value: _red,
                      onChanged: (v) => setState(() => _red = v!),
                    ),
                    if (_withClock) Clock(onLog: _trace, color: _red ? Colors.red : Colors.indigo),
                  ],
                ),
              ),
            ),
            Card(
              child: Padding(
                padding: const EdgeInsets.all(12),
                child: !_showSearch
                    ? Align(
                        alignment: Alignment.centerLeft,
                        child: OutlinedButton(
                          onPressed: () => setState(() => _showSearch = true),
                          child: const Text('Search...'),
                        ),
                      )
                    // autofocus: o foco assim que o campo aparece
                    : TextField(
                        autofocus: true,
                        decoration: const InputDecoration(hintText: 'the title follows the input'),
                        onChanged: (v) => setState(() => _search = v),
                      ),
              ),
            ),
            Text('Log', style: Theme.of(context).textTheme.titleSmall),
            for (final (i, line) in _log.indexed) Text('${i + 1}. $line', style: const TextStyle(fontSize: 12)),
          ],
        ),
      ),
    );
  }
}
  • linhas 56–61: a vida do próprio aplicativo. Em um celular, ele vai para segundo plano (você abre outro aplicativo, a tela se apaga) e depois volta: [AppLifecycleListener] notifica cada mudança ([resumed]: em primeiro plano; [inactive], [hidden], [paused]: passagem para segundo plano...). Você responderia a essas notificações para salvar um rascunho ou interromper um timer. O listener é criado em [initState] e liberado em [dispose]: o mesmo padrão do timer do relógio;
  • linha 95: marcar a caixa exibe o relógio ([initState]); desmarcá-la o oculta ([dispose]); mudar sua cor o redesenha ([didUpdateWidget]);
  • linhas 112–115: um campo que só aparece depois de tocar em “Search...”. [autofocus: true]: ele ganha o foco assim que aparece, e o teclado do celular se abre;
  • linha 68: o título do aplicativo é atualizado conforme você digita.

Mudamos a cor, removemos e depois adicionamos de novo o relógio, abrimos a busca e digitamos um nome:

Image

O log mostra a atividade do relógio: início, mudança de cor, parada, início.

Os alunos que fazem o curso de [React] vão compará-lo com [useEffect]: o que o [React] escreve em um efeito e em sua função de limpeza, o [Flutter] distribui entre [initState] e [dispose]; o que o [React] obtém da tabela de dependências de um efeito, o [Flutter] obtém por meio de [didUpdateWidget], comparando o widget antigo com o novo.

4.5. Exemplo 14: dados herdados

Como compartilhar dados e funções entre widgets distantes sem passá-los de parâmetro em parâmetro por todos os intermediários? Com dados herdados, como [InheritedWidget]. Este é o mecanismo que o próprio [Flutter] usa: [Theme.of(context)], [MediaQuery.of(context)], [Navigator.of(context)]... são leituras de dados herdados. O [React] chama isso de contexto; o [Angular] o chamaria de serviço.

4.5.1. Um conjunto de dados para todo o aplicativo

// =========================================================================
// lib/ex14_inherited_data/providers/log.dart - um dado para TODO o aplicativo
// -------------------------------------------------------------------------
// Como compartilhar dados e funções entre widgets
// distantes, sem passá-los de parâmetro em parâmetro por todos os
// intermediários? Com um InheritedWidget, um dado "herdado":
//   1. um widget PROVIDER, colocado no alto da árvore, carrega o dado;
//   2. qualquer descendente, em qualquer profundidade, o LÊ
//      com context.dependOnInheritedWidgetOfExactType<Provider>();
//   3. o descendente que o leu fica então INSCRITO: ele é reconstruído
//      quando o dado muda.
// É o mecanismo que o próprio Flutter usa: Theme.of(context),
// MediaQuery.of(context), Navigator.of(context)... são leituras de
// dados herdados.
//
// InheritedNotifier é uma variante pronta: o dado é um objeto
// que NOTIFICA suas alterações (um ChangeNotifier, que chama
// notifyListeners()), e o provider então reconstrói seus leitores.
// A convenção: um método estático of(context) para ler o dado.
// =========================================================================

import 'package:flutter/material.dart';

// o dado: um ChangeNotifier. notifyListeners() notifica seus inscritos
class Log extends ChangeNotifier {
  final List<String> lines = [];

  void trace(String message) {
    lines.insert(0, '${DateTime.now().toString().substring(11, 19)} $message');
    if (lines.length > 6) lines.removeLast();
    notifyListeners();
  }
}

// o provider: ele carrega o log e reconstrói seus leitores quando
// o log notifica uma alteração
class LogProvider extends InheritedNotifier<Log> {
  const LogProvider({super.key, required Log log, required super.child}) : super(notifier: log);

  // a leitura: o provider MAIS PRÓXIMO acima de context
  static Log of(BuildContext context) {
    final provider = context.dependOnInheritedWidgetOfExactType<LogProvider>();
    if (provider == null) {
      throw FlutterError('LogProvider.of: no LogProvider above this widget');
    }
    return provider.notifier!;
  }
}
  • linhas 25–31: os dados compartilhados: um log. É um [ChangeNotifier], um objeto que notifica seus ouvintes sobre as mudanças: todo método que o modifica chama [notifyListeners()];
  • linhas 37–38: o provider: um widget, situado no alto da árvore, que guarda o log. [InheritedNotifier] é um [InheritedWidget] pronto para um [ChangeNotifier]: quando o log notifica uma mudança, o provider reconstrói todos os widgets que o leram;
  • linhas 41–46: a leitura, por meio de um método estático [of(context)], como o usado pelo [Flutter]. [context.dependOnInheritedWidgetOfExactType<LogProvider>()] percorre a árvore a partir de [context] até o provider mais próximo e inscreve o widget que lê os dados: ele será reconstruído quando os dados mudarem. Se não houver nenhum provider acima dele, trata-se de um erro de programação: isso é sinalizado claramente.

4.5.2. Dados fornecidos por um widget

// =========================================================================
// lib/ex14_inherited_data/providers/cart.dart - um dado fornecido por UM widget
// -------------------------------------------------------------------------
// O carrinho só é fornecido a uma parte da árvore: os widgets
// que CartProvider envolve (veja main.dart). Dois providers colocados em
// dois lugares da tela dariam dois carrinhos independentes.
// O provider aqui é um StatefulWidget: é ele que CRIA o carrinho
// (didChangeDependencies) e o libera (dispose). Ele próprio usa o log.
// =========================================================================

import 'package:flutter/material.dart';

import 'log.dart';

typedef Item = ({String label, double price});

class Cart extends ChangeNotifier {
  final Log _log;
  final List<Item> items = [];

  Cart(this._log);

  // um valor calculado: fold "dobra" a lista em um único valor
  double get total => items.fold(0, (sum, a) => sum + a.price);

  void add(Item item) {
    items.add(item);
    _log.trace('cart: + ${item.label}');
    notifyListeners();
  }

  void remove(int index) {
    _log.trace('cart: - ${items[index].label}');
    items.removeAt(index);
    notifyListeners();
  }
}

class CartProvider extends StatefulWidget {
  final Widget child;

  const CartProvider({super.key, required this.child});

  // a leitura, pelo widget privado _InheritedCart colocado em build()
  static Cart of(BuildContext context) {
    final inherited = context.dependOnInheritedWidgetOfExactType<_InheritedCart>();
    if (inherited == null) {
      throw FlutterError('CartProvider.of: no CartProvider above this widget');
    }
    return inherited.notifier!;
  }

  @override
  State<CartProvider> createState() => _CartProviderState();
}

class _CartProviderState extends State<CartProvider> {
  Cart? _cart; // null enquanto não for criado

  // chamado logo após initState: o widget pode então LER os dados
  // herdados. getInheritedWidgetOfExactType: lê o log SEM se inscrever
  // nas suas alterações (o provider do carrinho não precisa ser reconstruído
  // a cada vez que o log muda)
  @override
  void didChangeDependencies() {
    super.didChangeDependencies();
    // ??=: o carrinho só é criado na primeira vez
    _cart ??= Cart(context.getInheritedWidgetOfExactType<LogProvider>()!.notifier!);
  }

  @override
  void dispose() {
    _cart?.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) => _InheritedCart(notifier: _cart!, child: widget.child);
}

class _InheritedCart extends InheritedNotifier<Cart> {
  const _InheritedCart({required super.notifier, required super.child});
}
  • linhas 17–24: o carrinho de compras, outro [ChangeNotifier]. Ele recebe o log na criação para registrar cada adição e remoção. [fold] “reduz” a lista a um único valor: a soma dos preços;
  • linhas 39–40: desta vez, o provider é um [StatefulWidget]: é ele quem cria o carrinho de compras e o libera. Ele só é fornecido aos widgets que engloba ([child]);
  • linhas 45–50: o widget privado [_InheritedCart], que o provider coloca acima de seu filho, lê os dados;
  • linhas 65–68: o carrinho é criado em [didChangeDependencies], que é chamado logo depois de [initState] e no qual um widget pode ler os dados herdados. [??=]: ele é criado somente na primeira vez. [getInheritedWidgetOfExactType] lê o log SEM se inscrever em suas mudanças: o provider do carrinho de compras não precisa ser reconstruído toda vez que o log muda;
  • linha 78: o provider coloca os dados herdados acima de seu filho;
  • linhas 81–82: os próprios dados herdados, que são privados.

4.5.3. Um provider configurado

// =========================================================================
// lib/ex14_inherited_data/providers/clock.dart - um provider PARAMETRIZADO
// -------------------------------------------------------------------------
// Um relógio, cujo período de atualização é um parâmetro do
// provider: ClockProvider(period: Duration(seconds: 5), ...).
// Dois providers aninhados: um widget lê o que está MAIS PRÓXIMO
// dele. Desta vez, escrevemos um InheritedWidget "à mão": é
// updateShouldNotify que diz se os leitores devem ser reconstruídos.
// O relógio para quando seu provider desaparece (dispose).
// =========================================================================

import 'dart:async';

import 'package:flutter/material.dart';

class ClockProvider extends StatefulWidget {
  final Duration period;
  final Widget child;

  const ClockProvider({super.key, this.period = const Duration(seconds: 1), required this.child});

  // o valor padrão: uma data congelada, lida por um widget sem provider
  static DateTime of(BuildContext context) =>
      context.dependOnInheritedWidgetOfExactType<_InheritedClock>()?.now ?? DateTime(2026);

  @override
  State<ClockProvider> createState() => _ClockProviderState();
}

class _ClockProviderState extends State<ClockProvider> {
  DateTime _now = DateTime.now();
  Timer? _timer;

  void _start() {
    _timer?.cancel();
    _timer = Timer.periodic(widget.period, (_) => setState(() => _now = DateTime.now()));
  }

  @override
  void initState() {
    super.initState();
    _start();
  }

  // se o pai altera o período, o timer é reiniciado
  @override
  void didUpdateWidget(ClockProvider oldWidget) {
    super.didUpdateWidget(oldWidget);
    if (oldWidget.period != widget.period) _start();
  }

  @override
  void dispose() {
    _timer?.cancel();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) => _InheritedClock(now: _now, child: widget.child);
}

class _InheritedClock extends InheritedWidget {
  final DateTime now;

  const _InheritedClock({required this.now, required super.child});

  // chamado quando o provider é reconstruído: os leitores devem
  // ser reconstruídos? Sim, se a hora mudou
  @override
  bool updateShouldNotify(_InheritedClock oldWidget) => oldWidget.now != now;
}
  • linha 23: a operação de leitura; sem um provider, um valor padrão (uma data fixa). [?.]: se nenhum provider for encontrado, o resultado é [null], e [??] então assume o valor padrão;
  • linhas 34–36: um timer, com o período especificado como parâmetro;
  • linhas 47–49: se o pai mudar o período, o timer é reiniciado;
  • linhas 62–70: desta vez, um [InheritedWidget] escrito “à mão”. Ele carrega um dado (a hora). Toda vez que o provider é reconstruído (a cada segundo), o [Flutter] chama [updateShouldNotify] com o widget antigo: se ele devolver [true], os widgets que leem os dados são reconstruídos.

4.5.4. Os widgets

// lib/ex14_inherited_data/catalog.dart - um descendente que ACRESCENTA ao carrinho
import 'package:flutter/material.dart';

import 'providers/cart.dart';

const catalog = <Item>[
  (label: 'Consultation', price: 30),
  (label: 'Vaccine', price: 12.5),
  (label: 'Certificate', price: 5),
];

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

  @override
  Widget build(BuildContext context) {
    // o carrinho fornecido por ShopPage (um erro se ninguém o fornecer)
    final cart = CartProvider.of(context);
    return Card(
      child: Column(
        children: [
          for (final a in catalog)
            ListTile(
              dense: true,
              title: Text('${a.label} (${a.price} €)'),
              trailing: IconButton(icon: const Icon(Icons.add_shopping_cart), onPressed: () => cart.add(a)),
            ),
        ],
      ),
    );
  }
}
  • Linha 18: o catálogo lê o carrinho de compras fornecido acima e adiciona itens a ele.
// =========================================================================
// lib/ex14_inherited_data/cart_summary.dart
// -------------------------------------------------------------------------
// Outro descendente: o MESMO carrinho de Catalog, mas SEU PRÓPRIO
// relógio, atualizado a cada 5 segundos. Um widget só lê os
// providers colocados ACIMA dele: CartSummary portanto coloca um segundo
// ClockProvider ao redor do seu conteúdo, que entrega a um pequeno
// widget, _Content (cujo context está, ele sim, ABAIXO deste provider).
// =========================================================================

import 'package:flutter/material.dart';

import 'providers/clock.dart';
import 'providers/cart.dart';

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

  @override
  Widget build(BuildContext context) {
    return const ClockProvider(period: Duration(seconds: 5), child: _Content());
  }
}

class _Content extends StatelessWidget {
  const _Content();

  @override
  Widget build(BuildContext context) {
    final cart = CartProvider.of(context);
    final now = ClockProvider.of(context); // o mais próximo: o de 5 s
    return Card(
      child: Padding(
        padding: const EdgeInsets.all(12),
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.start,
          children: [
            Text(
              'Cart (${cart.items.length} item(s)) - ${now.toString().substring(11, 19)}',
              style: Theme.of(context).textTheme.titleSmall,
            ),
            for (final (i, a) in cart.items.indexed)
              Row(
                children: [
                  Text(a.label),
                  TextButton(onPressed: () => cart.remove(i), child: const Text('remove')),
                ],
              ),
            Text('Total: ${cart.total} €', style: const TextStyle(fontWeight: FontWeight.bold)),
          ],
        ),
      ),
    );
  }
}
  • Linha 21: o resumo coloca um segundo provider de relógio, com período de 5 segundos, ao redor de seu conteúdo. Um widget só lê os providers colocados acima dele: é por isso que o conteúdo é um widget separado, [_Content], cujo [context] está ABAIXO deste provider (o [context] de [CartSummary], por sua vez, está acima dele);
  • Linhas 30–31: ele lê o MESMO carrinho que o catálogo, mas o relógio mais próximo é o de 5 segundos.
// =========================================================================
// lib/ex14_inherited_data/main.dart - três níveis de dados herdados
// -------------------------------------------------------------------------
//   - o log: fornecido bem no topo (acima de MaterialApp), para todo o
//     aplicativo;
//   - o carrinho, fornecido por ShopPage: compartilhado por Catalog e
//     CartSummary, que veem o MESMO carrinho;
//   - o relógio, fornecido por ShopPage (período padrão, 1 s) E por
//     CartSummary (5 s): cada um com o seu.
// =========================================================================

import 'package:flutter/material.dart';

import 'catalog.dart';
import 'providers/clock.dart';
import 'providers/log.dart';
import 'providers/cart.dart';
import 'cart_summary.dart';

void main() {
  runApp(
    LogProvider(
      log: Log(),
      child: MaterialApp(
        debugShowCheckedModeBanner: false,
        theme: ThemeData(colorSchemeSeed: Colors.indigo),
        home: const ShopPage(),
      ),
    ),
  );
}

// a hora do relógio da página: um pequeno widget, colocado ABAIXO do provider
class _PageTime extends StatelessWidget {
  const _PageTime();

  @override
  Widget build(BuildContext context) {
    final time = ClockProvider.of(context).toString().substring(11, 19);
    return Text('Clock of the page: $time', style: const TextStyle(color: Colors.grey));
  }
}

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

  @override
  Widget build(BuildContext context) {
    // a página lê o log: ela será reconstruída a cada nova linha
    final log = LogProvider.of(context);
    return ClockProvider(
      child: CartProvider(
        child: Scaffold(
          appBar: AppBar(title: const Text('Example 14 - the inherited data')),
          body: ListView(
            padding: const EdgeInsets.all(16),
            children: [
              const _PageTime(),
              const Catalog(),
              const CartSummary(),
              const SizedBox(height: 12),
              Text('Log (provided to the whole application)', style: Theme.of(context).textTheme.titleSmall),
              for (final line in log.lines) Text(line, style: const TextStyle(fontSize: 12)),
            ],
          ),
        ),
      ),
    );
  }
}
  • linhas 22–24: o provider do log é colocado acima de [MaterialApp]: o log fica disponível em TODO o aplicativo, inclusive em janelas e em outras telas;
  • linhas 34–40: um pequeno widget, colocado abaixo do provider de relógio da página;
  • linha 50: a página lê o log; ela será reconstruída a cada nova linha;
  • linhas 51–52: a página fornece um relógio (período padrão: um segundo) e um carrinho de compras para tudo o que ela contém.

Adicionamos três itens e depois removemos um:

Image

O relógio da página avança a cada segundo; o relógio do carrinho de compras avança a cada cinco segundos. O log mostra as adições e a remoção. O exemplo 20 delegará todo esse trabalho ao pacote [provider], que o escreve em uma única linha, mas se baseia exatamente neste mecanismo.

4.6. Exemplo 15: reutilizando comportamentos

Um widget reutiliza uma view. Como reutilizar um comportamento, junto com seu estado (destacar o que foi tocado, disparar uma ação após um toque longo, dar o foco na inicialização)? O [React] tem “hooks personalizados”; o [Flutter] e o [Dart] têm três ferramentas.

4.6.1. Um widget “envelope”

// =========================================================================
// lib/ex15_behaviors/highlighter.dart - um comportamento em um widget
// -------------------------------------------------------------------------
// A primeira maneira de reutilizar um COMPORTAMENTO (com seu estado): um
// widget "wrapper", que adiciona esse comportamento a qualquer filho.
//     Highlighter(color: ..., child: ListTile(...))
// Este destaca seu filho enquanto ele está sendo TOCADO (o dedo colocado na
// tela) e, com um mouse (web, computador), enquanto o cursor está SOBRE ELE.
// Cada Highlighter tem seu próprio estado: duas linhas não se atrapalham.
// =========================================================================

import 'package:flutter/material.dart';

class Highlighter extends StatefulWidget {
  final Color color;
  final Widget child;

  const Highlighter({super.key, this.color = const Color(0xFFFFF3CD), required this.child});

  @override
  State<Highlighter> createState() => _HighlighterState();
}

class _HighlighterState extends State<Highlighter> {
  bool _touched = false;
  bool _hovered = false;

  @override
  Widget build(BuildContext context) {
    // MouseRegion: os movimentos do mouse; Listener: os contatos
    // do dedo (ou os cliques), no nível mais baixo
    return MouseRegion(
      onEnter: (_) => setState(() => _hovered = true),
      onExit: (_) => setState(() => _hovered = false),
      child: Listener(
        onPointerDown: (_) => setState(() => _touched = true),
        onPointerUp: (_) => setState(() => _touched = false),
        onPointerCancel: (_) => setState(() => _touched = false),
        // AnimatedContainer: uma mudança de cor ANIMADA (200 ms)
        child: AnimatedContainer(
          duration: const Duration(milliseconds: 200),
          color: _touched || _hovered ? widget.color : Colors.transparent,
          child: widget.child,
        ),
      ),
    );
  }
}
  • linhas 32–34: [MouseRegion] notifica quando o mouse entra no widget ou sai dele (na web ou em um computador; um celular não tem mouse);
  • linhas 35–38: [Listener] notifica, no nível mais baixo, cada toque do dedo (ou cada clique): pressionar, soltar, cancelar;
  • linhas 40–42: um [Container] animado: quando sua cor muda, ele faz a transição da cor antiga para a nova em 200 milissegundos, sem exigir nenhum código adicional. O [Flutter] tem toda uma família desses widgets “implicitamente animados”: [AnimatedOpacity], [AnimatedPadding], [AnimatedAlign]...

[Highlighter] aplica seu comportamento a qualquer filho: [Highlighter(child: ListTile(...))].

4.6.2. Um widget que contém uma animação

// =========================================================================
// lib/ex15_behaviors/long_press.dart - um botão de toque longo
// -------------------------------------------------------------------------
//     LongPressButton(duration: Duration(seconds: 1), onAction: remove, child: ...)
// A ação só é executada se o botão for mantido pressionado durante
// toda a duração: uma proteção contra toques acidentais. Um anel
// se preenche durante o toque.
// O preenchimento é uma ANIMAÇÃO: um AnimationController produz um
// valor que vai de 0 a 1 durante a duração dada, a cada quadro da
// tela. Ele precisa de um "ticker" (a pulsação dos quadros): o mixin
// SingleTickerProviderStateMixin o adiciona ao objeto State. Um MIXIN é
// a maneira do Dart de reutilizar código em várias classes (veja
// autofocus.dart).
// =========================================================================

import 'package:flutter/material.dart';

class LongPressButton extends StatefulWidget {
  final Duration duration;
  final VoidCallback onAction;
  final Widget child;

  const LongPressButton({
    super.key,
    this.duration = const Duration(seconds: 1),
    required this.onAction,
    required this.child,
  });

  @override
  State<LongPressButton> createState() => _LongPressButtonState();
}

// "with": o objeto State recebe, além disso, o código do mixin
class _LongPressButtonState extends State<LongPressButton> with SingleTickerProviderStateMixin {
  late final AnimationController _animation;

  @override
  void initState() {
    super.initState();
    // vsync: this: o ticker fornecido pelo mixin
    _animation = AnimationController(vsync: this, duration: widget.duration)
      // o fim da animação: o toque durou o suficiente
      ..addStatusListener((status) {
        if (status == AnimationStatus.completed) {
          _animation.reset();
          widget.onAction();
        }
      });
  }

  // quando o widget é removido: nenhuma animação órfã
  @override
  void dispose() {
    _animation.dispose();
    super.dispose();
  }

  void _start() => _animation.forward(from: 0);

  // o dedo levanta cedo demais: o anel se esvazia
  void _stop() {
    if (_animation.isAnimating) _animation.reverse();
  }

  @override
  Widget build(BuildContext context) {
    return GestureDetector(
      onTapDown: (_) => _start(),
      onTapUp: (_) => _stop(),
      onTapCancel: _stop,
      // AnimatedBuilder: reconstrói APENAS este trecho, a cada quadro
      child: AnimatedBuilder(
        animation: _animation,
        builder: (context, child) => Row(
          mainAxisSize: MainAxisSize.min,
          children: [
            SizedBox(
              width: 22,
              height: 22,
              child: CircularProgressIndicator(value: _animation.value, strokeWidth: 3, color: Colors.red),
            ),
            const SizedBox(width: 8),
            child!, // o filho, construído uma vez por todas
          ],
        ),
        child: widget.child,
      ),
    );
  }
}
  • linha 35: [with]: o objeto [State] também recebe o código de um mixin. Um mixin é a forma como o [Dart] reutiliza código em várias classes sem herança. Este mixin fornece um “ticker” — a taxa de atualização da tela (60 quadros por segundo ou mais) — de que uma animação precisa;
  • linhas 42–47: um [AnimationController] gera, a cada quadro, um valor que vai de 0 a 1 durante a duração especificada. [vsync: this]: o ticker fornecido pelo mixin. [..addStatusListener(...)]: quando a animação chega ao fim ([completed]), o toque durou o suficiente: a animação volta a zero e a ação é executada;
  • linhas 59–63: o dedo toca o botão: a animação parte de 0; se ele for levantado cedo demais, a animação retrocede;
  • linhas 69–71: gestos: pressionar, soltar, cancelar (o dedo escorregou para fora do botão);
  • linhas 73–87: [AnimatedBuilder] reconstrói somente esta parte da tela a cada quadro da animação: um anel ([CircularProgressIndicator]) cujo valor corresponde à animação. O elemento fixo (o texto do botão) é construído uma única vez ([child]) e passado a [builder].

4.6.3. Um comportamento em um mixin

// =========================================================================
// lib/ex15_behaviors/autofocus.dart - um comportamento em um MIXIN
// -------------------------------------------------------------------------
// A segunda maneira de reutilizar um comportamento: um mixin sobre State.
//     class _MyPageState extends State<MyPage> with FocusOnStart { ... }
// O objeto State recebe um FocusNode (startFocus), que assume o foco
// assim que a tela é exibida e que é liberado junto com ela: o mixin
// completa o initState e o dispose da classe que o usa.
// "on State<T>": este mixin só se aplica a um objeto State, cujos
// métodos ele pode portanto usar (initState, dispose, mounted...).
// (Para um simples campo, o parâmetro autofocus: true do TextField faz
// a mesma coisa: o mixin mostra o mecanismo, reutilizável para outra coisa.)
// =========================================================================

import 'package:flutter/widgets.dart';

mixin FocusOnStart<T extends StatefulWidget> on State<T> {
  final startFocus = FocusNode();

  @override
  void initState() {
    super.initState(); // o initState da classe (ou do mixin) "acima"
    // após a primeira exibição: o campo existe, damos-lhe o foco
    WidgetsBinding.instance.addPostFrameCallback((_) {
      if (mounted) startFocus.requestFocus();
    });
  }

  @override
  void dispose() {
    startFocus.dispose();
    super.dispose();
  }
}
  • linha 17: um mixin que só se aplica a um objeto [State] ([on State<T>]): ele pode, portanto, usar seus métodos;
  • linha 18: o objeto [State] que usa o mixin recebe este campo;
  • linhas 21–25: o mixin [initState] é complementado: [super.initState()] chama o da classe “pai” (a de [State], ou outro mixin). Depois da exibição inicial, o campo existe: o foco é dado a ele. [mounted]: o objeto [State] ainda está na árvore?;
  • linhas 30–32: ele também complementa [dispose], para liberar o [FocusNode].

4.6.4. Uso

// =========================================================================
// lib/ex15_behaviors/main.dart - reutilizando comportamentos
// -------------------------------------------------------------------------
// Três ferramentas do Flutter e do Dart para reutilizar um COMPORTAMENTO (e
// seu estado), e não uma simples exibição:
//   - um widget "wrapper" (Highlighter);
//   - um widget que carrega uma animação (LongPressButton);
//   - um mixin sobre State (FocusOnStart).
// =========================================================================

import 'package:flutter/material.dart';

import 'long_press.dart';
import 'autofocus.dart';
import 'highlighter.dart';

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

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

  @override
  State<BehaviorsPage> createState() => _BehaviorsPageState();
}

// o mixin FocusOnStart: este objeto State recebe startFocus
class _BehaviorsPageState extends State<BehaviorsPage> with FocusOnStart {
  final List<String> _doctors = ['Mme Marie PELISSIER', 'Mr Paul TATOU', 'Melle Sophie DUPONT'];
  String _message = '';

  void _remove(String name) {
    setState(() {
      _doctors.remove(name);
      _message = '$name has been deleted.';
    });
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Example 15 - reusing behaviors')),
      body: ListView(
        padding: const EdgeInsets.all(16),
        children: [
          TextField(
            focusNode: startFocus, // o FocusNode fornecido pelo mixin
            decoration: const InputDecoration(hintText: 'this field received the focus on its own'),
          ),
          const SizedBox(height: 12),
          const Text(
            'Touch the rows; hold a button pressed for one second to delete.',
            style: TextStyle(color: Colors.grey),
          ),
          for (final (i, m) in _doctors.indexed)
            Highlighter(
              key: ValueKey(m),
              // uma linha em cada duas: a cor padrão; as outras, verde
              color: i.isEven ? const Color(0xFFFFF3CD) : const Color(0xFFD1E7DD),
              child: ListTile(
                title: Text(m),
                trailing: LongPressButton(
                  onAction: () => _remove(m),
                  child: const Text('Delete', style: TextStyle(color: Colors.red)),
                ),
              ),
            ),
          const SizedBox(height: 12),
          if (_message.isNotEmpty) Text(_message, style: const TextStyle(color: Colors.indigo)),
        ],
      ),
    );
  }
}
  • linha 35: a tela usa o mixin;
  • linha 54: o [FocusNode] fornecido pelo mixin;
  • linhas 63–71: cada linha é destacada quando tocada; seu botão “Delete” só tem efeito depois de mantido pressionado por um segundo.

Mantendo o primeiro botão pressionado (o anel se enche, a linha é destacada); depois, após pressionar completamente o segundo botão:

4.7. Exemplo 16: uma janela de confirmação reutilizável

“Tem certeza?”: o [Flutter] fornece tudo de que você precisa. A função [showDialog] exibe uma janela modal sobre a tela e devolve um [Future], preenchido com o valor que a janela transmite ao ser fechada.

4.7.1. A janela

// =========================================================================
// lib/ex16_confirmation/confirmation.dart - "Tem certeza?"
// -------------------------------------------------------------------------
// O Flutter fornece tudo o que é preciso: showDialog() exibe um diálogo
// MODAL acima da tela e retorna um Future, resolvido com o valor
// que o diálogo passa ao fechar: Navigator.pop(context, value).
// O código chamador se escreve portanto de forma muito simples:
//
//     if (await confirm(context, 'Delete this doctor?')) { ... }
//
// Fechar o diálogo SEM responder (toque fora, botão Voltar do
// celular, tecla Esc) resolve o Future com null: isso é tratado
// como um "não".
// =========================================================================

import 'package:flutter/material.dart';

Future<bool> confirm(BuildContext context, String message) async {
  final answer = await showDialog<bool>(
    context: context,
    // AlertDialog: um diálogo Material, com um título, um conteúdo e botões
    builder: (context) => AlertDialog(
      title: const Text('Confirmation'),
      content: Text(message),
      actions: [
        // autofocus: o botão "No" (a escolha menos perigosa) recebe o foco
        TextButton(autofocus: true, onPressed: () => Navigator.pop(context, false), child: const Text('No, go back')),
        FilledButton(
          style: FilledButton.styleFrom(backgroundColor: Colors.red),
          onPressed: () => Navigator.pop(context, true),
          child: const Text('Yes, confirm'),
        ),
      ],
    ),
  );
  return answer ?? false; // null: diálogo fechado sem resposta
}
  • linha 18: uma função comum, que pode ser usada em qualquer lugar onde haja um [context] disponível;
  • linhas 19–22: [showDialog] abre a janela criada por [builder] e devolve um [Future<bool?>]: o valor passado quando a janela é fechada;
  • linhas 23–25: [AlertDialog] é a caixa de diálogo do [Material Design]: um título, um conteúdo e botões;
  • linha 27: [Navigator.pop(context, false)] fecha a janela transmitindo [false]. [autofocus]: o botão “No” — a opção menos arriscada — recebe o foco (pressionar Enter acidentalmente não exclui nada);
  • linha 36: fechar a janela SEM responder (tocar fora da janela, pressionar o botão Voltar do celular ou pressionar a tecla Esc) resolve o [Future] como [null]: isso é tratado como um “não”.

O código que chama a janela é então tão simples de escrever quanto com o [window.confirm] do navegador: [if (await confirm(context, 'Delete this doctor?')) { ... }]. O cliente [React] exigia um contexto, uma promise feita à mão e um “portal” para obter o mesmo resultado; com o [Flutter], é assim que as janelas normalmente funcionam.

4.7.2. Uso

// =========================================================================
// lib/ex16_confirmation/main.dart - usando o diálogo de confirmação
// -------------------------------------------------------------------------
// Uma exclusão, depois uma mensagem passageira na parte de baixo da tela (SnackBar),
// com um botão "Undo": a outra maneira, muito comum em dispositivos móveis, de
// proteger o usuário de um erro.
// =========================================================================

import 'package:flutter/material.dart';

import 'confirmation.dart';

typedef Contact = ({int id, String name});

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

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

  @override
  State<ContactsPage> createState() => _ContactsPageState();
}

class _ContactsPageState extends State<ContactsPage> {
  final List<Contact> _contacts = [
    (id: 1, name: 'Jean MARTIN'),
    (id: 2, name: 'Alice DURAND'),
    (id: 3, name: 'Luc GERMAN'),
  ];
  String _message = '';

  // uma função async: ela "espera" a resposta do usuário
  Future<void> _remove(Contact c) async {
    final yes = await confirm(context, 'Delete the contact ${c.name}?');
    // após um await, a tela pode ter desaparecido: verificamos se ainda está lá
    if (!mounted) return;
    if (!yes) {
      setState(() => _message = 'Deletion abandoned.');
      return;
    }
    final position = _contacts.indexOf(c);
    setState(() {
      _contacts.remove(c);
      _message = '${c.name} has been deleted.';
    });
    // ScaffoldMessenger: exibe uma mensagem passageira na parte de baixo da tela
    ScaffoldMessenger.of(context).showSnackBar(
      SnackBar(
        content: Text('${c.name} deleted'),
        action: SnackBarAction(
          label: 'Undo',
          onPressed: () => setState(() {
            _contacts.insert(position, c);
            _message = '${c.name} is back.';
          }),
        ),
      ),
    );
  }

  Future<void> _removeAll() async {
    final yes = await confirm(context, 'Delete the ${_contacts.length} contacts?');
    if (yes && mounted) {
      setState(() {
        _contacts.clear();
        _message = 'All the contacts have been deleted.';
      });
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Example 16 - a confirmation dialog')),
      body: ListView(
        padding: const EdgeInsets.all(16),
        children: [
          for (final c in _contacts)
            ListTile(
              leading: const Icon(Icons.person),
              title: Text(c.name),
              trailing: IconButton(
                icon: const Icon(Icons.delete_outline, color: Colors.red),
                onPressed: () => _remove(c),
              ),
            ),
          if (_contacts.isEmpty)
            const ListTile(
              title: Text('No contact.', style: TextStyle(color: Colors.grey)),
            ),
          const SizedBox(height: 12),
          Align(
            alignment: Alignment.centerLeft,
            child: FilledButton(
              style: FilledButton.styleFrom(backgroundColor: Colors.red),
              // null: botão desabilitado quando a lista está vazia
              onPressed: _contacts.isEmpty ? null : _removeAll,
              child: const Text('Delete all'),
            ),
          ),
          const SizedBox(height: 12),
          if (_message.isNotEmpty) Text(_message, style: const TextStyle(color: Colors.indigo)),
        ],
      ),
    );
  }
}
  • linhas 41–44: uma função [async]: ela espera a resposta do usuário. Depois de um [await], a tela pode ter desaparecido (o usuário saiu): verificamos se ele ainda está lá ([mounted]) antes de modificar o estado ou chamar [context]. O analisador sinaliza quando essa verificação é omitida;
  • linhas 55–62: depois da exclusão, uma mensagem temporária aparece na parte inferior da tela ([SnackBar]), com um botão “Undo” que restaura o contato à sua posição original. Este é outro método, muito comum em dispositivos móveis, para proteger o usuário de um erro: agir imediatamente, mas permitir que o usuário desfaça;
  • linha 105: [null] desabilita o botão quando a lista está vazia.

A janela de confirmação; depois a exclusão é concluída, com sua mensagem fugaz: