FormControlName — Angular

Связывает FormControl в существующем FormGroup с элементом управления формы по имени.

API

class FormControlName extends NgControl implements OnChanges ,OnDestroy {
  constructor(parent: ControlContainer, validators: (ValidatorFn | Validator)[], asyncValidators: (AsyncValidatorFn | AsyncValidator)[], valueAccessors: ControlValueAccessor[], _ngModelWarningConfig: string | null, renderer?: Renderer2 | undefined, injector?: Injector | undefined): FormControlName;
  readonly control: FormControl<any>;
  @Input('formControlName') name: string | number | null;
  @Input('disabled') set isDisabled(value: boolean);
  @Input('ngModel') model: any;
  @Output('ngModelChange') update: EventEmitter<any>;
  viewToModelUpdate(newValue: any): void;
  readonly path: string[];
  readonly formDirective: any;
  override valueAccessor: ControlValueAccessor | null;
  protected override isCustomControlBased: boolean;
  protected override readonly selectedValueAccessor: ControlValueAccessor | null;
  protected override parseErrorsValidator: ValidatorFn | null;
  protected override customControlBindings: { value?: unknown; disabled?: boolean | undefined; touched?: boolean | undefined; dirty?: boolean | undefined; valid?: boolean | undefined; invalid?: boolean | undefined; pending?: boolean | undefined; required?: boolean | undefined; errors?: ValidationErrors | null | undefined; } | null;
  protected override setupCustomControl(): void;
  protected override ngControlUpdate(host: ControlDirectiveHost<undefined>, bindRequired: boolean): void;
  protected override readonly shouldBindRequired: boolean;
  protected override removeParseErrorsValidator(control: AbstractControl<any, any, any> | null | undefined): void;
  override readonly value: any;
  override readonly valid: boolean | null;
  override readonly invalid: boolean | null;
  override readonly pending: boolean | null;
  override readonly disabled: boolean | null;
  override readonly enabled: boolean | null;
  override readonly errors: ValidationErrors | null;
  override readonly pristine: boolean | null;
  override readonly dirty: boolean | null;
  override readonly touched: boolean | null;
  override readonly status: string | null;
  override readonly untouched: boolean | null;
  override readonly statusChanges: any;
  override readonly valueChanges: any;
  override readonly validator: ValidatorFn | null;
  override readonly asyncValidator: AsyncValidatorFn | null;
  override reset(value?: any): void;
  override hasError(errorCode: string, path?: string | (string | number)[] | undefined): boolean;
  override getError(errorCode: string, path?: string | (string | number)[] | undefined): any;
}

constructor

FormControlName

@paramparentControlContainer

@paramvalidators(ValidatorFn | Validator)[]

@paramasyncValidators(AsyncValidatorFn | AsyncValidator)[]

@paramvalueAccessorsControlValueAccessor[]

@param_ngModelWarningConfigstring | null

@paramrendererRenderer2 | undefined

@paraminjectorInjector | undefined

@returnsFormControlName

control

FormControl<any>

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

name

string | number | null

Отслеживает имя FormControl, связанного с директивой. Имя соответствует ключу в родительском FormGroup или FormArray. Принимает имя в виде строки или числа. Строковый формат имени удобен для отдельных форм, а числовой позволяет связывать элементы управления формы с индексами при переборе элементов управления в FormArray.

isDisabled

boolean

В режиме разработки вызывает предупреждение о том, что этот входной параметр не следует использовать с реактивными формами.

model

any

@deprecated

начиная с версии 6

update

EventEmitter<any>

@deprecated

начиная с версии 6

viewToModelUpdate

void

Устанавливает новое значение для модели представления и генерирует событие ngModelChange.

@paramnewValueany

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

@returnsvoid

path

string[]

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

formDirective

any

Директива верхнего уровня для этой группы, если она есть; в противном случае — null.

valueAccessor

ControlValueAccessor | null

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

isCustomControlBased

boolean

selectedValueAccessor

ControlValueAccessor | null

parseErrorsValidator

ValidatorFn | null

Функция-валидатор, возвращающая текущие ошибки разбора.

customControlBindings

{ value?: unknown; disabled?: boolean | undefined; touched?: boolean | undefined; dirty?: boolean | undefined; valid?: boolean | undefined; invalid?: boolean | undefined; pending?: boolean | undefined; required?: boolean | undefined; errors?: ValidationErrors | null | undefined; } | null

Отслеживает последние связанные значения, чтобы избежать ненужных обновлений FVC.

setupCustomControl

void

@returnsvoid

ngControlUpdate

void

@paramhostControlDirectiveHost<undefined>

@parambindRequiredboolean

@returnsvoid

shouldBindRequired

boolean

Следует ли элементу управления связывать свойство required (в режиме пользовательского элемента управления).

Может быть переопределён подклассами, которые обрабатывают required иначе.

removeParseErrorsValidator

void

@paramcontrolAbstractControl<any, any, any> | null | undefined

@returnsvoid

value

any

Возвращает значение элемента управления, если он существует; в противном случае — null.

valid

boolean | null

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

invalid

boolean | null

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

pending

boolean | null

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

disabled

boolean | null

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

enabled

boolean | null

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

errors

ValidationErrors | null

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

pristine

boolean | null

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

dirty

boolean | null

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

touched

boolean | null

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

status

string | null

Возвращает статус валидации элемента управления. Возможные значения: 'VALID', 'INVALID', 'DISABLED' и 'PENDING'. Если элемент управления отсутствует, возвращается null.

untouched

boolean | null

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

statusChanges

any

Возвращает мультикастовый Observable, который выдаёт статус валидации при каждом его вычислении для элемента управления. Если элемент управления отсутствует, возвращается null.

valueChanges

any

Возвращает мультикастовый Observable изменений значения элемента управления. Он выдаёт новое значение при каждом изменении значения элемента управления в пользовательском интерфейсе или программно. Если элемент управления отсутствует, возвращается null.

validator

ValidatorFn | null

Функция синхронной валидации, объединяющая все синхронные валидаторы, зарегистрированные в этой директиве.

asyncValidator

AsyncValidatorFn | null

Функция асинхронной валидации, объединяющая все асинхронные валидаторы, зарегистрированные в этой директиве.

reset

void

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

@paramvalueany

@returnsvoid

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'

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

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'

Описание

Связывает FormControl в существующем FormGroup с элементом управления формы по имени.

Экспортируется модулем

ReactiveFormsModule

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

Регистрация FormControl в группе

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

import {Component} from '@angular/core';
import {FormControl, FormGroup, Validators} from '@angular/forms';

@Component({
  selector: 'example-app',
  template: `
    <form [formGroup]="form" (ngSubmit)="onSubmit()">
      @if (first.invalid) {
        <div>Name is too short.</div>
      }
      <input formControlName="first" placeholder="First name" />
      <input formControlName="last" placeholder="Last name" />

      <button type="submit">Submit</button>
    </form>
    <button (click)="setValue()">Set preset value</button>
  `,
  standalone: false,
})
export class SimpleFormGroup {
  form = new FormGroup({
    first: new FormControl('Nancy', Validators.minLength(2)),
    last: new FormControl('Drew'),
  });

  get first(): any {
    return this.form.get('first');
  }

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

  setValue() {
    this.form.setValue({first: 'Carson', last: 'Drew'});
  }
}

Примеры formControlName с различными типами элементов управления формы см. в разделах:

Переключатели: RadioControlValueAccessor
Списки выбора: SelectControlValueAccessor

Использование с ngModel устарело

Поддержка использования входного свойства ngModel и события ngModelChange с директивами реактивных форм объявлена устаревшей в Angular v6 и будет удалена в будущей версии Angular.