FormArray

Отслеживает значение и состояние валидности массива экземпляров FormControl, FormGroup или FormArray.

API

class FormArray<TControl extends AbstractControl<any> = any> extends AbstractControl<
  ɵTypedOrUntyped<TControl, ɵFormArrayValue<TControl>, any>,
  ɵTypedOrUntyped<TControl, ɵFormArrayRawValue<TControl>, any>
> {
  constructor(controls: TControl[], validatorOrOpts?: ValidatorFn | AbstractControlOptions | ValidatorFn[] | null | undefined, asyncValidator?: AsyncValidatorFn | AsyncValidatorFn[] | null | undefined): FormArray<TControl>;
  controls: ɵTypedOrUntyped<TControl, TControl[], AbstractControl<any, any, any>[]>;
  at(index: number): ɵTypedOrUntyped<TControl, TControl, AbstractControl<any, any, any>>;
  push(control: TControl | TControl[], options?: { emitEvent?: boolean | undefined; }): void;
  insert(index: number, control: TControl, options?: { emitEvent?: boolean | undefined; }): void;
  removeAt(index: number, options?: { emitEvent?: boolean | undefined; }): void;
  setControl(index: number, control: TControl, options?: { emitEvent?: boolean | undefined; }): void;
  readonly length: number;
  setValue(value: ɵIsAny<TControl, any[], ɵRawValue<TControl>[]>, options?: { onlySelf?: boolean | undefined; emitEvent?: boolean | undefined; }): void;
  patchValue(value: ɵIsAny<TControl, any[], ɵValue<TControl>[]>, options?: { onlySelf?: boolean | undefined; emitEvent?: boolean | undefined; }): void;
  reset(value?: ɵTypedOrUntyped<TControl, ɵIsAny<TControl, any[], ɵValue<TControl>[]>, any>, options?: { onlySelf?: boolean | undefined; emitEvent?: boolean | undefined; overwriteDefaultValue?: boolean | undefined; }): void;
  getRawValue(): ɵIsAny<TControl, any[], ɵRawValue<TControl>[]>;
  clear(options?: { emitEvent?: boolean | undefined; }): void;
  readonly override value: TValue;
  override get validator(): ValidatorFn | null;
  override get asyncValidator(): AsyncValidatorFn | null;
  override readonly parent: FormGroup<any> | FormArray<any> | null;
  override readonly status: FormControlStatus;
  override readonly valid: boolean;
  override readonly invalid: boolean;
  override readonly pending: boolean;
  override readonly disabled: boolean;
  override readonly enabled: boolean;
  readonly override errors: ValidationErrors | null;
  override readonly pristine: boolean;
  override readonly dirty: boolean;
  override readonly touched: boolean;
  override readonly untouched: boolean;
  readonly override events: any;
  readonly override valueChanges: Observable<TValue>;
  readonly override statusChanges: Observable<FormControlStatus>;
  override readonly updateOn: FormHooks;
  override setValidators(validators: ValidatorFn | ValidatorFn[] | null): void;
  override setAsyncValidators(validators: AsyncValidatorFn | AsyncValidatorFn[] | null): void;
  override addValidators(validators: ValidatorFn | ValidatorFn[]): void;
  override addAsyncValidators(validators: AsyncValidatorFn | AsyncValidatorFn[]): void;
  override removeValidators(validators: ValidatorFn | ValidatorFn[]): void;
  override removeAsyncValidators(validators: AsyncValidatorFn | AsyncValidatorFn[]): void;
  override hasValidator(validator: ValidatorFn): boolean;
  override hasAsyncValidator(validator: AsyncValidatorFn): boolean;
  override clearValidators(): void;
  override clearAsyncValidators(): void;
  override markAsTouched(opts?: { onlySelf?: boolean | undefined; emitEvent?: boolean | undefined; } | undefined): void;
  override markAsTouched(opts?: { onlySelf?: boolean | undefined; emitEvent?: boolean | undefined; sourceControl?: AbstractControl<any, any, any> | undefined; } | undefined): void;
  override markAllAsDirty(opts?: { emitEvent?: boolean | undefined; }): void;
  override markAllAsTouched(opts?: { emitEvent?: boolean | undefined; }): void;
  override markAsUntouched(opts?: { onlySelf?: boolean | undefined; emitEvent?: boolean | undefined; } | undefined): void;
  override markAsUntouched(opts: { onlySelf?: boolean | undefined; emitEvent?: boolean | undefined; sourceControl?: AbstractControl<any, any, any> | undefined; }): void;
  override markAsDirty(opts?: { onlySelf?: boolean | undefined; emitEvent?: boolean | undefined; } | undefined): void;
  override markAsDirty(opts: { onlySelf?: boolean | undefined; emitEvent?: boolean | undefined; sourceControl?: AbstractControl<any, any, any> | undefined; }): void;
  override markAsPristine(opts?: { onlySelf?: boolean | undefined; emitEvent?: boolean | undefined; } | undefined): void;
  override markAsPristine(opts: { onlySelf?: boolean | undefined; emitEvent?: boolean | undefined; sourceControl?: AbstractControl<any, any, any> | undefined; }): void;
  override markAsPending(opts?: { onlySelf?: boolean | undefined; emitEvent?: boolean | undefined; } | undefined): void;
  override markAsPending(opts: { onlySelf?: boolean | undefined; emitEvent?: boolean | undefined; sourceControl?: AbstractControl<any, any, any> | undefined; }): void;
  override disable(opts?: { onlySelf?: boolean | undefined; emitEvent?: boolean | undefined; } | undefined): void;
  override disable(opts: { onlySelf?: boolean | undefined; emitEvent?: boolean | undefined; sourceControl?: AbstractControl<any, any, any> | undefined; }): void;
  override enable(opts?: { onlySelf?: boolean | undefined; emitEvent?: boolean | undefined; }): void;
  override setParent(parent: FormGroup<any> | FormArray<any> | null): void;
  override updateValueAndValidity(opts?: { onlySelf?: boolean | undefined; emitEvent?: boolean | undefined; } | undefined): void;
  override updateValueAndValidity(opts: { onlySelf?: boolean | undefined; emitEvent?: boolean | undefined; sourceControl?: AbstractControl<any, any, any> | undefined; }): void;
  override setErrors(errors: ValidationErrors | null, opts?: { emitEvent?: boolean | undefined; } | undefined): void;
  override setErrors(errors: ValidationErrors | null, opts?: { emitEvent?: boolean | undefined; shouldHaveEmitted?: boolean | undefined; } | undefined): void;
  override get<P extends string | readonly (string | number)[]>(path: P): AbstractControl<ɵGetProperty<TRawValue, P>, ɵGetProperty<TRawValue, P>, any> | null;
  override get<P extends string | Array<string | number>>(path: P): AbstractControl<ɵGetProperty<TRawValue, P>, ɵGetProperty<TRawValue, P>, any> | null;
  override getError(errorCode: string, path?: string | (string | number)[] | undefined): any;
  override hasError(errorCode: string, path?: string | (string | number)[] | undefined): boolean;
  override readonly root: AbstractControl<any, any, any>;
}

constructor

FormArray<TControl>

Создаёт новый экземпляр FormArray.

@paramcontrolsTControl[]

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

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

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

@paramasyncValidatorAsyncValidatorFn | AsyncValidatorFn[] | null | undefined

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

@returnsFormArray<TControl>

controls

ɵTypedOrUntyped<TControl, TControl[], AbstractControl<any, any, any>[]>

at

ɵTypedOrUntyped<TControl, TControl, AbstractControl<any, any, any>>

Получает AbstractControl по указанному index в массиве.

@paramindexnumber

Индекс элемента управления, который нужно получить из массива. Если index отрицательный, отсчёт ведётся с конца массива; если индекс очень мал (меньше -length), результат не определён. Это поведение аналогично Array.at(index).

@returnsɵTypedOrUntyped<TControl, TControl, AbstractControl<any, any, any>>

push

void

Добавляет новый AbstractControl в конец массива.

@paramcontrolTControl | TControl[]

Элемент управления формой, который нужно добавить

@paramoptions{ emitEvent?: boolean | undefined; }

Указывает, следует ли этому экземпляру FormArray генерировать события после добавления нового элемента управления.

emitEvent: если задано значение true или параметр не указан (по умолчанию), оба наблюдаемых объекта statusChanges и valueChanges генерируют события с последними значениями статуса и значения при добавлении элемента управления. Если задано значение false, события не генерируются.

ПРИМЕЧАНИЕ: Добавление элемента в FormArray не помечает его как изменённый. Чтобы пометить его как изменённый, вызовите markAsDirty().

@returnsvoid

insert

void

Вставляет новый AbstractControl по указанному index в массиве.

@paramindexnumber

Индекс массива, по которому нужно вставить элемент управления. Если index отрицательный, отсчёт ведётся с конца массива. Если index очень мал (меньше -length), элемент добавляется в начало массива. Это поведение аналогично Array.splice(index, 0, control).

@paramcontrolTControl

Элемент управления формой, который нужно вставить

@paramoptions{ emitEvent?: boolean | undefined; }

Указывает, следует ли этому экземпляру FormArray генерировать события после вставки нового элемента управления.

emitEvent: если задано значение true или параметр не указан (по умолчанию), оба наблюдаемых объекта statusChanges и valueChanges генерируют события с последними значениями статуса и значения при вставке элемента управления. Если задано значение false, события не генерируются.

ПРИМЕЧАНИЕ: Вставка элемента в FormArray не помечает его как изменённый. Чтобы пометить его как изменённый, вызовите markAsDirty().

@returnsvoid

removeAt

void

Удаляет элемент управления по указанному index в массиве.

@paramindexnumber

Индекс массива, по которому нужно удалить элемент управления. Если index отрицательный, отсчёт ведётся с конца массива. Если index очень мал (меньше -length), удаляется первый элемент. Это поведение аналогично Array.splice(index, 1).

@paramoptions{ emitEvent?: boolean | undefined; }

Указывает, следует ли этому экземпляру FormArray генерировать события после удаления элемента управления.

emitEvent: если задано значение true или параметр не указан (по умолчанию), оба наблюдаемых объекта statusChanges и valueChanges генерируют события с последними значениями статуса и значения при удалении элемента управления. Если задано значение false, события не генерируются.

ПРИМЕЧАНИЕ: Удаление элемента из FormArray не помечает его как изменённый. Чтобы пометить его как изменённый, вызовите markAsDirty().

@returnsvoid

setControl

void

Заменяет существующий элемент управления.

@paramindexnumber

Индекс массива, по которому нужно заменить элемент управления. Если index отрицательный, отсчёт ведётся с конца массива. Если index очень мал (меньше -length), заменяется первый элемент. Это поведение аналогично Array.splice(index, 1, control).

@paramcontrolTControl

Элемент управления AbstractControl, заменяющий существующий элемент управления

@paramoptions{ emitEvent?: boolean | undefined; }

Указывает, следует ли этому экземпляру FormArray генерировать события после замены существующего элемента управления новым.

emitEvent: если задано значение true или параметр не указан (по умолчанию), оба наблюдаемых объекта statusChanges и valueChanges генерируют события с последними значениями статуса и значения после замены элемента управления новым. Если задано значение false, события не генерируются.

@returnsvoid

length

number

Длина массива элементов управления.

setValue

void

Задаёт значение FormArray. Метод принимает массив, соответствующий структуре элемента управления.

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

@paramvalueɵIsAny<TControl, any[], ɵRawValue<TControl>[]>

Массив значений элементов управления

@paramoptions{ onlySelf?: boolean | undefined; emitEvent?: boolean | undefined; }

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

onlySelf: если задано значение true, каждое изменение влияет только на этот элемент управления, но не на его родительский элемент. Значение по умолчанию — false.
emitEvent: если задано значение true или параметр не указан (по умолчанию), оба наблюдаемых объекта statusChanges и valueChanges генерируют события с последними значениями статуса и значения при обновлении значения элемента управления. Если задано значение false, события не генерируются. Параметры конфигурации передаются методу * updateValueAndValidity.

@returnsvoid

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

Задание значений элементов управления в массиве формы

const arr = new FormArray([
  new FormControl(),
  new FormControl()
]);
console.log(arr.value);   // [null, null]

arr.setValue(['Nancy', 'Drew']);
console.log(arr.value);   // ['Nancy', 'Drew']

patchValue

void

Частично задаёт значение FormArray. Метод принимает массив, соответствующий структуре элемента управления, и старается сопоставить значения с правильными элементами управления в группе.

Он принимает как массивы с дополнительными элементами, так и массивы с пропущенными элементами, не выбрасывая ошибку.

@paramvalueɵIsAny<TControl, any[], ɵValue<TControl>[]>

Массив последних значений элементов управления

@paramoptions{ onlySelf?: boolean | undefined; emitEvent?: boolean | undefined; }

onlySelf: если задано значение true, каждое изменение влияет только на этот элемент управления, но не на его родительский элемент. Значение по умолчанию — false.
emitEvent: если задано значение true или параметр не указан (по умолчанию), оба наблюдаемых объекта statusChanges и valueChanges генерируют события с последними значениями статуса и значения при обновлении значения элемента управления. Если задано значение false, события не генерируются. Параметры конфигурации передаются методу updateValueAndValidity.

@returnsvoid

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

Частичное задание значений элементов управления в массиве формы

const arr = new FormArray([
   new FormControl(),
   new FormControl()
]);
console.log(arr.value);   // [null, null]

arr.patchValue(['Nancy']);
console.log(arr.value);   // ['Nancy', null]

reset

void

Сбрасывает FormArray, помечает все дочерние элементы как pristine и untouched, а значения всех дочерних элементов устанавливает в null или в карты со значениями null.

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

@paramvalueɵTypedOrUntyped<TControl, ɵIsAny<TControl, any[], ɵValue<TControl>[]>, any>

Массив значений элементов управления

@paramoptions{ onlySelf?: boolean | undefined; emitEvent?: boolean | undefined; overwriteDefaultValue?: boolean | undefined; }

onlySelf: если задано значение true, каждое изменение влияет только на этот элемент управления, но не на его родительский элемент. Значение по умолчанию — false.
emitEvent: если задано значение true или параметр не указан (по умолчанию), оба наблюдаемых объекта statusChanges и valueChanges генерируют события с последними значениями статуса и значения при сбросе элемента управления. Если задано значение false, события не генерируются. Параметры конфигурации передаются методу * updateValueAndValidity.

@returnsvoid

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

Сброс значений в массиве формы

const arr = new FormArray([
   new FormControl(),
   new FormControl()
]);
arr.reset(['name', 'last name']);

console.log(arr.value);  // ['name', 'last name']

Сброс значений в массиве формы и статуса отключения первого элемента управления

arr.reset([
  {value: 'name', disabled: true},
  'last'
]);

console.log(arr.value);  // ['last']
console.log(arr.at(0).status);  // 'DISABLED'

getRawValue

ɵIsAny<TControl, any[], ɵRawValue<TControl>[]>

Общее значение массива, включая отключённые элементы управления.

Возвращает все значения независимо от статуса отключения.

@returnsɵIsAny<TControl, any[], ɵRawValue<TControl>[]>

clear

void

Удаляет все элементы управления из FormArray.

@paramoptions{ emitEvent?: boolean | undefined; }

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

emitEvent: если задано значение true или параметр не указан (по умолчанию), оба наблюдаемых объекта statusChanges и valueChanges генерируют события с последними значениями статуса и значения при удалении всех элементов управления из этого экземпляра FormArray. Если задано значение false, события не генерируются.

@returnsvoid

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

Удаление всех элементов из FormArray

const arr = new FormArray([
   new FormControl(),
   new FormControl()
]);
console.log(arr.length);  // 2

arr.clear();
console.log(arr.length);  // 0

Это более простой и эффективный способ, чем удалять все элементы по одному:

const arr = new FormArray([
   new FormControl(),
   new FormControl()
]);

while (arr.length) {
   arr.removeAt(0);
}

value

TValue

Текущее значение элемента управления.

Для FormControl — текущее значение.
Для включённого FormGroup — значения включённых элементов управления в виде объекта с парой «ключ — значение» для каждого элемента группы.
Для отключённого FormGroup — значения всех элементов управления в виде объекта с парой «ключ — значение» для каждого элемента группы.
Для включённого FormArray — значения включённых элементов управления в виде массива.
Для отключённого FormArray — значения всех элементов управления в виде массива.

validator

ValidatorFn | null

Возвращает функцию, которая синхронно определяет допустимость этого элемента управления. Если добавлено несколько валидаторов, возвращается одна объединённая функция. Дополнительные сведения см. в разделе Validators.compose().

validator

ValidatorFn | null

asyncValidator

AsyncValidatorFn | null

Возвращает функцию, которая асинхронно определяет допустимость этого элемента управления. Если добавлено несколько валидаторов, возвращается одна объединённая функция. Дополнительные сведения см. в разделе Validators.compose().

asyncValidator

AsyncValidatorFn | null

parent

FormGroup<any> | FormArray<any> | null

Родительский элемент управления.

status

FormControlStatus

Статус проверки элемента управления.

valid

boolean

Элемент управления является valid, если его status имеет значение VALID.

invalid

boolean

Элемент управления является invalid, если его status имеет значение INVALID.

pending

boolean

Элемент управления находится в состоянии pending, если его status имеет значение PENDING.

disabled

boolean

Элемент управления является disabled, если его status имеет значение DISABLED.

Отключённые элементы управления не проходят проверку и не включаются в общее значение родительских элементов управления.

enabled

boolean

Элемент управления является enabled, пока его status не имеет значение DISABLED.

errors

ValidationErrors | null

Объект, содержащий ошибки, возникшие при неудачной проверке, или null, если ошибок нет.

pristine

boolean

Элемент управления считается pristine, если пользователь ещё не изменял его значение в пользовательском интерфейсе.

dirty

boolean

Элемент управления считается dirty, если пользователь изменил его значение в пользовательском интерфейсе.

touched

boolean

Значение true, если элемент управления помечен как touched.

Элемент управления помечается как touched, когда пользователь инициирует для него событие blur.

untouched

boolean

Значение true, если элемент управления не был помечен как затронутый

Элемент управления считается untouched, если пользователь ещё не инициировал для него событие blur.

events

any

Многоадресный наблюдаемый объект, который генерирует событие каждый раз при изменении состояния элемента управления. Он генерирует события при изменении значения, статуса, состояния pristine или touched.

Примечание: при изменении значения событие генерируется сразу после обновления значения этого элемента управления. Значение родительского элемента управления (например, если этот FormControl является частью FormGroup) обновляется позже, поэтому обращение к значению родительского элемента управления (с помощью свойства value) из обработчика этого события может вернуть ещё не обновлённое значение. Вместо этого подпишитесь на events родительского элемента управления. Для других типов событий события генерируются после обновления родительского элемента управления.

valueChanges

Observable<TValue>

Многоадресный наблюдаемый объект, который генерирует событие каждый раз при изменении значения элемента управления — в пользовательском интерфейсе или программно. Он также генерирует событие при каждом вызове enable() или disable(), если в качестве аргумента функции не передан параметр {emitEvent: false}.

Примечание: событие генерируется сразу после обновления значения этого элемента управления. Значение родительского элемента управления (например, если этот FormControl является частью FormGroup) обновляется позже, поэтому обращение к значению родительского элемента управления (с помощью свойства value) из обработчика этого события может вернуть ещё не обновлённое значение. Вместо этого подпишитесь на событие valueChanges родительского элемента управления.

statusChanges

Observable<FormControlStatus>

Многоадресный наблюдаемый объект, который генерирует событие каждый раз при пересчёте status проверки элемента управления.

updateOn

FormHooks

Сообщает стратегию обновления AbstractControl (то есть событие, при наступлении которого элемент управления обновляется). Возможные значения: 'change' | 'blur' | 'submit' Значение по умолчанию: 'change'

setValidators

void

Задаёт синхронные валидаторы, активные для этого элемента управления. При вызове заменяются все существующие синхронные валидаторы.

При добавлении или удалении валидатора во время выполнения необходимо вызвать updateValueAndValidity(), чтобы новые правила проверки вступили в силу.

Чтобы добавить новый валидатор, не затрагивая существующие, рассмотрите возможность использования метода addValidators().

@paramvalidatorsValidatorFn | ValidatorFn[] | null

@returnsvoid

setAsyncValidators

void

Задаёт асинхронные валидаторы, активные для этого элемента управления. При вызове заменяются все существующие асинхронные валидаторы.

Чтобы добавить новый валидатор, не затрагивая существующие, рассмотрите возможность использования метода addAsyncValidators().

@paramvalidatorsAsyncValidatorFn | AsyncValidatorFn[] | null

@returnsvoid

addValidators

void

Добавляет синхронный валидатор или валидаторы в этот элемент управления, не затрагивая другие валидаторы.

При добавлении или удалении валидатора во время выполнения необходимо вызвать updateValueAndValidity(), чтобы новое правило проверки вступило в силу.

Добавление уже существующего валидатора не повлияет на результат. Если в массиве validators есть повторяющиеся функции-валидаторы, в элемент управления формы будет добавлен только первый экземпляр.

@paramvalidatorsValidatorFn | ValidatorFn[]

Новая функция-валидатор или функции-валидаторы, которые нужно добавить в этот элемент управления.

@returnsvoid

addAsyncValidators

void

Добавляет асинхронный валидатор или валидаторы в этот элемент управления, не затрагивая другие валидаторы.

Добавление уже существующего валидатора не повлияет на результат.

@paramvalidatorsAsyncValidatorFn | AsyncValidatorFn[]

Новая асинхронная функция-валидатор или функции-валидаторы, которые нужно добавить в этот элемент управления.

@returnsvoid

removeValidators

void

Удаляет синхронный валидатор из этого элемента управления, не затрагивая другие валидаторы. Валидаторы сравниваются по ссылке на функцию; необходимо передать ссылку именно на ту же функцию-валидатор, которая была установлена изначально. Если указанный валидатор не найден, он игнорируется.

@paramvalidatorsValidatorFn | ValidatorFn[]

Валидатор или валидаторы, которые нужно удалить.

@returnsvoid

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

// Reference to the RequiredValidator
const ctrl = new FormControl<string | null>('', Validators.required);
ctrl.removeValidators(Validators.required);

// Reference to anonymous function inside MinValidator
const minValidator = Validators.min(3);
const ctrl = new FormControl<string | null>('', minValidator);
expect(ctrl.hasValidator(minValidator)).toEqual(true)
expect(ctrl.hasValidator(Validators.min(3))).toEqual(false)

ctrl.removeValidators(minValidator);

removeAsyncValidators

void

Удаляет асинхронный валидатор из этого элемента управления, не затрагивая другие валидаторы. Валидаторы сравниваются по ссылке на функцию; необходимо передать ссылку именно на ту же функцию-валидатор, которая была установлена изначально. Если указанный валидатор не найден, он игнорируется.

@paramvalidatorsAsyncValidatorFn | AsyncValidatorFn[]

Асинхронный валидатор или валидаторы, которые нужно удалить.

@returnsvoid

hasValidator

boolean

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

@paramvalidatorValidatorFn

Валидатор, наличие которого нужно проверить. Сравнение выполняется по ссылке на функцию.

@returnsboolean

Найден ли указанный валидатор в этом элементе управления.

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

// Reference to the RequiredValidator
const ctrl = new FormControl<number | null>(0, Validators.required);
expect(ctrl.hasValidator(Validators.required)).toEqual(true)

// Reference to anonymous function inside MinValidator
const minValidator = Validators.min(3);
const ctrl = new FormControl<number | null>(0, minValidator);
expect(ctrl.hasValidator(minValidator)).toEqual(true)
expect(ctrl.hasValidator(Validators.min(3))).toEqual(false)

hasAsyncValidator

boolean

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

@paramvalidatorAsyncValidatorFn

Асинхронный валидатор, наличие которого нужно проверить. Сравнение выполняется по ссылке на функцию.

@returnsboolean

Найден ли указанный асинхронный валидатор в этом элементе управления.

clearValidators

void

Очищает список синхронных валидаторов.

@returnsvoid

clearAsyncValidators

void

Очищает список асинхронных валидаторов.

@returnsvoid

markAsTouched

2 перегрузки

Помечает элемент управления как touched. Элемент управления считается затронутым при событиях фокусировки и потери фокуса, не изменяющих значение.

@paramopts{ onlySelf?: boolean | undefined; emitEvent?: boolean | undefined; } | undefined

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

onlySelf: если значение равно true, помечается только этот элемент управления. Если значение равно false или не указано, помечаются все непосредственные предки. Значение по умолчанию — false.
emitEvent: если значение равно true или не указано (по умолчанию), наблюдаемый объект events отправляет TouchedChangeEvent, у которого свойство touched имеет значение true. Если значение равно false, события не отправляются.

@returnsvoid

@paramopts

{ onlySelf?: boolean | undefined; emitEvent?: boolean | undefined; sourceControl?: AbstractControl<any, any, any> | undefined; } | undefined

@returnsvoid

markAllAsDirty

void

Помечает элемент управления и все его дочерние элементы управления как dirty.

@paramopts{ emitEvent?: boolean | undefined; }

emitEvent: если значение равно true или не указано (по умолчанию), наблюдаемый объект events отправляет PristineChangeEvent, у которого свойство pristine имеет значение false. Если значение равно false, события не отправляются.

@returnsvoid

markAllAsTouched

void

Помечает элемент управления и все его дочерние элементы управления как touched.

@paramopts{ emitEvent?: boolean | undefined; }

emitEvent: если значение равно true или не указано (по умолчанию), наблюдаемый объект events отправляет TouchedChangeEvent, у которого свойство touched имеет значение true. Если значение равно false, события не отправляются.

@returnsvoid

markAsUntouched

2 перегрузки

Помечает элемент управления как untouched.

Если у элемента управления есть дочерние элементы, они также помечаются как untouched, а состояние touched всех родительских элементов управления пересчитывается.

@paramopts{ onlySelf?: boolean | undefined; emitEvent?: boolean | undefined; } | undefined

onlySelf: если значение равно true, помечается только этот элемент управления. Если значение равно false или не указано, помечаются все непосредственные предки. Значение по умолчанию — false.
emitEvent: если значение равно true или не указано (по умолчанию), наблюдаемый объект events отправляет TouchedChangeEvent, у которого свойство touched имеет значение false. Если значение равно false, события не отправляются.

@returnsvoid

@paramopts

{ onlySelf?: boolean | undefined; emitEvent?: boolean | undefined; sourceControl?: AbstractControl<any, any, any> | undefined; }

@returnsvoid

markAsDirty

2 перегрузки

Помечает элемент управления как dirty. Элемент управления становится измененным, когда его значение меняется через пользовательский интерфейс; сравните с markAsTouched.

@paramopts{ onlySelf?: boolean | undefined; emitEvent?: boolean | undefined; } | undefined

onlySelf: если значение равно true, помечается только этот элемент управления. Если значение равно false или не указано, помечаются все непосредственные предки. Значение по умолчанию — false.
emitEvent: если значение равно true или не указано (по умолчанию), наблюдаемый объект events отправляет PristineChangeEvent, у которого свойство pristine имеет значение false. Если значение равно false, события не отправляются.

@returnsvoid

@paramopts

{ onlySelf?: boolean | undefined; emitEvent?: boolean | undefined; sourceControl?: AbstractControl<any, any, any> | undefined; }

@returnsvoid

markAsPristine

2 перегрузки

Помечает элемент управления как pristine.

Если у элемента управления есть дочерние элементы, они также помечаются как pristine, а состояние pristine всех родительских элементов управления пересчитывается.

@paramopts{ onlySelf?: boolean | undefined; emitEvent?: boolean | undefined; } | undefined

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

onlySelf: если значение равно true, помечается только этот элемент управления. Если значение равно false или не указано, помечаются все непосредственные предки. Значение по умолчанию — false.
emitEvent: если значение равно true или не указано (по умолчанию), наблюдаемый объект events отправляет PristineChangeEvent, у которого свойство pristine имеет значение true. Если значение равно false, события не отправляются.

@returnsvoid

@paramopts

{ onlySelf?: boolean | undefined; emitEvent?: boolean | undefined; sourceControl?: AbstractControl<any, any, any> | undefined; }

@returnsvoid

markAsPending

2 перегрузки

Помечает элемент управления как pending.

Элемент управления находится в состоянии ожидания, пока выполняется асинхронная проверка.

@paramopts{ onlySelf?: boolean | undefined; emitEvent?: boolean | undefined; } | undefined

onlySelf: если значение равно true, помечается только этот элемент управления. Если значение равно false или не указано, помечаются все непосредственные предки. Значение по умолчанию — false.
emitEvent: если значение равно true или не указано (по умолчанию), наблюдаемый объект statusChanges отправляет событие с последним состоянием, присвоенным элементу управления при переводе в состояние ожидания, а наблюдаемый объект events отправляет StatusChangeEvent, у которого свойство status имеет значение PENDING. Если значение равно false, события не отправляются.

@returnsvoid

@paramopts

{ onlySelf?: boolean | undefined; emitEvent?: boolean | undefined; sourceControl?: AbstractControl<any, any, any> | undefined; }

@returnsvoid

disable

2 перегрузки

Отключает элемент управления. Это означает, что он исключается из проверок и агрегированного значения любого родительского элемента. Его статус — DISABLED.

Если у элемента управления есть дочерние элементы, они также отключаются.

@paramopts{ onlySelf?: boolean | undefined; emitEvent?: boolean | undefined; } | undefined

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

onlySelf: если значение равно true, помечается только этот элемент управления. Если значение равно false или не указано, помечаются все непосредственные предки. Значение по умолчанию — false.
emitEvent: если значение равно true или не указано (по умолчанию), наблюдаемые объекты statusChanges, valueChanges и events отправляют события с последним статусом и значением при отключении элемента управления. Если значение равно false, события не отправляются.

@returnsvoid

@paramopts

{ onlySelf?: boolean | undefined; emitEvent?: boolean | undefined; sourceControl?: AbstractControl<any, any, any> | undefined; }

@returnsvoid

enable

void

Включает элемент управления. Это означает, что он учитывается при проверках и в агрегированном значении родительского элемента. Его статус пересчитывается на основе значения и валидаторов.

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

@paramopts{ onlySelf?: boolean | undefined; emitEvent?: boolean | undefined; }

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

onlySelf: если значение равно true, помечается только этот элемент управления. Если значение равно false или не указано, помечаются все непосредственные предки. Значение по умолчанию — false.
emitEvent: если значение равно true или не указано (по умолчанию), наблюдаемые объекты statusChanges, valueChanges и events отправляют события с последним статусом и значением при включении элемента управления. Если значение равно false, события не отправляются.

@returnsvoid

setParent

void

Устанавливает родительский элемент управления для этого элемента управления

@paramparentFormGroup<any> | FormArray<any> | null

Новый родительский элемент.

@returnsvoid

updateValueAndValidity

2 перегрузки

Пересчитывает значение и статус проверки элемента управления.

По умолчанию также обновляются значение и валидность всех родительских элементов.

@paramopts{ onlySelf?: boolean | undefined; emitEvent?: boolean | undefined; } | undefined

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

onlySelf: если значение равно true, обновляется только этот элемент управления. Если значение равно false или не указано, обновляются все непосредственные предки. Значение по умолчанию — false.
emitEvent: если значение равно true или не указано (по умолчанию), наблюдаемые объекты statusChanges, valueChanges и events отправляют события с последним статусом и значением при обновлении элемента управления. Если значение равно false, события не отправляются.

@returnsvoid

@paramopts

{ onlySelf?: boolean | undefined; emitEvent?: boolean | undefined; sourceControl?: AbstractControl<any, any, any> | undefined; }

@returnsvoid

setErrors

2 перегрузки

Устанавливает ошибки элемента управления формы при выполнении проверок вручную, а не автоматически.

Вызов setErrors также обновляет валидность родительского элемента управления.

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

@paramerrorsValidationErrors | null

@paramopts{ emitEvent?: boolean | undefined; } | undefined

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

emitEvent: если значение равно true или не указано (по умолчанию), наблюдаемый объект statusChanges отправляет событие после установки ошибок.

@returnsvoid

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

Вручную задайте ошибки для элемента управления

const login = new FormControl('someLogin');
login.setErrors({
  notUnique: true
});

expect(login.valid).toEqual(false);
expect(login.errors).toEqual({ notUnique: true });

login.setValue('someOtherLogin');

expect(login.valid).toEqual(true);

@paramerrorsValidationErrors | null

@paramopts{ emitEvent?: boolean | undefined; shouldHaveEmitted?: boolean | undefined; } | undefined

@returnsvoid

get

2 перегрузки

Получает дочерний элемент управления по его имени или пути.

Эта сигнатура метода get поддерживает строки и массивы const (.get(['foo', 'bar'] as const)).

@parampathP

@returnsAbstractControl<ɵGetProperty<TRawValue, P>, ɵGetProperty<TRawValue, P>, any> | null

Получает дочерний элемент управления по его имени или пути.

Эта сигнатура метода get поддерживает массивы, не являющиеся константными (изменяемые). Вывод информации о типе будет менее точным, поэтому по возможности используйте массив readonly.

@parampathP

@returnsAbstractControl<ɵGetProperty<TRawValue, P>, ɵGetProperty<TRawValue, P>, any> | null

getError

any

Возвращает данные об ошибке для элемента управления, указанного путем.

@paramerrorCodestring

Код ошибки, которую нужно проверить

@parampathstring | (string | number)[] | undefined

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

@returnsany

Данные об указанной ошибке. Если элемент управления или ошибка отсутствуют, возвращается null.

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

Например, для следующей FormGroup:

form = new FormGroup({
  address: new FormGroup({ street: new FormControl() })
});

Путь к элементу управления 'street' от корневой формы: 'address' -> 'street'.

Его можно передать этому методу в одном из двух форматов:

Массив строк с именами элементов управления, например ['address', 'street']
Список имен элементов управления, разделенных точками и записанных в одной строке, например 'address.street'

hasError

boolean

Сообщает, содержит ли элемент управления с указанным путём заданную ошибку.

@paramerrorCodestring

Код ошибки для проверки

@parampathstring | (string | number)[] | undefined

Список имён элементов управления, определяющий путь от текущего элемента управления до элемента управления, в котором следует проверить наличие ошибок.

@returnsboolean

наличие указанной ошибки у элемента управления по заданному пути.

Если элемент управления отсутствует, возвращается false.

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

Например, для следующей FormGroup:

form = new FormGroup({
  address: new FormGroup({ street: new FormControl() })
});

Путь к элементу управления 'street' от корневой формы будет таким: 'address' -> 'street'.

Его можно передать этому методу в одном из двух форматов:

Массив строк с именами элементов управления, например ['address', 'street']
Список имён элементов управления, разделённых точками, в виде одной строки, например 'address.street'

Если путь не указан, этот метод проверяет наличие ошибки у текущего элемента управления.

root

AbstractControl<any, any, any>

Возвращает предка верхнего уровня этого элемента управления.

Описание

Отслеживает значение и состояние валидности массива экземпляров FormControl, FormGroup или FormArray.

FormArray объединяет значения каждого дочернего элемента FormControl в массив. Статус вычисляется путём сведения значений статусов дочерних элементов. Например, если один из элементов управления в FormArray недействителен, весь массив становится недействительным. Аналогично, если все элементы управления в FormArray отключены, весь массив становится отключённым.

FormArray принимает один обобщённый аргумент — тип содержащихся в нём элементов управления. Если вам нужен массив с разнородными элементами, используйте UntypedFormArray.

FormArray — один из четырёх основных строительных блоков, используемых для определения форм в Angular, наряду с FormControl, FormGroup и FormRecord.

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

Создание массива элементов управления формы

const arr = new FormArray([
  new FormControl('Nancy', Validators.minLength(2)),
  new FormControl('Drew'),
]);

console.log(arr.value);   // ['Nancy', 'Drew']
console.log(arr.status);  // 'VALID'

Создание массива формы с валидаторами на уровне массива

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

Два типа валидаторов передаются отдельно — вторым и третьим аргументами соответственно — либо вместе в виде объекта параметров.

const arr = new FormArray([
  new FormControl('Nancy'),
  new FormControl('Drew')
], {validators: myValidator, asyncValidators: myAsyncValidator});

Установка свойства updateOn для всех элементов управления в массиве формы

Объект параметров используется для установки значения по умолчанию для свойства updateOn каждого дочернего элемента управления. Если на уровне массива задать updateOn равным 'blur', для всех дочерних элементов управления по умолчанию будет установлено значение 'blur', если только для дочернего элемента явно не задано другое значение updateOn.

const arr = new FormArray([
   new FormControl()
], {updateOn: 'blur'});

Добавление элементов управления в массив формы и их удаление

Чтобы изменить элементы управления в массиве, используйте методы push, insert, removeAt или clear самого FormArray. Эти методы обеспечивают правильное отслеживание элементов управления в иерархии формы. Не изменяйте напрямую массив элементов AbstractControl, используемый для создания экземпляра FormArray, так как это может привести к странному и неожиданному поведению, например к нарушению обнаружения изменений.

Super-powered by Google ©2010–2025.
Code licensed under an MIT-style License. Documentation licensed under CC BY 4.0.
https://angular.dev/api/forms/FormArray