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

NgForm

建立一個最上層的 FormGroup 實例,並把它繫結到一個表單,以追蹤表單的聚合值及其驗證狀態。

Creates a top-level FormGroup instance and binds it to a form to track aggregate form value and validation status.

檢視"說明"...

Exported from

選擇器

屬性

屬性說明
submitted: boolean唯讀

返回是否已觸發表單提交。

Returns whether the form submission has been triggered.

form: FormGroup

為此表單建立的 FormGroup

The FormGroup instance created for this form.

@Output()
ngSubmit: EventEmitter

“ngSubmit” 的事件發射器

Event emitter for the "ngSubmit" event

@Input('ngFormOptions')
options: { updateOn?: FormHooks; }

NgForm 實例的選項。接受下列屬性:

Tracks options for the NgForm instance.

updateOn:為所有子級的 NgModel 設定 updateOn 的預設值(除非子 NgModel 透過 ngModelOptions 顯式指定了這個值)。 可能的值有:'change' | 'blur' | 'submit'.

updateOn: Sets the default updateOn value for all child NgModels below it unless explicitly set by a child NgModel using ngModelOptions). Defaults to 'change'. Possible values: 'change' | 'blur' | 'submit'

formDirective: Form唯讀

指令實例。

The directive instance.

control: FormGroup唯讀

內部 FormGroup 實例。

The internal FormGroup instance.

path: string[]唯讀

返回表示該組路徑的陣列。由於此指令始終位於呼叫表單的最上層,因此它始終是一個空陣列。

Returns an array representing the path to this group. Because this directive always lives at the top level of a form, it is always an empty array.

controls: { [key: string]: AbstractControl; }唯讀

返回此組中控制元件的對映表。

Returns a map of the controls in this group.

繼承自 ControlContainer

繼承自 AbstractControlDirective

範本變數參考手冊

識別符號用途
ngForm#myTemplateVar="ngForm"

說明

只要你匯入了 FormsModule,該指令就會預設在所有 <form> 標籤上生效。你不需要再新增任何特殊的選擇器。

As soon as you import the FormsModule, this directive becomes active by default on all <form> tags. You don't need to add a special selector.

你可以以 ngForm 作為 key 把該指令匯出到一個區域性範本變數(如 #myForm="ngForm")。這是可選的,但很有用。 來自本指令背後的 FormGroup 實例的很多屬性,都被複制到了指令自身,所以拿到一個對該指令的參考就可以讓你訪問此表單的聚合值和驗證狀態, 還有那些使用者互動類別的屬性,比如 dirtytouched

You optionally export the directive into a local template variable using ngForm as the key (ex: #myForm="ngForm"). This is optional, but useful. Many properties from the underlying FormGroup instance are duplicated on the directive itself, so a reference to it gives you access to the aggregate value and validity status of the form, as well as user interaction properties like dirty and touched.

要使用該表單註冊的子控制元件,請使用帶有 name 屬性的 NgModel。你可以使用 NgModelGroup 在表單中建立子組。

To register child controls with the form, use NgModel with a name attribute. You may use NgModelGroup to create sub-groups within the form.

如果需要,還可以監聽該指令的 ngSubmit 事件,以便當使用者觸發了一次表單提交時得到通知。發出 ngSubmit 事件時,會攜帶原始的 DOM 表單提交事件。

If necessary, listen to the directive's ngSubmit event to be notified when the user has triggered a form submission. The ngSubmit event emits the original form submission event.

在範本驅動表單中,所有 <form> 標籤都會自動應用上 NgForm 指令。 如果你只想匯入 FormsModule 而不想把它應用於某些表單中,比如,要想使用 HTML5 驗證,你可以新增 ngNoForm 屬性, 這樣標籤就不會在 <form> 上建立 NgForm 指令了。 在響應式表單中,則不需要用 ngNoForm,因為 NgForm 指令不會自動應用到 <form> 標籤上,你只要別主動新增 formGroup 指令就可以了。

In template driven forms, all <form> tags are automatically tagged as NgForm. To import the FormsModule but skip its usage in some forms, for example, to use native HTML5 validation, add the ngNoForm and the <form> tags won't create an NgForm directive. In reactive forms, using ngNoForm is unnecessary because the <form> tags are inert. In that case, you would refrain from using the formGroup directive.

監聽表單提交

Listening for form submission

下面的示例顯示如何從 “ngSubmit” 事件中捕獲表單值。

The following example shows how to capture the form values from the "ngSubmit" event.

      
      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>
  `,
})
export class SimpleFormComp {
  onSubmit(f: NgForm) {
    console.log(f.value);  // { first: '', last: '' }
    console.log(f.valid);  // false
  }
}
    

Setting the update options

The following example shows you how to change the "updateOn" option from its default using ngFormOptions.

      
      <form [ngFormOptions]="{updateOn: 'blur'}">
   <input name="one" ngModel>  <!-- this ngModel will update on blur -->
</form>
    

Native DOM validation UI

In order to prevent the native DOM form validation UI from interfering with Angular's form validation, Angular automatically adds the novalidate attribute on any <form> whenever FormModule or ReactiveFormModule are imported into the application. If you want to explicitly enable native DOM validation UI with Angular forms, you can add the ngNativeValidate attribute to the <form> element:

      
      <form ngNativeValidate>
  ...
</form>
    

方法

在該組中設定控制元件指令,重新計算其值和有效性並將該實例新增到內部指令列表的方法。

Method that sets up the control directive in this group, re-calculates its value and validity, and adds the instance to the internal list of directives.

      
      addControl(dir: NgModel): void
    
引數
dir NgModel

NgModel 指令實例。

The NgModel directive instance.

返回值

void

從提供的 NgModel 指令中檢索 FormControl

Retrieves the FormControl instance from the provided NgModel directive.

      
      getControl(dir: NgModel): FormControl
    
引數
dir NgModel

NgModel 指令實例。

The NgModel directive instance.

返回值

FormControl

從指令的內部列表中刪除 NgModel

Removes the NgModel instance from the internal list of directives

      
      removeControl(dir: NgModel): void
    
引數
dir NgModel

NgModel 指令實例。

The NgModel directive instance.

返回值

void

向表單新增一個新的 NgModelGroup 指令實例。

Adds a new NgModelGroup directive instance to the form.

      
      addFormGroup(dir: NgModelGroup): void
    
引數
dir NgModelGroup

NgModelGroup 指令實例。

The NgModelGroup directive instance.

返回值

void

從表單中刪除 NgModelGroup

Removes the NgModelGroup directive instance from the form.

      
      removeFormGroup(dir: NgModelGroup): void
    
引數
dir NgModelGroup

NgModelGroup 指令實例。

The NgModelGroup directive instance.

返回值

void

為所提供的 NgModelGroup 指令實例檢索其 FormGroup

Retrieves the FormGroup for a provided NgModelGroup directive instance

      
      getFormGroup(dir: NgModelGroup): FormGroup
    
引數
dir NgModelGroup

NgModelGroup 指令實例。

The NgModelGroup directive instance.

返回值

FormGroup

為所提供的 NgControl 指令設定新值。

Sets the new value for the provided NgControl directive.

      
      updateModel(dir: NgControl, value: any): void
    
引數
dir NgControl

NgControl 指令實例。

The NgControl directive instance.

value any

指令控制元件的新值。

The new value for the directive's control.

返回值

void

設定此 FormGroup 的值。

Sets the value for this FormGroup.

      
      setValue(value: { [key: string]: any; }): void
    
引數
value object

新值

The new value

返回值

void

在表單上觸發 “submit” 事件時呼叫的方法。觸發 ngSubmit 發出 “submit” 事件。

Method called when the "submit" event is triggered on the form. Triggers the ngSubmit emitter to emit the "submit" event as its payload.

      
      onSubmit($event: Event): boolean
    
引數
$event Event

"submit" 事件物件

The "submit" event object

返回值

boolean

在表單上觸發 “reset” 事件時要呼叫的方法。

Method called when the "reset" event is triggered on the form.

      
      onReset(): void
    
引數

沒有引數。

返回值

void

將表單重置為初始值並重置其提交狀態。

Resets the form to an initial value and resets its submitted status.

      
      resetForm(value: any = undefined): void
    
引數
value any

表單的新值。

The new value for the form.

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

void

繼承自 AbstractControlDirective