Form表单

具有数据收集、校验和提交功能的表单，包含复选框、单选框、输入框、下拉选择框等元素。

该组件需要与 Angular表单 结合使用，开发者根据需要可以自由选择 响应式表单 或 模板驱动表单.

使用该组件前请确保您已经阅读并掌握了 Forms 的使用方式。

表单

我们提供了以下三种排列方式：

  • 水平排列：标签和表单控件水平排列；（默认）
  • 垂直排列：标签和表单控件上下垂直排列；
  • 行内排列：表单项水平行内排列。

表单项 nz-form-item

表单项用于区分表单中不同的区域，包含表单域和表单标签(可选)。

表单标签 nz-form-label

用于标示当前表单项的内容，可选。

表单域 nz-form-control

表单一定会包含表单域，表单域可以是输入控件，标准表单域，标签，下拉菜单，文本域等。

  1. <form nz-form>
  2.   <nz-form-item>
  3.     <nz-form-label [nzSpan]="6" nzFor="email">E-mail</nz-form-label>
  4.     <nz-form-control [nzSpan]="14">
  5.       <input nz-input name="email" type="email" id="email">
  6.     </nz-form-control>
  7.   </nz-form-item >
  8. </form>
  1. import { NzFormModule } from 'ng-zorro-antd/form';

代码演示Form表单 - 图2

Form表单 - 图3

内联登录栏

内联登录栏，常用在顶部导航栏中。

  1. import { Component, OnInit } from '@angular/core';
  2. import { FormBuilder, FormGroup, Validators } from '@angular/forms';
  4. @Component({
  5.   selector: 'nz-demo-form-horizontal-login',
  6.   template: `
  7.     <form nz-form [nzLayout]="'inline'" [formGroup]="validateForm" (ngSubmit)="submitForm()">
  8.       <nz-form-item>
  9.         <nz-form-control nzErrorTip="Please input your username!">
  10.           <nz-input-group nzPrefixIcon="user">
  11.             <input formControlName="userName" nz-input placeholder="Username" />
  12.           </nz-input-group>
  13.         </nz-form-control>
  14.       </nz-form-item>
  15.       <nz-form-item>
  16.         <nz-form-control nzErrorTip="Please input your Password!">
  17.           <nz-input-group nzPrefixIcon="lock">
  18.             <input formControlName="password" nz-input type="password" placeholder="Password" />
  19.           </nz-input-group>
  20.         </nz-form-control>
  21.       </nz-form-item>
  22.       <nz-form-item>
  23.         <nz-form-control>
  24.           <button nz-button nzType="primary" [disabled]="!validateForm.valid">Log in</button>
  25.         </nz-form-control>
  26.       </nz-form-item>
  27.     </form>
  28.   `
  29. })
  30. export class NzDemoFormHorizontalLoginComponent implements OnInit {
  31.   validateForm!: FormGroup;
  33.   submitForm(): void {
  34.     for (const i in this.validateForm.controls) {
  35.       this.validateForm.controls[i].markAsDirty();
  36.       this.validateForm.controls[i].updateValueAndValidity();
  37.     }
  38.   }
  40.   constructor(private fb: FormBuilder) {}
  42.   ngOnInit(): void {
  43.     this.validateForm = this.fb.group({
  44.       userName: [null, [Validators.required]],
  45.       password: [null, [Validators.required]],
  46.       remember: [true]
  47.     });
  48.   }
  49. }

Form表单 - 图4

登录框

普通的登录框，可以容纳更多的元素。

  1. import { Component, OnInit } from '@angular/core';
  2. import { FormBuilder, FormGroup, Validators } from '@angular/forms';
  4. @Component({
  5.   selector: 'nz-demo-form-normal-login',
  6.   template: `
  7.     <form nz-form [formGroup]="validateForm" class="login-form" (ngSubmit)="submitForm()">
  8.       <nz-form-item>
  9.         <nz-form-control nzErrorTip="Please input your username!">
  10.           <nz-input-group nzPrefixIcon="user">
  11.             <input type="text" nz-input formControlName="userName" placeholder="Username" />
  12.           </nz-input-group>
  13.         </nz-form-control>
  14.       </nz-form-item>
  15.       <nz-form-item>
  16.         <nz-form-control nzErrorTip="Please input your Password!">
  17.           <nz-input-group nzPrefixIcon="lock">
  18.             <input type="password" nz-input formControlName="password" placeholder="Password" />
  19.           </nz-input-group>
  20.         </nz-form-control>
  21.       </nz-form-item>
  22.       <div nz-row class="login-form-margin">
  23.         <div nz-col [nzSpan]="12">
  24.           <label nz-checkbox formControlName="remember">
  25.             <span>Remember me</span>
  26.           </label>
  27.         </div>
  28.         <div nz-col [nzSpan]="12">
  29.           <a class="login-form-forgot">Forgot password</a>
  30.         </div>
  31.       </div>
  32.       <button nz-button class="login-form-button login-form-margin" [nzType]="'primary'">Log in</button>
  33.       Or <a> register now! </a>
  34.     </form>
  35.   `,
  36.   styles: [
  37.     `
  38.       .login-form {
  39.         max-width: 300px;
  40.       }
  42.       .login-form-margin {
  43.         margin-bottom: 16px;
  44.       }
  46.       .login-form-forgot {
  47.         float: right;
  48.       }
  50.       .login-form-button {
  51.         width: 100%;
  52.       }
  53.     `
  54.   ]
  55. })
  56. export class NzDemoFormNormalLoginComponent implements OnInit {
  57.   validateForm!: FormGroup;
  59.   submitForm(): void {
  60.     for (const i in this.validateForm.controls) {
  61.       this.validateForm.controls[i].markAsDirty();
  62.       this.validateForm.controls[i].updateValueAndValidity();
  63.     }
  64.   }
  66.   constructor(private fb: FormBuilder) {}
  68.   ngOnInit(): void {
  69.     this.validateForm = this.fb.group({
  70.       userName: [null, [Validators.required]],
  71.       password: [null, [Validators.required]],
  72.       remember: [true]
  73.     });
  74.   }
  75. }

Form表单 - 图5

注册新用户

用户填写必须的信息以注册新用户。

  1. import { Component, OnInit } from '@angular/core';
  2. import { FormBuilder, FormControl, FormGroup, Validators } from '@angular/forms';
  4. @Component({
  5.   selector: 'nz-demo-form-register',
  6.   template: `
  7.     <form nz-form [formGroup]="validateForm" (ngSubmit)="submitForm()">
  8.       <nz-form-item>
  9.         <nz-form-label [nzSm]="6" [nzXs]="24" nzRequired nzFor="email">E-mail</nz-form-label>
  10.         <nz-form-control [nzSm]="14" [nzXs]="24" nzErrorTip="The input is not valid E-mail!">
  11.           <input nz-input formControlName="email" id="email" />
  12.         </nz-form-control>
  13.       </nz-form-item>
  14.       <nz-form-item>
  15.         <nz-form-label [nzSm]="6" [nzXs]="24" nzFor="password" nzRequired>Password</nz-form-label>
  16.         <nz-form-control [nzSm]="14" [nzXs]="24" nzErrorTip="Please input your password!">
  17.           <input nz-input type="password" id="password" formControlName="password" (ngModelChange)="updateConfirmValidator()" />
  18.         </nz-form-control>
  19.       </nz-form-item>
  20.       <nz-form-item>
  21.         <nz-form-label [nzSm]="6" [nzXs]="24" nzFor="checkPassword" nzRequired>Confirm Password</nz-form-label>
  22.         <nz-form-control [nzSm]="14" [nzXs]="24" [nzErrorTip]="errorTpl">
  23.           <input nz-input type="password" formControlName="checkPassword" id="checkPassword" />
  24.           <ng-template #errorTpl let-control>
  25.             <ng-container *ngIf="control.hasError('required')">
  26.               Please confirm your password!
  27.             </ng-container>
  28.             <ng-container *ngIf="control.hasError('confirm')">
  29.               Two passwords that you enter is inconsistent!
  30.             </ng-container>
  31.           </ng-template>
  32.         </nz-form-control>
  33.       </nz-form-item>
  34.       <nz-form-item>
  35.         <nz-form-label [nzSm]="6" [nzXs]="24" nzFor="nickname" nzRequired>
  36.           <span>
  37.             Nickname
  38.             <i nz-icon nz-tooltip nzTooltipTitle="What do you want other to call you" nzType="question-circle" nzTheme="outline"></i>
  39.           </span>
  40.         </nz-form-label>
  41.         <nz-form-control [nzSm]="14" [nzXs]="24" nzErrorTip="Please input your nickname!">
  42.           <input nz-input id="nickname" formControlName="nickname" />
  43.         </nz-form-control>
  44.       </nz-form-item>
  45.       <nz-form-item>
  46.         <nz-form-label [nzSm]="6" [nzXs]="24" nzFor="phoneNumber" nzRequired>Phone Number</nz-form-label>
  47.         <nz-form-control
  48.           [nzSm]="14"
  49.           [nzXs]="24"
  50.           [nzValidateStatus]="validateForm.controls['phoneNumber']"
  51.           nzErrorTip="Please input your phone number!"
  52.         >
  53.           <nz-input-group [nzAddOnBefore]="addOnBeforeTemplate">
  54.             <ng-template #addOnBeforeTemplate>
  55.               <nz-select formControlName="phoneNumberPrefix" class="phone-select">
  56.                 <nz-option nzLabel="+86" nzValue="+86"></nz-option>
  57.                 <nz-option nzLabel="+87" nzValue="+87"></nz-option>
  58.               </nz-select>
  59.             </ng-template>
  60.             <input formControlName="phoneNumber" id="'phoneNumber'" nz-input />
  61.           </nz-input-group>
  62.         </nz-form-control>
  63.       </nz-form-item>
  64.       <nz-form-item>
  65.         <nz-form-label [nzSm]="6" [nzXs]="24" nzFor="website" nzRequired>Website</nz-form-label>
  66.         <nz-form-control [nzSm]="14" [nzXs]="24" nzErrorTip="Please input website!">
  67.           <input nz-input id="website" formControlName="website" placeholder="website" />
  68.         </nz-form-control>
  69.       </nz-form-item>
  70.       <nz-form-item>
  71.         <nz-form-label [nzSm]="6" [nzXs]="24" nzFor="captcha" nzRequired>Captcha</nz-form-label>
  72.         <nz-form-control
  73.           [nzSm]="14"
  74.           [nzXs]="24"
  75.           nzErrorTip="Please input the captcha you got!"
  76.           nzExtra="We must make sure that your are a human."
  77.         >
  78.           <div nz-row [nzGutter]="8">
  79.             <div nz-col [nzSpan]="12">
  80.               <input nz-input formControlName="captcha" id="captcha" />
  81.             </div>
  82.             <div nz-col [nzSpan]="12">
  83.               <button nz-button (click)="getCaptcha($event)">Get captcha</button>
  84.             </div>
  85.           </div>
  86.         </nz-form-control>
  87.       </nz-form-item>
  88.       <nz-form-item nz-row class="register-area">
  89.         <nz-form-control [nzSpan]="14" [nzOffset]="6">
  90.           <label nz-checkbox formControlName="agree">
  91.             <span>I have read the <a>agreement</a></span>
  92.           </label>
  93.         </nz-form-control>
  94.       </nz-form-item>
  95.       <nz-form-item nz-row class="register-area">
  96.         <nz-form-control [nzSpan]="14" [nzOffset]="6">
  97.           <button nz-button nzType="primary">Register</button>
  98.         </nz-form-control>
  99.       </nz-form-item>
  100.     </form>
  101.   `,
  103.   styles: [
  104.     `
  105.       [nz-form] {
  106.         max-width: 600px;
  107.       }
  109.       .phone-select {
  110.         width: 70px;
  111.       }
  113.       .register-are {
  114.         margin-bottom: 8px;
  115.       }
  116.     `
  117.   ]
  118. })
  119. export class NzDemoFormRegisterComponent implements OnInit {
  120.   validateForm!: FormGroup;
  122.   submitForm(): void {
  123.     for (const i in this.validateForm.controls) {
  124.       this.validateForm.controls[i].markAsDirty();
  125.       this.validateForm.controls[i].updateValueAndValidity();
  126.     }
  127.   }
  129.   updateConfirmValidator(): void {
  130.     /** wait for refresh value */
  131.     Promise.resolve().then(() => this.validateForm.controls.checkPassword.updateValueAndValidity());
  132.   }
  134.   confirmationValidator = (control: FormControl): { [s: string]: boolean } => {
  135.     if (!control.value) {
  136.       return { required: true };
  137.     } else if (control.value !== this.validateForm.controls.password.value) {
  138.       return { confirm: true, error: true };
  139.     }
  140.     return {};
  141.   };
  143.   getCaptcha(e: MouseEvent): void {
  144.     e.preventDefault();
  145.   }
  147.   constructor(private fb: FormBuilder) {}
  149.   ngOnInit(): void {
  150.     this.validateForm = this.fb.group({
  151.       email: [null, [Validators.email, Validators.required]],
  152.       password: [null, [Validators.required]],
  153.       checkPassword: [null, [Validators.required, this.confirmationValidator]],
  154.       nickname: [null, [Validators.required]],
  155.       phoneNumberPrefix: ['+86'],
  156.       phoneNumber: [null, [Validators.required]],
  157.       website: [null, [Validators.required]],
  158.       captcha: [null, [Validators.required]],
  159.       agree: [false]
  160.     });
  161.   }
  162. }

Form表单 - 图6

高级搜索

三列栅格式的表单排列方式，常用于数据表格的高级搜索。

有部分定制的样式代码，由于输入标签长度不确定，需要根据具体情况自行调整。

  1. import { Component, OnInit } from '@angular/core';
  2. import { FormBuilder, FormControl, FormGroup } from '@angular/forms';
  4. @Component({
  5.   selector: 'nz-demo-form-advanced-search',
  6.   template: `
  7.     <form nz-form [formGroup]="validateForm" class="ant-advanced-search-form">
  8.       <div nz-row [nzGutter]="24">
  9.         <div nz-col [nzSpan]="8" *ngFor="let control of controlArray" [hidden]="!control.show">
  10.           <nz-form-item>
  11.             <nz-form-label [nzFor]="'field' + control.index">Field {{ control.index }}</nz-form-label>
  12.             <nz-form-control>
  13.               <input nz-input placeholder="placeholder" [formControlName]="'field' + control.index" [attr.id]="'field' + control.index" />
  14.             </nz-form-control>
  15.           </nz-form-item>
  16.         </div>
  17.       </div>
  18.       <div nz-row>
  19.         <div nz-col [nzSpan]="24" class="search-area">
  20.           <button nz-button [nzType]="'primary'">Search</button>
  21.           <button nz-button (click)="resetForm()">Clear</button>
  22.           <a class="collapse" (click)="toggleCollapse()">
  23.             Collapse
  24.             <i nz-icon [nzType]="isCollapse ? 'down' : 'up'"></i>
  25.           </a>
  26.         </div>
  27.       </div>
  28.     </form>
  29.     <div class="search-result-list">
  30.       Search Result List
  31.     </div>
  32.   `,
  34.   styles: [
  35.     `
  36.       .ant-advanced-search-form {
  37.         padding: 24px;
  38.         background: #fbfbfb;
  39.         border: 1px solid #d9d9d9;
  40.         border-radius: 6px;
  41.       }
  43.       .search-result-list {
  44.         margin-top: 16px;
  45.         border: 1px dashed #e9e9e9;
  46.         border-radius: 6px;
  47.         background-color: #fafafa;
  48.         min-height: 200px;
  49.         text-align: center;
  50.         padding-top: 80px;
  51.       }
  53.       [nz-form-label] {
  54.         overflow: visible;
  55.       }
  57.       button {
  58.         margin-left: 8px;
  59.       }
  61.       .collapse {
  62.         margin-left: 8px;
  63.         font-size: 12px;
  64.       }
  66.       .search-area {
  67.         text-align: right;
  68.       }
  69.     `
  70.   ]
  71. })
  72. export class NzDemoFormAdvancedSearchComponent implements OnInit {
  73.   validateForm!: FormGroup;
  74.   controlArray: Array<{ index: number; show: boolean }> = [];
  75.   isCollapse = true;
  77.   toggleCollapse(): void {
  78.     this.isCollapse = !this.isCollapse;
  79.     this.controlArray.forEach((c, index) => {
  80.       c.show = this.isCollapse ? index < 6 : true;
  81.     });
  82.   }
  84.   resetForm(): void {
  85.     this.validateForm.reset();
  86.   }
  88.   constructor(private fb: FormBuilder) {}
  90.   ngOnInit(): void {
  91.     this.validateForm = this.fb.group({});
  92.     for (let i = 0; i < 10; i++) {
  93.       this.controlArray.push({ index: i, show: i < 6 });
  94.       this.validateForm.addControl(`field${i}`, new FormControl());
  95.     }
  96.   }
  97. }

Form表单 - 图7

动态增减表单项

动态增加、减少表单项。

  1. import { Component, OnInit } from '@angular/core';
  2. import { FormBuilder, FormControl, FormGroup, Validators } from '@angular/forms';
  4. @Component({
  5.   selector: 'nz-demo-form-dynamic-form-item',
  6.   template: `
  7.     <form nz-form [formGroup]="validateForm" (ngSubmit)="submitForm()">
  8.       <nz-form-item *ngFor="let control of listOfControl; let i = index">
  9.         <nz-form-label [nzXs]="24" [nzSm]="4" *ngIf="i == 0" [nzFor]="control.controlInstance">Passengers </nz-form-label>
  10.         <nz-form-control
  11.           [nzXs]="24"
  12.           [nzSm]="20"
  13.           [nzOffset]="i == 0 ? 0 : 4"
  14.           nzErrorTip="Please input passenger's name or delete this field."
  15.         >
  16.           <input
  17.             class="passenger-input"
  18.             nz-input
  19.             placeholder="placeholder"
  20.             [attr.id]="control.id"
  21.             [formControlName]="control.controlInstance"
  22.           />
  23.           <i nz-icon nzType="minus-circle-o" class="dynamic-delete-button" (click)="removeField(control, $event)"></i>
  24.         </nz-form-control>
  25.       </nz-form-item>
  26.       <nz-form-item>
  27.         <nz-form-control [nzXs]="{ span: 24, offset: 0 }" [nzSm]="{ span: 20, offset: 4 }">
  28.           <button nz-button nzType="dashed" class="add-button" (click)="addField($event)">
  29.             <i nz-icon nzType="plus"></i>
  30.             Add field
  31.           </button>
  32.         </nz-form-control>
  33.       </nz-form-item>
  34.       <nz-form-item>
  35.         <nz-form-control [nzXs]="{ span: 24, offset: 0 }" [nzSm]="{ span: 20, offset: 4 }">
  36.           <button nz-button nzType="primary">Submit</button>
  37.         </nz-form-control>
  38.       </nz-form-item>
  39.     </form>
  40.   `,
  42.   styles: [
  43.     `
  44.       .dynamic-delete-button {
  45.         cursor: pointer;
  46.         position: relative;
  47.         top: 4px;
  48.         font-size: 24px;
  49.         color: #999;
  50.         transition: all 0.3s;
  51.       }
  53.       .dynamic-delete-button:hover {
  54.         color: #777;
  55.       }
  57.       .passenger-input {
  58.         width: 60%;
  59.         margin-right: 8px;
  60.       }
  62.       [nz-form] {
  63.         max-width: 600px;
  64.       }
  66.       .add-button {
  67.         width: 60%;
  68.       }
  69.     `
  70.   ]
  71. })
  72. export class NzDemoFormDynamicFormItemComponent implements OnInit {
  73.   validateForm!: FormGroup;
  74.   listOfControl: Array<{ id: number; controlInstance: string }> = [];
  76.   addField(e?: MouseEvent): void {
  77.     if (e) {
  78.       e.preventDefault();
  79.     }
  80.     const id = this.listOfControl.length > 0 ? this.listOfControl[this.listOfControl.length - 1].id + 1 : 0;
  82.     const control = {
  83.       id,
  84.       controlInstance: `passenger${id}`
  85.     };
  86.     const index = this.listOfControl.push(control);
  87.     console.log(this.listOfControl[this.listOfControl.length - 1]);
  88.     this.validateForm.addControl(this.listOfControl[index - 1].controlInstance, new FormControl(null, Validators.required));
  89.   }
  91.   removeField(i: { id: number; controlInstance: string }, e: MouseEvent): void {
  92.     e.preventDefault();
  93.     if (this.listOfControl.length > 1) {
  94.       const index = this.listOfControl.indexOf(i);
  95.       this.listOfControl.splice(index, 1);
  96.       console.log(this.listOfControl);
  97.       this.validateForm.removeControl(i.controlInstance);
  98.     }
  99.   }
  101.   submitForm(): void {
  102.     for (const i in this.validateForm.controls) {
  103.       this.validateForm.controls[i].markAsDirty();
  104.       this.validateForm.controls[i].updateValueAndValidity();
  105.     }
  106.     console.log(this.validateForm.value);
  107.   }
  109.   constructor(private fb: FormBuilder) {}
  111.   ngOnInit(): void {
  112.     this.validateForm = this.fb.group({});
  113.     this.addField();
  114.   }
  115. }

Form表单 - 图8

时间类控件

时间类组件的输入和输出类型均为 Date 类型，可以通过 date-fns 工具库进行进一步的处理。

  1. import { Component, OnInit } from '@angular/core';
  2. import { FormBuilder, FormGroup } from '@angular/forms';
  4. @Component({
  5.   selector: 'nz-demo-form-time-related-controls',
  6.   template: `
  7.     <form nz-form [formGroup]="validateForm" (ngSubmit)="submitForm()">
  8.       <nz-form-item>
  9.         <nz-form-label [nzSm]="8" [nzXs]="24" nzRequired>DatePicker</nz-form-label>
  10.         <nz-form-control [nzSm]="16" [nzXs]="24">
  11.           <nz-date-picker formControlName="datePicker"></nz-date-picker>
  12.         </nz-form-control>
  13.       </nz-form-item>
  14.       <nz-form-item>
  15.         <nz-form-label [nzSm]="8" [nzXs]="24" nzRequired>DatePicker[ShowTime]</nz-form-label>
  16.         <nz-form-control [nzSm]="16" [nzXs]="24">
  17.           <nz-date-picker nzShowTime formControlName="datePickerTime"></nz-date-picker>
  18.         </nz-form-control>
  19.       </nz-form-item>
  20.       <nz-form-item>
  21.         <nz-form-label [nzSm]="8" [nzXs]="24" nzRequired>MonthPicker</nz-form-label>
  22.         <nz-form-control [nzSm]="16" [nzXs]="24">
  23.           <nz-date-picker nzMode="month" formControlName="monthPicker"></nz-date-picker>
  24.         </nz-form-control>
  25.       </nz-form-item>
  26.       <nz-form-item>
  27.         <nz-form-label [nzSm]="8" [nzXs]="24" nzRequired>RangePicker</nz-form-label>
  28.         <nz-form-control [nzSm]="16" [nzXs]="24">
  29.           <nz-range-picker formControlName="rangePicker"></nz-range-picker>
  30.         </nz-form-control>
  31.       </nz-form-item>
  32.       <nz-form-item>
  33.         <nz-form-label [nzSm]="8" [nzXs]="24" nzRequired>RangePicker[showTime]</nz-form-label>
  34.         <nz-form-control [nzSm]="16" [nzXs]="24">
  35.           <nz-range-picker nzShowTime formControlName="rangePickerTime"></nz-range-picker>
  36.         </nz-form-control>
  37.       </nz-form-item>
  38.       <nz-form-item>
  39.         <nz-form-label [nzSm]="8" [nzXs]="24" nzRequired>TimePicker</nz-form-label>
  40.         <nz-form-control [nzSm]="16" [nzXs]="24">
  41.           <nz-time-picker formControlName="timePicker"></nz-time-picker>
  42.         </nz-form-control>
  43.       </nz-form-item>
  44.       <nz-form-item>
  45.         <nz-form-control [nzXs]="{ span: 24, offset: 0 }" [nzSm]="{ span: 16, offset: 8 }">
  46.           <button nz-button nzType="primary">Submit</button>
  47.         </nz-form-control>
  48.       </nz-form-item>
  49.     </form>
  50.   `,
  51.   styles: [
  52.     `
  53.       form {
  54.         max-width: 600px;
  55.       }
  56.     `
  57.   ]
  58. })
  59. export class NzDemoFormTimeRelatedControlsComponent implements OnInit {
  60.   validateForm!: FormGroup;
  62.   submitForm(): void {
  63.     console.log(this.validateForm.value);
  64.   }
  66.   constructor(private fb: FormBuilder) {}
  68.   ngOnInit(): void {
  69.     this.validateForm = this.fb.group({
  70.       datePicker: [null],
  71.       datePickerTime: [null],
  72.       monthPicker: [null],
  73.       rangePicker: [[]],
  74.       rangePickerTime: [[]],
  75.       timePicker: [null]
  76.     });
  77.   }
  78. }

Form表单 - 图9

响应式表单验证

我们在 nz-form-control 上 提供了 nzValidateStatus``nzHasFeedback 等属性，当使用响应式表单时，可以自己定义校验的时机和内容。

  1. nzValidateStatus: 校验状态，默认自动从 nz-form-control 中的 NgControl 获得校验状态，也可以手动指定为特定的 NgControl。
  2. nzHasFeedback：用于给输入框添加反馈图标。

  3. nzSuccessTip``nzWarningTip``nzErrorTip``nzValidatingTip：设置不同状态校验文案。

    当同一种状态下存在多种提示情况时，nzSuccessTip``nzWarningTip``nzErrorTip``nzValidatingTip 均支持传入 TemplateRef<{ $implicit: FormControl } 类型，可以通过模板变量)导出 FormControl 后用于切换不同的提示信息。
    当 FormControl.status 为 INVALID 并且错误包含 {warning：true} 时，nz-form-control 显示警告状态。

  1. import { Component } from '@angular/core';
  3. import { FormBuilder, FormControl, FormGroup, ValidationErrors, Validators } from '@angular/forms';
  4. import { Observable, Observer } from 'rxjs';
  6. @Component({
  7.   selector: 'nz-demo-form-validate-reactive',
  8.   template: `
  9.     <form nz-form [formGroup]="validateForm" (ngSubmit)="submitForm(validateForm.value)">
  10.       <nz-form-item>
  11.         <nz-form-label [nzSpan]="7" nzRequired>Username</nz-form-label>
  12.         <nz-form-control [nzSpan]="12" nzHasFeedback nzValidatingTip="Validating..." [nzErrorTip]="userErrorTpl">
  13.           <input nz-input formControlName="userName" placeholder="async validate try to write JasonWood" />
  14.           <ng-template #userErrorTpl let-control>
  15.             <ng-container *ngIf="control.hasError('required')">
  16.               Please input your username!
  17.             </ng-container>
  18.             <ng-container *ngIf="control.hasError('duplicated')">
  19.               The username is redundant!
  20.             </ng-container>
  21.           </ng-template>
  22.         </nz-form-control>
  23.       </nz-form-item>
  24.       <nz-form-item>
  25.         <nz-form-label [nzSpan]="7" nzRequired>E-mail</nz-form-label>
  26.         <nz-form-control [nzSpan]="12" nzHasFeedback [nzErrorTip]="emailErrorTpl">
  27.           <input nz-input formControlName="email" placeholder="email" type="email" />
  28.           <ng-template #emailErrorTpl let-control>
  29.             <ng-container *ngIf="control.hasError('email')">
  30.               The input is not valid E-mail!
  31.             </ng-container>
  32.             <ng-container *ngIf="control.hasError('required')">
  33.               Please input your E-mail!
  34.             </ng-container>
  35.           </ng-template>
  36.         </nz-form-control>
  37.       </nz-form-item>
  38.       <nz-form-item>
  39.         <nz-form-label [nzSpan]="7" nzRequired>Password</nz-form-label>
  40.         <nz-form-control [nzSpan]="12" nzHasFeedback nzErrorTip="Please input your password!">
  41.           <input nz-input type="password" formControlName="password" (ngModelChange)="validateConfirmPassword()" />
  42.         </nz-form-control>
  43.       </nz-form-item>
  44.       <nz-form-item>
  45.         <nz-form-label [nzSpan]="7" nzRequired>Confirm Password</nz-form-label>
  46.         <nz-form-control [nzSpan]="12" nzHasFeedback [nzErrorTip]="passwordErrorTpl">
  47.           <input nz-input type="password" formControlName="confirm" placeholder="confirm your password" />
  48.           <ng-template #passwordErrorTpl let-control>
  49.             <ng-container *ngIf="control.hasError('required')">
  50.               Please confirm your password!
  51.             </ng-container>
  52.             <ng-container *ngIf="control.hasError('confirm')">
  53.               Password is inconsistent!
  54.             </ng-container>
  55.           </ng-template>
  56.         </nz-form-control>
  57.       </nz-form-item>
  58.       <nz-form-item>
  59.         <nz-form-label [nzSpan]="7" nzRequired>Comment</nz-form-label>
  60.         <nz-form-control [nzSpan]="12" nzErrorTip="Please write something here!">
  61.           <textarea formControlName="comment" nz-input rows="2" placeholder="write any thing"></textarea>
  62.         </nz-form-control>
  63.       </nz-form-item>
  64.       <nz-form-item>
  65.         <nz-form-control [nzOffset]="7" [nzSpan]="12">
  66.           <button nz-button nzType="primary" [disabled]="!validateForm.valid">Submit</button>
  67.           <button nz-button (click)="resetForm($event)">Reset</button>
  68.         </nz-form-control>
  69.       </nz-form-item>
  70.     </form>
  71.   `,
  73.   styles: [
  74.     `
  75.       [nz-form] {
  76.         max-width: 600px;
  77.       }
  79.       button {
  80.         margin-left: 8px;
  81.       }
  82.     `
  83.   ]
  84. })
  85. export class NzDemoFormValidateReactiveComponent {
  86.   validateForm: FormGroup;
  88.   submitForm(value: { userName: string; email: string; password: string; confirm: string; comment: string }): void {
  89.     for (const key in this.validateForm.controls) {
  90.       this.validateForm.controls[key].markAsDirty();
  91.       this.validateForm.controls[key].updateValueAndValidity();
  92.     }
  93.     console.log(value);
  94.   }
  96.   resetForm(e: MouseEvent): void {
  97.     e.preventDefault();
  98.     this.validateForm.reset();
  99.     for (const key in this.validateForm.controls) {
  100.       this.validateForm.controls[key].markAsPristine();
  101.       this.validateForm.controls[key].updateValueAndValidity();
  102.     }
  103.   }
  105.   validateConfirmPassword(): void {
  106.     setTimeout(() => this.validateForm.controls.confirm.updateValueAndValidity());
  107.   }
  109.   userNameAsyncValidator = (control: FormControl) =>
  110.     new Observable((observer: Observer<ValidationErrors | null>) => {
  111.       setTimeout(() => {
  112.         if (control.value === 'JasonWood') {
  113.           // you have to return `{error: true}` to mark it as an error event
  114.           observer.next({ error: true, duplicated: true });
  115.         } else {
  116.           observer.next(null);
  117.         }
  118.         observer.complete();
  119.       }, 1000);
  120.     });
  122.   confirmValidator = (control: FormControl): { [s: string]: boolean } => {
  123.     if (!control.value) {
  124.       return { error: true, required: true };
  125.     } else if (control.value !== this.validateForm.controls.password.value) {
  126.       return { confirm: true, error: true };
  127.     }
  128.     return {};
  129.   };
  131.   constructor(private fb: FormBuilder) {
  132.     this.validateForm = this.fb.group({
  133.       userName: ['', [Validators.required], [this.userNameAsyncValidator]],
  134.       email: ['', [Validators.email, Validators.required]],
  135.       password: ['', [Validators.required]],
  136.       confirm: ['', [this.confirmValidator]],
  137.       comment: ['', [Validators.required]]
  138.     });
  139.   }
  140. }

Form表单 - 图10

模板驱动表单验证

当使用模板驱动表单时，模板可以根据模板设定自动进行校验。

  1. nzHasFeedback：用于给输入框添加反馈图标。

  2. nzSuccessTip``nzWarningTip``nzErrorTip``nzValidatingTip：设置不同状态校验文案。

    当同一种状态下存在多种提示情况时，nzSuccessTip``nzWarningTip``nzErrorTip``nzValidatingTip 均支持传入 TemplateRef<{ $implicit: NgModel } 类型，可以通过模板变量)导出 NgModel 后用于切换不同的提示信息。

  1. import { Component } from '@angular/core';
  3. @Component({
  4.   selector: 'nz-demo-form-validate-template',
  5.   template: `
  6.     <form nz-form>
  7.       <nz-form-item>
  8.         <nz-form-label [nzSpan]="5">Required</nz-form-label>
  9.         <nz-form-control nzHasFeedback [nzSpan]="12" nzErrorTip="Input is required">
  10.           <input nz-input [ngModel]="'Required Input'" name="required" required />
  11.         </nz-form-control>
  12.       </nz-form-item>
  13.       <nz-form-item>
  14.         <nz-form-label [nzSpan]="5">MaxLength</nz-form-label>
  15.         <nz-form-control nzHasFeedback [nzSpan]="12" nzErrorTip="MaxLength is 6">
  16.           <input nz-input [ngModel]="'MaxLength is 6'" name="maxlength" maxlength="6" />
  17.         </nz-form-control>
  18.       </nz-form-item>
  19.       <nz-form-item>
  20.         <nz-form-label [nzSpan]="5">MinLength</nz-form-label>
  21.         <nz-form-control nzHasFeedback [nzSpan]="12" nzErrorTip="MinLength is 6">
  22.           <input nz-input [ngModel]="'MinLength is 6'" name="minlength" minlength="6" />
  23.         </nz-form-control>
  24.       </nz-form-item>
  25.       <nz-form-item>
  26.         <nz-form-label [nzSpan]="5">Email</nz-form-label>
  27.         <nz-form-control nzHasFeedback [nzSpan]="12" nzErrorTip="Email is not valid">
  28.           <input nz-input [ngModel]="'Input Email'" name="email" email />
  29.         </nz-form-control>
  30.       </nz-form-item>
  31.       <nz-form-item>
  32.         <nz-form-label [nzSpan]="5">Pattern</nz-form-label>
  33.         <nz-form-control nzHasFeedback [nzSpan]="12" nzErrorTip="Pattern not match">
  34.           <input nz-input [ngModel]="'Match pattern'" name="pattern" pattern=".{3,}" />
  35.         </nz-form-control>
  36.       </nz-form-item>
  37.       <nz-form-item>
  38.         <nz-form-label [nzSpan]="5">Mix</nz-form-label>
  39.         <nz-form-control nzHasFeedback [nzSpan]="12" [nzErrorTip]="combineTpl">
  40.           <input nz-input [ngModel]="'MaxLength is 12 and MinLength is 6'" name="mix" minlength="6" maxlength="12" required />
  41.           <ng-template #combineTpl let-control>
  42.             <ng-container *ngIf="control.hasError('maxlength')">MaxLength is 12</ng-container>
  43.             <ng-container *ngIf="control.hasError('minlength')">MinLength is 6</ng-container>
  44.             <ng-container *ngIf="control.hasError('required')">Input is required</ng-container>
  45.           </ng-template>
  46.         </nz-form-control>
  47.       </nz-form-item>
  48.     </form>
  49.   `,
  50.   styles: [
  51.     `
  52.       [nz-form] {
  53.         max-width: 600px;
  54.       }
  55.     `
  56.   ]
  57. })
  58. export class NzDemoFormValidateTemplateComponent {}

Form表单 - 图11

自动提示

让提示变得更简单。
需要预先自定义 Validators 和提供 nzAutoTips，它们优先级如下：

  • Validators > nzAutoTips
  • 通过 @Input 设置 nzAutoTips
  • 通过全局配置设置 nzAutoTips

另外，你可以使用 nzDisableAutoTips 去禁用它。

  1. import { Component } from '@angular/core';
  2. import { AbstractControl, FormBuilder, FormControl, FormGroup, ValidatorFn, Validators } from '@angular/forms';
  3. import { NzSafeAny } from 'ng-zorro-antd/core/types';
  4. import { Observable, Observer } from 'rxjs';
  6. @Component({
  7.   selector: 'nz-demo-form-auto-tips',
  8.   template: `
  9.     <form nz-form [nzAutoTips]="autoTips" [formGroup]="validateForm" (ngSubmit)="submitForm(validateForm.value)">
  10.       <nz-form-item>
  11.         <nz-form-label [nzSpan]="7" nzRequired>Username</nz-form-label>
  12.         <nz-form-control [nzSpan]="12" nzValidatingTip="Validating...">
  13.           <input nz-input formControlName="userName" placeholder="async validate try to write JasonWood" />
  14.         </nz-form-control>
  15.       </nz-form-item>
  16.       <nz-form-item>
  17.         <nz-form-label [nzSpan]="7" nzRequired>Mobile</nz-form-label>
  18.         <nz-form-control [nzSpan]="12">
  19.           <input nz-input formControlName="mobile" placeholder="mobile" />
  20.         </nz-form-control>
  21.       </nz-form-item>
  22.       <nz-form-item>
  23.         <nz-form-label [nzSpan]="7" nzRequired>E-mail</nz-form-label>
  24.         <nz-form-control [nzSpan]="12">
  25.           <input nz-input formControlName="email" placeholder="email" type="email" />
  26.         </nz-form-control>
  27.       </nz-form-item>
  28.       <nz-form-item>
  29.         <nz-form-label [nzSpan]="7" nzRequired>Password</nz-form-label>
  30.         <nz-form-control [nzSpan]="12" nzDisableAutoTips nzErrorTip="Please input your password!">
  31.           <input nz-input type="password" formControlName="password" (ngModelChange)="validateConfirmPassword()" />
  32.         </nz-form-control>
  33.       </nz-form-item>
  34.       <nz-form-item>
  35.         <nz-form-label [nzSpan]="7" nzRequired>Confirm Password</nz-form-label>
  36.         <nz-form-control [nzSpan]="12" nzDisableAutoTips [nzErrorTip]="passwordErrorTpl">
  37.           <input nz-input type="password" formControlName="confirm" placeholder="confirm your password" />
  38.           <ng-template #passwordErrorTpl let-control>
  39.             <ng-container *ngIf="control.hasError('required')">
  40.               Please confirm your password!
  41.             </ng-container>
  42.             <ng-container *ngIf="control.hasError('confirm')">
  43.               Password is inconsistent!
  44.             </ng-container>
  45.           </ng-template>
  46.         </nz-form-control>
  47.       </nz-form-item>
  48.       <nz-form-item>
  49.         <nz-form-control [nzOffset]="7" [nzSpan]="12">
  50.           <button nz-button nzType="primary">Submit</button>
  51.         </nz-form-control>
  52.       </nz-form-item>
  53.     </form>
  54.   `,
  55.   styles: [
  56.     `
  57.       [nz-form] {
  58.         max-width: 600px;
  59.       }
  60.     `
  61.   ]
  62. })
  63. export class NzDemoFormAutoTipsComponent {
  64.   validateForm: FormGroup;
  66.   // current locale is key of the nzAutoTips
  67.   autoTips: Record<string, Record<string, string>> = {
  68.     'zh-cn': {
  69.       required: '必填项',
  70.       email: '邮箱格式不正确'
  71.     },
  72.     en: {
  73.       required: 'Input is required',
  74.       email: 'The input is not valid email'
  75.     }
  76.   };
  78.   submitForm(value: { userName: string; email: string; password: string; confirm: string; comment: string }): void {
  79.     for (const key in this.validateForm.controls) {
  80.       this.validateForm.controls[key].markAsDirty();
  81.       this.validateForm.controls[key].updateValueAndValidity();
  82.     }
  83.     console.log(value);
  84.   }
  86.   validateConfirmPassword(): void {
  87.     setTimeout(() => this.validateForm.controls.confirm.updateValueAndValidity());
  88.   }
  90.   userNameAsyncValidator = (control: FormControl) =>
  91.     new Observable((observer: Observer<MyValidationErrors | null>) => {
  92.       setTimeout(() => {
  93.         if (control.value === 'JasonWood') {
  94.           observer.next({
  95.             duplicated: { 'zh-cn': `用户名已存在`, en: `The username is redundant!` }
  96.           });
  97.         } else {
  98.           observer.next(null);
  99.         }
  100.         observer.complete();
  101.       }, 1000);
  102.     });
  104.   confirmValidator = (control: FormControl): { [s: string]: boolean } => {
  105.     if (!control.value) {
  106.       return { error: true, required: true };
  107.     } else if (control.value !== this.validateForm.controls.password.value) {
  108.       return { confirm: true, error: true };
  109.     }
  110.     return {};
  111.   };
  113.   constructor(private fb: FormBuilder) {
  114.     // use `MyValidators`
  115.     const { required, maxLength, minLength, email, mobile } = MyValidators;
  116.     this.validateForm = this.fb.group({
  117.       userName: ['', [required, maxLength(12), minLength(6)], [this.userNameAsyncValidator]],
  118.       mobile: ['', [required, mobile]],
  119.       email: ['', [required, email]],
  120.       password: ['', [required]],
  121.       confirm: ['', [this.confirmValidator]]
  122.     });
  123.   }
  124. }
  126. // current locale is key of the MyErrorsOptions
  127. export type MyErrorsOptions = { 'zh-cn': string; en: string } & Record<string, NzSafeAny>;
  128. export type MyValidationErrors = Record<string, MyErrorsOptions>;
  130. export class MyValidators extends Validators {
  131.   static minLength(minLength: number): ValidatorFn {
  132.     return (control: AbstractControl): MyValidationErrors | null => {
  133.       if (Validators.minLength(minLength)(control) === null) {
  134.         return null;
  135.       }
  136.       return { minlength: { 'zh-cn': `最小长度为 ${minLength}`, en: `MinLength is ${minLength}` } };
  137.     };
  138.   }
  140.   static maxLength(maxLength: number): ValidatorFn {
  141.     return (control: AbstractControl): MyValidationErrors | null => {
  142.       if (Validators.maxLength(maxLength)(control) === null) {
  143.         return null;
  144.       }
  145.       return { maxlength: { 'zh-cn': `最大长度为 ${maxLength}`, en: `MaxLength is ${maxLength}` } };
  146.     };
  147.   }
  149.   static mobile(control: AbstractControl): MyValidationErrors | null {
  150.     const value = control.value;
  152.     if (isEmptyInputValue(value)) {
  153.       return null;
  154.     }
  156.     return isMobile(value) ? null : { mobile: { 'zh-cn': `手机号码格式不正确`, en: `Mobile phone number is not valid` } };
  157.   }
  158. }
  160. function isEmptyInputValue(value: NzSafeAny): boolean {
  161.   return value == null || value.length === 0;
  162. }
  164. function isMobile(value: string): boolean {
  165.   return typeof value === 'string' && /(^1\d{10}$)/.test(value);
  166. }

Form表单 - 图12

手动指定表单状态

用户可以在通过 nz-form-control 的 nzValidateStatus 属性直接设定表单的状态。

  1. nzValidateStatus: 校验状态，可选 ‘success’, ‘warning’, ‘error’, ‘validating’。
  2. nzHasFeedback：用于给输入框添加反馈图标。
  3. nzSuccessTip``nzWarningTip``nzErrorTip``nzValidatingTip：设置不同状态校验文案。
  1. import { Component } from '@angular/core';
  3. @Component({
  4.   selector: 'nz-demo-form-validate-static',
  5.   template: `
  6.     <form nz-form>
  7.       <nz-form-item>
  8.         <nz-form-label [nzSpan]="5">Fail</nz-form-label>
  9.         <nz-form-control nzValidateStatus="error" [nzSpan]="12" nzErrorTip="Should be combination of numbers & alphabets">
  10.           <input nz-input [ngModel]="'unavailable choice'" name="errorValid" />
  11.         </nz-form-control>
  12.       </nz-form-item>
  13.       <nz-form-item>
  14.         <nz-form-label [nzSpan]="5">Warning</nz-form-label>
  15.         <nz-form-control nzValidateStatus="warning" [nzSpan]="12">
  16.           <input nz-input [ngModel]="'Warning'" name="warningValid" />
  17.         </nz-form-control>
  18.       </nz-form-item>
  19.       <nz-form-item>
  20.         <nz-form-label [nzSpan]="5">Validating</nz-form-label>
  21.         <nz-form-control [nzSpan]="12" nzValidateStatus="validating" nzHasFeedback nzValidatingTip="I'm validating the content">
  22.           <input nz-input [ngModel]="'The content is being validated'" name="validating" />
  23.         </nz-form-control>
  24.       </nz-form-item>
  25.       <nz-form-item>
  26.         <nz-form-label [nzSpan]="5">Success</nz-form-label>
  27.         <nz-form-control [nzSpan]="12" nzValidateStatus="success" nzHasFeedback>
  28.           <input nz-input [ngModel]="'The content'" name="successValid" />
  29.         </nz-form-control>
  30.       </nz-form-item>
  31.       <nz-form-item>
  32.         <nz-form-label [nzSpan]="5">Warning</nz-form-label>
  33.         <nz-form-control [nzSpan]="12" nzValidateStatus="warning" nzHasFeedback nzWarningTip="Should be combination of numbers & alphabets">
  34.           <input nz-input [ngModel]="'Warning'" name="warningHighValid" />
  35.         </nz-form-control>
  36.       </nz-form-item>
  37.       <nz-form-item>
  38.         <nz-form-label [nzSpan]="5">Fail</nz-form-label>
  39.         <nz-form-control [nzSpan]="12" nzValidateStatus="error" nzHasFeedback nzErrorTip="Should be combination of numbers & alphabets">
  40.           <input nz-input [ngModel]="'unavailable choice'" name="invalidValid" />
  41.         </nz-form-control>
  42.       </nz-form-item>
  43.       <nz-form-item>
  44.         <nz-form-label [nzSpan]="5">Success</nz-form-label>
  45.         <nz-form-control [nzSpan]="12" nzValidateStatus="success" nzHasFeedback>
  46.           <nz-date-picker name="date-picker-success"></nz-date-picker>
  47.         </nz-form-control>
  48.       </nz-form-item>
  49.       <nz-form-item>
  50.         <nz-form-label [nzSpan]="5">Warning</nz-form-label>
  51.         <nz-form-control [nzSpan]="12" nzValidateStatus="warning" nzHasFeedback>
  52.           <nz-time-picker name="time-picker-warning"></nz-time-picker>
  53.         </nz-form-control>
  54.       </nz-form-item>
  55.       <nz-form-item>
  56.         <nz-form-label [nzSpan]="5">Error</nz-form-label>
  57.         <nz-form-control [nzSpan]="12" nzValidateStatus="error" nzHasFeedback>
  58.           <nz-select name="select-error" [ngModel]="'Option 1'">
  59.             <nz-option nzValue="Option 1" nzLabel="Option 1"></nz-option>
  60.             <nz-option nzValue="Option 2" nzLabel="Option 2"></nz-option>
  61.           </nz-select>
  62.         </nz-form-control>
  63.       </nz-form-item>
  64.       <nz-form-item>
  65.         <nz-form-label [nzSpan]="5">Validating</nz-form-label>
  66.         <nz-form-control [nzSpan]="12" nzValidateStatus="validating" nzHasFeedback>
  67.           <nz-select name="select-validate" [ngModel]="'Option 2'">
  68.             <nz-option nzValue="Option 1" nzLabel="Option 1"></nz-option>
  69.             <nz-option nzValue="Option 2" nzLabel="Option 2"></nz-option>
  70.           </nz-select>
  71.         </nz-form-control>
  72.       </nz-form-item>
  73.       <nz-form-item>
  74.         <nz-form-label [nzSpan]="5">Success</nz-form-label>
  75.         <nz-form-control [nzSpan]="12" nzValidateStatus="success" nzHasFeedback>
  76.           <nz-input-number name="inputnumber-success" style="width:100%"></nz-input-number>
  77.         </nz-form-control>
  78.       </nz-form-item>
  79.     </form>
  80.   `,
  81.   styles: [
  82.     `
  83.       [nz-form] {
  84.         max-width: 600px;
  85.       }
  87.       nz-date-picker ::ng-deep .ant-calendar-picker {
  88.         width: 100%;
  89.       }
  91.       nz-date-picker,
  92.       nz-time-picker {
  93.         width: 100%;
  94.       }
  95.     `
  96.   ]
  97. })
  98. export class NzDemoFormValidateStaticComponent {}

Form表单 - 图13

表单联动

使用 setValue 来动态设置其他控件的值。

  1. import { Component, OnInit } from '@angular/core';
  2. import { FormBuilder, FormGroup, Validators } from '@angular/forms';
  4. @Component({
  5.   selector: 'nz-demo-form-coordinated',
  6.   template: `
  7.     <form nz-form [formGroup]="validateForm" (ngSubmit)="submitForm()">
  8.       <nz-form-item>
  9.         <nz-form-label [nzSpan]="5" nzRequired nzFor="note">Note</nz-form-label>
  10.         <nz-form-control [nzSpan]="12" nzErrorTip="Please input your username!">
  11.           <input id="note" type="text" nz-input formControlName="note" />
  12.         </nz-form-control>
  13.       </nz-form-item>
  14.       <nz-form-item>
  15.         <nz-form-label [nzSpan]="5" nzFor="gender" nzRequired>Gender</nz-form-label>
  16.         <nz-form-control [nzSpan]="12" nzErrorTip="Please select your gender!">
  17.           <nz-select
  18.             id="gender"
  19.             formControlName="gender"
  20.             nzPlaceHolder="Select a option and change input text above"
  21.             (ngModelChange)="genderChange($event)"
  22.           >
  23.             <nz-option nzValue="male" nzLabel="male"></nz-option>
  24.             <nz-option nzValue="female" nzLabel="female"></nz-option>
  25.           </nz-select>
  26.         </nz-form-control>
  27.       </nz-form-item>
  28.       <nz-form-item>
  29.         <nz-form-control [nzSpan]="12" [nzOffset]="5">
  30.           <button nz-button nzType="primary">Submit</button>
  31.         </nz-form-control>
  32.       </nz-form-item>
  33.     </form>
  34.   `,
  35.   styles: [
  36.     `
  37.       [nz-form] {
  38.         max-width: 600px;
  39.       }
  40.     `
  41.   ]
  42. })
  43. export class NzDemoFormCoordinatedComponent implements OnInit {
  44.   validateForm!: FormGroup;
  46.   submitForm(): void {
  47.     for (const i in this.validateForm.controls) {
  48.       this.validateForm.controls[i].markAsDirty();
  49.       this.validateForm.controls[i].updateValueAndValidity();
  50.     }
  51.   }
  53.   genderChange(value: string): void {
  54.     this.validateForm.get('note')!.setValue(value === 'male' ? 'Hi, man!' : 'Hi, lady!');
  55.   }
  57.   constructor(private fb: FormBuilder) {}
  59.   ngOnInit(): void {
  60.     this.validateForm = this.fb.group({
  61.       note: [null, [Validators.required]],
  62.       gender: [null, [Validators.required]]
  63.     });
  64.   }
  65. }

Form表单 - 图14

表单布局

表单有三种布局。

  1. import { Component, OnInit } from '@angular/core';
  2. import { FormBuilder, FormGroup, Validators } from '@angular/forms';
  4. @Component({
  5.   selector: 'nz-demo-form-layout',
  6.   template: `
  7.     <form nz-form [nzLayout]="validateForm.get('formLayout')?.value" [formGroup]="validateForm" (ngSubmit)="submitForm()">
  8.       <nz-form-item>
  9.         <nz-form-label [nzSpan]="isHorizontal ? 4 : null">Form Layout</nz-form-label>
  10.         <nz-form-control [nzSpan]="isHorizontal ? 14 : null">
  11.           <nz-radio-group formControlName="formLayout">
  12.             <label nz-radio-button [nzValue]="'horizontal'">Horizontal</label>
  13.             <label nz-radio-button [nzValue]="'vertical'">Vertical</label>
  14.             <label nz-radio-button [nzValue]="'inline'">Inline</label>
  15.           </nz-radio-group>
  16.         </nz-form-control>
  17.       </nz-form-item>
  18.       <nz-form-item>
  19.         <nz-form-label [nzSpan]="isHorizontal ? 4 : null">Field A</nz-form-label>
  20.         <nz-form-control [nzSpan]="isHorizontal ? 14 : null" nzErrorTip="Please input your username!">
  21.           <input nz-input formControlName="fieldA" placeholder="input placeholder" />
  22.         </nz-form-control>
  23.       </nz-form-item>
  24.       <nz-form-item>
  25.         <nz-form-label [nzSpan]="isHorizontal ? 4 : null">Field B</nz-form-label>
  26.         <nz-form-control [nzSpan]="isHorizontal ? 14 : null" nzErrorTip="Please input your Password!">
  27.           <input nz-input formControlName="filedB" placeholder="input placeholder" />
  28.         </nz-form-control>
  29.       </nz-form-item>
  30.       <nz-form-item>
  31.         <nz-form-control [nzSpan]="isHorizontal ? 14 : null" [nzOffset]="isHorizontal ? 4 : null">
  32.           <button nz-button nzType="primary">Submit</button>
  33.         </nz-form-control>
  34.       </nz-form-item>
  35.     </form>
  36.   `,
  37.   styles: [
  38.     `
  39.       [nz-form]:not(.ant-form-inline):not(.ant-form-vertical) {
  40.         max-width: 600px;
  41.       }
  42.     `
  43.   ]
  44. })
  45. export class NzDemoFormLayoutComponent implements OnInit {
  46.   validateForm!: FormGroup;
  48.   submitForm(): void {
  49.     for (const i in this.validateForm.controls) {
  50.       this.validateForm.controls[i].markAsDirty();
  51.       this.validateForm.controls[i].updateValueAndValidity();
  52.     }
  53.   }
  55.   get isHorizontal(): boolean {
  56.     return this.validateForm.controls.formLayout?.value === 'horizontal';
  57.   }
  59.   constructor(private fb: FormBuilder) {}
  61.   ngOnInit(): void {
  62.     this.validateForm = this.fb.group({
  63.       formLayout: ['horizontal'],
  64.       fieldA: [null, [Validators.required]],
  65.       filedB: [null, [Validators.required]]
  66.     });
  67.   }
  68. }

Form表单 - 图15

动态校验规则

根据不同情况执行不同的校验规则。

  1. import { Component, OnInit } from '@angular/core';
  2. import { FormBuilder, FormGroup, Validators } from '@angular/forms';
  4. @Component({
  5.   selector: 'nz-demo-form-dynamic-rule',
  6.   template: `
  7.     <form nz-form [formGroup]="validateForm" (ngSubmit)="submitForm()">
  8.       <nz-form-item>
  9.         <nz-form-label [nzSpan]="4" nzRequired nzFor="name">Name</nz-form-label>
  10.         <nz-form-control [nzSpan]="8" nzErrorTip="Please input your name">
  11.           <input type="text" nz-input formControlName="name" placeholder="Please input your name" />
  12.         </nz-form-control>
  13.       </nz-form-item>
  14.       <nz-form-item>
  15.         <nz-form-label [nzSpan]="4" nzFor="nickname" [nzRequired]="validateForm.get('required')?.value">Nickname</nz-form-label>
  16.         <nz-form-control [nzSpan]="8" nzErrorTip="Please input your nickname">
  17.           <input type="text" nz-input formControlName="nickname" placeholder="Please input your nickname" />
  18.         </nz-form-control>
  19.       </nz-form-item>
  20.       <nz-form-item>
  21.         <nz-form-control [nzSpan]="8" [nzOffset]="4">
  22.           <label nz-checkbox formControlName="required" (ngModelChange)="requiredChange($event)">Nickname is required</label>
  23.         </nz-form-control>
  24.       </nz-form-item>
  25.       <nz-form-item>
  26.         <nz-form-control [nzSpan]="8" [nzOffset]="4">
  27.           <button nz-button nzType="primary">Check</button>
  28.         </nz-form-control>
  29.       </nz-form-item>
  30.     </form>
  31.   `
  32. })
  33. export class NzDemoFormDynamicRuleComponent implements OnInit {
  34.   validateForm!: FormGroup;
  36.   submitForm(): void {
  37.     for (const i in this.validateForm.controls) {
  38.       this.validateForm.controls[i].markAsDirty();
  39.       this.validateForm.controls[i].updateValueAndValidity();
  40.     }
  41.   }
  43.   requiredChange(required: boolean): void {
  44.     if (!required) {
  45.       this.validateForm.get('nickname')!.clearValidators();
  46.       this.validateForm.get('nickname')!.markAsPristine();
  47.     } else {
  48.       this.validateForm.get('nickname')!.setValidators(Validators.required);
  49.       this.validateForm.get('nickname')!.markAsDirty();
  50.     }
  51.     this.validateForm.get('nickname')!.updateValueAndValidity();
  52.   }
  54.   constructor(private fb: FormBuilder) {}
  56.   ngOnInit(): void {
  57.     this.validateForm = this.fb.group({
  58.       name: [null, [Validators.required]],
  59.       nickname: [null],
  60.       required: [false]
  61.     });
  62.   }
  63. }

API

[nz-form]directive

参数说明类型默认值全局配置
[nzLayout]表单布局‘horizontal’ | ‘vertical’ | ‘inline’‘horizontal’
[nzNoColon]配置 nz-form-label 的 [nzNoColon] 的默认值booleanfalse✅
[nzAutoTips]配置 nz-form-control 的 [nzAutoTips] 的默认值, 具体用法请参考示例：自动提示Record<string, Record<string, string>>{}✅
[nzDisableAutoTips]配置 nz-form-control 的 [nzDisableAutoTips] 的默认值booleanfalse✅

nz-form-itemcomponent

表单项用于区分表单中不同的区域，包含表单域和表单标签(可选)。

所有 nz-row 的参数在 nz-form-item 上均可直接使用。

nz-form-labelcomponent

用于标示当前表单项的内容，可选。

所有 nz-col 的参数在 nz-form-label 上均可直接使用。

参数说明类型默认值
[nzRequired]当前项是否为必填，仅影响样式booleanfalse
[nzNoColon]是否不显示 label 后面的冒号booleanfalse
[nzFor]label 标签的 for 属性string-

nz-form-controlcomponent

注意：由于 Angular Form 目前提供的状态变更订阅不完整。手动更改表单状态时，例如 markAsDirty 后，需要执行 updateValueAndValidity 通知 nz-form-control 进行状态变更。

表单一定会包含表单域，表单域可以是输入控件，标准表单域，标签，下拉菜单，文本域等。

所有 nz-col 的参数在 nz-form-control 上均可直接使用。

参数说明类型默认值
[nzValidateStatus]会根据传入的 FormControl 或 NgModel 自动生成校验状态，也可以直接指定状态，不传入时默认值为 nz-form-control 中包裹的第一个 FormControl 或 NgModel‘success’ | ‘warning’ | ‘error’ | ‘validating’ | FormControl | NgModelnz-form-control 中包裹的第一个 FormControl 或 NgModel
[nzHasFeedback]配合 nzValidateStatus 属性使用，展示校验状态图标booleanfalse
[nzExtra]用于显示表单额外提示信息string | TemplateRef<void>-
[nzSuccessTip]校验状态 success 时提示信息string | TemplateRef<{ $implicit: FormControl | NgModel }>-
[nzWarningTip]校验状态 warning 时提示信息string | TemplateRef<{ $implicit: FormControl | NgModel }>-
[nzErrorTip]校验状态 error 时提示信息string | TemplateRef<{ $implicit: FormControl | NgModel }>-
[nzValidatingTip]正在校验时提示信息string | TemplateRef<{ $implicit: FormControl | NgModel }>-
[nzAutoTips]配置提示的对象, 具体用法请参考示例：自动提示Record<string, Record<string, string>>--
[nzDisableAutoTips]禁用自动提示boolean--

nz-form-splitcomponent

用于显示分隔符 -

nz-form-textcomponent

在 nz-form-control 中直接显示文本