FormGroupDirective — Angular

Связывает существующий FormGroup или FormRecord с элементом DOM.

API

class FormGroupDirective extends AbstractFormDirective {
  @Input('formGroup') form: FormGroup<any>;
  @Output() ngSubmit: EventEmitter<any>;
  readonly control: FormGroup<any>;
  override readonly submitted: boolean;
  override directives: FormControlName[];
  protected override onChanges(changes: { [propName: string]: SimpleChange<any>; }): void;
  protected override onDestroy(): void;
  override readonly formDirective: Form;
  override readonly path: string[];
  override addControl(dir: FormControlName): FormControl<any>;
  override getControl(dir: FormControlName): FormControl<any>;
  override removeControl(dir: FormControlName): void;
  override addFormGroup(dir: FormGroupName): void;
  override removeFormGroup(dir: FormGroupName): void;
  override getFormGroup(dir: FormGroupName): FormGroup<any>;
  override getFormArray(dir: FormArrayName): FormArray<any>;
  override addFormArray(dir: FormArrayName): void;
  override removeFormArray(dir: FormArrayName): void;
  override updateModel(dir: FormControlName, value: any): void;
  override onReset(): void;
  override resetForm(value?: any, options?: { onlySelf?: boolean | undefined; emitEvent?: boolean | undefined; }): void;
  override onSubmit($event: Event): boolean;
  override name: string | number | null;
  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;
}

form

FormGroup<any>

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

ngSubmit

EventEmitter<any>

Генерирует событие при отправке формы.

control

FormGroup<any>

Возвращает FormGroup, связанный с этой директивой.

submitted

boolean

Сообщает, была ли инициирована отправка формы.

directives

FormControlName[]

Отслеживает список добавленных экземпляров FormControlName

ngOnChanges

void

@paramchanges{ [propName: string]: SimpleChange<any>; }

@returnsvoid

ngOnDestroy

void

@returnsvoid

onChanges

void

@paramchanges{ [propName: string]: SimpleChange<any>; }

@returnsvoid

onDestroy

void

@returnsvoid

formDirective

Form

Возвращает экземпляр этой директивы.

path

string[]

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

addControl

FormControl<any>

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

@paramdirFormControlName

Экземпляр директивы FormControlName.

@returnsFormControl<any>

getControl

FormControl<any>

Получает экземпляр FormControl из указанной директивы FormControlName

@paramdirFormControlName

Экземпляр директивы FormControlName.

@returnsFormControl<any>

removeControl

void

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

@paramdirFormControlName

Экземпляр директивы FormControlName.

@returnsvoid

addFormGroup

void

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

@paramdirFormGroupName

Экземпляр директивы FormGroupName.

@returnsvoid

removeFormGroup

void

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

@paramdirFormGroupName

Экземпляр директивы FormGroupName.

@returnsvoid

getFormGroup

FormGroup<any>

Получает FormGroup для указанного экземпляра директивы FormGroupName

@paramdirFormGroupName

Экземпляр директивы FormGroupName.

@returnsFormGroup<any>

getFormArray

FormArray<any>

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

@paramdirFormArrayName

Экземпляр директивы FormArrayName.

@returnsFormArray<any>

addFormArray

void

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

@paramdirFormArrayName

Экземпляр директивы FormArrayName.

@returnsvoid

removeFormArray

void

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

@paramdirFormArrayName

Экземпляр директивы FormArrayName.

@returnsvoid

updateModel

void

Задает новое значение для указанной директивы FormControlName.

@paramdirFormControlName

Экземпляр директивы FormControlName.

@paramvalueany

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

@returnsvoid

onReset

void

Метод, вызываемый при возникновении события "reset" для формы.

@returnsvoid

resetForm

void

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

@paramvalueany

Новое значение формы.

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

@returnsvoid

onSubmit

boolean

Метод, вызываемый при возникновении события "submit" для формы. Запускает эмиттер ngSubmit для генерации события "submit" с этим событием в качестве полезной нагрузки.

@param$eventEvent

Объект события "submit"

@returnsboolean

name

string | number | null

Имя элемента управления

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

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'

Описание

Связывает существующий FormGroup или FormRecord с элементом DOM.

Эта директива принимает существующий экземпляр FormGroup. Затем она использует этот экземпляр FormGroup, чтобы сопоставить любые дочерние экземпляры FormControl, FormGroup/FormRecord и FormArray с дочерними директивами FormControlName, FormGroupName и FormArrayName.

Экспортировано из

ReactiveFormsModule

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

Регистрация группы формы

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

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