Construir un formulario con validación

Las aplicaciones a menudo requieren que los usuarios ingresen información en un campo de texto. Por ejemplo, es posible que requieras que los usuarios inicien sesión con una combinación de correo electrónico y contraseña.

Para hacer que las aplicaciones sean seguras y fáciles de usar, verifica si la información que el usuario ha proporcionado es válida. Si el usuario ha completado correctamente el formulario, procesa la información. Si el usuario envía información incorrecta, muestra un mensaje de error amigable que le informe qué salió mal.

En este ejemplo, aprenderás cómo agregar validación a un formulario que tiene un solo campo de texto siguiendo estos pasos:

1. Crear un Form con una GlobalKey.
2. Añadir un TextFormField con lógica de validación.
3. Crear un botón para validar y enviar el formulario.

Crea un Form. El Widget Form actúa como un contenedor para agrupar y validar múltiples campos de formulario.

Al crear el formulario, proporciona una GlobalKey. Esto asigna un identificador único a tu Form. También te permite validar el formulario más adelante.

Crea el formulario como un StatefulWidget. Esto te permite crear una única GlobalKey<FormState>() una vez. Luego puedes almacenarla como una variable y acceder a ella en diferentes puntos.

Si hicieras esto como un StatelessWidget, tendrías que almacenar esta clave en algún lugar. Dado que consume muchos recursos, no querrías generar una nueva GlobalKey cada vez que ejecutes el método build.

import 'package:flutter/material.dart';
​
// Define a custom Form widget.
class MyCustomForm extends StatefulWidget {
  const MyCustomForm({super.key});
​
  @override
  MyCustomFormState createState() {
    return MyCustomFormState();
  }
}
​
// Define a corresponding State class.
// This class holds data related to the form.
class MyCustomFormState extends State<MyCustomForm> {
  // Create a global key that uniquely identifies the Form widget
  // and allows validation of the form.
  //
  // Note: This is a `GlobalKey<FormState>`,
  // not a GlobalKey<MyCustomFormState>.
  final _formKey = GlobalKey<FormState>();
​
  @override
  Widget build(BuildContext context) {
    // Build a Form widget using the _formKey created above.
    return Form(
      key: _formKey,
      child: const Column(
        children: <Widget>[
          // Add TextFormFields and ElevatedButton here.
        ],
      ),
    );
  }
}

Aunque el Form está en su lugar, no tiene una forma para que los usuarios ingresen texto. Ese es el trabajo de un TextFormField. El Widget TextFormField renderiza un campo de texto de Material Design y puede mostrar errores de validación cuando ocurren.

Valida la entrada proporcionando una función validator() al TextFormField. Si la entrada del usuario no es válida, la función validator devuelve un String que contiene un mensaje de error. Si no hay errores, el validator debe devolver null.

Para este ejemplo, crea un validator que asegure que el TextFormField no esté vacío. Si está vacío, devuelve un mensaje de error amigable.

TextFormField(
  // The validator receives the text that the user has entered.
  validator: (value) {
    if (value == null || value.isEmpty) {
      return 'Please enter some text';
    }
    return null;
  },
),

Ahora que tienes un formulario con un campo de texto, proporciona un botón que el usuario pueda tocar para enviar la información.

Cuando el usuario intente enviar el formulario, verifica si el formulario es válido. Si lo es, muestra un mensaje de éxito. Si no lo es (el campo de texto no tiene contenido), muestra el mensaje de error.

ElevatedButton(
  onPressed: () {
    // Validate returns true if the form is valid, or false otherwise.
    if (_formKey.currentState!.validate()) {
      // If the form is valid, display a snackbar. In the real world,
      // you'd often call a server or save the information in a database.
      ScaffoldMessenger.of(context).showSnackBar(
        const SnackBar(content: Text('Processing Data')),
      );
    }
  },
  child: const Text('Submit'),
),

Para validar el formulario, utiliza la _formKey creada en el paso 1. Puedes utilizar el acceso _formKey.currentState para acceder a FormState, que es creado automáticamente por Flutter al construir un Form.

La clase FormState contiene el método validate(). Cuando se llama al método validate(), este ejecuta la función validator() para cada campo de texto en el formulario. Si todo está correcto, el método validate() devuelve true. Si algún campo de texto contiene errores, el método validate() reconstruye el formulario para mostrar los mensajes de error y devuelve false.

Para aprender a recuperar estos valores, consulta la receta Recuperar el valor de un campo de texto.