8fb34bcd43
Support for using the `ngModel` input property and `ngModelChange`
event with reactive form directives has been deprecated in
Angular v6 and will be removed in Angular v7.
Now deprecated:
```html
<input [formControl]="control" [(ngModel)]="value">
```
```ts
this.value = 'some value';
```
This has been deprecated for a few reasons. First, developers have
found this pattern confusing. It seems like the actual `ngModel`
directive is being used, but in fact it's an input/output property
named `ngModel` on the reactive form directive that simply approximates
(some of) its behavior. Specifically, it allows getting/setting the
value and intercepting value events. However, some of `ngModel`'s other
features - like delaying updates with`ngModelOptions` or exporting the
directive - simply don't work, which has understandably caused some
confusion.
In addition, this pattern mixes template-driven and reactive forms
strategies, which we generally don't recommend because it doesn't take
advantage of the full benefits of either strategy. Setting the value in
the template violates the template-agnostic principles behind reactive
forms, whereas adding a FormControl/FormGroup layer in the class removes
the convenience of defining forms in the template.
To update your code before v7, you'll want to decide whether to stick
with reactive form directives (and get/set values using reactive forms
patterns) or switch over to template-driven directives.
After (choice 1 - use reactive forms):
```html
<input [formControl]="control">
```
```ts
this.control.setValue('some value');
```
After (choice 2 - use template-driven forms):
```html
<input [(ngModel)]="value">
```
```ts
this.value = 'some value';
```
You can also choose to silence this warning by providing a config for
`ReactiveFormsModule` at import time:
```ts
imports: [
ReactiveFormsModule.withConfig({warnOnNgModelWithFormControl: 'never'});
]
```
Alternatively, you can choose to surface a separate warning for each
instance of this pattern with a config value of `"always"`. This may
help to track down where in the code the pattern is being used as the
code is being updated.
Note: `warnOnNgModelWithFormControl` is set up as deprecated so that it
can be removed in v7 when it is no longer needed. This will not display
properly in API docs yet because dgeni doesn't yet support deprecating
properties in object literals, but we have an open issue to resolve the
discrepancy here: https://github.com/angular/angular/issues/22640.
PR Close #22633
91 lines
3.0 KiB
TypeScript
91 lines
3.0 KiB
TypeScript
/**
|
|
* @license
|
|
* Copyright Google Inc. All Rights Reserved.
|
|
*
|
|
* Use of this source code is governed by an MIT-style license that can be
|
|
* found in the LICENSE file at https://angular.io/license
|
|
*/
|
|
|
|
|
|
import {FormErrorExamples as Examples} from './error_examples';
|
|
|
|
export class ReactiveErrors {
|
|
static controlParentException(): void {
|
|
throw new Error(
|
|
`formControlName must be used with a parent formGroup directive. You'll want to add a formGroup
|
|
directive and pass it an existing FormGroup instance (you can create one in your class).
|
|
|
|
Example:
|
|
|
|
${Examples.formControlName}`);
|
|
}
|
|
|
|
static ngModelGroupException(): void {
|
|
throw new Error(
|
|
`formControlName cannot be used with an ngModelGroup parent. It is only compatible with parents
|
|
that also have a "form" prefix: formGroupName, formArrayName, or formGroup.
|
|
|
|
Option 1: Update the parent to be formGroupName (reactive form strategy)
|
|
|
|
${Examples.formGroupName}
|
|
|
|
Option 2: Use ngModel instead of formControlName (template-driven strategy)
|
|
|
|
${Examples.ngModelGroup}`);
|
|
}
|
|
static missingFormException(): void {
|
|
throw new Error(`formGroup expects a FormGroup instance. Please pass one in.
|
|
|
|
Example:
|
|
|
|
${Examples.formControlName}`);
|
|
}
|
|
|
|
static groupParentException(): void {
|
|
throw new Error(
|
|
`formGroupName must be used with a parent formGroup directive. You'll want to add a formGroup
|
|
directive and pass it an existing FormGroup instance (you can create one in your class).
|
|
|
|
Example:
|
|
|
|
${Examples.formGroupName}`);
|
|
}
|
|
|
|
static arrayParentException(): void {
|
|
throw new Error(
|
|
`formArrayName must be used with a parent formGroup directive. You'll want to add a formGroup
|
|
directive and pass it an existing FormGroup instance (you can create one in your class).
|
|
|
|
Example:
|
|
|
|
${Examples.formArrayName}`);
|
|
}
|
|
|
|
static disabledAttrWarning(): void {
|
|
console.warn(`
|
|
It looks like you're using the disabled attribute with a reactive form directive. If you set disabled to true
|
|
when you set up this control in your component class, the disabled attribute will actually be set in the DOM for
|
|
you. We recommend using this approach to avoid 'changed after checked' errors.
|
|
|
|
Example:
|
|
form = new FormGroup({
|
|
first: new FormControl({value: 'Nancy', disabled: true}, Validators.required),
|
|
last: new FormControl('Drew', Validators.required)
|
|
});
|
|
`);
|
|
}
|
|
|
|
static ngModelWarning(directiveName: string): void {
|
|
console.warn(`
|
|
It looks like you're using ngModel on the same form field as ${directiveName}.
|
|
Support for using the ngModel input property and ngModelChange event with
|
|
reactive form directives has been deprecated in Angular v6 and will be removed
|
|
in Angular v7.
|
|
|
|
For more information on this, see our API docs here:
|
|
https://angular.io/api/forms/${directiveName === 'formControl' ? 'FormControlDirective'
|
|
: 'FormControlName'}#use-with-ngmodel
|
|
`);
|
|
}
|
|
}
|