FormBuilder — Angular

Создает AbstractControl на основе конфигурации, заданной пользователем.

API

class FormBuilder {
  readonly nonNullable: NonNullableFormBuilder;
  group<T extends {}>(controls: T, options?: AbstractControlOptions | null | undefined): FormGroup<ɵNullableFormControls<T>>;
  group(controls: { [key: string]: any; }, options: { [key: string]: any; }): FormGroup<any>;
  record<T>(controls: { [key: string]: T; }, options?: AbstractControlOptions | null): FormRecord<ɵElement<T, null>>;
  control<T>(formState: T | FormControlState<T>, opts: FormControlOptions & { initialValueIsDefault: true; }): FormControl<T>;
  control<T>(formState: T | FormControlState<T>, opts: FormControlOptions & { nonNullable: true; }): FormControl<T>;
  control<T>(formState: T | FormControlState<T>, opts: FormControlOptions, asyncValidator: AsyncValidatorFn | AsyncValidatorFn[]): FormControl<T | null>;
  control<T>(formState: T | FormControlState<T>, validatorOrOpts?: ValidatorFn | FormControlOptions | ValidatorFn[] | null | undefined, asyncValidator?: AsyncValidatorFn | AsyncValidatorFn[] | null | undefined): FormControl<T | null>;
  array<T>(controls: T[], validatorOrOpts?: ValidatorFn | AbstractControlOptions | ValidatorFn[] | null | undefined, asyncValidator?: AsyncValidatorFn | AsyncValidatorFn[] | null | undefined): FormArray<ɵElement<T, null>>;
}

nonNullable

NonNullableFormBuilder

Возвращает FormBuilder, в котором автоматически создаваемые элементы FormControl имеют {nonNullable: true} и не допускают значения null.

Создание элементов управления, не допускающих значения null

При создании элемент управления не будет допускать значение null и будет сбрасываться до исходного значения.

let nnfb = new FormBuilder().nonNullable;
let name = nnfb.control('Alex'); // FormControl<string>
name.reset();
console.log(name); // 'Alex'

Создание групп или массивов, не допускающих значения null

При создании группы или массива все автоматически создаваемые внутренние элементы управления не будут допускать значения null и будут сбрасываться до исходных значений.

let nnfb = new FormBuilder().nonNullable;
let name = nnfb.group({who: 'Alex'}); // FormGroup<{who: FormControl<string>}>
name.reset();
console.log(name); // {who: 'Alex'}

Создание допускающих значение null полей в группах или массивах

Поле по-прежнему может допускать значение null. В частности, любой FormControl, который уже создан, не будет изменен. Например:

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}

Поскольку внутренний элемент управления явно создается вызывающим кодом, конструктор не может контролировать способ его создания и исключить null.

group

2 перегрузки

Создает экземпляр FormGroup. Принимает один обобщенный аргумент — объект, содержащий все ключи и соответствующие типы внутренних элементов управления.

@paramcontrolsT

Коллекция дочерних элементов управления. Ключ каждого дочернего элемента — это имя, под которым он зарегистрирован. Каждое значение может быть одним из следующих вариантов:

Экземпляр AbstractControl — передается без изменений.
Исходное значение — сокращенная форма записи fb.control(value).
Объект FormControlState ({value, disabled}) — инициализирует элемент управления значением и состоянием отключения.
Кортеж ControlConfig — [value | FormControlState, validatorOrOpts?, asyncValidator?]. Второй элемент принимает ValidatorFn, массив значений ValidatorFn или объект AbstractControlOptions (используйте его, чтобы задать updateOn). Необязательный третий элемент принимает AsyncValidatorFn или массив значений AsyncValidatorFn.

@paramoptionsAbstractControlOptions | null | undefined

Объект параметров конфигурации для FormGroup. Объект должен иметь тип AbstractControlOptions и может содержать следующие поля:

validators: Функция синхронного валидатора или массив функций-валидаторов.
asyncValidators: Один асинхронный валидатор или массив функций асинхронных валидаторов.
updateOn: Событие, при котором следует обновить элемент управления (варианты: 'change' | 'blur' | submit').

@returnsFormGroup<ɵNullableFormControls<T>>

Примечания по использованию

Различные способы задания значения элемента управления

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),
});

Создает экземпляр FormGroup.

@deprecated

Этот API не является типобезопасным и может приводить к проблемам при переименовании в Closure Compiler. Вместо этого используйте перегрузку FormBuilder#group с AbstractControlOptions. Обратите внимание: AbstractControlOptions требует, чтобы validators и asyncValidators были допустимыми валидаторами. Если вы используете пользовательские валидаторы, убедитесь, что параметр их функции проверки имеет тип AbstractControl, а не подкласса, например FormGroup. Эти функции будут вызваны с объектом типа AbstractControl, который нельзя автоматически привести к подклассу, поэтому TypeScript считает это ошибкой. Например, измените сигнатуру (group: FormGroup) => ValidationErrors|null на (group: AbstractControl) => ValidationErrors|null.

@paramcontrols{ [key: string]: any; }

Запись дочерних элементов управления. Ключ каждого дочернего элемента — это имя, под которым зарегистрирован элемент управления.

@paramoptions{ [key: string]: any; }

Объект параметров конфигурации для FormGroup. Устаревший объект конфигурации состоит из следующих полей:

validator: Функция синхронного валидатора или массив функций-валидаторов.
asyncValidator: Один асинхронный валидатор или массив функций асинхронных валидаторов. Примечание: устаревший формат признан устаревшим и может быть удален в одном из следующих основных выпусков Angular.

@returnsFormGroup<any>

record

FormRecord<ɵElement<T, null>>

Создает экземпляр FormRecord. Принимает один обобщенный аргумент — объект, содержащий все ключи и соответствующие типы внутренних элементов управления.

@paramcontrols{ [key: string]: T; }

Коллекция дочерних элементов управления. Ключ каждого дочернего элемента — это имя, под которым он зарегистрирован.

@paramoptionsAbstractControlOptions | null

Объект параметров конфигурации для FormRecord. Объект должен иметь тип AbstractControlOptions и может содержать следующие поля:

validators: Функция синхронного валидатора или массив функций-валидаторов.
asyncValidators: Один асинхронный валидатор или массив функций асинхронных валидаторов.
updateOn: Событие, при котором следует обновить элемент управления (варианты: 'change' | 'blur' | submit').

@returnsFormRecord<ɵElement<T, null>>

control

4 перегрузки

@deprecated

Вместо этого используйте nonNullable.

@paramformStateT | FormControlState<T>

@paramoptsFormControlOptions & { initialValueIsDefault: true; }

@returnsFormControl<T>

@paramformStateT | FormControlState<T>

@paramoptsFormControlOptions & { nonNullable: true; }

@returnsFormControl<T>

@deprecated

При передаче аргумента options аргумент asyncValidator не оказывает влияния.

@paramformStateT | FormControlState<T>

@paramoptsFormControlOptions

@paramasyncValidatorAsyncValidatorFn | AsyncValidatorFn[]

@returnsFormControl<T | null>

@paramformStateT | FormControlState<T>

@paramvalidatorOrOptsValidatorFn | FormControlOptions | ValidatorFn[] | null | undefined

@paramasyncValidatorAsyncValidatorFn | AsyncValidatorFn[] | null | undefined

@returnsFormControl<T | null>

array

FormArray<ɵElement<T, null>>

Создает FormArray из заданного массива конфигураций, валидаторов и параметров. Принимает один обобщенный аргумент — тип каждого элемента управления в массиве.

@paramcontrolsT[]

Массив дочерних элементов управления или конфигураций элементов управления. При регистрации каждому дочернему элементу управления присваивается индекс.

@paramvalidatorOrOptsValidatorFn | AbstractControlOptions | ValidatorFn[] | null | undefined

Функция синхронного валидатора, массив таких функций или объект AbstractControlOptions, содержащий функции проверки и событие запуска проверки.

@paramasyncValidatorAsyncValidatorFn | AsyncValidatorFn[] | null | undefined

Один асинхронный валидатор или массив функций асинхронных валидаторов.

@returnsFormArray<ɵElement<T, null>>

Описание

Создает AbstractControl на основе конфигурации, заданной пользователем.

FormBuilder предоставляет синтаксический сахар, упрощающий создание экземпляров FormControl, FormGroup или FormArray. Это сокращает объем шаблонного кода, необходимого для создания сложных форм.