feat(forms): clear (remove all) components from a FormArray (#28918)

renanmontebelo · kara · commit a68b1a1894b3 · 2019-03-07T19:52:49.000-08:00
This method is a more convenient and efficient way of removing all components from a FormArray. Before it, we needed to loop the FormArray removing each component until empty. Resolves #18531 PR Close #28918
diff --git a/packages/forms/src/model.ts b/packages/forms/src/model.ts
@@ -1895,6 +1895,43 @@ export class FormArray extends AbstractControl {
     });
   }
 
+  /**
+   * Remove all controls in the `FormArray`.
+   *
+   * @usageNotes
+   * ### Remove all elements from a FormArray
+   *
+   * ```ts
+   * const arr = new FormArray([
+   *    new FormControl(),
+   *    new FormControl()
+   * ]);
+   * console.log(arr.length);  // 2
+   *
+   * arr.clear();
+   * console.log(arr.length);  // 0
+   * ```
+   *
+   * It's a simpler and more efficient alternative to removing all elements one by one:
+   *
+   * ```ts
+   * const arr = new FormArray([
+   *    new FormControl(),
+   *    new FormControl()
+   * ]);
+   *
+   * while (arr.length) {
+   *    arr.removeAt(0);
+   * }
+   * ```
+   */
+  clear(): void {
+    if (this.controls.length < 1) return;
+    this._forEachChild((control: AbstractControl) => control._registerOnCollectionChange(() => {}));
+    this.controls.splice(0);
+    this.updateValueAndValidity();
+  }
+
   /** @internal */
   _syncPendingControls(): boolean {
     let subtreeUpdated = this.controls.reduce((updated: boolean, child: AbstractControl) => {
diff --git a/packages/forms/test/form_array_spec.ts b/packages/forms/test/form_array_spec.ts
@@ -59,6 +59,20 @@ import {of } from 'rxjs';
         expect(a.controls).toEqual([c1, c3]);
       });
 
+      it('should support clearing', () => {
+        a.push(c1);
+        a.push(c2);
+        a.push(c3);
+
+        a.clear();
+
+        expect(a.controls).toEqual([]);
+
+        a.clear();
+
+        expect(a.controls).toEqual([]);
+      });
+
       it('should support inserting', () => {
         a.push(c1);
         a.push(c3);
diff --git a/tools/public_api_guard/forms/forms.d.ts b/tools/public_api_guard/forms/forms.d.ts
@@ -170,6 +170,7 @@ export declare class FormArray extends AbstractControl {
     readonly length: number;
     constructor(controls: AbstractControl[], validatorOrOpts?: ValidatorFn | ValidatorFn[] | AbstractControlOptions | null, asyncValidator?: AsyncValidatorFn | AsyncValidatorFn[] | null);
     at(index: number): AbstractControl;
+    clear(): void;
     getRawValue(): any[];
     insert(index: number, control: AbstractControl): void;
     patchValue(value: any[], options?: {
