Skip to content

3. Primeros pasos con Flutter

3.1. Ejemplo 01: la estructura de una aplicación Flutter

3.1.1. El proyecto

Un proyecto [Flutter] se crea con el comando [flutter create]:

flutter create --org fr.stahe --platforms=android,web,windows my_application
  • [--org fr.stahe]: el prefijo del identificador de la aplicación, escrito al revés como un nombre de dominio. La aplicación [Android] se llamará [fr.stahe.my_application]; dos aplicaciones instaladas en el mismo teléfono deben tener identificadores diferentes;
  • [--platforms=...]: las plataformas de destino. Para cada una, [flutter create] crea una carpeta ([android/], [web/], [windows/], y también [ios/], [macos/], [linux/] si se solicitan): un pequeño proyecto específico de la plataforma que simplemente lanza el motor de [Flutter] y carga la aplicación en él. Rara vez se modifica (el nombre de la aplicación, el ícono y los permisos);
  • [my_application]: el nombre del proyecto, que también es el nombre del paquete [Dart]: letras minúsculas, números y guiones bajos.

El comando genera una aplicación completa, lista para ejecutarse (un contador). El proyecto de ejemplos se creó de la misma manera y, luego, su carpeta [lib/] se completó manualmente para reunir veinticinco aplicaciones en un solo proyecto: así comparten los mismos paquetes, que se descargan una sola vez.

3.1.2. El archivo pubspec.yaml

El archivo [pubspec.yaml] describe el proyecto: su nombre, la versión requerida de [Dart], los paquetes utilizados y los archivos incluidos con la aplicación. El de los ejemplos:

# ==========================================================================
# pubspec.yaml - la descripción del proyecto de ejemplos
# --------------------------------------------------------------------------
# Un único proyecto Flutter para los 25 ejemplos: cada uno tiene su carpeta en
# lib/ y su propio punto de entrada (main.dart), que se indica al comando
# flutter run con la opción -t (target):
#
#     flutter run -t lib/ex05_controlled_fields/main.dart
#
# Las bibliotecas (los "paquetes") se descargan de pub.dev con el
# comando flutter pub get (que flutter run ejecuta automáticamente).
# ==========================================================================

name: examples_flutter
description: The 25 small examples of the course Step-by-step introduction to the Flutter framework.
# sin publicación en pub.dev: esto es una aplicación, no una biblioteca
publish_to: none
version: 1.0.0

environment:
  # la versión requerida del lenguaje Dart
  sdk: ^3.12.0

dependencies:
  flutter:
    sdk: flutter
  # direcciones "limpias" en la web (ejemplo 17)
  flutter_web_plugins:
    sdk: flutter
  # los textos del propio Flutter (botones de diálogo, calendario...)
  # en inglés y en francés (ejemplos 05, 21)
  flutter_localizations:
    sdk: flutter
  # fechas y números con formato según el idioma (ejemplos 09, 21)
  intl: any
  # el enrutador (ejemplos 17, 18)
  go_router: ^16.2.0
  # un estado compartido por toda la aplicación (ejemplos 20, 24, 25)
  provider: ^6.1.5
  # un pequeño diccionario clave -> valor, guardado en el dispositivo (ejemplos 20, 21, 23)
  shared_preferences: ^2.5.3
  # solicitudes HTTP (ejemplos 22 a 25)
  http: ^1.5.0
  # mostrar imágenes SVG (ejemplo 03, CAPTCHA de los ejemplos 22 a 25)
  flutter_svg: ^2.2.1

dev_dependencies:
  # las pruebas (y las capturas de pantalla del curso, ver test/captures)
  flutter_test:
    sdk: flutter
  # las reglas de estilo recomendadas por el equipo de Flutter (ver analysis_options.yaml)
  flutter_lints: ^6.0.0

flutter:
  # los íconos de Material Design (Icons.add, Icons.delete...)
  uses-material-design: true
  # los archivos distribuidos CON la aplicación: se leen por su ruta
  assets:
    - assets/
    - assets/i18n/
  # una fuente monoespaciada (para mostrar JSON), distribuida con la aplicación
  fonts:
    - family: RobotoMono
      fonts:
        - asset: assets/fonts/RobotoMono-Regular.ttf
        - asset: assets/fonts/RobotoMono-Bold.ttf
          weight: 700
  • Líneas 14–18: el nombre del proyecto (que también es el nombre del paquete; los archivos del proyecto se importan mediante [package:examples_flutter/...]), su descripción y su versión. [publish_to: none]: este proyecto no es una biblioteca; nunca se publicará en [pub.dev];
  • líneas 20–22: la versión requerida del lenguaje [Dart]. El prefijo [^] acepta cualquier versión posterior dentro de la misma versión mayor (3.12, 3.13… pero no 4.0);
  • líneas 24–45: los paquetes que necesita la aplicación. Algunos provienen del propio SDK de [Flutter] ([sdk: flutter]): [flutter] (el framework), [flutter_localizations] (los textos de [Flutter] traducidos a cada idioma), [flutter_web_plugins] (una configuración específica de la web). Los demás se descargan de pub.dev, el repositorio de los paquetes de [Dart]: su propósito se explica en los comentarios y cada uno se demostrará en el ejemplo que lo utiliza. [intl: any]: cualquier versión ([flutter_localizations] impone la suya);
  • líneas 47–52: paquetes utilizados solo para el desarrollo y no incluidos en la aplicación distribuida: [flutter_test] (pruebas) y [flutter_lints] (reglas de estilo del analizador);
  • líneas 54–67: la configuración específica de [Flutter]:
    • [uses-material-design: true]: la aplicación utiliza la fuente de íconos de [Material Design] ([Icons.add], [Icons.delete]...);
    • [assets]: los archivos incluidos con la aplicación (imágenes, diccionarios, etc.), que se leen mediante su ruta. Al especificar una carpeta ([assets/]), se entregan directamente todos los archivos que contiene;
    • [fonts]: una fuente incluida con la aplicación; [Roboto Mono], una fuente monoespaciada, se utiliza para mostrar JSON. La fuente estándar de [Material Design], [Roboto], es la fuente del sistema [Android]: no es necesario incluirla.

Las versiones de los paquetes siguen la misma convención que en [npm]: [^16.2.0] acepta cualquier versión 16.x.y a partir de la 16.2.0. El comando [flutter pub get] descarga los paquetes y escribe las versiones exactas seleccionadas en el archivo [pubspec.lock]. [flutter run] lo ejecuta automáticamente cuando [pubspec.yaml] ha cambiado; [VS Code] también lo ejecuta en cuanto se guarda este archivo. Para agregar un paquete, en lugar de editar el archivo manualmente, puede escribir [flutter pub add go_router]: el comando agrega la línea con la última versión del paquete.

3.1.3. El archivo analysis_options.yaml

El analizador de [Dart] verifica el código mientras se escribe: [VS Code] subraya los errores en rojo y las advertencias en amarillo o azul. También puede ejecutarlo para todo el proyecto con [flutter analyze]. Sus reglas:

# ==========================================================================
# analysis_options.yaml - las reglas del analizador de código Dart
# --------------------------------------------------------------------------
# El analizador revisa el código mientras se escribe (VS Code subraya los
# errores) y mediante el comando flutter analyze. Partimos de las reglas
# recomendadas por el equipo de Flutter (paquete flutter_lints)...
# ==========================================================================

include: package:flutter_lints/flutter.yaml

analyzer:
  language:
    # ... más estrictas: sin conversión implícita de un tipo dynamic
    strict-casts: true
    strict-raw-types: true

linter:
  rules:
    # comillas simples en todas partes, como en los ejemplos del curso
    prefer_single_quotes: true
    # "final" para una variable local que nunca se reasigna
    prefer_final_locals: true
    # se permiten cadenas demasiado largas (textos de los ejemplos)
    lines_longer_than_80_chars: false
  • línea 9: las reglas recomendadas por el equipo de [Flutter] (paquete [flutter_lints]): un widget debe tener un constructor [const] si es posible, un controlador debe liberarse, etc.;
  • Líneas 14–15: tipado más estricto. [Dart] es un lenguaje de tipado estático, pero tiene un tipo [dynamic] (“cualquier cosa”): el JSON decodificado, por ejemplo, está formado por [dynamic]. [strict-casts] prohíbe la conversión implícita a otro tipo: hay que escribirla explícitamente ([json['lastName'] as String]), y cualquier error ocurre ahí y es visible;
  • Líneas 20–24: algunas reglas de estilo: usar comillas simples para las cadenas (comillas dobles si la cadena contiene un apóstrofo: ["it's"]), y [final] para las variables que nunca se reasignan.

3.1.4. El punto de entrada: main.dart

Por ejemplo, hay un archivo llamado [main.dart], que contiene la función [main], el punto de entrada de todo programa [Dart]. El del ejemplo 01:

// =========================================================================
// lib/ex01_first_application/main.dart - una primera aplicación
// -------------------------------------------------------------------------
// Todo, en una aplicación Flutter, es un WIDGET: un objeto que describe
// una parte de la pantalla (un texto, un botón, un margen, una columna...).
// Los widgets se anidan unos dentro de otros y forman un ÁRBOL.
// Un widget tiene un método build(), que DEVUELVE los widgets que
// lo componen. Flutter llama a build() para producir la pantalla;
// LO LLAMA DE NUEVO cada vez que cambia el estado del widget (setState), y
// actualiza la pantalla con el nuevo resultado.
// =========================================================================

import 'package:flutter/material.dart';

// datos "ordinarios", fuera de los widgets: nunca cambian
const title = 'Welcome to Flutter';
const languages = ['Dart', 'Flutter', 'Material Design'];

// "12:05:09": la hora actual, con dos 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)}';
}

// el punto de entrada de todo programa Dart
void main() {
  // runApp: Flutter toma el control de la pantalla y muestra en ella el widget RAÍZ
  runApp(const Application());
}

// el widget raíz: configura la aplicación (título, tema, primera pantalla).
// StatelessWidget: un widget SIN estado, descrito por completo por sus parámetros
class Application extends StatelessWidget {
  const Application({super.key});

  @override
  Widget build(BuildContext context) {
    // MaterialApp: una aplicación con los colores y el comportamiento de
    // Material Design, el lenguaje visual de Google
    return MaterialApp(
      title: 'Example 01',
      // sin banner "DEBUG" en la esquina de la pantalla
      debugShowCheckedModeBanner: false,
      // los colores de toda la aplicación, derivados de un color base
      theme: ThemeData(colorSchemeSeed: Colors.indigo),
      home: const HomePage(),
    );
  }
}

// un widget CON estado: consta de dos partes, el widget en sí (que nunca
// cambia) y un objeto State (que contiene los datos que cambian)
class HomePage extends StatefulWidget {
  const HomePage({super.key});

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

// el "_": esta clase es PRIVADA, invisible fuera de este archivo
class _HomePageState extends State<HomePage> {
  // el ESTADO: campos simples del objeto State
  int _counter = 0;
  String _time = currentTime();

  // la función a la que llama el botón
  void _increment() {
    // setState: el estado se modifica DENTRO de la función que se pasa a setState;
    // Flutter vuelve entonces a llamar a build() para actualizar la pantalla. Nunca
    // modificamos la pantalla nosotros mismos
    setState(() {
      _counter++;
      _time = currentTime();
    });
  }

  @override
  Widget build(BuildContext context) {
    // Scaffold: la estructura de una pantalla Material (barra superior, cuerpo...)
    return Scaffold(
      appBar: AppBar(title: const Text('Example 01 - a first application')),
      // Padding: un margen alrededor de su hijo
      body: Padding(
        padding: const EdgeInsets.all(16),
        // Column: hijos colocados uno debajo del otro
        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} inserta el valor de una expresión en una cadena
            Text('It is written in ${languages.join(', ')} (${languages.length} languages).'),
            const SizedBox(height: 16),
            // onPressed: la función a la que se llama cuando se presiona el botón (ver ejemplo 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)),
            ),
          ],
        ),
      ),
    );
  }
}

Empecemos por el final: el programa.

  • Línea 13: la biblioteca [Material] de [Flutter]: todos los widgets de [Material Design], el lenguaje visual de [Google] (botones, campos de entrada, barras, ventanas, etc.). Importa por sí misma el resto de [Flutter];
  • líneas 16–17: dos valores de datos ordinarios, declarados fuera de los widgets: nunca cambian. [const]: una constante conocida en tiempo de compilación;
  • líneas 20–23: una función ordinaria que devuelve la hora actual en el formato “12:05:09”. Contiene una pequeña función propia, [twoDigits], escrita en una sola línea con [=>];
  • líneas 27–29: la función [main], llamada al iniciar. [runApp] inicia [Flutter]: toma el control de la pantalla y muestra el widget que se le proporciona, la raíz de la aplicación.

El widget raíz, [Application]:

  • Línea 34: un widget es una clase. Esta clase hereda de [StatelessWidget], un widget sin estado: lo que muestra depende únicamente de sus parámetros y nunca cambia por sí solo;
  • Línea 29: su constructor. [{super.key}]: un parámetro con nombre opcional que se pasa a la clase padre. Todos los widgets lo tienen: la “clave” que lo identifica (véase el ejemplo 04). El constructor es [const]: [Application()] puede ser una constante que [Flutter] nunca necesita reconstruir;
  • Líneas 38–47: el método [build], el núcleo de un widget. Devuelve los widgets que lo componen. [@override]: sobrescribe el método [build] de la clase padre. El parámetro [context] es la posición del widget en el árbol de widgets: sirve para recuperar lo que proporcionan sus ancestros (el tema, por ejemplo, línea 90);
  • líneas 41–47: [MaterialApp] es el widget que convierte un árbol de widgets en una aplicación [Material]: un título ([title], el nombre de la aplicación en la lista de aplicaciones recientes del teléfono o en la pestaña del navegador), un tema ([theme]) y una pantalla de inicio ([home]). [debugShowCheckedModeBanner: false] elimina el banner “DEBUG” que una aplicación en desarrollo muestra en una esquina. [ThemeData(colorSchemeSeed: Colors.indigo)]: todos los colores de la aplicación (botones, barras, campos, etc.) se derivan de un único color base, según las reglas de [Material Design] 3.

La primera pantalla, [HomePage], tiene datos que cambian: es un widget con estado.

  • Líneas 54–58: un [StatefulWidget] consta de dos partes. El widget en sí, como cualquier widget, nunca cambia (sus campos serían [final]); su única tarea es crear, mediante [createState], un objeto [State], que a su vez contiene los datos que cambian. [Flutter] crea este objeto una sola vez y lo conserva mientras el widget permanezca en el mismo lugar del árbol;
  • línea 62: el objeto [State]. Su nombre comienza con un guion bajo: en [Dart], todo lo que comienza con [_] es privado e invisible fuera del archivo;
  • líneas 64–65: el estado: campos simples del objeto [State];
  • líneas 68–75: el método llamado por el botón. No afecta la pantalla: cambia el estado dentro de la función pasada a [setState]. [setState] ejecuta esta función y luego notifica a [Flutter] que el estado ha cambiado: [Flutter] llamará a [build], comparará el nuevo árbol de widgets con el anterior y volverá a dibujar lo que ha cambiado;
  • líneas 79–105: el [build] de la pantalla:
    • [Scaffold] (“andamio”) es la estructura de una pantalla [Material]: una barra superior ([appBar]), un cuerpo ([body]) y, si se solicitan, una barra inferior, un botón flotante y un menú lateral;
    • [AppBar]: la barra superior; su título es un widget ([Text]), como casi todo en [Flutter];
    • [Padding]: un margen alrededor de su único hijo, [child]. [EdgeInsets.all(16)]: 16 puntos en cada lado (un “punto” lógico, independiente de la densidad de pantalla: aproximadamente 2,6 píxeles en el teléfono de las capturas de pantalla);
    • [Column]: sus hijos, [children], dispuestos uno debajo del otro. [crossAxisAlignment: CrossAxisAlignment.start]: alineados a la izquierda (el eje “transversal” de una columna es el eje horizontal);
    • [Text]: texto. Su estilo puede derivarse del tema: [Theme.of(context).textTheme.headlineSmall] es el estilo para los “títulos pequeños”;
    • [SizedBox]: una caja vacía con una altura especificada, un espacio entre dos widgets;
    • línea 98: [${expression}] inserta el valor de una expresión en una cadena; [$_counter] basta para una variable simple (línea 104);
    • línea 101: un botón. [onPressed] recibe la función que se llamará cuando se presione el botón. Se especifica la función misma, sin paréntesis: [onPressed: _increment()] la llamaría de inmediato, durante la construcción de la pantalla;
    • líneas 104–105: texto que depende del estado. Cuando el estado cambia, se llama a [build] y este texto cambia.

Dos notas sobre [Dart]:

  • casi todos los argumentos de los widgets son parámetros con nombre ([title: ...], [child: ...]): el árbol de widgets se lee como una descripción, y el orden de los argumentos no importa. Un parámetro con nombre es opcional, a menos que se declare como [required];
  • la palabra clave [const] antes de un widget ([const SizedBox(height: 12)]) lo crea una vez por todas en tiempo de compilación. [Flutter] sabe entonces que nunca cambia y no pierde tiempo comparándolo. El analizador señala cualquier [const] que se haya omitido; [VS Code] sabe agregarlos por sí solo.

El árbol de widgets de la pantalla, tal como lo muestra la herramienta [Flutter DevTools] (inspector de widgets):

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

En una aplicación [Flutter], se escribe muy poco código de “implementación” y mucho código “descriptivo”: la pantalla es un árbol de widgets, cada uno configurado mediante sus parámetros. Es el mismo concepto que JSX de [React], pero sin un lenguaje de plantillas: el árbol se escribe en [Dart].

3.1.5. Ejecución

En la consola abierta en la carpeta [examples_flutter], con el emulador [Android] en ejecución:

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

La consola muestra:

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=...

La primera vez, la compilación de la aplicación [Android] (con la herramienta [Gradle]) tarda uno o dos minutos; las compilaciones siguientes tardan solo unos segundos. La aplicación se instala en el emulador y se inicia. A la izquierda, la pantalla de inicio; a la derecha, después de presionar el botón dos veces:

Dos experimentos para probar:

  • Cambie el texto del título en [main.dart], guarde el archivo y escriba `r` en la consola (o simplemente guarde el archivo en [VS Code]): la pantalla se actualiza en un segundo y el contador conserva su valor. Esto es una “recarga en caliente” (hot reload): el nuevo código se inyecta en la aplicación en ejecución; [Flutter] llama a [build], pero los objetos [State] se conservan. R (“reinicio en caliente”, hot restart) reinicia la aplicación desde [main]: el contador vuelve a 0;
  • Inicie la misma aplicación en el navegador: [flutter run -d chrome -t lib/ex01_first_application/main.dart]. Es la misma pantalla, renderizada por el mismo motor; solo cambia el tamaño de la ventana. Con [-d windows], es una aplicación [Windows].

3.2. Ejemplo 02: el estado y los valores calculados

El estado es el núcleo de [Flutter], tal como lo es de [React]. Este ejemplo calcula el precio con IVA de un artículo:

// =========================================================================
// lib/ex02_state/main.dart - el estado y los valores calculados
// -------------------------------------------------------------------------
// Una pequeña calculadora de precios con IVA incluido:
//   - el ESTADO: los campos del objeto State; cambiarlos DENTRO de setState()
//     hace que build() se ejecute de nuevo, lo que produce la pantalla con los nuevos valores;
//   - un valor CALCULADO a partir del estado NO es estado: es un
//     "getter" (o una variable local de build), recalculado en cada llamada
//     a build(). Siempre está actualizado, sin nada que sincronizar;
//   - un dato que depende de los valores SUCESIVOS del estado (el historial
//     de los totales) se actualiza donde cambia el estado: en setState;
//   - el título de la aplicación (pestaña del navegador, lista de aplicaciones
//     recientes del teléfono) también es un widget, Title:
//     sigue al estado como el resto de la pantalla.
// =========================================================================

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

// un formateador de montos en euros, a la estadounidense (€1,234.50), ver ejemplo 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> {
  // el estado
  String _label = 'Pen';
  double _priceExclVat = 2.5;
  int _quantity = 1;
  double _vatRate = 20; // en %
  // el historial de los últimos 5 cambios del total con IVA incluido
  final List<String> _history = [];

  // un controlador da acceso al TEXTO de un campo de entrada: aquí necesitamos uno
  // para devolverlo a su valor inicial (Reset). El ejemplo 05
  // los estudia en detalle
  final _labelField = TextEditingController(text: 'Pen');
  final _priceField = TextEditingController(text: '2.5');

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

  // TODOS los cambios del estado pasan por este método: anota el
  // total con IVA antes del cambio, aplica el cambio y completa
  // el historial si el total ha cambiado
  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();
        }
      }
    });
  }

  // cambiar el artículo restablece la cantidad a 1: lo hacemos donde sabemos
  // POR QUÉ cambia el estado
  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';
  }

  // el objeto State desaparece (salimos de la pantalla): se liberan los controladores
  @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: el título de la aplicación SIGUE al estado, como todo lo demás
    return Title(
      title: 'Incl. VAT: ${euros.format(_totalInclVat)}',
      color: Colors.indigo,
      child: Scaffold(
        appBar: AppBar(title: const Text('Example 02 - the state')),
        // ListView: una columna que se desplaza si excede la altura de la pantalla
        body: ListView(
          padding: const EdgeInsets.all(16),
          children: [
            Card(
              child: Padding(
                padding: const EdgeInsets.all(16),
                child: Column(
                  children: [
                    // onChanged: se llama en cada pulsación de tecla, con el nuevo texto
                    TextField(
                      controller: _labelField,
                      decoration: const InputDecoration(labelText: 'Item'),
                      onChanged: _changeLabel,
                    ),
                    TextField(
                      controller: _priceField,
                      decoration: const InputDecoration(labelText: 'Unit price excl. VAT'),
                      // el teclado numérico del teléfono, con el punto decimal
                      keyboardType: const TextInputType.numberWithOptions(decimal: true),
                      // tryParse: null si el texto no es un número; también se acepta una coma
                      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: el botón está deshabilitado
                          onPressed: _quantity > 0 ? () => _change(() => _quantity--) : null,
                        ),
                        Text('$_quantity', style: totalStyle),
                        IconButton(icon: const Icon(Icons.add), onPressed: () => _change(() => _quantity++)),
                      ],
                    ),
                    const SizedBox(height: 8),
                    // botones de los que solo UNO está seleccionado: la tasa de 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),
                    // una línea de texto por elemento del historial (ver ejemplo 03)
                    for (final line in _history) Text('• $line'),
                  ],
                ),
              ),
            ),
          ],
        ),
      ),
    );
  }

  // una línea "etiqueta ....... monto": un método que produce 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),
        ],
      ),
    );
  }
}
  • Línea 21: un formateador de importes al estilo del inglés de EE. UU. (€1,234.50), creado una sola vez fuera de los widgets, con el paquete [intl] (véase el ejemplo 09). [final]: una variable que se asigna una sola vez, pero cuyo valor no se conoce hasta el momento de la ejecución (a diferencia de [const]);
  • líneas 23–28: el programa; esta vez, [MaterialApp] se escribe directamente en [main]. Así comenzarán la mayoría de los ejemplos;
  • líneas 42–45: cuatro datos de estado, campos simples, de tipo: [String], [double], [int]. En [Dart], [int] y [double], existen dos tipos distintos de números;
  • línea 47: el historial de los últimos cinco cambios del total, una lista. El campo es [final]: la lista nunca se reemplazará; se modificará (agregados, eliminaciones);
  • líneas 52–53: dos controladores de campo de entrada. Un campo de entrada de [Flutter] almacena su texto en un controlador, que se crea y se le asigna: el texto puede entonces leerse o cambiarse desde el código (botón Restablecer). El ejemplo 05 los trata en detalle;
  • líneas 56–58: tres valores calculados a partir del estado. NO son campos de estado; son getters: métodos sin paréntesis que se usan como campos ([_totalInclVat]). Se recalculan cada vez que se leen, por lo que siempre están actualizados. Es la misma regla que ya vimos con [React]: solo almacenamos en el estado lo que no podemos calcular; todo lo demás se calcula;
  • Líneas 63–73: el historial de los totales con IVA depende de los valores sucesivos del total, lo que un getter no puede expresar. Por lo tanto, TODOS los cambios de estado pasan por el método [_change], que recibe como parámetro el cambio que se debe realizar (una función sin parámetros ni valor de retorno, de tipo [void Function()]): registra el total antes del cambio, aplica el cambio en `[setState]`, lo compara con el total después del cambio y actualiza el historial si ha cambiado. Este es el lugar natural para este cálculo: donde cambia el estado, y no en `[build]` (que solo debe describir la pantalla);
  • líneas 78–81: cambiar el artículo restablece la cantidad a 1. Esto se hace en el método que gestiona el cambio del campo, donde sabemos por qué cambia el estado;
  • líneas 85–93: varios cambios de estado dentro de un único [setState]: [build] se llamará una sola vez. Luego los controladores reciben su texto inicial: los campos lo muestran de inmediato;
  • líneas 98–101: [dispose] se llama cuando el objeto [State] desaparece definitivamente (se sale de la pantalla). Aquí se liberan los objetos creados, en este caso los controladores. El ejemplo 13 ilustrará el ciclo de vida de un objeto [State].

El método [build]:

  • línea 106: un estilo de texto, calculado a partir del tema: el estilo de título de tamaño mediano ([titleMedium]), en negrita. [copyWith] crea una copia de un objeto con propiedades modificadas: es una convención de [Flutter] que veremos a menudo. [!] le indica a [Dart] que el valor no es [null] (el tipo de [titleMedium] es [TextStyle?], un estilo, o [null]);
  • Líneas 109–111: el widget [Title] proporciona el título de la aplicación: en la web, es el título de la pestaña del navegador; en [Android], es el nombre que aparece en la lista de aplicaciones recientes. Mientras que [React] usaba un efecto ([useEffect]) para modificar [document.title] una vez mostrada la pantalla, [Flutter] no requiere nada especial: el título es un widget, descrito por [build] igual que el resto de la pantalla, y se actualiza automáticamente con el estado;
  • línea 115: [ListView] es una columna que se desplaza cuando supera la altura de la pantalla. En un teléfono, esto es casi siempre lo que se necesita: una [Column] demasiado alta quedaría cortada (y [Flutter] mostraría una franja amarilla y negra que indica un “desbordamiento”);
  • líneas 124–127: un campo de entrada ([TextField]): su controlador, su etiqueta ([decoration: InputDecoration(labelText: ...)]) y [onChanged], la función llamada con cada pulsación de tecla, junto con el nuevo texto;
  • líneas 130–135: el precio. [keyboardType] selecciona el teclado del teléfono: en este caso, el teclado numérico, con la coma. El texto ingresado se convierte en número mediante [double.tryParse], que devuelve [null] si el texto no es un número ([?? 0]: en este caso, 0). La coma francesa se acepta reemplazándola por un punto;
  • líneas 138–147: la cantidad, con dos botones, “–” y “+”. [Row] coloca a sus hijos uno al lado del otro; [Expanded] le da a su hijo todo el ancho restante. [IconButton]: un botón que es solo un ícono. [onPressed: null] deshabilita un botón: el valor no puede bajar de 0;
  • líneas 152–159: la tasa de IVA, tres botones “segmentados”, de los cuales solo uno está seleccionado. [selected] recibe un conjunto de valores ([{_vatRate}]: un [Set] de un elemento), [onSelectionChanged] el nuevo conjunto seleccionado;
  • líneas 173–177: los resultados: tres líneas generadas por el método [_line];
  • línea 190: una línea de texto por elemento del historial, generada por un bucle [for] escrito dentro de la lista de hijos (véase el ejemplo 03);
  • líneas 202–208: un método que crea widgets. [{TextStyle? style}]: un parámetro con nombre opcional que toma por defecto el valor [null] si no se proporciona. Dividir un [build] en métodos lo hace más legible; el ejemplo 10 mostrará que a menudo es mejor convertirlos en verdaderos widgets.

Modificamos el precio, la cantidad y la tasa, y luego el artículo:

Cada vez que cambia el total con IVA, se agrega una línea al historial. Cambiar el artículo restablece la cantidad a 1 (a la derecha).

La diferencia con [React] radica en un detalle: [React] refleja el comportamiento del componente, que recrea sus variables cada vez; el estado debe, por lo tanto, almacenarse por separado, mediante [useState]. En [Flutter], el estado reside en un objeto ([State]), creado una sola vez y conservado: son sus campos, y [build] es solo uno de sus métodos. Por lo tanto, no necesitamos hooks ni sus reglas (como no llamarlos dentro de una condición ni gestionar sus dependencias). La regla de oro sigue siendo la misma: modificamos el estado solo en [setState], y [build] simplemente describe la pantalla a partir del estado.

3.3. Ejemplo 03: escribir un árbol de widgets

En [Flutter] no hay un lenguaje de plantillas: la pantalla se escribe en [Dart]. Para las condiciones y los bucles, [Dart] ofrece herramientas para crear listas de hijos. Este ejemplo muestra una lista de médicos, que se puede filtrar:

// =========================================================================
// lib/ex03_widgets/main.dart - escribir un árbol de widgets
// -------------------------------------------------------------------------
// Flutter no tiene lenguaje de plantillas (ni HTML ni JSX): las
// pantallas se escriben en Dart, con constructores de widgets anidados.
// Para condiciones y bucles, Dart ofrece herramientas pensadas para
// construir LISTAS de hijos (children: [...]):
//   - if (condition) widget          : un hijo que solo EXISTE si la
//                                      condición es verdadera ("collection if");
//   - if (c) widgetA else widgetB    : uno O el otro;
//   - condition ? widgetA : widgetB  : lo mismo, en una expresión;
//   - for (final x in list) widget   : un hijo por cada elemento de la lista
//                                      ("collection for");
//   - ...otherList                   : los elementos de otra lista,
//                                      insertados en este lugar ("spread");
//   - switch (value) { pattern => ... } : un valor entre varios.
// Y todo lo que está antes del return de build() es código ordinario.
// =========================================================================

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

// una "enumeración": los únicos valores posibles de una especialidad
enum Specialty { generalPractitioner, pediatrician, cardiologist }

// una clase de datos: sus campos son final, un objeto Doctor
// nunca cambia. El constructor "const" permite crear constantes con ella
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),
];

// "un valor entre varios, según un valor": una EXPRESIÓN switch.
// El compilador comprueba que se manejan todos los casos de la enumeración
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 los demás 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 = ''; // el texto buscado
  bool _onlyAvailable = false;
  bool _showHelp = true;

  @override
  Widget build(BuildContext context) {
    // la lista mostrada: una variable ordinaria, recalculada en 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();

    // "uno de los tres bloques": se calcula ANTES del return, con 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: [
          // un hijo por médico: "collection for", con su posición (indexada)
          for (final (i, m) in displayed.indexed)
            // Opacity: los médicos no disponibles se muestran en gris
            Opacity(
              opacity: m.available ? 1 : 0.5,
              // ListTile: una fila de lista Material (ícono, título, subtítulo, elemento final)
              child: ListTile(
                leading: CircleAvatar(child: Text('${i + 1}')),
                title: Text('${m.title} ${m.firstName} ${m.lastName}'),
                // Wrap: como un Row, pero que pasa a la línea siguiente si falta espacio
                subtitle: Wrap(
                  spacing: 6,
                  crossAxisAlignment: WrapCrossAlignment.center,
                  children: [icon(m.specialty), Text(label(m.specialty))],
                ),
                trailing: Chip(
                  label: Text(m.available ? 'available' : 'unavailable'),
                  // un color elegido mediante una expresión condicional
                  backgroundColor: m.available ? Colors.green.shade100 : Colors.grey.shade300,
                ),
              ),
            ),
        ],
      );
    }

    return Scaffold(
      appBar: AppBar(
        // una imagen SVG distribuida con la aplicación (carpeta assets/, ver 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: un interruptor, con su etiqueta
          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 solo EXISTE si _showHelp es 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),
          // un estilo CALCULADO: el tamaño del texto depende del número de médicos mostrados
          Text(
            '${displayed.length} doctor(s) displayed - the size of this text depends on it.',
            style: TextStyle(fontSize: 12 + displayed.length * 2.0),
          ),
        ],
      ),
    );
  }
}
  • línea 24: una enumeración: los tres únicos valores posibles para una especialidad ([Specialty.pediatrician]...);
  • líneas 28–36: una clase de datos. Sus campos son [final]: un [Doctor] nunca cambia. El constructor [Doctor(this.id, this.title, ...)] asigna directamente sus argumentos a los campos del mismo nombre. Es [const]: se pueden crear médicos constantes (línea 39);
  • líneas 47–50: “un valor entre varios, según un valor”: una expresión [switch] (no una instrucción), que tiene un valor. Cada caso se escribe como [pattern => value]. Para una enumeración, el compilador verifica que se traten todos los casos: agregar una especialidad sin completar este [switch] provocaría un error de compilación;
  • líneas 53–56: el mismo principio se aplica al seleccionar un ícono; el patrón [_] significa “todos los demás casos”. Los íconos de [Material Design] son constantes de la clase [Icons];
  • líneas 77–79: el estado de la pantalla.

El método [build]:

  • líneas 84–91: la lista mostrada: una variable que se recalcula con cada llamada a [build]. [where] conserva los elementos que cumplen una condición; [toList()] convierte el resultado en una lista;
  • líneas 94–100: uno de tres valores posibles, seleccionado mediante [if] antes de [return]. Un widget es un valor como cualquier otro: se puede almacenar en una variable. [final Widget content;] declara la variable sin inicializarla: el compilador verifica que cada rama le asigne un valor exactamente una vez;
  • líneas 103–117: la lista. Un `[for]` escrito dentro de una lista literal (`[children: [ ... ]]`) agrega un elemento a ella en cada iteración del bucle: es un “for de colección”. [displayed.indexed] devuelve tuplas (posición, médico), que [(i, m)] “desempaqueta” en dos variables;
  • línea 106: [Opacity] vuelve parcialmente transparente a su hijo: los médicos no disponibles aparecen atenuados. El valor se calcula con el operador [? :];
  • líneas 108–112: [ListTile] es el elemento de lista de [Material Design]: un elemento inicial ([leading], aquí un disco que muestra la posición), un título, un subtítulo y un elemento final ([trailing]). Todos son widgets: cualquier widget. El subtítulo es un [Wrap]: una [Row] que pasa a la línea siguiente cuando no hay suficiente espacio (en un teléfono, el ícono y la especialidad no siempre cabrían junto a la etiqueta “disponible”);
  • Líneas 117–120: una “viñeta” ([Chip]), cuyo texto y color dependen del médico. [Colors.green.shade100]: un tono claro de verde.

[return]:

  • línea 131: una imagen SVG, incluida con la aplicación (carpeta [assets/], declarada en [pubspec.yaml]). [Flutter] no puede renderizar SVG por sí solo: el paquete [flutter_svg] proporciona el widget [SvgPicture]. Para una imagen PNG o JPEG, [Flutter] tiene el widget [Image.asset];
  • Líneas 138–139: el campo de búsqueda. [hintText] es el texto atenuado que se muestra mientras el campo está vacío; [prefixIcon] es un ícono a la izquierda. Esta vez, sin controlador: solo necesitamos el valor ingresado, recibido mediante [onChanged];
  • líneas 142–145: un interruptor, con su etiqueta: un elemento de lista que se toca para alternar;
  • línea 150: una función anónima, escrita directamente dentro del parámetro: alterna el estado;
  • líneas 155–160: un “if de colección”: la tarjeta de ayuda existe solo si [_showHelp] es verdadero. No hay ningún widget “oculto”: cuando la condición es falsa, la lista de hijos tiene un elemento menos;
  • línea 163: el contenido seleccionado anteriormente;
  • líneas 167–168: un estilo calculado: el tamaño del texto depende del número de médicos mostrados.

Para resumir las herramientas de [Dart] que reemplazan, dentro de una lista de hijos, lo que otros frameworks escriben en sus plantillas:

En Dart
Función
if (condition) widget
un hijo que existe solo si la condición es verdadera
if (c) widgetA else widgetB
uno u otro
condition? widgetA : widgetB
uno u otro, dentro de una expresión
for (final x in list) widget
un hijo por cada elemento de la lista
...otherList
los elementos de otra lista, insertados en este lugar
...[widgetA, widgetB]
varios hijos a la vez (a menudo después de una instrucción `if`)
switch (value) { pattern => widget }
un hijo entre varios, según un valor

Al inicio, luego después de escribir “gen” y ocultar la ayuda, y luego con “xyz”:

3.4. Ejemplo 04: eventos

Un widget interactivo recibe funciones como parámetros, que se llaman cuando ocurre algo; a menudo se denominan “callbacks”. Este ejemplo gestiona una lista de tareas pendientes:

// =========================================================================
// lib/ex04_events/main.dart - reaccionar a las acciones del usuario
// -------------------------------------------------------------------------
// Un widget interactivo recibe como parámetros las FUNCIONES a las que debe llamar
// cuando ocurre algo ("callbacks"):
//   - onPressed: f                  : se llama a f al presionar (botones);
//   - onPressed: () => remove(t)    : una función anónima, para pasarle sus
//                                     propios argumentos;
//   - onChanged, onSubmitted...     : la función recibe un dato (el
//                                     texto, la casilla marcada...);
//   - GestureDetector               : agrega gestos (toque, pulsación larga,
//                                     doble toque, arrastre...) a
//                                     CUALQUIER widget;
//   - Dismissible                   : deslizar una fila para eliminarla,
//                                     el gesto típico de un celular.
// Para actuar sobre un campo de entrada desde el código (leer o borrar su
// texto, darle el foco), le asociamos un CONTROLADOR y un 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 = [];
  // el controlador del campo: su texto (lectura, escritura);
  // el FocusNode: su foco (el cursor y el teclado del teléfono)
  final _field = TextEditingController();
  final _focus = FocusNode();
  // un campo del objeto State que NO se muestra: modificarlo
  // no requiere 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');
  }

  // lo llaman el botón Y la tecla Enter del teclado (onSubmitted)
  void _add() {
    final label = _field.text.trim();
    if (label.isEmpty) {
      return;
    }
    setState(() {
      _tasks.add(Task(_nextId++, label));
      _trace('added "$label"');
    });
    _field.clear();
    // el foco vuelve al campo: se puede escribir la siguiente tarea
    _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)');
    });
  }

  // los detalles de un toque: su posición, relativa al 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: atajos de teclado (un teclado
                // físico: computadora, emulador, tableta); Esc borra el 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)'),
                    // la tecla "Enter" del teclado del teléfono
                    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 la fila hacia la izquierda la elimina.
            // key: la IDENTIDAD de la fila, para que Flutter sepa cuál
            // ha desaparecido (ver la explicación en el 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(
                // la casilla está A LA IZQUIERDA, como en una lista de tareas
                controlAffinity: ListTileControlAffinity.leading,
                value: t.done,
                // la casilla pasa su nuevo valor (bool?, de ahí el "!")
                onChanged: (checked) => _toggle(t, checked!),
                title: Text(
                  t.label,
                  style: t.done ? const TextStyle(decoration: TextDecoration.lineThrough, color: Colors.grey) : null,
                ),
                // una función anónima: la tarea de ESTA fila como argumento
                secondary: IconButton(
                  icon: const Icon(Icons.delete_outline, color: Colors.red),
                  onPressed: () => _remove(t, 'button'),
                ),
              ),
            ),
          const SizedBox(height: 12),
          // GestureDetector: cualquier widget se vuelve sensible a los 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)),
        ],
      ),
    );
  }
}
  • líneas 23–28: una tarea. [done] no es [final]: la modificaremos. [{this.done = false}]: un parámetro con nombre opcional, con su valor por defecto;
  • líneas 49–53: el estado: la lista de tareas y un registro de eventos;
  • líneas 56–57: para manipular el campo de entrada desde el código, se le asocian dos objetos: un controlador ([TextEditingController]), que da acceso a su texto, y un [FocusNode], que da acceso a su foco (el cursor parpadeante y el teclado del teléfono, que se abre cuando un campo tiene el foco);
  • Línea 60: un campo del objeto [State] que no se muestra: modificarlo no requiere un [setState]. Esto es lo que [React] llama una “referencia” ([useRef]); en [Flutter], es un campo ordinario;
  • líneas 63–66: el controlador y el [FocusNode] se liberan cuando la pantalla desaparece;
  • líneas 69–71: una línea adicional al principio del registro. [TimeOfDay] es la hora del día de [Flutter]; [format(context)] la formatea según las convenciones del idioma de la aplicación;
  • líneas 75–86: agregar una tarea, activado por el botón Y por la tecla Enter del teclado. Leemos el texto del controlador ([_field.text]), agregamos la tarea (en [setState]), vaciamos el campo ([_field.clear()]) y le devolvemos el foco ([_focus.requestFocus()]): ya se puede escribir la siguiente tarea;
  • Líneas 89–92: marcar o desmarcar una tarea. Modificamos el propio objeto [Task], en [setState]. A diferencia de [React], no es necesario crear una nueva lista: [setState] notifica [Flutter] que el estado ha cambiado, sin importar cómo cambió;
  • líneas 96–99: eliminación, ya sea mediante el botón o deslizando (véase más abajo);
  • Líneas 104–106: la función llamada al tocar el área inferior. Recibe los detalles del evento: en este caso, [localPosition], la posición del dedo relativa al widget tocado.

El método [build]:

  • Líneas 121–122: [CallbackShortcuts] asocia atajos de teclado con funciones para un teclado físico (computadora, emulador, tableta con teclado): la tecla Esc vacía el campo. [{ key: function }] es un [Map] literal;
  • Líneas 124–129: el campo de entrada, vinculado a su controlador y a su [FocusNode]. [textInputAction] selecciona la tecla “Enter” del teclado del teléfono; [onSubmitted] se llama cuando se presiona, junto con el texto (que no se usa: el parámetro se llama [_], por convención);
  • línea 134: el botón llama al mismo método;
  • líneas 138–151: una línea por tarea, dentro de un [Dismissible]: un widget que se desliza con el dedo para eliminarlo, el gesto típico de una lista en un teléfono. [direction]: solo hacia la izquierda; [background]: lo que aparece debajo de la fila durante el deslizamiento (un ícono de papelera sobre un fondo rojo); [onDismissed]: la función llamada cuando la fila se desliza fuera de la pantalla;
  • línea 143: la clave de [Dismissible]. Cuando cambia una lista de widgets, [Flutter] compara la lista anterior con la nueva para determinar qué widgets conservar: sin clave, los empareja por su posición (el primero con el primero, el segundo con el segundo, y así sucesivamente). Si la primera tarea desaparece, la segunda ocuparía su lugar… con el estado de la primera. Una clave le da a cada widget una identidad: [Flutter] entonces empareja los widgets por sus claves. La clave debe ser única entre los hermanos y estable: el identificador de la tarea, no su posición. Un [Dismissible] requiere una clave;
  • líneas 152–157: un elemento de lista con una casilla de verificación. [controlAffinity] coloca la casilla a la izquierda. [onChanged] recibe el nuevo valor de la casilla, de tipo [bool?] (una casilla puede tener un tercer estado, “indeterminado”): [!] indica que no es [null];
  • línea 160: el estilo de la etiqueta depende de la tarea: tachado y gris si está hecha, el estilo por defecto ([null]) en caso contrario;
  • líneas 163–165: un botón de “papelera”. La función anónima [() => _remove(t, 'button')] permite pasar argumentos: la tarea de esta línea;
  • Líneas 171–174: [GestureDetector] hace que cualquier widget responda a gestos: toque ([onTap], [onTapDown]...), doble toque, pulsación larga, deslizamiento, pellizco... Aquí, una simple caja de color ([Container]) responde a tres gestos;
  • líneas 175–178: [Container] es una caja que permite especificar margen, fondo, borde, tamaño y alineación. [decoration] describe su fondo: un color, esquinas redondeadas. [Color(0xFFE7F5FF)]: un color especificado por su código ARGB (opacidad FF, luego rojo, verde, azul);
  • línea 184: el registro.

Agregue una tarea, marque la segunda, toque el área inferior; luego arrastre la primera tarea hacia la izquierda (a la mitad durante el arrastre; a la derecha una vez eliminada la línea):

En [React], los eventos del navegador ([click], [keydown]...) son los mismos para todos los elementos; en [Flutter], cada widget interactivo declara los suyos, con parámetros tipados ([onPressed], [onChanged], [onSubmitted]...), y [GestureDetector] agrega gestos a los que no tienen ninguno. El editor, que conoce los parámetros de cada widget, los sugiere a medida que se escribe.

3.5. Ejemplo 05: todos los tipos de campos

Este ejemplo utiliza el formulario del ejemplo 05 del curso de [React], con los campos de entrada de [Flutter]: cuadros de texto, botones de opción, casillas de verificación, listas desplegables, listas con viñetas, controles deslizantes y calendarios.

// =========================================================================
// lib/ex05_controlled_fields/main.dart - todos los tipos de campos
// -------------------------------------------------------------------------
// Un campo CONTROLADO muestra un valor del estado y notifica al widget de
// cada cambio (onChanged), que actualiza el estado: el estado es la
// única fuente de verdad. Modificar el estado (desde el código) modifica el campo.
// Lo que onChanged pasa depende del campo:
//   - TextField (con un controlador)  -> el texto (String);
//   - Checkbox, Switch                 -> bool? / bool;
//   - Radio (en un RadioGroup)          -> el valor del botón elegido;
//   - DropdownButton                   -> el valor del elemento elegido;
//   - FilterChip                       -> bool: ¿está seleccionado el chip?
//   - Slider                           -> double;
//   - showDatePicker (un diálogo)      -> un Future<DateTime?>.
// El TextField es un caso especial: guarda su texto en un
// TextEditingController, que nosotros creamos, leemos (controller.text),
// modificamos... y liberamos (dispose).
// Misma forma que el ejemplo 05 del curso de React; todo ocurre en el
// teléfono, sin 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),
      // los textos del propio Flutter (calendario, botones OK / CANCEL) en
      // inglés (ver ejemplo 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> {
  // un estado por cada campo del formulario
  String _title = 'Mme';
  final _name = TextEditingController();
  final _age = TextEditingController(text: '30');
  String _presentation = '';
  bool _newsletter = false;
  final Set<String> _hobbies = {'reading'}; // un CONJUNTO: sin duplicados
  String _country = 'fr';
  final Set<String> _languages = {};
  DateTime? _birthDate; // null: todavía no se ha elegido
  double _satisfaction = 3;
  String? _sent;

  @override
  void initState() {
    super.initState();
    // un controlador NOTIFICA a sus oyentes en cada cambio del texto:
    // la pantalla se redibuja (el modelo se muestra en vivo)
    _name.addListener(_redraw);
    _age.addListener(_redraw);
  }

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

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

  // "2026-10-05": el formato de fecha de la API de RdvMedecins
  String? get _birthDateText => _birthDate?.toIso8601String().substring(0, 10);

  // todos los valores, reunidos en un solo objeto (lo que se enviaría a un servidor)
  Map<String, Object?> get _model => {
    'title': _title,
    'name': _name.text.trim(),
    'age': int.tryParse(_age.text), // null si el campo está vacío
    'presentation': _presentation,
    'newsletter': _newsletter,
    'hobbies': _hobbies.toList(),
    'country': _country,
    'languages': _languages.toList(),
    'birthDate': _birthDateText,
    'satisfaction': _satisfaction.round(),
  };

  // la fecha de nacimiento: un diálogo de calendario. showDatePicker devuelve
  // un Future, la fecha elegida (o null: diálogo cerrado sin elegir)
  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);
    }
  }

  // el estado modificado POR EL CÓDIGO: los campos lo siguen
  void _example() {
    setState(() {
      _title = 'Mr';
      _name.text = 'MARTIN';
      _age.text = '42';
      _hobbies
        ..clear()
        ..addAll(['sport', 'cinema']);
      _country = 'be';
    });
  }

  void _send() {
    // JsonEncoder.withIndent: JSON con sangría; jsonEncode: en una sola línea
    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: el valor elegido (groupValue) y la función a la que se llama
          // cuando se elige uno de los botones Radio que contiene
          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 cuando su hijo GANA o PIERDE el foco. El campo
          // no está vinculado al estado en cada pulsación de tecla: su texto solo se lee
          // al salir del campo (como onBlur en 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, // SIN setState: no se redibuja nada
            ),
          ),
          // una sola casilla: 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),
          // varios chips para UN conjunto: el valor se agrega o se quita
          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),
              // una lista desplegable: value indica qué elemento está elegido
              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(
                // un control deslizante: 5 posiciones, 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: los botones pasan a la línea siguiente en una pantalla estrecha
          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('  '): el JSON, con sangría de 2 espacios
            child: Text(
              const JsonEncoder.withIndent('  ').convert(_model),
              style: const TextStyle(fontFamily: 'RobotoMono', fontSize: 12),
            ),
          ),
          // un bloque que solo existe después de un envío; ...[ ] inserta VARIOS 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)),
            ),
          ],
        ],
      ),
    );
  }
}

Un campo controlado muestra un valor del estado y notifica al widget de cualquier cambio ([onChanged]), que actualiza el estado: el estado es la única fuente de verdad. Esto es válido para todos los campos de [Flutter]... excepto los cuadros de texto, que almacenan su texto en un controlador.

  • Líneas 39–41: el texto de [Flutter] en sí (los días y meses del calendario, los botones “OK” y “CANCEL” de sus ventanas) está en inglés por defecto. Declaramos los idiomas de la aplicación ([supportedLocales]), el idioma seleccionado ([locale]) y los “delegados” que proporcionan las traducciones de [Flutter], en el paquete [flutter_localizations]. El ejemplo 21 volverá sobre esto;
  • líneas 56–66: un estado por campo. [final _name = TextEditingController()]: para un campo de texto, el estado es el propio controlador; [Set<String>]: un conjunto (sin duplicados) de pasatiempos e idiomas; [DateTime? _birthDate]: una fecha, o [null] hasta que se selecciona una;
  • líneas 69–74: [initState] se llama una sola vez, cuando se crea el objeto [State] (véase el ejemplo 13). Un controlador notifica a sus oyentes ([addListener]) de cada cambio en su texto: la pantalla se vuelve a dibujar para que el modelo mostrado en la parte inferior siga la entrada. [setState(() {})]: no hay nada que cambiar, solo que volver a dibujar;
  • línea 87: la fecha en el formato de la API [RdvMedecins], “2026-10-05”. [_birthDate?.toIso8601String()]: el operador [?.] llama al método solo si [_birthDate] no es [null] (de lo contrario, el resultado es [null]);
  • líneas 90–100: todos los valores, combinados en un [Map] (que se enviaría a un servidor). [int.tryParse(_age.text)]: la edad, o [null] si el campo no es un número;
  • líneas 105–113: la fecha de nacimiento se selecciona en una ventana de calendario. [showDatePicker] abre la ventana y devuelve un [Future]: la fecha seleccionada, más tarde, cuando el usuario ha cerrado la ventana (o [null] si la cerró sin hacer una selección). El método es [async]: [await] espera a que [Future] termine sin bloquear la aplicación. Este mecanismo se usa dondequiera que haya que esperar (una ventana, un servidor);
  • líneas 118–126: el estado modificado por el código: los campos lo siguen. Para un cuadro de texto, se escribe en su controlador. [..clear()..addAll([...])]: la “cascada” de [Dart], varias llamadas a métodos sobre el mismo objeto;
  • línea 132: [jsonEncode] (de [dart:convert]) crea el JSON a partir de un [Map].

Los campos en [build]:

  • líneas 146–151: botones de opción. [RadioGroup] contiene el valor seleccionado ([groupValue]) y la función llamada cuando se selecciona otro valor ([onChanged]); contiene los botones [Radio], cada uno con su propio valor. [...[a, b, c]] inserta varios widgets a la vez: para cada título, un botón, su etiqueta y un espacio;
  • líneas 160–169: dos campos de texto lado a lado, en un [Row]. [Expanded(flex: 2, ...)]: el nombre ocupa el doble de espacio que la edad. El teclado del campo de la edad es numérico;
  • Líneas 178–186: un campo no controlado: [TextFormField] puede recibir un valor inicial ([initialValue]) en lugar de un controlador, y gestionar su propio texto. El texto se actualiza con cada pulsación de tecla, SIN [setState]: no se redibuja nada. El widget [Focus] notifica cuando su hijo gana o pierde el foco ([onFocusChange]): el redibujado solo ocurre al salir del campo. Esto equivale al evento [blur] de HTML;
  • líneas 190–195: una sola casilla de verificación y su etiqueta;
  • líneas 199–206: opciones múltiples para UN conjunto: casillas de verificación para seleccionar ([FilterChip]). Cada viñeta está seleccionada si el conjunto contiene su valor; al tocarla se agrega o se quita el valor. [Wrap] coloca a sus hijos uno al lado del otro y pasa a la línea siguiente cuando ya no hay espacio;
  • líneas 216–222: una lista desplegable. [value] indica qué elemento está seleccionado; [items] enumera los elementos, cada uno con su valor y su widget. [for (final MapEntry(key: code, value: name) in countries.entries)] recorre las entradas del [Map] [countries] “desempaquetando” cada una en dos variables, [code] y [name];
  • líneas 230–234: idiomas hablados, también listados con viñetas. (En [Flutter], no existe una lista de selección múltiple: las viñetas o las casillas de verificación cumplen esta función);
  • líneas 244–249: un control deslizante, de 1 a 5, en cuatro intervalos ([divisions]). Su valor es un [double];
  • líneas 254–259: la fecha de nacimiento y el botón que abre el calendario;
  • líneas 278–279: el modelo, en vivo: su JSON, con sangría de dos espacios, en la fuente monoespaciada incluida con la aplicación;
  • líneas 283–289: un bloque que solo aparece después de enviar un mensaje: [if] seguido de [...[ ]] inserta varios widgets, o ninguno.

Usted elige el título, un nombre, pasatiempos y un idioma; luego abre el calendario; luego envía:

La siguiente tabla resume lo que cada campo transmite a su función correspondiente, [onChanged]:

Campo
Valor transmitido
TextField, TextFormField
String (texto); o se lee el controlador
Checkbox, CheckboxListTile
bool? (marcada, desmarcada o indeterminada)
Switch, SwitchListTile
bool
Radio (en un RadioGroup)
el valor del botón seleccionado (T?)
DropdownButton<T>
el valor del elemento seleccionado (T?)
FilterChip
bool: ¿está seleccionada la viñeta?
SegmentedButton<T>
Set<T>: los valores seleccionados
Slider
double
showDatePicker
Future<DateTime?>: la fecha seleccionada, más adelante

3.6. Ejemplo 06: un formulario, un objeto, un reducer

El ejemplo 05 tenía un campo de estado por cada campo del formulario. Para un formulario real, preferimos un objeto que contenga todos los valores (el modelo) y describimos sus cambios en una sola función, el reducer: [reducer(currentState, action) -> newState]. Esto es lo que hace el hook [useReducer] en [React]; en [Flutter], no hay nada que importar: [Dart] proporciona todo lo necesario.

// =========================================================================
// lib/ex06_reducer/main.dart - un formulario, un objeto, un reducer
// -------------------------------------------------------------------------
// El ejemplo 05 tenía un campo de estado por cada campo del formulario. Para un
// formulario real, preferimos UN objeto que contenga todos los valores, el
// MODELO (aquí un objeto Profile, no modificable), y describimos sus
// cambios en una sola función, el REDUCER:
//
//     reducer(currentState, action) -> newState
//
// El widget ya no modifica el estado: DESCRIBE lo ocurrido, con un objeto
// ProfileAction (Edit(Field.lastName, 'Dupont'), Leave(Field.lastName)...), y
// el reducer deduce de él el nuevo estado. Toda la lógica está en un
// solo lugar, en una función PURA (misma entrada, misma salida, sin efecto
// secundario), fácil de probar.
// Dart se presta bien a esto: una clase "sealed" enumera todas las acciones
// posibles, y un switch sobre una acción lo verifica el compilador
// (un caso olvidado es un error).
//
// El estado también guarda, por cada campo, si ha sido "tocado" (abandonado al
// menos una vez); de ahí deducimos si está "modificado" (su valor difiere del
// valor inicial) y si está deshabilitado.
// =========================================================================

import 'dart:convert';

import 'package:flutter/material.dart';

// el nombre de cada campo del formulario
enum Field { title, firstName, lastName, age, newsletter, email, country, birthDate, presentation }

// los datos del formulario: un objeto NO MODIFICABLE (todos sus campos son
// final). Para "modificarlo", construimos uno nuevo (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,
  });

  // una copia, en la que se cambian algunos campos (los demás se conservan);
  // "??": el nuevo valor si se proporciona, de lo contrario el anterior
  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,
    );
  }

  // el valor de un campo, designado por su nombre
  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,
  };

  // una copia en la que UN campo, designado por su nombre, tiene un nuevo 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: '',
);

// el estado completo: los valores y los campos ya abandonados
class ProfileState {
  final Profile values;
  final Set<Field> touched;

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

// las acciones posibles. "sealed": no hay otras que las de
// este archivo, el compilador lo sabe
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();
}

// el reducer: NUNCA modifica el estado que recibe, devuelve uno nuevo.
// El switch "desestructura" cada acción: Edit(:final field, ...) lee
// sus campos en variables del mismo nombre
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];
// los campos de texto: cada uno tendrá su controlador
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, {});
  // un controlador por campo de texto; un "map": Field -> controlador
  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();
  }

  // LA única manera de cambiar el estado: describir lo ocurrido
  void _dispatch(ProfileAction action) {
    setState(() => _state = reducer(_state, action));
    // el reducer puede haber cambiado un texto (Uppercase, Reset): los
    // campos de entrada deben mostrarlo
    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 DEDUCIDOS del estado
  bool _modified(Field c) => _v.value(c) != initial.value(c);
  bool _disabled(Field c) => c == Field.email && !_v.newsletter; // el correo electrónico requiere el boletín informativo
  bool get _formModified => Field.values.any(_modified);

  // un campo de texto vinculado al modelo: un método que lo construye
  Widget _field(Field field, String label, {int lines = 1}) {
    // Focus: sabemos cuándo se ABANDONA el campo (pierde el 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())),
                  // se suelta el control deslizante: el campo ha sido "abandonado"
                  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: una tabla, con sus columnas y sus filas
          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),
                ),
              ],
            ),
          ),
        ],
      ),
    );
  }
}

El modelo:

  • línea 30: el nombre de cada campo del formulario;
  • líneas 34–43: los datos del formulario: un objeto no editable, todos cuyos campos son [final];
  • líneas 45–54: un constructor con parámetros con nombre, todos obligatorios ([required]);
  • líneas 59–79: para “modificar” un objeto no editable, se crea una copia en la que se cambian algunos campos: este es el método [copyWith], una variante de [Flutter] (que encontramos con [TextStyle]). Cada parámetro es opcional ([String? title]: una cadena o [null]); [title ?? this.title]: el valor nuevo si se proporciona; de lo contrario, el anterior;
  • líneas 84–93: el valor de un campo designado por su nombre: una expresión [switch] sobre la enumeración;
  • líneas 97–106: una copia en la que UN campo, designado por su nombre, tiene un valor nuevo. [v as String]: el valor recibido (de tipo [Object], que puede ser cualquier cosa) se convierte en una cadena; si no fuera una cadena, se produciría un error en tiempo de ejecución;
  • línea 109: un [Map] “nombre del campo -> valor”, creado por un [for] dentro de un literal [Map]. [c.name]: el nombre de un valor de la enumeración (“firstName”);
  • líneas 112–121: los valores iniciales;
  • líneas 125–129: el estado completo: los valores y todos los campos que ya se han procesado (“tocados”).

Las acciones y el reducer:

  • líneas 134–154: las acciones posibles: una clase sellada ([sealed]) y sus cuatro subclases. [sealed] le indica al compilador que no hay más subclases que las de este archivo. Una acción describe lo que ocurrió: [Edit(Field.lastName, 'Dupont')], [Leave(Field.lastName)]...;
  • líneas 160–167: el reducer. Es una función pura: misma entrada, misma salida, sin efectos secundarios; nunca modifica el estado recibido, sino que devuelve uno nuevo. El [switch] se aplica a la acción, y cada caso es un patrón que prueba su tipo: [Edit(:final field, :final value)] verifica que la acción sea un [Edit], y almacena sus campos [field] y [value] en variables del mismo nombre. Como la clase es sellada, el compilador verifica que las cuatro acciones estén cubiertas; agregar una quinta sin completar el reducer produciría un error de compilación;
  • línea 162: un nuevo conjunto, compuesto por los elementos del conjunto anterior ([...state.touched]) y el campo que se abandona.

La pantalla:

  • línea 193: el estado de la pantalla: UN solo campo, el objeto [ProfileState];
  • línea 195: un controlador de campo de texto, en un [Map] creado por un [for];
  • líneas 206–213: el ÚNICO método para cambiar el estado: describir lo que ocurrió. [_dispatch] (el nombre que le da [React]) calcula el nuevo estado mediante el reducer, dentro de [setState]. Luego, dado que el reducer pudo haber modificado algún texto (Uppercase, Reset), los valores se copian a los controladores que aún no los tienen;
  • líneas 221–223: valores derivados del estado: un campo está modificado si su valor difiere del valor inicial; el correo electrónico está deshabilitado sin el boletín; el formulario está modificado si alguno de sus campos lo está ([any]). [Field.values]: la lista de valores de la enumeración;
  • líneas 226–237: un método que crea un campo de texto vinculado al modelo: su controlador, su estado deshabilitado ([enabled]) y dos acciones: [Edit] en cada pulsación de tecla, [Leave] cuando pierde el foco;
  • En [build], cada campo describe sus cambios mediante una acción: [_dispatch(Edit(Field.title, t!))], [_dispatch(const Uppercase())]...;
  • líneas 320–338: una tabla ([DataTable]), con sus columnas y filas: el estado de cada campo monitoreado;
  • líneas 344–349: un texto compuesto por varias secciones con estilos diferentes: [Text.rich] y su [TextSpan].

Cambiamos el nombre, salimos del campo y nos suscribimos al boletín; luego ponemos el nombre en mayúsculas:

Toda la lógica del formulario está contenida en el reducer (una función de apenas unas líneas, sin ningún widget), que se puede probar por separado. Ahora los widgets simplemente muestran el estado y describen lo que ocurre.

3.7. Ejemplo 07: validación manual de un formulario

Una función pura, [validate(account)], devuelve los errores de los campos; se llama cada vez que se ejecuta [build], por lo que los errores siempre están al día. No se muestran de inmediato (un formulario vacío cubierto de rojo resulta desagradable), solo para un campo que ya se ha abandonado. Al enviar el formulario se muestran todos los errores.

// =========================================================================
// lib/ex07_validation/main.dart - validar un formulario, a mano
// -------------------------------------------------------------------------
// Una función PURA, validate(account), devuelve los errores de los campos; la
// llamamos en cada build(), así que los errores siempre están actualizados.
// No los mostramos de inmediato (un formulario vacío cubierto de rojo es
// desagradable): solo para un campo ya abandonado ("touched"). Al enviar
// se marcan todos los campos como tocados y solo se actúa si el formulario
// es válido. Un TextField muestra un error debajo del campo, en rojo,
// cuando se le da un texto de error: InputDecoration(errorText: ...).
//
// Mismas reglas que el servidor de RdvMedecins (formulario "Crear una cuenta").
// ADVERTENCIA: esta validación es solo una COMODIDAD para el usuario (una
// respuesta inmediata, sin ida y vuelta al servidor). No protege
// nada: cualquiera puede enviar al servidor una solicitud construida
// a mano (curl...). Por eso el servidor SIEMPRE vuelve a validarlo todo (ver ejemplo 25).
// =========================================================================

import 'package:flutter/material.dart';

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

// un "record": un pequeño grupo de valores con nombre, sin tener que escribir una clase
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;

// las reglas: una función pura, que solo depende de su argumento.
// Devuelve, por cada campo con error, su mensaje
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.';
  }
  // una regla que compara DOS 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';
  // un controlador 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();
  }

  // la cuenta, tal como se escribió: un record construido bajo 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 los errores aparecen
      // aquí, la cuenta se enviaría al servidor (ver ejemplo 25)
      _success = validate(_account).isEmpty;
    });
  }

  @override
  Widget build(BuildContext context) {
    // los errores: se recalculan en cada build(), nunca se guardan en el estado
    final errors = validate(_account);

    // el error a MOSTRAR para un campo: solo si ha sido tocado
    String? error(Field c) => _touched.contains(c) ? errors[c] : null;

    // un campo de texto: etiqueta, error y una marca de verificación verde si está tocado y es 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, // los caracteres están ocultos
          decoration: InputDecoration(
            labelText: label,
            errorText: error(c),
            // el error puede ocupar dos líneas
            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),
        ],
      ),
    );
  }
}

// un pequeño widget privado: un mensaje sobre un fondo de color
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),
    );
  }
}
  • línea 24: la cuenta ingresada es un record: un pequeño grupo de valores con nombre, sin necesidad de escribir una clase. [typedef] le asigna un nombre. Un record se escribe como [(title: 'Mr', firstName: 'Marie', ...)] y se lee como [account.firstName];
  • líneas 27–28: una expresión regular (el formato de un nombre de usuario) y una constante: las mismas reglas que el servidor [RdvMedecins];
  • líneas 32–59: las reglas: una función pura que depende solo de su argumento y devuelve un [Map] “campo con error → mensaje”. La última regla compara DOS campos: la confirmación y la contraseña;
  • líneas 82–84: un validador por cada campo de texto;
  • línea 86: los campos que ya se han abandonado;
  • líneas 99–105: la cuenta, tal como se ingresó: un record generado bajo demanda a partir de los validadores. [_texts[Field.firstName]!]: el acceso a un [Map] devuelve un valor o [null] (puede que falte la clave); el [!] confirma que está presente;
  • líneas 108–113: el envío marca todos los campos como tocados (aparecen los errores) y luego actúa solo si el formulario es válido;
  • línea 120: en [build], los errores se recalculan cada vez; nunca se almacenan en el estado;
  • línea 123: una función local: el error que se debe mostrar para un campo, solo si ha sido tocado;
  • líneas 126–142: una función local que crea un campo. [InputDecoration] sabe mostrar un error: [errorText]. Cuando no es [null], el campo se enmarca en rojo y el mensaje se muestra debajo (en no más de dos líneas: [errorMaxLines]). [suffixIcon]: un ícono a la derecha del campo (en este caso, una marca de verificación verde para un campo completado y válido). [obscureText] oculta los caracteres de una contraseña;
  • líneas 165–168: mensajes de fin de formulario;
  • líneas 176–187: un pequeño widget privado, para no repetir dos veces el mismo recuadro de color.

Complete algunos campos y envíe; luego corrija todo y vuelva a enviar:

ATENCIÓN: esta validación es solo una comodidad para el usuario: una respuesta inmediata sin intercambio con el servidor. No protege nada: cualquiera puede enviar al servidor una solicitud elaborada manualmente ([curl]…), y el código de una aplicación móvil puede modificarse. Por eso el servidor siempre revalida todo (véase el ejemplo 25).

3.8. Ejemplo 08: formularios de Flutter, Form y FormField

El formulario del ejemplo 07, escrito con las herramientas que proporciona [Flutter] mismo. Mientras que [React] requiere una biblioteca ([React Hook Form]), [Flutter] tiene sus propios widgets de formulario:

// =========================================================================
// lib/ex08_form/main.dart - los formularios de Flutter: Form y FormField
// -------------------------------------------------------------------------
// El formulario del ejemplo 07, escrito con las herramientas de formulario que
// Flutter proporciona por sí mismo:
//   - Form: un widget que AGRUPA campos de formulario (FormField);
//     se accede a él mediante una "clave global", GlobalKey<FormState>;
//   - TextFormField, DropdownButtonFormField...: campos que saben
//     validarse a sí mismos. Su parámetro validator es una función:
//         (value) -> null si el valor es correcto, de lo contrario el mensaje de error;
//   - autovalidateMode: CUÁNDO validar (aquí, en cuanto el usuario ha
//     modificado el campo, y luego en cada pulsación de tecla);
//   - form.validate(): valida TODOS los campos, muestra sus
//     errores y devuelve true si todo está bien;
//   - form.save(): llama al onSaved de cada campo, que guarda su
//     valor donde queramos.
// Los campos NO están controlados: cada uno guarda su valor, el Form solo
// lo lee al validar y al guardar.
// =========================================================================

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> {
  // la clave que da acceso al estado del formulario (validate, save, reset)
  final _formKey = GlobalKey<FormState>();
  // la clave de UN campo: para volver a validar la confirmación cuando cambia la contraseña
  final _confirmationKey = GlobalKey<FormFieldState<String>>();
  // la contraseña se lee en la regla de la confirmación: un controlador
  final _password = TextEditingController();
  // los valores guardados por los callbacks onSaved
  final Map<String, String> _account = {};
  // null: aún no se ha enviado; '': envío rechazado; de lo contrario, el 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 su valor en _account
    setState(() => _sent = jsonEncode(_account));
  }

  // FÁBRICAS de reglas: cada una devuelve una función de validación
  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: el valor inicial; el campo gestiona luego el suyo propio
            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,
              // una regla escrita directamente: una función 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;
              },
              // la contraseña cambia: la confirmación se valida de nuevo
              // (si ya se ha escrito)
              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,
              // una regla que lee OTRO 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'),
              ),
          ],
        ),
      ),
    );
  }
}
  • Línea 46: un formulario llamado [Form] contiene campos de formulario. Para interactuar con él desde el código (validar, guardar), le asignamos una clave global, [GlobalKey]: un objeto que da acceso al estado de un widget en el árbol ([_formKey.currentState]);
  • línea 48: la clave de UN campo, para poder revalidarlo por separado;
  • línea 50: un controlador para la contraseña: la regla de confirmación debe leerlo;
  • línea 52: los valores almacenados al enviar;
  • líneas 62–69: [validate()] valida todos los campos del formulario, muestra los errores que haya y devuelve [true] si todo es correcto. [save()] llama entonces a la función [onSaved] de cada campo, que asigna su valor;
  • líneas 73–77: generadores de reglas. Una regla de validación ([FormFieldValidator]) es una función que recibe el valor del campo y devuelve [null] si es válido; de lo contrario, devuelve el mensaje de error. [_required('...')] crea una regla; [_maximum(20, other)] crea una regla que aplica primero la regla [other]y luego la suya ([??]: si la primera no encuentra nada);
  • línea 83: el formulario y su clave;
  • líneas 89–94: una lista desplegable que también es un campo de formulario. [initialValue]: su valor inicial; después, el campo gestiona su propio valor;
  • líneas 96–100: un [TextFormField] es un [TextField] que además es un campo de formulario: tiene una regla ([validator]), una función de guardado ([onSaved]) y un modo de validación automática: [AutovalidateMode.onUserInteraction] valida el campo en cuanto el usuario lo modifica, y luego con cada pulsación de tecla;
  • líneas 112–117: una regla escrita directamente, con dos pruebas;
  • líneas 132–134: cuando cambia la contraseña, la confirmación se revalida mediante la clave del campo, si ya se ha ingresado;
  • línea 144: una regla que lee OTRO campo.

Ingrese algunos valores incorrectos y envíe; luego corríjalos:

¿Cuál de los dos métodos conviene elegir? [Form] y [TextFormField] bastan para un formulario cuyas reglas se escriben en la aplicación. Pero en este curso, las reglas del servidor tienen prioridad: el caso de estudio no tiene reglas en la aplicación y muestra el error devuelto por el servidor debajo de cada campo (ejemplo 25). Este es el método utilizado en el ejemplo 07, que trata los campos y sus errores.

3.9. Ejemplo 09: formateo de valores

Cada fila de la tabla muestra un fragmento de código y lo que muestra en pantalla.

3.9.1. Funciones de formateo

[Flutter] no tiene un mecanismo de formateo integrado (los “pipes” de [Angular]): en [build], llamamos a funciones estándar, almacenadas en un archivo y que se pueden probar por separado:

// =========================================================================
// lib/ex09_formatting/formatting.dart - funciones de formato "caseras"
// -------------------------------------------------------------------------
// Flutter no tiene un mecanismo propio de formato (Angular tiene sus
// "pipes"): en build(), llamamos a FUNCIONES ordinarias, guardadas
// en un archivo y que se pueden probar por separado:
//     timeRange(slot)           -> "8:00 - 8:20"
//     timeRange(slot, Part.start) -> "8:00"
// Dart también permite AGREGAR métodos a un tipo existente, con una
// "extension": 'marie pelissier'.capitalized -> 'Marie Pelissier'.
// Para fechas, números, montos, el paquete intl conoce las
// convenciones de cada idioma (ver main.dart).
// =========================================================================

// una franja horaria, tal como la describe la API de 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" en lugar de "8:5"
String _time(int h, int m) => '$h:${m.toString().padLeft(2, '0')}';

// un parámetro OPCIONAL, con su valor por defecto: [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)}',
};

// una EXTENSIÓN del tipo String: nuevos métodos para TODAS las cadenas
extension Formatting on String {
  // "marie pelissier" -> "Marie Pelissier"; \p{L}: una letra, con o sin acento
  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" (el formato de la API de RdvMedecins) -> una fecha
DateTime toDate(String day) => DateTime.parse(day);
  • líneas 16–22: un horario, tal como lo describe la API [RdvMedecins]: horas y minutos, como números;
  • línea 28: “8:05” en lugar de “8:5”: [padLeft(2, '0')] rellena con ceros a la izquierda;
  • líneas 31–34: una función con un parámetro posicional opcional (entre corchetes), junto con su valor predeterminado: [timeRange(c)] o [timeRange(c, Part.start)];
  • líneas 38–47: una extensión: agrega métodos (en este caso, getters) al tipo [String], a TODAS las cadenas: ['marie pelissier'.capitalized]. Es una particularidad de [Dart], muy útil para el formateo. [replaceAllMapped] reemplaza cada palabra (una secuencia de letras, con o sin acento: [\p{L}+] con [unicode: true]) por el valor devuelto por la función;
  • línea 51: “2026-10-05” (el formato de la API) -> una fecha ([DateTime]).

3.9.2. La pantalla

// =========================================================================
// lib/ex09_formatting/main.dart - formatear valores
// -------------------------------------------------------------------------
// Cada fila de la tabla muestra un fragmento de código y lo que muestra.
// Los formateadores del paquete intl (DateFormat, NumberFormat) se crean
// una sola vez, fuera de los widgets: construirlos cuesta más que
// usarlos.
// Los nombres de los días y meses de cada idioma no se cargan
// por defecto: initializeDateFormatting() los carga, 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';

// fechas: formatos "predefinidos" (yMMMd, yMMMMEEEEd, Hms...), o un patrón
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 y montos
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'; // una fecha en el formato de la API de 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 puede ser ASÍNCRONO: esperamos a que se carguen los idiomas
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 mostrado, valor): una fila de la tabla, como "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)),
      // dos transformaciones seguidas: el resultado de la primera pasa a la 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: una tabla simple; la primera columna ocupa el 55% del ancho
          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)),
                  ),
                ],
              ),
              // un record se puede "desestructurar": (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'),
            ),
          ),
        ],
      ),
    );
  }
}
  • líneas 21–25: formateadores de fechas del paquete [intl]. [DateFormat] contiene formatos “predefinidos”, identificados por las partes que se desea mostrar: [yMMMd] (año, mes abreviado, día), [yMMMMEEEEd] (más el día completo de la semana), [Hms] (horas, minutos, segundos)... También se puede especificar un patrón: ['MM/dd/yyyy HH:mm']. El segundo parámetro es el idioma;
  • líneas 27–29: formateadores de números: montos, enteros, porcentajes;
  • líneas 40–42: los nombres de los días y de los meses de cada idioma no se cargan de manera predeterminada: [initializeDateFormatting] los carga, antes de [runApp]. [main] puede ser asíncrona;
  • líneas 65–83: la tabla: una lista de records posicionales [(code, value)], sin nombres de campo;
  • líneas 93–111: [Table] dibuja una tabla sencilla. [columnWidths]: la primera columna ocupa el 55 % del ancho; [border]: líneas entre las filas. [for (final (code, value) in rows)] descompone cada record;
  • línea 124: recorre las entradas de un [Map]: [:key] es un atajo de [key: key];
  • línea 127: la función personalizada.

Para fechas, números y montos, [intl] cumple la misma función que la API [Intl] de los navegadores web: conoce las convenciones de cada idioma (separadores, nombres de los meses, orden de los componentes). La tabla utiliza las convenciones del inglés estadounidense (€1,234.50, “mes día, año”); observe que en francés un espacio fino sin salto separa los miles (1 234,50 €), y el orden es “día mes año” (la fila [frenchDay]).