packages/forms/src/form_builder.ts - main - githubmirror/angular

packages/forms/src/form_builder.ts
548 строк22 KB
arturovt
docs: document FormBuilder.group() controlsConfig value shapes
21 май 2026, 00:07
21 май 2026, 00:073b8503f
/**
 * @license
 * Copyright Google LLC All Rights Reserved.
 *
 * Use of this source code is governed by an MIT-style license that can be
 * found in the LICENSE file at https://angular.dev/license
 */

import {inject, Service} from '@angular/core';

import {AsyncValidatorFn, ValidatorFn} from './directives/validators';
import {AbstractControl, AbstractControlOptions} from './model/abstract_model';
import {FormArray, UntypedFormArray} from './model/form_array';
import {
  FormControl,
  FormControlOptions,
  FormControlState,
  UntypedFormControl,
} from './model/form_control';
import {FormGroup, FormRecord, UntypedFormGroup} from './model/form_group';

function isAbstractControlOptions(
  options: AbstractControlOptions | {[key: string]: any} | null | undefined,
): options is AbstractControlOptions {
  return (
    !!options &&
    ((options as AbstractControlOptions).asyncValidators !== undefined ||
      (options as AbstractControlOptions).validators !== undefined ||
      (options as AbstractControlOptions).updateOn !== undefined)
  );
}

/**
 * The union of all validator types that can be accepted by a ControlConfig.
 */
type ValidatorConfig = ValidatorFn | AsyncValidatorFn | ValidatorFn[] | AsyncValidatorFn[];

/**
 * The compiler may not always be able to prove that the elements of the control config are a tuple
 * (i.e. occur in a fixed order). This slightly looser type is used for inference, to catch cases
 * where the compiler cannot prove order and position.
 *
 * For example, consider the simple case `fb.group({foo: ['bar', Validators.required]})`. The
 * compiler will infer this as an array, not as a tuple.
 */
type PermissiveControlConfig<T> = Array<T | FormControlState<T> | ValidatorConfig>;

/**
 * Helper type to allow the compiler to accept [XXXX, { updateOn: string }] as a valid shorthand
 * argument for .group()
 */
interface PermissiveAbstractControlOptions extends Omit<AbstractControlOptions, 'updateOn'> {
  updateOn?: string;
}

// Note: these two types have been extracted into type aliases to work around a .d.ts generation
// issue in TypeScript 5.7. See: https://github.com/Microsoft/TypeScript/issues/60506. The types
// have to be exported for the workaround to work.
/** A map of nullable form controls. */
export type ɵNullableFormControls<T> = {[K in keyof T]: ɵElement<T[K], null>};

/** A map of non-nullable form controls. */
export type ɵNonNullableFormControls<T> = {[K in keyof T]: ɵElement<T[K], never>};

/**
 * ControlConfig<T> is a tuple containing a value of type T, plus optional validators and async
 * validators.
 *
 * @publicApi
 */
export type ControlConfig<T> = [
  T | FormControlState<T>,
  (ValidatorFn | ValidatorFn[])?,
  (AsyncValidatorFn | AsyncValidatorFn[])?,
];

/**
 * FormBuilder accepts values in various container shapes, as well as raw values.
 * Element returns the appropriate corresponding model class, given the container T.
 * The flag N, if not never, makes the resulting `FormControl` have N in its type.
 */
export type ɵElement<T, N extends null> =
  // The `extends` checks are wrapped in arrays in order to prevent TypeScript from applying type unions
  // through the distributive conditional type. This is the officially recommended solution:
  // https://www.typescriptlang.org/docs/handbook/2/conditional-types.html#distributive-conditional-types
  //
  // Identify FormControl container types.
  [T] extends [FormControl<infer U>]
    ? FormControl<U>
    : // Or FormControl containers that are optional in their parent group.
      [T] extends [FormControl<infer U> | undefined]
      ? FormControl<U>
      : // FormGroup containers.
        [T] extends [FormGroup<infer U>]
        ? FormGroup<U>
        : // Optional FormGroup containers.
          [T] extends [FormGroup<infer U> | undefined]
          ? FormGroup<U>
          : // FormRecord containers.
            [T] extends [FormRecord<infer U>]
            ? FormRecord<U>
            : // Optional FormRecord containers.
              [T] extends [FormRecord<infer U> | undefined]
              ? FormRecord<U>
              : // FormArray containers.
                [T] extends [FormArray<infer U>]
                ? FormArray<U>
                : // Optional FormArray containers.
                  [T] extends [FormArray<infer U> | undefined]
                  ? FormArray<U>
                  : // Otherwise unknown AbstractControl containers.
                    [T] extends [AbstractControl<infer U>]
                    ? AbstractControl<U>
                    : // Optional AbstractControl containers.
                      [T] extends [AbstractControl<infer U> | undefined]
                      ? AbstractControl<U>
                      : // FormControlState object container, which produces a nullable control.
                        [T] extends [FormControlState<infer U>]
                        ? FormControl<U | N>
                        : // A ControlConfig tuple, which produces a nullable control.
                          [T] extends [PermissiveControlConfig<infer U>]
                          ? FormControl<
                              Exclude<U, ValidatorConfig | PermissiveAbstractControlOptions> | N
                            >
                          : FormControl<T | N>;

/**
 * @description
 * Creates an `AbstractControl` from a user-specified configuration.
 *
 * The `FormBuilder` provides syntactic sugar that shortens creating instances of a
 * `FormControl`, `FormGroup`, or `FormArray`. It reduces the amount of boilerplate needed to
 * build complex forms.
 *
 * @see [Reactive Forms Guide](guide/forms/reactive-forms)
 *
 * @publicApi
 */
@Service()
export class FormBuilder {
  private useNonNullable: boolean = false;

  /**
   * @description
   * Returns a FormBuilder in which automatically constructed `FormControl` elements
   * have `{nonNullable: true}` and are non-nullable.
   *
   * **Constructing non-nullable controls**
   *
   * When constructing a control, it will be non-nullable, and will reset to its initial value.
   *
   * ```ts
   * let nnfb = new FormBuilder().nonNullable;
   * let name = nnfb.control('Alex'); // FormControl<string>
   * name.reset();
   * console.log(name); // 'Alex'
   * ```
   *
   * **Constructing non-nullable groups or arrays**
   *
   * When constructing a group or array, all automatically created inner controls will be
   * non-nullable, and will reset to their initial values.
   *
   * ```ts
   * let nnfb = new FormBuilder().nonNullable;
   * let name = nnfb.group({who: 'Alex'}); // FormGroup<{who: FormControl<string>}>
   * name.reset();
   * console.log(name); // {who: 'Alex'}
   * ```
   * **Constructing *nullable* fields on groups or arrays**
   *
   * It is still possible to have a nullable field. In particular, any `FormControl` which is
   * *already* constructed will not be altered. For example:
   *
   * ```ts
   * let nnfb = new FormBuilder().nonNullable;
   * // FormGroup<{who: FormControl<string|null>}>
   * let name = nnfb.group({who: new FormControl('Alex')});
   * name.reset(); console.log(name); // {who: null}
   * ```
   *
   * Because the inner control is constructed explicitly by the caller, the builder has
   * no control over how it is created, and cannot exclude the `null`.
   */
  get nonNullable(): NonNullableFormBuilder {
    const nnfb = new FormBuilder();
    nnfb.useNonNullable = true;
    return nnfb as NonNullableFormBuilder;
  }

  /**
   * @description
   * Constructs a new `FormGroup` instance. Accepts a single generic argument, which is an object
   * containing all the keys and corresponding inner control types.
   *
   * @param controls A collection of child controls. The key for each child is the name
   * under which it is registered. Each value can be one of:
   * * An `AbstractControl` instance — passed through as-is.
   * * A raw value — shorthand for `fb.control(value)`.
   * * A `FormControlState` object (`{value, disabled}`) — initializes the control with a value
   *   and disabled status.
   * * A `ControlConfig` tuple — `[value | FormControlState, validatorOrOpts?, asyncValidator?]`.
   *   The second element accepts a `ValidatorFn`, an array of `ValidatorFn`, or an
   *   `AbstractControlOptions` object (use this to set `updateOn`). The optional third element
   *   accepts an `AsyncValidatorFn` or an array of `AsyncValidatorFn`.
   *
   * @param options Configuration options object for the `FormGroup`. The object should have the
   * `AbstractControlOptions` type and might contain the following fields:
   * * `validators`: A synchronous validator function, or an array of validator functions.
   * * `asyncValidators`: A single async validator or array of async validator functions.
   * * `updateOn`: The event upon which the control should be updated (options: 'change' | 'blur'
   * | submit').
   *
   * @usageNotes
   *
   * ### Different ways to specify a control value
   *
   * ```ts
   * const fb = new FormBuilder();
   *
   * fb.group({
   *   // Raw value — equivalent to fb.control('Ada')
   *   name: 'Ada',
   *
   *   // FormControlState — sets initial value and disabled status
   *   city: {value: 'London', disabled: true},
   *
   *   // ControlConfig tuple — value with a sync validator
   *   email: ['ada@example.com', Validators.email],
   *
   *   // ControlConfig tuple — value, sync validator, and async validator
   *   username: ['ada', Validators.required, checkUsernameAvailable],
   *
   *   // ControlConfig tuple — disabled value with updateOn option
   *   role: [{value: 'admin', disabled: true}, {updateOn: 'blur'}],
   *
   *   // Pre-built control — passed through unchanged
   *   address: new FormControl('', Validators.required),
   * });
   * ```
   */
  group<T extends {}>(
    controls: T,
    options?: AbstractControlOptions | null,
  ): FormGroup<ɵNullableFormControls<T>>;

  /**
   * @description
   * Constructs a new `FormGroup` instance.
   *
   * @deprecated This API is not typesafe and can result in issues with Closure Compiler renaming.
   * Use the `FormBuilder#group` overload with `AbstractControlOptions` instead.
   * Note that `AbstractControlOptions` expects `validators` and `asyncValidators` to be valid
   * validators. If you have custom validators, make sure their validation function parameter is
   * `AbstractControl` and not a sub-class, such as `FormGroup`. These functions will be called
   * with an object of type `AbstractControl` and that cannot be automatically downcast to a
   * subclass, so TypeScript sees this as an error. For example, change the `(group: FormGroup) =>
   * ValidationErrors|null` signature to be `(group: AbstractControl) => ValidationErrors|null`.
   *
   * @param controls A record of child controls. The key for each child is the name
   * under which the control is registered.
   *
   * @param options Configuration options object for the `FormGroup`. The legacy configuration
   * object consists of:
   * * `validator`: A synchronous validator function, or an array of validator functions.
   * * `asyncValidator`: A single async validator or array of async validator functions
   * Note: the legacy format is deprecated and might be removed in one of the next major versions
   * of Angular.
   */
  group(controls: {[key: string]: any}, options: {[key: string]: any}): FormGroup;

  group(
    controls: {[key: string]: any},
    options: AbstractControlOptions | {[key: string]: any} | null = null,
  ): FormGroup {
    const reducedControls = this._reduceControls(controls);
    let newOptions: FormControlOptions = {};
    if (isAbstractControlOptions(options)) {
      // `options` are `AbstractControlOptions`
      newOptions = options;
    } else if (options !== null) {
      // `options` are legacy form group options
      newOptions.validators = (options as any).validator;
      newOptions.asyncValidators = (options as any).asyncValidator;
    }
    return new FormGroup(reducedControls, newOptions);
  }

  /**
   * @description
   * Constructs a new `FormRecord` instance. Accepts a single generic argument, which is an object
   * containing all the keys and corresponding inner control types.
   *
   * @param controls A collection of child controls. The key for each child is the name
   * under which it is registered.
   *
   * @param options Configuration options object for the `FormRecord`. The object should have the
   * `AbstractControlOptions` type and might contain the following fields:
   * * `validators`: A synchronous validator function, or an array of validator functions.
   * * `asyncValidators`: A single async validator or array of async validator functions.
   * * `updateOn`: The event upon which the control should be updated (options: 'change' | 'blur'
   * | submit').
   */
  record<T>(
    controls: {[key: string]: T},
    options: AbstractControlOptions | null = null,
  ): FormRecord<ɵElement<T, null>> {
    const reducedControls = this._reduceControls(controls);
    // Cast to `any` because the inferred types are not as specific as Element.
    return new FormRecord(reducedControls, options) as any;
  }

  /** @deprecated Use `nonNullable` instead. */
  control<T>(
    formState: T | FormControlState<T>,
    opts: FormControlOptions & {
      initialValueIsDefault: true;
    },
  ): FormControl<T>;

  control<T>(
    formState: T | FormControlState<T>,
    opts: FormControlOptions & {nonNullable: true},
  ): FormControl<T>;

  /**
   * @deprecated When passing an `options` argument, the `asyncValidator` argument has no effect.
   */
  control<T>(
    formState: T | FormControlState<T>,
    opts: FormControlOptions,
    asyncValidator: AsyncValidatorFn | AsyncValidatorFn[],
  ): FormControl<T | null>;

  control<T>(
    formState: T | FormControlState<T>,
    validatorOrOpts?: ValidatorFn | ValidatorFn[] | FormControlOptions | null,
    asyncValidator?: AsyncValidatorFn | AsyncValidatorFn[] | null,
  ): FormControl<T | null>;

  /**
   * @description
   * Constructs a new `FormControl` with the given state, validators and options. Sets
   * `{nonNullable: true}` in the options to get a non-nullable control. Otherwise, the
   * control will be nullable. Accepts a single generic argument, which is the type  of the
   * control's value.
   *
   * @param formState Initializes the control with an initial state value, or
   * with an object that contains both a value and a disabled status.
   *
   * @param validatorOrOpts A synchronous validator function, or an array of
   * such functions, or a `FormControlOptions` object that contains
   * validation functions and a validation trigger.
   *
   * @param asyncValidator A single async validator or array of async validator
   * functions.
   *
   * @usageNotes
   *
   * ### Initialize a control as disabled
   *
   * The following example returns a control with an initial value in a disabled state.
   *
   * {@example forms/ts/formBuilder/form_builder_example.ts region='disabled-control'}
   */
  control<T>(
    formState: T | FormControlState<T>,
    validatorOrOpts?: ValidatorFn | ValidatorFn[] | FormControlOptions | null,
    asyncValidator?: AsyncValidatorFn | AsyncValidatorFn[] | null,
  ): FormControl {
    let newOptions: FormControlOptions = {};
    if (!this.useNonNullable) {
      return new FormControl(formState, validatorOrOpts, asyncValidator);
    }
    if (isAbstractControlOptions(validatorOrOpts)) {
      // If the second argument is options, then they are copied.
      newOptions = validatorOrOpts;
    } else {
      // If the other arguments are validators, they are copied into an options object.
      newOptions.validators = validatorOrOpts;
      newOptions.asyncValidators = asyncValidator;
    }
    return new FormControl<T>(formState, {...newOptions, nonNullable: true});
  }

  /**
   * Constructs a new `FormArray` from the given array of configurations,
   * validators and options. Accepts a single generic argument, which is the type of each control
   * inside the array.
   *
   * @param controls An array of child controls or control configs. Each child control is given an
   *     index when it is registered.
   *
   * @param validatorOrOpts A synchronous validator function, or an array of such functions, or an
   *     `AbstractControlOptions` object that contains
   * validation functions and a validation trigger.
   *
   * @param asyncValidator A single async validator or array of async validator functions.
   */
  array<T>(
    controls: Array<T>,
    validatorOrOpts?: ValidatorFn | ValidatorFn[] | AbstractControlOptions | null,
    asyncValidator?: AsyncValidatorFn | AsyncValidatorFn[] | null,
  ): FormArray<ɵElement<T, null>> {
    const createdControls = controls.map((c) => this._createControl(c));
    // Cast to `any` because the inferred types are not as specific as Element.
    return new FormArray(createdControls, validatorOrOpts, asyncValidator) as any;
  }

  /** @internal */
  _reduceControls<T>(controls: {
    [k: string]: T | ControlConfig<T> | FormControlState<T> | AbstractControl<T>;
  }): {[key: string]: AbstractControl} {
    const createdControls: {[key: string]: AbstractControl} = {};
    Object.keys(controls).forEach((controlName) => {
      createdControls[controlName] = this._createControl(controls[controlName]);
    });
    return createdControls;
  }

  /** @internal */
  _createControl<T>(
    controls: T | FormControlState<T> | ControlConfig<T> | FormControl<T> | AbstractControl<T>,
  ): FormControl<T> | FormControl<T | null> | AbstractControl<T> {
    if (controls instanceof FormControl) {
      return controls as FormControl<T>;
    } else if (controls instanceof AbstractControl) {
      // A control; just return it
      return controls;
    } else if (Array.isArray(controls)) {
      // ControlConfig Tuple
      const value: T | FormControlState<T> = controls[0];
      const validator: ValidatorFn | ValidatorFn[] | null =
        controls.length > 1 ? controls[1]! : null;
      const asyncValidator: AsyncValidatorFn | AsyncValidatorFn[] | null =
        controls.length > 2 ? controls[2]! : null;
      return this.control<T>(value, validator, asyncValidator);
    } else {
      // T or FormControlState<T>
      return this.control<T>(controls);
    }
  }
}

/**
 * @description
 * `NonNullableFormBuilder` is similar to {@link FormBuilder}, but automatically constructed
 * {@link FormControl} elements have `{nonNullable: true}` and are non-nullable.
 *
 * @see [FormBuilder and NonNullableFormBuilder](guide/forms/typed-forms#formbuilder-and-nonnullableformbuilder)
 *
 * @publicApi
 */
@Service({factory: () => inject(FormBuilder).nonNullable})
export abstract class NonNullableFormBuilder {
  /**
   * Similar to `FormBuilder#group`, except any implicitly constructed `FormControl`
   * will be non-nullable (i.e. it will have `nonNullable` set to true). Note
   * that already-constructed controls will not be altered.
   */
  abstract group<T extends {}>(
    controls: T,
    options?: AbstractControlOptions | null,
  ): FormGroup<ɵNonNullableFormControls<T>>;

  /**
   * Similar to `FormBuilder#record`, except any implicitly constructed `FormControl`
   * will be non-nullable (i.e. it will have `nonNullable` set to true). Note
   * that already-constructed controls will not be altered.
   */
  abstract record<T>(
    controls: {[key: string]: T},
    options?: AbstractControlOptions | null,
  ): FormRecord<ɵElement<T, never>>;

  /**
   * Similar to `FormBuilder#array`, except any implicitly constructed `FormControl`
   * will be non-nullable (i.e. it will have `nonNullable` set to true). Note
   * that already-constructed controls will not be altered.
   */
  abstract array<T>(
    controls: Array<T>,
    validatorOrOpts?: ValidatorFn | ValidatorFn[] | AbstractControlOptions | null,
    asyncValidator?: AsyncValidatorFn | AsyncValidatorFn[] | null,
  ): FormArray<ɵElement<T, never>>;

  /**
   * Similar to `FormBuilder#control`, except this overridden version of `control` forces
   * `nonNullable` to be `true`, resulting in the control always being non-nullable.
   */
  abstract control<T>(
    formState: T | FormControlState<T>,
    validatorOrOpts?: ValidatorFn | ValidatorFn[] | AbstractControlOptions | null,
    asyncValidator?: AsyncValidatorFn | AsyncValidatorFn[] | null,
  ): FormControl<T>;
}

/**
 * UntypedFormBuilder is the same as `FormBuilder`, but it provides untyped controls.
 */
@Service()
export class UntypedFormBuilder extends FormBuilder {
  /**
   * Like `FormBuilder#group`, except the resulting group is untyped.
   */
  override group(
    controlsConfig: {[key: string]: any},
    options?: AbstractControlOptions | null,
  ): UntypedFormGroup;

  /**
   * @deprecated This API is not typesafe and can result in issues with Closure Compiler renaming.
   * Use the `FormBuilder#group` overload with `AbstractControlOptions` instead.
   */
  override group(
    controlsConfig: {[key: string]: any},
    options: {[key: string]: any},
  ): UntypedFormGroup;

  override group(
    controlsConfig: {[key: string]: any},
    options: AbstractControlOptions | {[key: string]: any} | null = null,
  ): UntypedFormGroup {
    return super.group(controlsConfig, options);
  }

  /**
   * Like `FormBuilder#control`, except the resulting control is untyped.
   */
  override control(
    formState: any,
    validatorOrOpts?: ValidatorFn | ValidatorFn[] | FormControlOptions | null,
    asyncValidator?: AsyncValidatorFn | AsyncValidatorFn[] | null,
  ): UntypedFormControl {
    return super.control(formState, validatorOrOpts, asyncValidator);
  }

  /**
   * Like `FormBuilder#array`, except the resulting array is untyped.
   */
  override array(
    controlsConfig: any[],
    validatorOrOpts?: ValidatorFn | ValidatorFn[] | AbstractControlOptions | null,
    asyncValidator?: AsyncValidatorFn | AsyncValidatorFn[] | null,
  ): UntypedFormArray {
    return super.array(controlsConfig, validatorOrOpts, asyncValidator);
  }
}