HOWTO · Angular

Restablecer formularios en Angular 2

Uno de los usos más comunes de ngForm es restablecer los valores de todos los controles de formulario en su página a su estado inicial.

En esta página

Restablecer un formulario en Angular significa devolver sus controles a un estado limpio: los valores vuelven a null o a los valores predeterminados que proporciones, y se borran indicadores de estado como dirty, touched y submitted. La llamada que debes usar depende de cuál de las dos API de formularios de Angular utilice tu formulario, así que el primer paso es identificarla.

Los fragmentos siguientes son código fuente de una aplicación Angular: se ejecutan dentro de un proyecto Angular, no como scripts independientes. Por eso las plantillas se muestran como marcado del navegador y las llamadas de la clase como código en línea, sin una salida de consola atribuida. Un pequeño script independiente al final modela el estado resultante para que el comportamiento pueda comprobarse directamente.

Elige la API de restablecimiento para tu formulario de Angular

Angular 2 incluye dos módulos de formularios, y cada uno tiene su propio método de restablecimiento:

  • Los formularios basados en plantillas provienen de FormsModule. Angular adjunta automáticamente la directiva ngForm a cada elemento <form>, lo que crea un objeto NgForm que realiza el seguimiento del valor, la validez y el estado de cada control. Puedes restablecer todo el formulario a través de ese objeto con resetForm().
  • Los formularios reactivos provienen de ReactiveFormsModule. Construyes un FormGroup en la clase del componente y lo vinculas en la plantilla con [formGroup]. Lo restableces con el método reset() propio del grupo.

Se trata de API distintas: resetForm() existe en NgForm, mientras que reset() existe en FormGroup y en controles individuales. Comprueba qué módulo importa tu aplicación y elige la llamada correspondiente.

Restablecer un formulario basado en plantillas con NgForm

Con FormsModule importado en tu NgModule, captura la instancia de NgForm en la plantilla asignando #myForm="ngForm". El archivo de plantilla del componente queda así (las etiquetas visibles del ejemplo permanecen en inglés):

<form #myForm="ngForm" (ngSubmit)="onSubmit(myForm)">
  <input name="username" ngModel required>
  <input name="email" ngModel required>
  <button type="submit">Submit</button>
  <button type="button" (click)="myForm.resetForm()">Reset</button>
</form>

Al hacer clic en el botón «Reset» se invoca resetForm() en la instancia de NgForm. El valor de cada control vuelve a null, y Angular borra los indicadores dirty, touched y submitted para que el formulario se comporte como si el usuario nunca hubiera interactuado con él. Si prefieres mantener la llamada dentro de la clase, vincula el botón a (click)="onReset(myForm)", importa NgForm desde @angular/forms y define onReset(form: NgForm) { form.resetForm(); } en el componente.

Restablecer un formulario reactivo con FormGroup

Un formulario reactivo mantiene su modelo en la clase del componente. Con ReactiveFormsModule importado, crea el grupo en la clase —por ejemplo loginForm = new FormGroup({ username: new FormControl(''), email: new FormControl('') })— y vincúlalo en la plantilla con [formGroup]. Las etiquetas visibles del ejemplo permanecen en inglés:

<form [formGroup]="loginForm" (ngSubmit)="onSubmit()">
  <input formControlName="username">
  <input formControlName="email">
  <button type="submit">Submit</button>
  <button type="button" (click)="loginForm.reset()">Reset</button>
</form>

Llamar a reset() en el FormGroup establece el valor de cada control en null y restaura los indicadores de estado pristine y untouched; la misma llamada funciona dentro de la clase como this.loginForm.reset(). Es el equivalente reactivo de NgForm.resetForm(), no el mismo método.

Restaurar valores predeterminados o restablecer un solo control

Ambos métodos de restablecimiento aceptan un objeto de valores opcional, que es la forma de restaurar valores predeterminados en lugar de vaciar los campos. Pasa un objeto cuyas claves coincidan con los nombres de tus controles: form.resetForm({ username: 'guest', email: 'guest@example.com' }) para un formulario basado en plantillas, o this.loginForm.reset({ username: 'guest', email: 'guest@example.com' }) para uno reactivo.

Mantén las claves alineadas con los nombres de control que registraste. A diferencia de patchValue(), reset() está pensado para describir el estado de todo el grupo, por lo que usar nombres coincidentes es lo que garantiza que cada control quede con el valor esperado.

Para restablecer solo un campo y dejar los demás como los dejó el usuario, llama a reset() en ese único control: form.controls['username'].reset() a través del NgForm en un formulario basado en plantillas, o this.loginForm.get('username').reset() a través del FormGroup en un formulario reactivo. El reset() individual borra el valor de ese control y sus propios indicadores dirty y touched; los demás controles conservan sus valores y su estado.

Comprobar los valores y el estado después de un restablecimiento

Después de restablecer todo el formulario, el valor de cada control es null (o el valor predeterminado que proporcionaste), form.pristine y form.untouched vuelven a ser true, y dirty y touched regresan a false. En un formulario basado en plantillas, NgForm también borra su indicador submitted, por lo que los mensajes de error condicionados por algo como myForm.submitted && username.invalid desaparecen hasta el próximo envío.

Restablecer no elimina los validadores. Un control marcado como required deja de ser válido en cuanto su valor se restablece a null, por lo que form.valid lo refleja de inmediato aunque el campo parezca intacto. Si solo quieres borrar los indicadores de interacción conservando los valores introducidos, llama a markAsPristine() y markAsUntouched() en el formulario o en el control en lugar de restablecerlo.

Las transiciones de valores e indicadores son lo bastante pequeñas para verificarlas fuera de un proyecto Angular. Ejecuta este ejemplo (las etiquetas que imprime permanecen en inglés):

function resetControl(control, value = null) {
  control.value = value;
  control.dirty = false;
  control.touched = false;
}

const username = { value: 'adil', dirty: true, touched: true };
const email = { value: 'adil@example.com', dirty: true, touched: true };

resetControl(username);
resetControl(email, 'guest@example.com');

console.log('username:', username);
console.log('email:', email);

Salida:

username: { value: null, dirty: false, touched: false }
email: { value: 'guest@example.com', dirty: false, touched: false }

La primera llamada reproduce control.reset() sin argumento: el valor queda en null y ambos indicadores se borran; la segunda reproduce control.reset('guest@example.com'), que restaura un valor predeterminado con la misma limpieza de indicadores.