NgForm — Angular | Spec-Zone.ru

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

API

class NgForm extends ControlContainer implements Form ,AfterViewInit {
  constructor(validators: (ValidatorFn | Validator)[], asyncValidators: (AsyncValidatorFn | AsyncValidator)[], callSetDisabledState?: SetDisabledStateOption | undefined): NgForm;
  readonly submitted: boolean;
  form: FormGroup<any>;
  @Output() ngSubmit: EventEmitter<any>;
  @Input('ngFormOptions') options: { updateOn?: FormHooks | undefined; };
  readonly formDirective: Form;
  readonly control: FormGroup<any>;
  readonly path: string[];
  readonly controls: { [key: string]: AbstractControl<any, any, any>; };
  addControl(dir: NgModel): void;
  getControl(dir: NgModel): FormControl<any>;
  removeControl(dir: NgModel): void;
  addFormGroup(dir: NgModelGroup): void;
  removeFormGroup(dir: NgModelGroup): void;
  getFormGroup(dir: NgModelGroup): FormGroup<any>;
  updateModel(dir: NgControl, value: any): void;
  setValue(value: { [key: string]: any; }): void;
  onSubmit($event: Event): boolean;
  onReset(): void;
  resetForm(value?: any): void;
  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;
}

constructor

NgForm

@paramvalidators(ValidatorFn | Validator)[]

@paramasyncValidators(AsyncValidatorFn | AsyncValidator)[]

@paramcallSetDisabledStateSetDisabledStateOption | undefined

@returnsNgForm

submitted

boolean

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

form

FormGroup<any>

Экземпляр FormGroup, созданный для этой формы.

ngSubmit

EventEmitter<any>

Эмиттер события для события "ngSubmit"

options

{ updateOn?: FormHooks | undefined; }

Отслеживает параметры экземпляра NgForm.

updateOn: Задает значение updateOn по умолчанию для всех дочерних элементов NgModels ниже по дереву, если оно явно не задано дочерним элементом NgModel с помощью ngModelOptions). По умолчанию — 'change'. Возможные значения: 'change' | 'blur' | 'submit'.

formDirective

Form

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

control

FormGroup<any>

Внутренний экземпляр FormGroup.

path

string[]

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

controls

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

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

addControl

void

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

@paramdirNgModel

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

@returnsvoid

getControl

FormControl<any>

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

@paramdirNgModel

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

@returnsFormControl<any>

removeControl

void

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

@paramdirNgModel

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

@returnsvoid

addFormGroup

void

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

@paramdirNgModelGroup

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

@returnsvoid

removeFormGroup

void

Удаляет экземпляр директивы NgModelGroup из формы.

@paramdirNgModelGroup

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

@returnsvoid

getFormGroup

FormGroup<any>

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

@paramdirNgModelGroup

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

@returnsFormGroup<any>

updateModel

void

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

@paramdirNgControl

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

@paramvalueany

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

@returnsvoid

setValue

void

Задает значение для этой FormGroup.

@paramvalue{ [key: string]: any; }

Новое значение

@returnsvoid

onSubmit

boolean

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

@param$eventEvent

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

@returnsboolean

onReset

void

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

@returnsvoid

resetForm

void

Сбрасывает форму до исходного значения и сбрасывает ее состояние отправки.

@paramvalueany

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

@returnsvoid

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

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

statusChanges

any

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

valueChanges

any

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

Описание

После импорта FormsModule эта директива автоматически включается по умолчанию для всех тегов <form>. Добавлять специальный селектор не нужно.

При желании можно экспортировать директиву в локальную переменную шаблона, используя ngForm в качестве ключа (например, #myForm="ngForm"). Это необязательно, но полезно. Многие свойства базового экземпляра FormGroup продублированы в самой директиве, поэтому ссылка на нее предоставляет доступ к совокупному значению и состоянию допустимости формы, а также к свойствам взаимодействия с пользователем, таким как dirty и touched.

Чтобы зарегистрировать дочерние элементы управления в форме, используйте NgModel с атрибутом name. Для создания подгрупп в форме можно использовать NgModelGroup.

При необходимости подпишитесь на событие ngSubmit директивы, чтобы получать уведомления, когда пользователь отправляет форму. Событие ngSubmit передает исходное событие отправки формы.

В формах с привязкой к шаблону все теги <form> автоматически помечаются как NgForm. Чтобы импортировать FormsModule, но не использовать его в некоторых формах, например для применения встроенной проверки HTML5, добавьте ngNoForm, и теги <form> не будут создавать директиву NgForm. В реактивных формах использовать ngNoForm не нужно, поскольку теги <form> неактивны. В этом случае не следует использовать директиву formGroup.

Экспортируется из

FormsModule

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

Прослушивание отправки формы

В следующем примере показано, как получить значения формы из события "ngSubmit".

import {Component} from '@angular/core';
import {NgForm} from '@angular/forms';

@Component({
  selector: 'example-app',
  template: `
    <form #f="ngForm" (ngSubmit)="onSubmit(f)" novalidate>
      <input name="first" ngModel required #first="ngModel" />
      <input name="last" ngModel />
      <button>Submit</button>
    </form>

    <p>First name value: {{ first.value }}</p>
    <p>First name valid: {{ first.valid }}</p>
    <p>Form value: {{ f.value | json }}</p>
    <p>Form valid: {{ f.valid }}</p>
  `,
  standalone: false,
})
export class SimpleFormComp {
  onSubmit(f: NgForm) {
    console.log(f.value); // { first: '', last: '' }
    console.log(f.valid); // false
  }
}

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

В следующем примере показано, как изменить параметр "updateOn" со значения по умолчанию с помощью ngFormOptions.

<form [ngFormOptions]="{updateOn: 'blur'}">
   <input name="one" ngModel>  <!-- this ngModel will update on blur -->
</form>

Встроенный интерфейс проверки DOM

Чтобы встроенный интерфейс проверки формы DOM не мешал проверке форм Angular, Angular автоматически добавляет атрибут novalidate к любому элементу <form>, когда в приложение импортируется FormModule или ReactiveFormModule. Чтобы явно включить встроенный интерфейс проверки DOM в формах Angular, можно добавить атрибут ngNativeValidate к элементу <form>:

<form ngNativeValidate>
  ...
</form>