This is the base class for FormControl
, FormGroup
, and FormArray
.
这是 FormControl
、FormGroup
和 FormArray
的基类。
说明 It provides some of the shared behavior that all controls and groups of controls have, like running validators, calculating status, and resetting state. It also defines the properties that are shared between all sub-classes, like value
, valid
, and dirty
. It shouldn't be instantiated directly.
它提供了一些所有控件和控件组共有的行为,比如运行验证器、计算状态和重置状态。 它还定义了一些所有子类共享的属性,如 value
、valid
和 dirty
。不允许直接实例化它。
构造函数 Initialize the AbstractControl instance.
初始化这个 AbstractControl 实例。
constructor(validator: ValidatorFn | null, asyncValidator: AsyncValidatorFn | null) 参数 validatorThe function that determines the synchronous validity of this control.
用于决定该控件有效性的同步函数。
asyncValidatorThe function that determines the asynchronous validity of this control.
用于决定该控件有效性的异步函数。
属性 属性名 类型 说明 valueany
只读 The current value of the control.
控件的当前值。
For a FormControl
, the current value.
对于 FormControl
,它是当前值。
For a FormGroup
, the values of enabled controls as an object with a key-value pair for each member of the group.
对于 FormGroup
,它是由组中的每个已启用的成员控件的名称和值组成的对象。
For a FormArray
, the values of enabled controls as an array.
对于 FormArray
,它是有所有已启用的控件的值组成的数组。
validatorValidatorFn | null
The function that determines the synchronous validity of this control.
用于决定该控件有效性的同步函数。
声明于构造函数中 asyncValidatorAsyncValidatorFn | null
The function that determines the asynchronous validity of this control.
用于决定该控件有效性的异步函数。
声明于构造函数中 parentFormGroup | FormArray
只读 The parent control.
父控件。
statusstring
只读 The validation status of the control. There are four possible validation status values:
控件的有效性状态。有四个可能的值:
VALID : This control has passed all validation checks.
VALID : 该控件通过了所有有效性检查。
INVALID : This control has failed at least one validation check.
INVALID 该控件至少有一个有效性检查失败了。
PENDING : This control is in the midst of conducting a validation check.
PENDING :该控件正在进行有效性检查,处于中间状态。
DISABLED : This control is exempt from validation checks.
DISABLED :该控件被禁用,豁免了有效性检查。
These status values are mutually exclusive, so a control cannot be both valid AND invalid or invalid AND disabled.
这些状态值是互斥的,因此一个控件不可能同时处于有效状态和无效状态或无效状态和禁用状态。
validboolean
只读 A control is valid
when its status
is VALID
.
当控件的 status
为 VALID
时,它就是 valid
的。
invalidboolean
只读 A control is invalid
when its status
is INVALID
.
当控件的 status
为 INVALID
时,它就是 invalid
的。
pendingboolean
只读 A control is pending
when its status
is PENDING
.
当控件的 status
为 PENDING
时,它就是 pending
的。
disabledboolean
只读 A control is disabled
when its status
is DISABLED
.
当控件的 status
为 DISABLED
时,它就是 disabled
。
enabledboolean
只读 A control is enabled
as long as its status
is not DISABLED
.
如果控件的 status
不是 DISABLED
时,它就是 enabled
。
errorsValidationErrors | null
只读 An object containing any errors generated by failing validation, or null if there are no errors.
一个对象,包含由失败的验证所生成的那些错误,如果没出错则为 null。
pristineboolean
只读 A control is pristine
if the user has not yet changed the value in the UI.
如果用户尚未修改 UI 中的值,则该控件是 pristine
(原始状态)的。
dirtyboolean
只读 A control is dirty
if the user has changed the value in the UI.
如果用户修改过 UI 中的值,则控件是 dirty
(脏) 的。
touchedboolean
只读 True if the control is marked as touched
.
如果控件被标记为 touched
(碰过) 则为 true
。
A control is marked touched
once the user has triggered a blur
event on it.
一旦用户在控件上触发了 blur
事件,则会将其标记为 touched
。
untouchedboolean
只读 True if the control has not been marked as touched
如果该控件尚未标记为 touched
,则为 true
。
A control is untouched
if the user has not yet triggered a blur
event on it.
如果用户尚未在控件上触发过 blur
事件,则该控件为 untouched
。
valueChangesObservable<any>
只读 A multicasting observable that emits an event every time the value of the control changes, in the UI or programmatically.
一个多播 Observable(可观察对象),每当控件的值发生变化时,它就会发出一个事件 —— 无论是通过 UI 还是通过程序。
statusChangesObservable<any>
只读 A multicasting observable that emits an event every time the validation status
of the control recalculates.
一个多播 Observable(可观察对象),每当控件的验证 status
被重新计算时,就会发出一个事件。
updateOnFormHooks
只读 Reports the update strategy of the AbstractControl
(meaning the event on which the control updates itself). Possible values: 'change'
| 'blur'
| 'submit'
Default value: 'change'
报告这个 AbstractControl
的更新策略(表示控件用来更新自身状态的事件)。 可能的值有 'change'
| 'blur'
| 'submit'
,默认值是 'change'
。
rootAbstractControl
只读 Retrieves the top-level ancestor of this control.
获取该控件的顶级祖先。
方法 Sets the synchronous validators that are active on this control. Calling this overwrites any existing sync validators.
设置该控件上所激活的同步验证器。调用它将会覆盖所有现存的同步验证器。
setValidators(newValidator: ValidatorFn | ValidatorFn [] | null): void 参数 返回值 void
Sets the async validators that are active on this control. Calling this overwrites any existing async validators.
设置该控件上所激活的异步验证器。调用它就会覆盖所有现存的异步验证器。
setAsyncValidators(newValidator: AsyncValidatorFn | AsyncValidatorFn [] | null): void 参数 返回值 void
Empties out the sync validator list.
清空同步验证器列表。
clearValidators(): void 参数 没有参数。
返回值 void
Empties out the async validator list.
清空异步验证器列表。
clearAsyncValidators(): void 参数 没有参数。
返回值 void
Marks the control as touched
. A control is touched by focus and blur events that do not change the value; compare markAsDirty
;
把该控件标记为 touched
。控件获得焦点并失去焦点不会修改这个值。与 markAsDirty
相对。
markAsTouched(opts: { onlySelf?: boolean; } = {}): void 参数 optsConfiguration options that determine how the control propagates changes and emits events events after marking is applied.
在应用完此标记后,该配置项会决定控件如何传播变更及发出事件。
onlySelf
: When true, mark only this control. When false or not supplied, marks all direct ancestors. Default is false.
onlySelf
:如果为 true
则只标记当前控件。如果为 false
或不提供,则标记它所有的直系祖先。默认为 false
。
可选. 默认值是 {}
.
返回值 void
Marks the control as untouched
.
把该控件标记为 untouched
。
markAsUntouched(opts: { onlySelf?: boolean; } = {}): void 参数 optsConfiguration options that determine how the control propagates changes and emits events after the marking is applied.
在应用完此标记后,该配置项会决定控件如何传播变更及发出事件。
onlySelf
: When true, mark only this control. When false or not supplied, marks all direct ancestors. Default is false.
onlySelf
:如果为 true
则只标记当前控件。如果为 false
或不提供,则标记它所有的直系祖先。默认为 false
。
可选. 默认值是 {}
.
返回值 void
If the control has any children, also marks all children as untouched
and recalculates the touched
status of all parent controls.
如果该控件有任何子控件,还会把所有子控件标记为 untouched
,并重新计算所有父控件的 touched
状态。
Marks the control as dirty
. A control becomes dirty when the control's is changed through the UI; compare markAsTouched
.
把控件标记为 dirty
。当控件通过 UI 修改过时控件会变成 dirty
的;与 markAsTouched
相对。
markAsDirty(opts: { onlySelf?: boolean; } = {}): void 参数 optsConfiguration options that determine how the control propagates changes and emits events after marking is applied.
在应用完此标记后,该配置项会决定控件如何传播变更以及发出事件。
onlySelf
: When true, mark only this control. When false or not supplied, marks all direct ancestors. Default is false.
onlySelf
:如果为 true
则只标记当前控件。如果为 false
或不提供,则标记它所有的直系祖先。默认为 false
。
可选. 默认值是 {}
.
返回值 void
Marks the control as pristine
.
把该控件标记为 pristine
(原始状态)。
markAsPristine(opts: { onlySelf?: boolean; } = {}): void 参数 optsConfiguration options that determine how the control emits events after marking is applied.
在应用完此标记后,该配置项会决定控件如何传播更改以及发出事件。
onlySelf
: When true, mark only this control. When false or not supplied, marks all direct ancestors. Default is false..
onlySelf
:如果为 true
则只标记当前控件。如果为 false
或不提供,则标记它所有的直系祖先。默认为 false
。
可选. 默认值是 {}
.
返回值 void
If the control has any children, marks all children as pristine
, and recalculates the pristine
status of all parent controls.
如果该控件有任何子控件,则把所有子控件标记为 pristine
,并重新计算所有父控件的 pristine
状态。
Marks the control as pending
.
把该控件标记为 pending
(待定)的。
markAsPending(opts: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void 参数 optsConfiguration options that determine how the control propagates changes and emits events after marking is applied.
在应用完此标记后,该配置项会决定控件如何传播变更以及发出事件。
onlySelf
: When true, mark only this control. When false or not supplied, marks all direct ancestors. Default is false..
onlySelf
:如果为 true
则只标记当前控件。如果为 false
或不提供,则标记它所有的直系祖先。默认为 false
。
emitEvent
: When true or not supplied (the default), the statusChanges
observable emits an event with the latest status the control is marked pending. When false, no events are emitted.
emitEvent
:如果为 true
或未提供(默认值),则 statusChanges
(Observable)会发出一个事件,传入控件的最近状态,并把控件标记为 pending
状态。 如果为 false
,则不会发出事件。
可选. 默认值是 {}
.
返回值 void
A control is pending while the control performs async validation.
当控件正在执行异步验证时,该控件是 pending
的。
Disables the control. This means the control is exempt from validation checks and excluded from the aggregate value of any parent. Its status is DISABLED
.
禁用此控件。这意味着该控件在表单验证检查时会被豁免,并且从其父控件的聚合值中排除它的值。它的状态是 DISABLED
。
disable(opts: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void 参数 optsConfiguration options that determine how the control propagates changes and emits events after the control is disabled.
在该控件被禁用之后,该配置项决定如何传播更改以及发出事件。
onlySelf
: When true, mark only this control. When false or not supplied, marks all direct ancestors. Default is false..
onlySelf
:如果为 true
,则只标记当前控件。如果为 false
或没有提供,则标记所有直系祖先。默认为 false
。
emitEvent
: When true or not supplied (the default), both the statusChanges
and valueChanges
observables emit events with the latest status and value when the control is disabled. When false, no events are emitted.
emitEvent
:如果为 true
或没有提供(默认),则当控件被禁用时,statusChanges
和 valueChanges
这两个 Observable 都会发出最近的状态和值。 如果为 false
,则不会发出事件。
可选. 默认值是 {}
.
返回值 void
If the control has children, all children are also disabled.
如果该控件有子控件,则所有子控件也会被禁用。
Enables the control. This means the control is included in validation checks and the aggregate value of its parent. Its status recalculates based on its value and its validators.
启用该控件。这意味着该控件包含在有效性检查中,并会出现在其父控件的聚合值中。它的状态会根据它的值和验证器而重新计算。
enable(opts: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void 参数 optsConfigure options that control how the control propagates changes and emits events when marked as untouched
当标记为 untouched
时,该配置项会决定该控件如何传播变更以及发出事件。
onlySelf
: When true, mark only this control. When false or not supplied, marks all direct ancestors. Default is false..
onlySelf
:如果为 true
,则只标记当前控件。如果为 false
或没有提供,则标记所有直系祖先。默认为 false
。
emitEvent
: When true or not supplied (the default), both the statusChanges
and valueChanges
observables emit events with the latest status and value when the control is enabled. When false, no events are emitted.
emitEvent
:如果为 true
或没有提供(默认),则当控件被启用时,statusChanges
和 valueChanges
这两个 Observable 都会发出最近的状态和值。 如果为 false
,则不会发出事件。
可选. 默认值是 {}
.
返回值 void
By default, if the control has children, all children are enabled.
默认情况下,如果该控件具有子控件,则所有子控件都会被启用。
setParent(parent: FormGroup | FormArray ): void 参数 parentSets the parent of the control
设置该控件的父控件
返回值 void
Sets the value of the control. Abstract method (implemented in sub-classes).
设置该控件的值。这是一个抽象方法(由子类实现)。
abstract setValue(value: any, options?: Object): void 参数 valueType: any
.
optionsType: Object
.
可选. 默认值是 undefined
.
返回值 void
Patches the value of the control. Abstract method (implemented in sub-classes).
修补(patch)该控件的值。这是一个抽象方法(由子类实现)。
abstract patchValue(value: any, options?: Object): void 参数 valueType: any
.
optionsType: Object
.
可选. 默认值是 undefined
.
返回值 void
Resets the control. Abstract method (implemented in sub-classes).
重置控件。这是一个抽象方法(由子类实现)。
abstract reset(value?: any, options?: Object): void 参数 valueType: any
.
可选. 默认值是 undefined
.
optionsType: Object
.
可选. 默认值是 undefined
.
返回值 void
Recalculates the value and validation status of the control.
重新计算控件的值和校验状态。
updateValueAndValidity(opts: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void 参数 optsConfiguration options determine how the control propagates changes and emits events after updates and validity checks are applied.
当更新和进行有效性检查之后,该配置项会决定控件如何传播变更并发出事件。
onlySelf
: When true, only update this control. When false or not supplied, update all direct ancestors. Default is false..
onlySelf
:如果为 true
,则只标记当前控件。如果为 false
或没有提供,则标记所有直系祖先。默认为 false
。
emitEvent
: When true or not supplied (the default), both the statusChanges
and valueChanges
observables emit events with the latest status and value when the control is updated. When false, no events are emitted.
emitEvent
:如果为 true
或没有提供(默认),则当控件被启用时,statusChanges
和 valueChanges
这两个 Observable 都会发出最近的状态和值。 如果为 false
,则不会发出事件。
可选. 默认值是 {}
.
返回值 void
By default, it also updates the value and validity of its ancestors.
默认情况下,它还会更新其直系祖先的值和有效性状态。
Sets errors on a form control when running validations manually, rather than automatically.
在手动(而不是自动)运行校验之后,设置表单控件上的错误信息。
setErrors(errors: ValidationErrors | null, opts: { emitEvent?: boolean; } = {}): void 参数 errorsType: ValidationErrors | null
.
optsType: {
emitEvent?: boolean;
}
.
可选. 默认值是 {}
.
返回值 void
Calling setErrors
also updates the validity of the parent control.
调用 setErrors
还会更新父控件的有效性状态。
Manually set the errors for a control 手动设置控件上的错误信息。 const login = new FormControl ('someLogin'); login.setErrors({ notUnique: true }); expect(login.valid).toEqual(false); expect(login.errors).toEqual({ notUnique: true }); login.setValue('someOtherLogin'); expect(login.valid).toEqual(true);
Retrieves a child control given the control's name or path.
根据指定的控件名称或路径获取子控件。
get(path: Array<string | number> | string): AbstractControl | null 参数 pathA dot-delimited string or array of string/number values that define the path to the control.
一个由点号(.
)分隔的字符串或 "字符串/数字" 数组定义的控件路径。
Retrieve a nested control 获取嵌套的控件 For example, to get a name
control nested within a person
sub-group:
比如,要获取子控件组 person
中的 name
控件:
this.form.get('person.name');
-OR-
this.form.get(['person', 'name']);
返回值 AbstractControl | null
Reports error data for a specific error occurring in this control or in another control.
获取发生在该控件或其他控件中发生的指定错误的出错数据。
getError(errorCode: string, path?: string[]): any 参数 errorCodeThe error code for which to retrieve data
要获取的数据的错误码
pathThe path to a control to check. If not supplied, checks for the error in this control.
要检查的控件的路径。如果没有提供该参数,则检查该控件中的错误。
可选. 默认值是 undefined
.
返回值 any
: The error data if the control with the given path has the given error, otherwise null or undefined.
如果指定路径下的控件具有指定的错误,则返回出错数据,否则为 null
或 undefined
。
Reports whether the control with the given path has the error specified.
报告指定路径下的控件上是否有指定的错误。
hasError(errorCode: string, path?: string[]): boolean 参数 errorCodeThe error code for which to retrieve data
要获取的数据的错误码
pathThe path to a control to check. If not supplied, checks for the error in this control.
要检查的控件的路径。如果没有提供该参数,则检查该控件中的错误。
可选. 默认值是 undefined
.
返回值 boolean
: True when the control with the given path has the error, otherwise false.
如果指定路径下的控件有这个错误则返回 true
,否则返回 false
。