填寫這份《一分鐘調查》,幫我們(開發組)做得更好!去填寫Home

AbstractControl

這是 FormControlFormGroupFormArray 的基底類別。

This is the base class for FormControl, FormGroup, and FormArray.

檢視"說明"...

      
      abstract class AbstractControl {
  constructor(validators: ValidatorFn | ValidatorFn[], asyncValidators: AsyncValidatorFn | AsyncValidatorFn[])
  value: any
  validator: ValidatorFn | null
  asyncValidator: AsyncValidatorFn | null
  parent: FormGroup | FormArray | null
  status: string
  valid: boolean
  invalid: boolean
  pending: boolean
  disabled: boolean
  enabled: boolean
  errors: ValidationErrors | null
  pristine: boolean
  dirty: boolean
  touched: boolean
  untouched: boolean
  valueChanges: Observable<any>
  statusChanges: Observable<any>
  updateOn: FormHooks
  root: AbstractControl
  setValidators(newValidator: ValidatorFn | ValidatorFn[]): void
  setAsyncValidators(newValidator: AsyncValidatorFn | AsyncValidatorFn[]): void
  clearValidators(): void
  clearAsyncValidators(): void
  markAsTouched(opts: { onlySelf?: boolean; } = {}): void
  markAllAsTouched(): void
  markAsUntouched(opts: { onlySelf?: boolean; } = {}): void
  markAsDirty(opts: { onlySelf?: boolean; } = {}): void
  markAsPristine(opts: { onlySelf?: boolean; } = {}): void
  markAsPending(opts: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void
  disable(opts: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void
  enable(opts: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void
  setParent(parent: FormGroup | FormArray): void
  abstract setValue(value: any, options?: Object): void
  abstract patchValue(value: any, options?: Object): void
  abstract reset(value?: any, options?: Object): void
  updateValueAndValidity(opts: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void
  setErrors(errors: ValidationErrors, opts: { emitEvent?: boolean; } = {}): void
  get(path: string | (string | number)[]): AbstractControl | null
  getError(errorCode: string, path?: string | (string | number)[]): any
  hasError(errorCode: string, path?: string | (string | number)[]): boolean
}
    

參見

說明

它提供了一些所有控制元件和控制元件組共有的行為,比如執行驗證器、計算狀態和重置狀態。 它還定義了一些所有子類別共享的屬性,如 valuevaliddirty。不允許直接實例化它。

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.

建構函式

初始化這個 AbstractControl 實例。

Initialize the AbstractControl instance.

      
      constructor(validators: ValidatorFn | ValidatorFn[], asyncValidators: AsyncValidatorFn | AsyncValidatorFn[])
    
引數
validators ValidatorFn | ValidatorFn[]

用於決定該控制元件有效性的同步函式。

The function or array of functions that is used to determine the validity of this control synchronously.

asyncValidators AsyncValidatorFn | AsyncValidatorFn[]

用於非同步確定此控制元件有效性的函式或函式陣列。

The function or array of functions that is used to determine validity of this control asynchronously.

屬性

屬性說明
value: any唯讀

控制元件的當前值。

The current value of the control.

  • 對於 FormControl,它是當前值。

    For a FormControl, the current value.

  • 對於啟用狀態的 FormGroup,它是由組中的每個已啟用的成員控制元件的名稱和值組成的物件。

    For an enabled FormGroup, the values of enabled controls as an object with a key-value pair for each member of the group.

  • 對於禁用狀態的 FormGroup,它是由組中的所有成員控制元件的名稱和值組成的物件。

    For a disabled FormGroup, the values of all controls as an object with a key-value pair for each member of the group.

  • 對於 FormArray,它是有所有已啟用的控制元件的值組成的陣列。

    For a FormArray, the values of enabled controls as an array.

validator: ValidatorFn | null

用於決定該控制元件有效性的非同步函式。

The function that is used to determine the validity of this control synchronously.

asyncValidator: AsyncValidatorFn | null

用於非同步確定此控制元件的有效性的函式。

The function that is used to determine the validity of this control asynchronously.

parent: FormGroup | FormArray | null唯讀

父控制元件。

The parent control.

status: string唯讀

控制元件的有效性狀態。有四個可能的值:

The validation status of the control. There are four possible validation status values:

  • VALID: 該控制元件通過了所有有效性檢查。

    VALID: This control has passed all validation checks.

  • INVALID 該控制元件至少有一個有效性檢查失敗了。

    INVALID: This control has failed at least one validation check.

  • PENDING:該控制元件正在進行有效性檢查,處於中間狀態。

    PENDING: This control is in the midst of conducting a validation check.

  • DISABLED:該控制元件被禁用,豁免了有效性檢查。

    DISABLED: This control is exempt from validation checks.

這些狀態值是互斥的,因此一個控制元件不可能同時處於有效狀態和無效狀態或無效狀態和禁用狀態。

These status values are mutually exclusive, so a control cannot be both valid AND invalid or invalid AND disabled.

valid: boolean唯讀

當控制元件的 statusVALID 時,它就是 valid 的。

A control is valid when its status is VALID.

參見:

invalid: boolean唯讀

當控制元件的 statusINVALID 時,它就是 invalid 的。

A control is invalid when its status is INVALID.

參見:

pending: boolean唯讀

當控制元件的 statusPENDING 時,它就是 pending 的。

A control is pending when its status is PENDING.

參見:

disabled: boolean唯讀

當控制元件的 statusDISABLED 時,它就是 disabled

A control is disabled when its status is DISABLED.

被禁用的控制元件會豁免有效性檢查,並且它的值不會聚合進其祖先控制元件中。

Disabled controls are exempt from validation checks and are not included in the aggregate value of their ancestor controls.

參見:

enabled: boolean唯讀

如果控制元件的 status 不是 DISABLED 時,它就是 enabled

A control is enabled as long as its status is not DISABLED.

參見:

errors: ValidationErrors | null唯讀

一個物件,包含由失敗的驗證所產生的那些錯誤,如果沒出錯則為 null。

An object containing any errors generated by failing validation, or null if there are no errors.

pristine: boolean唯讀

如果使用者尚未修改 UI 中的值,則該控制元件是 pristine(原始狀態)的。

A control is pristine if the user has not yet changed the value in the UI.

dirty: boolean唯讀

如果使用者修改過 UI 中的值,則控制元件是 dirty(髒) 的。

A control is dirty if the user has changed the value in the UI.

touched: boolean唯讀

如果控制元件被標記為 touched(碰過) 則為 true

True if the control is marked as touched.

一旦使用者在控制元件上觸發了 blur 事件,則會將其標記為 touched

A control is marked touched once the user has triggered a blur event on it.

untouched: boolean唯讀

如果該控制元件尚未標記為 touched,則為 true

True if the control has not been marked as touched

如果使用者尚未在控制元件上觸發過 blur 事件,則該控制元件為 untouched

A control is untouched if the user has not yet triggered a blur event on it.

valueChanges: Observable<any>唯讀

一個多播 Observable(可觀察物件),每當控制元件的值發生變化時,它就會發出一個事件 —— 無論是透過 UI 還是透過程式。每當你呼叫 enable()disable(),但沒有傳入 {emitEvent: false} 引數時,它也同樣會發出一個事件。

A multicasting observable that emits an event every time the value of the control changes, in the UI or programmatically. It also emits an event each time you call enable() or disable() without passing along {emitEvent: false} as a function argument.

statusChanges: Observable<any>唯讀

一個多播 Observable(可觀察物件),每當控制元件的驗證 status 被重新計算時,就會發出一個事件。

A multicasting observable that emits an event every time the validation status of the control recalculates.

參見:

updateOn: FormHooks唯讀

報告這個 AbstractControl 的更新策略(表示控制元件用來更新自身狀態的事件)。 可能的值有 'change' | 'blur' | 'submit',預設值是 'change'

Reports the update strategy of the AbstractControl (meaning the event on which the control updates itself). Possible values: 'change' | 'blur' | 'submit' Default value: 'change'

root: AbstractControl唯讀

獲取該控制元件的最上層祖先。

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[]): void
    
引數
newValidator ValidatorFn | ValidatorFn[]
返回值

void

在執行時新增或刪除驗證器時,必須呼叫 updateValueAndValidity() 才能使新驗證生效。

When you add or remove a validator at run time, you must call updateValueAndValidity() for the new validation to take effect.

設定該控制元件上所啟用的非同步驗證器。呼叫它就會覆蓋所有現存的非同步驗證器。

Sets the async validators that are active on this control. Calling this overwrites any existing async validators.

      
      setAsyncValidators(newValidator: AsyncValidatorFn | AsyncValidatorFn[]): void
    
引數
newValidator AsyncValidatorFn | AsyncValidatorFn[]
返回值

void

在執行時新增或刪除驗證器時,必須呼叫 updateValueAndValidity() 才能使新驗證生效。

When you add or remove a validator at run time, you must call updateValueAndValidity() for the new validation to take effect.

清空同步驗證器列表。

Empties out the sync validator list.

      
      clearValidators(): void
    
引數

沒有引數。

返回值

void

在執行時新增或刪除驗證器時,必須呼叫 updateValueAndValidity() 才能使新驗證生效。

When you add or remove a validator at run time, you must call updateValueAndValidity() for the new validation to take effect.

清空非同步驗證器列表。

Empties out the async validator list.

      
      clearAsyncValidators(): void
    
引數

沒有引數。

返回值

void

在執行時新增或刪除驗證器時,必須呼叫 updateValueAndValidity() 才能使新驗證生效。

When you add or remove a validator at run time, you must call updateValueAndValidity() for the new validation to take effect.

將控制元件標記為已 touched。focus 和 blur 事件不會改變該值,從而讓控制元件變為已觸控狀態。

Marks the control as touched. A control is touched by focus and blur events that do not change the value.

See also:

  • markAsUntouched()

  • markAsDirty()

  • 把該控制元件標記為 touched。控制元件獲得焦點並失去焦點不會修改這個值。與 markAsDirty 相對。

    markAsPristine()

      
      markAsTouched(opts: { onlySelf?: boolean; } = {}): void
    
引數
opts object

在應用完此標記後,該配置項會決定控制元件如何傳播變更及發出事件。

Configuration options that determine how the control propagates changes and emits events after marking is applied.

  • onlySelf:如果為 true 則只標記當前控制元件。如果為 false 或不提供,則標記它所有的直系祖先。預設為 false

    onlySelf: When true, mark only this control. When false or not supplied, marks all direct ancestors. Default is false.

可選. 預設值是 `{}`.
返回值

void

將控制元件及其所有後代控制元件標記為已 touched

Marks the control and all its descendant controls as touched.

See also:

  • markAsTouched()

      
      markAllAsTouched(): void
    
引數

沒有引數。

返回值

void

把該控制元件標記為 untouched

Marks the control as untouched.

See also:

  • markAsTouched()

  • markAsDirty()

  • markAsPristine()

      
      markAsUntouched(opts: { onlySelf?: boolean; } = {}): void
    
引數
opts object

在應用完此標記後,該配置項會決定控制元件如何傳播變更及發出事件。

Configuration options that determine how the control propagates changes and emits events after the marking is applied.

  • onlySelf:如果為 true 則只標記當前控制元件。如果為 false 或不提供,則標記它所有的直系祖先。預設為 false

    onlySelf: When true, mark only this control. When false or not supplied, marks all direct ancestors. Default is false.

可選. 預設值是 `{}`.
返回值

void

如果該控制元件有任何子控制元件,還會把所有子控制元件標記為 untouched,並重新計算所有父控制元件的 touched 狀態。

If the control has any children, also marks all children as untouched and recalculates the touched status of all parent controls.

把控制元件標記為 dirty。當控制元件透過 UI 修改過時控制元件會變成 dirty 的;與 markAsTouched 相對。

Marks the control as dirty. A control becomes dirty when the control's value is changed through the UI; compare markAsTouched.

See also:

  • markAsTouched()

  • markAsUntouched()

  • markAsPristine()

      
      markAsDirty(opts: { onlySelf?: boolean; } = {}): void
    
引數
opts object

在應用完此標記後,該配置項會決定控制元件如何傳播變更以及發出事件。

Configuration options that determine how the control propagates changes and emits events after marking is applied.

  • onlySelf:如果為 true 則只標記當前控制元件。如果為 false 或不提供,則標記它所有的直系祖先。預設為 false

    onlySelf: When true, mark only this control. When false or not supplied, marks all direct ancestors. Default is false.

可選. 預設值是 `{}`.
返回值

void

把該控制元件標記為 pristine(原始狀態)。

Marks the control as pristine.

See also:

  • markAsTouched()

  • markAsUntouched()

  • markAsDirty()

      
      markAsPristine(opts: { onlySelf?: boolean; } = {}): void
    
引數
opts object

在應用完此標記後,該配置項會決定控制元件如何傳播更改以及發出事件。

Configuration options that determine how the control emits events after marking is applied.

  • onlySelf:如果為 true 則只標記當前控制元件。如果為 false 或不提供,則標記它所有的直系祖先。預設為 false

    onlySelf: When true, mark only this control. When false or not supplied, marks all direct ancestors. Default is false.

可選. 預設值是 `{}`.
返回值

void

如果該控制元件有任何子控制元件,則把所有子控制元件標記為 pristine,並重新計算所有父控制元件的 pristine 狀態。

If the control has any children, marks all children as pristine, and recalculates the pristine status of all parent controls.

把該控制元件標記為 pending(待定)的。

Marks the control as pending.

See also:

      
      markAsPending(opts: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void
    
引數
opts object

在應用完此標記後,該配置項會決定控制元件如何傳播變更以及發出事件。

Configuration options that determine how the control propagates changes and emits events after marking is applied.

  • onlySelf:如果為 true 則只標記當前控制元件。如果為 false 或不提供,則標記它所有的直系祖先。預設為 false

    onlySelf: When true, mark only this control. When false or not supplied, marks all direct ancestors. Default is false.

  • emitEvent:如果為 true 或未提供(預設值),則 statusChanges(Observable)會發出一個事件,傳入控制元件的最近狀態,並把控制元件標記為 pending 狀態。 如果為 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.

可選. 預設值是 `{}`.
返回值

void

當控制元件正在執行非同步驗證時,該控制元件是 pending 的。

A control is pending while the control performs async validation.

禁用此控制元件。這意味著該控制元件在表單驗證檢查時會被豁免,並且從其父控制元件的聚合值中排除它的值。它的狀態是 DISABLED

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.

See also:

      
      disable(opts: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void
    
引數
opts object

在該控制元件被禁用之後,該配置項決定如何傳播更改以及發出事件。

Configuration options that determine how the control propagates changes and emits events after the control is disabled.

  • onlySelf:如果為 true,則只標記當前控制元件。如果為 false 或沒有提供,則標記所有直系祖先。預設為 false

    onlySelf: When true, mark only this control. When false or not supplied, marks all direct ancestors. Default is false.

  • emitEvent:如果為 true 或沒有提供(預設),則當控制元件被禁用時,statusChangesvalueChanges 這兩個 Observable 都會發出最近的狀態和值。 如果為 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.

可選. 預設值是 `{}`.
返回值

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.

See also:

      
      enable(opts: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void
    
引數
opts object

當標記為 untouched 時,該配置項會決定該控制元件如何傳播變更以及發出事件。

Configure options that control how the control propagates changes and emits events when marked as untouched

  • onlySelf:如果為 true,則只標記當前控制元件。如果為 false 或沒有提供,則標記所有直系祖先。預設為 false

    onlySelf: When true, mark only this control. When false or not supplied, marks all direct ancestors. Default is false.

  • emitEvent:如果為 true 或沒有提供(預設),則當控制元件被啟用時,statusChangesvalueChanges 這兩個 Observable 都會發出最近的狀態和值。 如果為 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.

可選. 預設值是 `{}`.
返回值

void

預設情況下,如果該控制元件具有子控制元件,則所有子控制元件都會被啟用。

By default, if the control has children, all children are enabled.

      
      setParent(parent: FormGroup | FormArray): void
    
引數
parent FormGroup | FormArray

設定該控制元件的父控制元件

Sets 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
    
引數
value any
options Object
可選. 預設值是 `undefined`.
返回值

void

修補(patch)該控制元件的值。這是一個抽象方法(由子類別實現)。

Patches the value of the control. Abstract method (implemented in sub-classes).

      
      abstract patchValue(value: any, options?: Object): void
    
引數
value any
options Object
可選. 預設值是 `undefined`.
返回值

void

重置控制元件。這是一個抽象方法(由子類別實現)。

Resets the control. Abstract method (implemented in sub-classes).

      
      abstract reset(value?: any, options?: Object): void
    
引數
value any
可選. 預設值是 `undefined`.
options Object
可選. 預設值是 `undefined`.
返回值

void

重新計算控制元件的值和校驗狀態。

Recalculates the value and validation status of the control.

      
      updateValueAndValidity(opts: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void
    
引數
opts object

當更新和進行有效性檢查之後,該配置項會決定控制元件如何傳播變更併發出事件。

Configuration options determine how the control propagates changes and emits events after updates and validity checks are applied.

  • onlySelf:如果為 true,則只標記當前控制元件。如果為 false 或沒有提供,則標記所有直系祖先。預設為 false

    onlySelf: When true, only update this control. When false or not supplied, update all direct ancestors. Default is false.

  • emitEvent:如果為 true 或沒有提供(預設),則當控制元件被啟用時,statusChangesvalueChanges 這兩個 Observable 都會發出最近的狀態和值。 如果為 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.

可選. 預設值是 `{}`.
返回值

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, opts: { emitEvent?: boolean; } = {}): void
    
引數
errors ValidationErrors
opts object
可選. 預設值是 `{}`.
返回值

void

呼叫 setErrors 還會更新父控制元件的有效性狀態。

Calling setErrors also updates the validity of the parent control.

使用說明

手動設定控制元件上的錯誤資訊。
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: string | (string | number)[]): AbstractControl | null
    
引數
path string | (string | number)[]

一個由點號(.)分隔的字串或 "字串/數字" 陣列定義的控制元件路徑。

A dot-delimited string or array of string/number values that define the path to the control.

返回值

AbstractControl | null

使用說明

獲取巢狀的控制元件
Retrieve a nested control

比如,要獲取子控制元件組 person 中的 name 控制元件:

For example, to get a name control nested within a person sub-group:

  • this.form.get('person.name');

-OR-

  • 或 -
  • this.form.get(['person', 'name']);
Retrieve a control in a FormArray

When accessing an element inside a FormArray, you can use an element index. For example, to get a price control from the first element in an items array you can use:

  • this.form.get('items.0.price');

-OR-

  • this.form.get(['items', 0, 'price']);

報告具有指定路徑的控制元件的錯誤資料。

Reports error data for the control with the given path.

      
      getError(errorCode: string, path?: string | (string | number)[]): any
    
引數
errorCode string

所查出的錯誤的錯誤碼

The code of the error to check

path string | (string | number)[]

一個控制元件名列表,用於指定要如何從當前控制元件移動到要查詢錯誤的那個控制元件。

A list of control names that designates how to move from the current control to the control that should be queried for errors.

可選. 預設值是 `undefined`.
返回值

特定錯誤的資料,如果該控制元件不存在或沒有錯誤,則返回 null。

any: error data for that particular error. If the control or error is not present, null is returned.

使用說明

比如,對於下列 FormGroup

For example, for the following FormGroup:

      
      form = new FormGroup({
  address: new FormGroup({ street: new FormControl() })
});
    

此 'street' 控制元件的從根表單開始的路徑應該是 'address' -> 'street'。

The path to the 'street' control from the root form would be 'address' -> 'street'.

呼叫此方法有兩種形式:

It can be provided to this method in one of two formats:

  1. 控制元件名稱的字串陣列,如 ['address', 'street']

    An array of string control names, e.g. ['address', 'street']

  2. 以一個字串表示的句號分隔的控制元件名稱列表,如 'address.street'

    A period-delimited list of control names in one string, e.g. 'address.street'

報告指定路徑下的控制元件上是否有指定的錯誤。

Reports whether the control with the given path has the error specified.

      
      hasError(errorCode: string, path?: string | (string | number)[]): boolean
    
引數
errorCode string

要獲取的資料的錯誤碼

The code of the error to check

path string | (string | number)[]

控制元件名稱列表,用於指定如何從當前控制元件移至應查詢錯誤的控制元件。

A list of control names that designates how to move from the current control to the control that should be queried for errors.

可選. 預設值是 `undefined`.
返回值

給定路徑中的控制元件中是否存在給定的錯誤。

boolean: whether the given error is present in the control at the given path.

如果指定路徑下的控制元件有這個錯誤則返回 true,否則返回 false

If the control is not present, false is returned.

使用說明

例如,對於以下 FormGroup

For example, for the following FormGroup:

      
      form = new FormGroup({
  address: new FormGroup({ street: new FormControl() })
});
    

此 'street' 控制元件的從根表單開始的路徑應該是 'address' -> 'street'。

The path to the 'street' control from the root form would be 'address' -> 'street'.

呼叫此方法有兩種形式:

It can be provided to this method in one of two formats:

  1. 控制元件名稱的字串陣列,如 ['address', 'street']

    An array of string control names, e.g. ['address', 'street']

  2. 以一個字串表示的句號分隔的控制元件名稱列表,如 'address.street'

    A period-delimited list of control names in one string, e.g. 'address.street'

如果沒有提供路徑,則檢查當前控制元件中的錯誤。

If no path is given, this method checks for the error on the current control.