cargdev/angular
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor(forms): deprecate ngModel usage on same field as formControl (#22633)

Browse Source 
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
This commit is contained in:
Kara Erickson
2018-03-07 09:46:10 -08:00
parent 6d1367d297
commit 8fb34bcd43
9 changed files with 360 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files

108
packages/forms/src/directives/reactive_directives/form_control_directive.ts
View File

@ -6,16 +6,23 @@
* found in the LICENSE file at https://angular.io/license
*/
import {Directive, EventEmitter, Inject, Input, OnChanges, Optional, Output, Self, SimpleChanges, forwardRef} from '@angular/core';
import {Directive, EventEmitter, Inject, InjectionToken, Input, OnChanges, Optional, Output, Self, SimpleChanges, forwardRef} from '@angular/core';
import {FormControl} from '../../model';
import {NG_ASYNC_VALIDATORS, NG_VALIDATORS} from '../../validators';
import {ControlValueAccessor, NG_VALUE_ACCESSOR} from '../control_value_accessor';
import {NgControl} from '../ng_control';
import {ReactiveErrors} from '../reactive_errors';
import {composeAsyncValidators, composeValidators, isPropertyUpdated, selectValueAccessor, setUpControl} from '../shared';
import {_ngModelWarning, composeAsyncValidators, composeValidators, isPropertyUpdated, selectValueAccessor, setUpControl} from '../shared';
import {AsyncValidator, AsyncValidatorFn, Validator, ValidatorFn} from '../validators';
/**
* Token to provide to turn off the ngModel warning on formControl and formControlName.
*/
export const NG_MODEL_WITH_FORM_CONTROL_WARNING =
new InjectionToken('NgModelWithFormControlWarning');
export const formControlBinding: any = {
provide: NgControl,
useExisting: forwardRef(() => FormControlDirective)
@ -61,6 +68,72 @@ export const formControlBinding: any = {
*
* * **NgModule**: `ReactiveFormsModule`
*
* ### Use with ngModel
*
* 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';
* ```
*
* By default, when you use this pattern, you will see a deprecation warning once in dev
* mode. You can 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.
*
* @stable
*/
@Directive({selector: '[formControl]', providers: [formControlBinding], exportAs: 'ngForm'})
@ -69,16 +142,39 @@ export class FormControlDirective extends NgControl implements OnChanges {
viewModel: any;
@Input('formControl') form: FormControl;
@Input('ngModel') model: any;
@Output('ngModelChange') update = new EventEmitter();
@Input('disabled')
set isDisabled(isDisabled: boolean) { ReactiveErrors.disabledAttrWarning(); }
// TODO(kara): remove next 4 properties once deprecation period is over
/** @deprecated as of v6 */
@Input('ngModel') model: any;
/** @deprecated as of v6 */
@Output('ngModelChange') update = new EventEmitter();
/**
* Static property used to track whether any ngModel warnings have been sent across
* all instances of FormControlDirective. Used to support warning config of "once".
*
* @internal
*/
static _ngModelWarningSentOnce = false;
/**
* Instance property used to track whether an ngModel warning has been sent out for this
* particular FormControlDirective instance. Used to support warning config of "always".
*
* @internal
*/
_ngModelWarningSent = false;
constructor(@Optional() @Self() @Inject(NG_VALIDATORS) validators: Array<Validator|ValidatorFn>,
@Optional() @Self() @Inject(NG_ASYNC_VALIDATORS) asyncValidators: Array<AsyncValidator|AsyncValidatorFn>,
@Optional() @Self() @Inject(NG_VALUE_ACCESSOR)
valueAccessors: ControlValueAccessor[]) {
valueAccessors: ControlValueAccessor[],
@Optional() @Inject(NG_MODEL_WITH_FORM_CONTROL_WARNING) private _ngModelWarningConfig: string|null) {
super();
this._rawValidators = validators || [];
this._rawAsyncValidators = asyncValidators || [];
@ -94,6 +190,8 @@ export class FormControlDirective extends NgControl implements OnChanges {
this.form.updateValueAndValidity({emitEvent: false});
}
if (isPropertyUpdated(changes, this.viewModel)) {
_ngModelWarning(
'formControl', FormControlDirective, this, this._ngModelWarningConfig);
this.form.setValue(this.model);
this.viewModel = this.model;
}

105
packages/forms/src/directives/reactive_directives/form_control_name.ts
View File

@ -15,9 +15,10 @@ import {ControlContainer} from '../control_container';
import {ControlValueAccessor, NG_VALUE_ACCESSOR} from '../control_value_accessor';
import {NgControl} from '../ng_control';
import {ReactiveErrors} from '../reactive_errors';
import {composeAsyncValidators, composeValidators, controlPath, isPropertyUpdated, selectValueAccessor} from '../shared';
import {_ngModelWarning, composeAsyncValidators, composeValidators, controlPath, isPropertyUpdated, selectValueAccessor} from '../shared';
import {AsyncValidator, AsyncValidatorFn, Validator, ValidatorFn} from '../validators';
import {NG_MODEL_WITH_FORM_CONTROL_WARNING} from './form_control_directive';
import {FormGroupDirective} from './form_group_directive';
import {FormArrayName, FormGroupName} from './form_group_name';
@ -75,6 +76,76 @@ export const controlNameBinding: any = {
*
* **NgModule**: {@link ReactiveFormsModule}
*
* ### Use with ngModel
*
* 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
* <form [formGroup]="form">
* <input formControlName="first" [(ngModel)]="value">
* </form>
* ```
*
* ```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
* <form [formGroup]="form">
* <input formControlName="first">
* </form>
* ```
*
* ```ts
* this.form.get('first').setValue('some value');
* ```
*
* After (choice 2 - use template-driven forms):
*
* ```html
* <input [(ngModel)]="value">
* ```
*
* ```ts
* this.value = 'some value';
* ```
*
* By default, when you use this pattern, you will see a deprecation warning once in dev
* mode. You can 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.
*
* @stable
*/
@Directive({selector: '[formControlName]', providers: [controlNameBinding]})
@ -86,18 +157,41 @@ export class FormControlName extends NgControl implements OnChanges, OnDestroy {
@Input('formControlName') name: string;
// TODO(kara): Replace ngModel with reactive API
@Input('ngModel') model: any;
@Output('ngModelChange') update = new EventEmitter();
@Input('disabled')
set isDisabled(isDisabled: boolean) { ReactiveErrors.disabledAttrWarning(); }
// TODO(kara): remove next 4 properties once deprecation period is over
/** @deprecated as of v6 */
@Input('ngModel') model: any;
/** @deprecated as of v6 */
@Output('ngModelChange') update = new EventEmitter();
/**
* Static property used to track whether any ngModel warnings have been sent across
* all instances of FormControlName. Used to support warning config of "once".
*
* @internal
*/
static _ngModelWarningSentOnce = false;
/**
* Instance property used to track whether an ngModel warning has been sent out for this
* particular FormControlName instance. Used to support warning config of "always".
*
* @internal
*/
_ngModelWarningSent = false;
constructor(
@Optional() @Host() @SkipSelf() parent: ControlContainer,
@Optional() @Self() @Inject(NG_VALIDATORS) validators: Array<Validator|ValidatorFn>,
@Optional() @Self() @Inject(NG_ASYNC_VALIDATORS) asyncValidators:
Array<AsyncValidator|AsyncValidatorFn>,
@Optional() @Self() @Inject(NG_VALUE_ACCESSOR) valueAccessors: ControlValueAccessor[]) {
@Optional() @Self() @Inject(NG_VALUE_ACCESSOR) valueAccessors: ControlValueAccessor[],
@Optional() @Inject(NG_MODEL_WITH_FORM_CONTROL_WARNING) private _ngModelWarningConfig: string|
null) {
super();
this._parent = parent;
this._rawValidators = validators || [];
@ -108,6 +202,7 @@ export class FormControlName extends NgControl implements OnChanges, OnDestroy {
ngOnChanges(changes: SimpleChanges) {
if (!this._added) this._setUpControl();
if (isPropertyUpdated(changes, this.viewModel)) {
_ngModelWarning('formControlName', FormControlName, this, this._ngModelWarningConfig);
this.viewModel = this.model;
this.formDirective.updateModel(this, this.model);
}