Spec-Zone.ru › Angular

NgModel

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

RadioControlValueAccessorSelectControlValueAccessor

API

class NgModel extends NgControl implements OnChanges ,OnDestroy {
  constructor(parent: ControlContainer, validators: (ValidatorFn | Validator)[], asyncValidators: (AsyncValidatorFn | AsyncValidator)[], valueAccessors: ControlValueAccessor[], _changeDetectorRef?: ChangeDetectorRef | null | undefined, callSetDisabledState?: SetDisabledStateOption | undefined, injector?: Injector | undefined, renderer?: Renderer2 | undefined): NgModel;
  readonly control: FormControl<any>;
  @Input() name: string;
  @Input('disabled') isDisabled: boolean;
  @Input('ngModel') model: any;
  @Input('ngModelOptions') options: { name?: string | undefined; standalone?: boolean | undefined; updateOn?: FormHooks | undefined; };
  @Output('ngModelChange') update: EventEmitter<any>;
  protected readonly shouldBindRequired: boolean;
  readonly path: string[];
  readonly formDirective: any;
  viewToModelUpdate(newValue: any): void;
  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 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

NgModel
@paramparentControlContainer
@paramvalidators(ValidatorFn | Validator)[]
@paramasyncValidators(AsyncValidatorFn | AsyncValidator)[]
@paramvalueAccessorsControlValueAccessor[]
@param_changeDetectorRefChangeDetectorRef | null | undefined
@paramcallSetDisabledStateSetDisabledStateOption | undefined
@paraminjectorInjector | undefined
@paramrendererRenderer2 | undefined
@returnsNgModel

control

FormControl<any>

name

string

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

isDisabled

boolean

Отслеживает, отключён ли элемент управления.

model

any

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

options

{ name?: string | undefined; standalone?: boolean | undefined; updateOn?: FormHooks | undefined; }

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

name: Альтернатива заданию атрибута name для элемента управления формы. См. пример использования NgModel в качестве самостоятельного элемента управления.

standalone: Если задано значение true, ngModel не будет регистрироваться в родительской форме и будет вести себя так, будто не входит в неё. По умолчанию — false. Если родительская форма отсутствует, этот параметр не действует.

updateOn: Определяет событие, при котором обновляются значение и состояние валидности элемента управления формы. По умолчанию — 'change'. Возможные значения: 'change' | 'blur' | 'submit'.

update

EventEmitter<any>

Генератор событий для создания события ngModelChange после обновления модели представления.

shouldBindRequired

boolean

Формы на основе шаблонов обрабатывают required с помощью директивы RequiredValidator.

У этой директивы есть входной параметр required и привязка к хосту [attr.required]. Она является источником достоверных данных о том, является ли поле обязательным, поэтому отключите для неё обычную привязку элемента управления.

path

string[]

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

formDirective

any

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

viewToModelUpdate

void

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

@paramnewValueany

Новое значение, сгенерированное ngModelChange.

@returnsvoid

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

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

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

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

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

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

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'

Описание

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

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

Эту директиву можно использовать отдельно или как часть более крупной формы. Чтобы активировать её, используйте селектор ngModel.

Директива принимает доменную модель в качестве необязательного Input. Если используется односторонняя привязка к ngModel с синтаксисом [], изменение значения доменной модели в классе компонента задаёт значение в представлении. Если используется двусторонняя привязка с синтаксисом [()] (также известным как «синтаксис банана в коробке»), значение в пользовательском интерфейсе всегда синхронизируется с доменной моделью в классе.

Чтобы проверить свойства связанного FormControl (например, состояние валидности), экспортируйте директиву в локальную переменную шаблона, используя ngModel в качестве ключа (например, #myVar="ngModel"). Затем можно получить доступ к элементу управления через свойство field директивы. Однако наиболее часто используемые свойства (например, valid и dirty) доступны и непосредственно у элемента управления. Полный список доступных напрямую свойств см. в разделе AbstractControlDirective.

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

  • FormsModule

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

Использование ngModel для самостоятельного элемента управления

В следующих примерах показан простой самостоятельный элемент управления с использованием ngModel:

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

@Component({
  selector: 'example-app',
  template: `
    <input [(ngModel)]="name" #ctrl="ngModel" required />

    <p>Value: {{ name }}</p>
    <p>Valid: {{ ctrl.valid }}</p>

    <button (click)="setValue()">Set value</button>
  `,
  standalone: false,
})
export class SimpleNgModelComp {
  name: string = '';

  setValue() {
    this.name = 'Nancy';
  }
}

При использовании ngModel внутри тегов <form> необходимо также указать атрибут name, чтобы элемент управления можно было зарегистрировать в родительской форме под этим именем.

В контексте родительской формы односторонняя или двусторонняя привязка часто не нужна, поскольку родительская форма синхронизирует значение за вас. Доступ к свойствам формы можно получить, экспортировав её в локальную переменную шаблона с помощью ngForm, например (#f="ngForm"). Используйте эту переменную при необходимости во время отправки формы.

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

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

В следующем примере показаны элементы управления с использованием ngModel внутри формы:

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
  }
}

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

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

<form>
  <input name="login" ngModel placeholder="Login">
  <input type="checkbox" ngModel [ngModelOptions]="{standalone: true}"> Show more options?
</form>
<!-- form value: {login: ''} -->

Задание атрибута name для ngModel с помощью параметров

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

<form>
  <my-custom-form-control name="Nancy" ngModel [ngModelOptions]="{name: 'user'}">
  </my-custom-form-control>
</form>
<!-- form value: {user: ''} -->

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

Spec-Zone.ru

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