HOWTO · Angular

AngularJS setPristine para restablecer el formulario

En AngularJS, `$setPristine()` restablece el estado de interacción prístino del formulario, pero no modifica los valores del modelo; para borrarlos o restaurarlos, actualiza el modelo por separado.

En esta página

En AngularJS, restablecer un formulario puede significar restablecer su estado de interacción, cambiar los valores asociados a sus campos o hacer ambas cosas. Llama al método $setPristine() del controlador del formulario para volver a marcar como prístinos el formulario y sus controles. Esto no los marca como no tocados ni cambia los valores del modelo. Actualiza el modelo por separado si quieres borrar o restaurar lo que escribió el usuario.

Entender los estados prístino y modificado, y el valor del modelo

$setPristine() es un método; $pristine y $dirty son propiedades booleanas de estado de un formulario o control. Un formulario comienza en estado prístino. Cuando el usuario cambia un control, AngularJS marca como modificado ese control y el formulario que lo contiene. Llamar a $setPristine() restablece los estados prístino y modificado, pero no restaura los valores originales ni borra el modelo.

El estado de interacción de foco es independiente: $touched y $untouched indican si un control ha perdido el foco, mientras que los estados prístino y modificado indican si cambió su valor. $setPristine() no restablece el estado de foco. Si también necesitas que los controles queden sin tocar, llama por separado al método $setUntouched() del formulario; de lo contrario, deja ese estado como está.

El controlador de un formulario con nombre se publica en el ámbito que lo contiene, bajo el name del formulario. El ejemplo siguiente usa la sintaxis controller-as para el controlador de la aplicación (vm) y accede al controlador del formulario mediante $scope.profileForm. Asocia los campos de entrada con ng-model y utiliza la misma propiedad del modelo para borrar o restaurar un campo.

Restablecer el estado del formulario con $setPristine()

Esta ilustración del código para el navegador conecta el formulario, los botones, el controlador y el controlador del formulario con nombre. Presupone que AngularJS está cargado en la página. El primer botón conserva el valor actual del campo mientras restablece el estado del formulario; el segundo borra el modelo y después restablece ese estado. Las etiquetas visibles dentro del bloque de código se mantienen en inglés.

<div ng-app="myApp" ng-controller="FormController as vm">
  <form name="profileForm">
    <label>
      Name
      <input name="name" ng-model="vm.profile.name">
    </label>
    <button type="button" ng-click="vm.resetState()">Mark form pristine</button>
    <button type="button" ng-click="vm.clearAndReset()">Clear and reset</button>
  </form>
</div>
<script>
  angular.module('myApp', []).controller('FormController', function ($scope) {
    var vm = this;
    vm.profile = { name: 'Ada' };
    vm.resetState = function () {
      $scope.profileForm.$setPristine();
    };
    vm.clearAndReset = function () {
      vm.profile.name = '';
      $scope.profileForm.$setPristine();
    };
    vm.restoreAndReset = function () {
      vm.profile.name = 'Ada';
      $scope.profileForm.$setPristine();
    };
  });
</script>

El controlador de eventos está definido en la misma instancia vm que nombra ng-controller, y cada botón llama a un método definido. AngularJS pone a disposición el controlador del formulario con nombre en $scope una vez enlazado el formulario, así que el controlador del clic puede llamar a $scope.profileForm.$setPristine(). resetState() deja sin cambios vm.profile.name. clearAndReset() modifica esa propiedad del modelo antes de restablecer el estado del formulario. El método independiente restoreAndReset() muestra cómo restaurar un valor guardado; llámalo desde un botón u otra acción de la aplicación cuando sea necesario.

Borrar o restaurar el valor del modelo por separado

Restablecer el estado de interacción y cambiar el valor de un campo son operaciones independientes. Para conservar el valor actual, llama a $setPristine() sin asignar nada al modelo. Para borrarlo, asigna una cadena vacía a la propiedad asociada; para restaurarlo, asigna el valor guardado. Si deben restablecerse tanto el valor como el estado de interacción, actualiza el modelo y llama a $setPristine(), como se muestra en el controlador correspondiente de arriba.

La siguiente simulación independiente en JavaScript ilustra ambas acciones sin necesitar AngularJS en tiempo de ejecución. Solo modela los cambios de estado y de valor; no es una implementación de formulario de AngularJS.

Ejecuta este ejemplo:

El código y las etiquetas o salidas visibles de esta sección se mantienen en inglés.

const form = {
  $dirty: true,
  $pristine: false,
  $setPristine() {
    this.$dirty = false;
    this.$pristine = true;
  }
};
const model = { name: 'Ada' };
model.name = '';
form.$setPristine();
console.log(JSON.stringify({ name: model.name, pristine: form.$pristine, dirty: form.$dirty }));
{"name":"","pristine":true,"dirty":false}

En esta simulación, asignar model.name = '' borra el valor y $setPristine() solo cambia las banderas de interacción modeladas. Para simular que se conserva el valor, omite la asignación. Para simular la restauración de un valor guardado, asígnalo antes de restablecer las banderas. En una aplicación de AngularJS, utiliza la propiedad real del modelo y el controlador del formulario que aparecen en el ejemplo para el navegador.

Verificar el comportamiento y evitar errores comunes

Después de ejecutar el controlador, inspecciona las propiedades $pristine y $dirty del formulario con nombre y comprueba vm.profile.name por separado. Con resetState(), el formulario queda prístino y conserva su valor actual. Con clearAndReset(), el valor queda vacío y el formulario queda prístino. Asignar un valor al modelo por sí solo no llama a $setPristine(), así que realiza ambas operaciones cuando busques los dos resultados.

No confundas los estados prístino y modificado con los estados tocado y no tocado. Usa $setUntouched() solo si también necesitas restablecer el estado relacionado con la pérdida del foco. No llames estado a $setPristine ni uses la propiedad mal escrita $errror para validar. Para mostrar un mensaje de campo obligatorio, comprueba la propiedad de validez correcta, como profileForm.name.$error.required. Los botones de restablecimiento usan type="button" para no enviar el formulario. Este procedimiento utiliza el controlador de formulario integrado de AngularJS y no requiere reemplazar directivas de formulario ni sobrescribir métodos del controlador.