FormGroup

Отслеживает значение и состояние валидности группы экземпляров FormControl.

API

class FormGroup<TControl extends {[K in keyof TControl]: AbstractControl<any>} = any> extends AbstractControl<
  ɵTypedOrUntyped<TControl, ɵFormGroupValue<TControl>, any>,
  ɵTypedOrUntyped<TControl, ɵFormGroupRawValue<TControl>, any>,
  ɵTypedOrUntyped<TControl, ɵFormGroupArgumentValue<TControl>, any>
> {
  constructor(controls: TControl, validatorOrOpts?: ValidatorFn | AbstractControlOptions | ValidatorFn[] | null | undefined, asyncValidator?: AsyncValidatorFn | AsyncValidatorFn[] | null | undefined): FormGroup<TControl>;
  controls: ɵTypedOrUntyped<TControl, TControl, { [key: string]: AbstractControl<any, any, any>; }>;
  registerControl<K extends string & keyof TControl>(name: K, control: TControl[K]): TControl[K];
  registerControl(this: FormGroup<{ [key: string]: AbstractControl<any, any, any>; }>, name: string, control: AbstractControl<any, any, any>): AbstractControl<any, any, any>;
  addControl(this: FormGroup<{ [key: string]: AbstractControl<any, any, any>; }>, name: string, control: AbstractControl<any, any, any>, options?: { emitEvent?: boolean | undefined; } | undefined): void;
  addControl<K extends string & keyof TControl>(name: K, control: Required<TControl>[K], options?: { emitEvent?: boolean | undefined; } | undefined): void;
  removeControl(this: FormGroup<{ [key: string]: AbstractControl<any, any, any>; }>, name: string, options?: { emitEvent?: boolean | undefined; } | undefined): void;
  removeControl<S extends string>(name: ɵOptionalKeys<TControl> & S, options?: { emitEvent?: boolean | undefined; } | undefined): void;
  setControl<K extends string & keyof TControl>(name: K, control: TControl[K], options?: { emitEvent?: boolean | undefined; } | undefined): void;
  setControl(this: FormGroup<{ [key: string]: AbstractControl<any, any, any>; }>, name: string, control: AbstractControl<any, any, any>, options?: { emitEvent?: boolean | undefined; } | undefined): void;
  contains<K extends string>(controlName: K): boolean;
  contains(this: FormGroup<{ [key: string]: AbstractControl<any, any, any>; }>, controlName: string): boolean;
  setValue(value: ɵIsAny<TControl, { [key: string]: any; }, { [K in keyof TControl]: ɵRawValue<TControl[K]>; }>, options?: { onlySelf?: boolean | undefined; emitEvent?: boolean | undefined; }): void;
  patchValue(value: ɵIsAny<TControl, { [key: string]: any; }, Partial<{ [K in keyof TControl]: ɵValue<TControl[K]>; }>>, options?: { onlySelf?: boolean | undefined; emitEvent?: boolean | undefined; }): void;
  reset(value?: ɵTypedOrUntyped<TControl, ɵIsAny<TControl, { [key: string]: any; }, Partial<{ [K in keyof TControl]: ɵValue<TControl[K]> | FormControlState<ɵValue<TControl[K]>>; }>>, any>, options?: { onlySelf?: boolean | undefined; emitEvent?: boolean | undefined; overwriteDefaultValue?: boolean | undefined; }): void;
  getRawValue(): ɵTypedOrUntyped<TControl, ɵIsAny<TControl, { [key: string]: any; }, { [K in keyof TControl]: ɵRawValue<TControl[K]>; }>, any>;
  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

FormGroup<TControl>

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

@paramcontrolsTControl

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

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

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

@paramasyncValidatorAsyncValidatorFn | AsyncValidatorFn[] | null | undefined

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

@returnsFormGroup<TControl>

controls

ɵTypedOrUntyped<TControl, TControl, { [key: string]: AbstractControl<any, any, any>; }>

registerControl

2 перегрузки

Регистрирует элемент управления в списке элементов управления группы. В строго типизированной группе элемент управления должен входить в тип группы (возможно, как необязательный ключ).

Этот метод не обновляет значение или валидность элемента управления. Вместо него используйте addControl.

@paramnameK

Имя элемента управления, регистрируемого в коллекции

@paramcontrolTControl[K]

Элемент управления для указанного имени

@returnsTControl[K]

@paramthisFormGroup<{ [key: string]: AbstractControl<any, any, any>; }>

@paramnamestring

@paramcontrolAbstractControl<any, any, any>

@returnsAbstractControl<any, any, any>

addControl

2 перегрузки

Добавляет элемент управления в эту группу. В строго типизированной группе элемент управления должен входить в тип группы (возможно, как необязательный ключ).

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

@paramthisFormGroup<{ [key: string]: AbstractControl<any, any, any>; }>

@paramnamestring

Имя элемента управления, добавляемого в коллекцию

@paramcontrolAbstractControl<any, any, any>

Элемент управления для указанного имени

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

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

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

@returnsvoid

@paramnameK

@paramcontrolRequired<TControl>[K]

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

@returnsvoid

removeControl

2 перегрузки

@paramthisFormGroup<{ [key: string]: AbstractControl<any, any, any>; }>

@paramnamestring

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

@returnsvoid

@paramnameɵOptionalKeys<TControl> & S

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

@returnsvoid

setControl

2 перегрузки

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

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

@paramnameK

Имя элемента управления, заменяемого в коллекции

@paramcontrolTControl[K]

Элемент управления для указанного имени

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

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

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

@returnsvoid

@paramthisFormGroup<{ [key: string]: AbstractControl<any, any, any>; }>

@paramnamestring

@paramcontrolAbstractControl<any, any, any>

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

@returnsvoid

contains

2 перегрузки

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

Для отключенных элементов управления возвращает false. Чтобы проверить только наличие элемента управления в группе, используйте вместо этого get.

@paramcontrolNameK

Имя элемента управления, наличие которого нужно проверить в коллекции

@returnsboolean

false для отключенных элементов управления, иначе true.

@paramthisFormGroup<{ [key: string]: AbstractControl<any, any, any>; }>

@paramcontrolNamestring

@returnsboolean

setValue

void

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

@paramvalueɵIsAny<TControl, { [key: string]: any; }, { [K in keyof TControl]: ɵRawValue<TControl[K]>; }>

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

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

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

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

@returnsvoid

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

Задание полного значения группы формы

const form = new FormGroup({
  first: new FormControl(),
  last: new FormControl()
});

console.log(form.value);   // {first: null, last: null}

form.setValue({first: 'Nancy', last: 'Drew'});
console.log(form.value);   // {first: 'Nancy', last: 'Drew'}

patchValue

void

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

Метод принимает как надмножества, так и подмножества группы, не вызывая ошибку.

@paramvalueɵIsAny<TControl, { [key: string]: any; }, Partial<{ [K in keyof TControl]: ɵValue<TControl[K]>; }>>

Объект, соответствующий структуре группы.

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

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

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

@returnsvoid

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

Частичное задание значения группы формы

const form = new FormGroup({
   first: new FormControl(),
   last: new FormControl()
});
console.log(form.value);   // {first: null, last: null}

form.patchValue({first: 'Nancy'});
console.log(form.value);   // {first: 'Nancy', last: null}

reset

void

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

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

@paramvalue

ɵTypedOrUntyped<TControl, ɵIsAny<TControl, { [key: string]: any; }, Partial<{ [K in keyof TControl]: ɵValue<TControl[K]> | FormControlState<ɵValue<TControl[K]>>; }>>, any>

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

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

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

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

@returnsvoid

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

Сброс значений группы формы

const form = new FormGroup({
  first: new FormControl('first name'),
  last: new FormControl('last name')
});

console.log(form.value);  // {first: 'first name', last: 'last name'}

form.reset({ first: 'name', last: 'last name' });

console.log(form.value);  // {first: 'name', last: 'last name'}

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

const form = new FormGroup({
  first: new FormControl('first name'),
  last: new FormControl('last name')
});

form.reset({
  first: {value: 'name', disabled: true},
  last: 'last'
});

console.log(form.value);  // {last: 'last'}
console.log(form.get('first').status);  // 'DISABLED'

getRawValue

ɵTypedOrUntyped<TControl, ɵIsAny<TControl, { [key: string]: any; }, { [K in keyof TControl]: ɵRawValue<TControl[K]>; }>, any>

Совокупное значение группы FormGroup, включая отключенные элементы управления.

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

@returns

ɵTypedOrUntyped<TControl, ɵIsAny<TControl, { [key: string]: any; }, { [K in keyof TControl]: ɵRawValue<TControl[K]>; }>, any>

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

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

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

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

@paramvalidatorsAsyncValidatorFn | AsyncValidatorFn[] | null

@returnsvoid

addValidators

void

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

Добавление уже существующего валидатора не даст никакого эффекта. Если в массиве 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 объединяет значения каждого дочернего FormControl в один объект, используя имя каждого элемента управления в качестве ключа. Статус группы вычисляется путём сведения значений статуса её дочерних элементов. Например, если один из элементов управления в группе недействителен, недействительной становится вся группа.

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

При создании экземпляра FormGroup передайте коллекцию дочерних элементов управления в качестве первого аргумента. Ключ каждого дочернего элемента задаёт имя элемента управления.

FormGroup предназначена для случаев, когда ключи известны заранее. Если необходимо динамически добавлять и удалять элементы управления, используйте вместо неё FormRecord.

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

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

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

const form = new FormGroup({
  first: new FormControl('Nancy', Validators.minLength(2)),
  last: new FormControl('Drew'),
});

console.log(form.value);   // {first: 'Nancy', last; 'Drew'}
console.log(form.status);  // 'VALID'

Аргумент типа и необязательные элементы управления

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

Если у вас есть необязательные элементы управления (то есть их можно удалить), используйте ? в типе:

const form = new FormGroup<{
  first: FormControl<string|null>,
  middle?: FormControl<string|null>, // Middle name is optional.
  last: FormControl<string|null>,
}>({
  first: new FormControl('Nancy'),
  last: new FormControl('Drew'),
});

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

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

const form = new FormGroup({
  password: new FormControl('', Validators.minLength(2)),
  passwordConfirm: new FormControl('', Validators.minLength(2)),
}, passwordMatchValidator);


function passwordMatchValidator(g: FormGroup) {
   return g.get('password').value === g.get('passwordConfirm').value
      ? null : {'mismatch': true};
}

Как и для экземпляров FormControl, валидаторы и асинхронные валидаторы можно передать в объекте параметров.

const form = new FormGroup({
  password: new FormControl('')
  passwordConfirm: new FormControl('')
}, { validators: passwordMatchValidator, asyncValidators: otherValidator });

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

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

const c = new FormGroup({
  one: new FormControl()
}, { updateOn: 'blur' });

Использование FormGroup с необязательными элементами управления

В FormGroup могут быть необязательные элементы управления. Такой элемент управления можно позднее удалить с помощью removeControl или не указывать при вызове reset. Необязательные элементы управления должны быть объявлены необязательными в типе группы.

const c = new FormGroup<{one?: FormControl<string>}>({
  one: new FormControl('')
});

Обратите внимание, что c.value.one имеет тип string|null|undefined. Это связано с тем, что вызов c.reset({}) без необязательного ключа one приведёт к тому, что он станет null.

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/FormGroup