Spec-Zone.ru › Angular

FormControl

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

AbstractControlРуководство по реактивным формамПримечания по использованиюFormControl: начало работы

API

interface FormControl<TValue = any> extends AbstractControl<TValue> {
  defaultValue: TValue;
  setValue(value: TValue, options?: { onlySelf?: boolean | undefined; emitEvent?: boolean | undefined; emitModelToViewChange?: boolean | undefined; emitViewToModelChange?: boolean | undefined; } | undefined): void;
  patchValue(value: TValue, options?: { onlySelf?: boolean | undefined; emitEvent?: boolean | undefined; emitModelToViewChange?: boolean | undefined; emitViewToModelChange?: boolean | undefined; } | undefined): void;
  reset(formState?: TValue | FormControlState<TValue> | undefined, options?: { onlySelf?: boolean | undefined; emitEvent?: boolean | undefined; overwriteDefaultValue?: boolean | undefined; } | undefined): void;
  getRawValue(): TValue;
  registerOnChange(fn: Function): void;
  registerOnDisabledChange(fn: (isDisabled: boolean) => void): 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>;
}

defaultValue

TValue

Значение по умолчанию этого FormControl, используемое при сбросе элемента управления без явного указания значения. Дополнительные сведения о настройке значения по умолчанию см. в разделе FormControlOptions#nonNullable.

setValue

void

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

@paramvalueTValue

Новое значение элемента управления.

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

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

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

patchValue

void

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

На этом уровне эта функция функционально идентична setValue. Она существует для симметрии с методом patchValue у FormGroups и FormArrays, где ее поведение отличается.

@paramvalueTValue
@paramoptions{ onlySelf?: boolean | undefined; emitEvent?: boolean | undefined; emitModelToViewChange?: boolean | undefined; emitViewToModelChange?: boolean | undefined; } | undefined
@returnsvoid

reset

void

Сбрасывает элемент управления формы, помечая его как pristine и untouched, и сбрасывая его значение. Новым значением станет переданное значение (если оно указано), null или исходное значение, если nonNullable было задано в конструкторе с помощью FormControlOptions.

// By default, the control will reset to null.
const dog = new FormControl('spot');
dog.reset(); // dog.value is null

// If this flag is set, the control will instead reset to the initial value.
const cat = new FormControl('tabby', {nonNullable: true});
cat.reset(); // cat.value is "tabby"

// A value passed to reset always takes precedence.
const fish = new FormControl('finn', {nonNullable: true});
fish.reset('bubble'); // fish.value is "bubble"
@paramformStateTValue | FormControlState<TValue> | undefined

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

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

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

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

getRawValue

TValue

Для простого FormControl необработанное значение совпадает со значением.

@returnsTValue

registerOnChange

void

Регистрирует обработчик событий изменения.

@paramfnFunction

Метод, вызываемый при изменении значения

@returnsvoid

registerOnDisabledChange

void

Регистрирует обработчик событий отключения.

@paramfn(isDisabled: boolean) => void

Метод, вызываемый при изменении статуса отключения.

@returnsvoid

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

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

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

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

@paramvalidatorsValidatorFn | ValidatorFn[]

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

@returnsvoid

addAsyncValidators

void

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

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

Добавление уже существующего валидатора не окажет никакого эффекта.

@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);

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

removeAsyncValidators

void

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

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

@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

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

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

@returnsvoid

clearAsyncValidators

void

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

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

@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 или не задано (по умолчанию), observable events генерирует событие TouchedChangeEvent, у которого свойство touched имеет значение false. Если значение равно false, события не генерируются.
@returnsvoid
@paramopts{ onlySelf?: boolean | undefined; emitEvent?: boolean | undefined; sourceControl?: AbstractControl<any, any, any> | undefined; }
@returnsvoid

markAsDirty

2 перегрузки

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

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

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

  • onlySelf: если значение равно true, помечается только этот элемент управления. Если значение равно false или не задано, помечаются все непосредственные предки. Значение по умолчанию — false.
  • emitEvent: если значение равно true или не задано (по умолчанию), observable 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 или не задано (по умолчанию), observable events генерирует событие PristineChangeEvent, у которого свойство pristine имеет значение true. Если значение равно false, события не генерируются.
@returnsvoid
@paramopts{ onlySelf?: boolean | undefined; emitEvent?: boolean | undefined; sourceControl?: AbstractControl<any, any, any> | undefined; }
@returnsvoid

markAsPending

2 перегрузки

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

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

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

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

  • onlySelf: если значение равно true, помечается только этот элемент управления. Если значение равно false или не задано, помечаются все непосредственные предки. Значение по умолчанию — false.
  • emitEvent: если значение равно true или не задано (по умолчанию), observable statusChanges генерирует событие с последним состоянием, которым помечен элемент управления как pending, а observable 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 или не задано (по умолчанию), observables 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; }

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

  • onlySelf: если значение равно true, помечается только этот элемент управления. Если значение равно false или не задано, помечаются все непосредственные предки. Значение по умолчанию — false.
  • emitEvent: если значение равно true или не задано (по умолчанию), observables 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 или не задано (по умолчанию), observables 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 или не задано (по умолчанию), observable 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'.

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

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

hasError

boolean

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

@paramerrorCodestring

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

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

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

@returnsboolean

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

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

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

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

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

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

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

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

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

root

AbstractControl<any, any, any>

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

Описание

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

Это один из четырех основных строительных блоков форм Angular наряду с FormGroup, FormArray и FormRecord. Класс наследуется от AbstractControl, который реализует большую часть базовых функций для доступа к значению, состоянию проверки, взаимодействиям с пользователем и событиям.

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

См. примеры использования ниже.

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

Инициализация элементов управления формы

Создайте FormControl с начальным значением.

const control = new FormControl('some value');
console.log(control.value);     // 'some value'

В следующем примере элемент управления инициализируется объектом состояния формы. В этом случае обязательны ключи value и disabled.

const control = new FormControl({ value: 'n/a', disabled: true });
console.log(control.value);     // 'n/a'
console.log(control.status);    // 'DISABLED'

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

const control = new FormControl('', Validators.required);
console.log(control.value);      // ''
console.log(control.status);     // 'INVALID'

В следующем примере элемент управления инициализируется с помощью объекта параметров.

const control = new FormControl('', {
   validators: Validators.required,
   asyncValidators: myAsyncValidator
});

Единственный аргумент типа

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

Если элемент управления инициализируется значением null или вы хотите указать более широкий тип, можно задать аргумент явно:

let fc = new FormControl<string|null>(null);
fc.setValue('foo');

Обратите внимание, что null всегда добавляется к типу элемента управления. Это связано с тем, что элемент управления станет null при вызове reset. Это поведение можно изменить, задав {nonNullable: true}.

Настройка обновления элемента управления при событии blur

Задайте для параметра updateOn значение 'blur', чтобы обновление происходило при событии blur event.

const control = new FormControl('', { updateOn: 'blur' });

Настройка обновления элемента управления при событии submit

Задайте для параметра updateOn значение 'submit', чтобы обновление происходило при событии submit event.

const control = new FormControl('', { updateOn: 'submit' });

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

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

const control = new FormControl('Nancy');

console.log(control.value); // 'Nancy'

control.reset('Drew');

console.log(control.value); // 'Drew'

Сброс элемента управления до исходного значения

Если требуется всегда сбрасывать элемент управления до исходного значения, а не до null, можно передать параметр nonNullable:

const control = new FormControl('Nancy', {nonNullable: true});

console.log(control.value); // 'Nancy'

control.reset();

console.log(control.value); // 'Nancy'

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

const control = new FormControl('Nancy');

console.log(control.value); // 'Nancy'
console.log(control.status); // 'VALID'

control.reset({ value: 'Drew', disabled: true });

console.log(control.value); // 'Drew'
console.log(control.status); // 'DISABLED'

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

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API