Form表单

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

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

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

表单#

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

  • 水平排列:标签和表单控件水平排列;(默认)
  • 垂直排列:标签和表单控件上下垂直排列;
  • 行内排列:表单项水平行内排列。

表单项 nz-form-item#

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

表单标签 nz-form-label#

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

表单域 nz-form-control#

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

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

代码演示

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

expand codeexpand code
      加载中
    

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

expand codeexpand code
      加载中
    
+86
We must make sure that your are a human.

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

expand codeexpand code
      加载中
    

动态增加、减少表单项。

expand codeexpand code
      加载中
    

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

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

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

expand codeexpand code
      加载中
    

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

  1. nzHasFeedback:用于给输入框添加反馈图标。
  2. nzSuccessTipnzWarningTipnzErrorTipnzValidatingTip:设置不同状态校验文案。

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

expand codeexpand code
      加载中
    

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

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

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

使用当前的语言环境(zh-cn,en...)作为 nzAutoTipskey 去查找提示,如果没找到会再用 default 查找一次。

expand codeexpand code
      加载中
    
Option 1
Option 2

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

  1. nzValidateStatus: 校验状态,可选 'success', 'warning', 'error', 'validating'。
  2. nzHasFeedback:用于给输入框添加反馈图标。
  3. nzSuccessTipnzWarningTipnzErrorTipnzValidatingTip:设置不同状态校验文案。
expand codeexpand code
      加载中
    
Select a option and change input text above

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

expand codeexpand code
      加载中
    

表单有三种布局。

expand codeexpand code
      加载中
    

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

expand codeexpand code
      加载中
    

使用 nzLabelWrap 可以开启 label 换行。

expand codeexpand code
      加载中
    

表单标签文本对齐方式。

expand codeexpand code
      加载中
    

API#

[nz-form]#

参数说明类型默认值全局配置
[nzLayout]表单布局'horizontal' | 'vertical' | 'inline''horizontal'
[nzAutoTips]配置 nz-form-control[nzAutoTips] 的默认值, 具体用法请参考示例:自动提示Record<string, Record<string, string>>{}
[nzDisableAutoTips]配置 nz-form-control[nzDisableAutoTips] 的默认值booleanfalse
[nzNoColon]配置 nz-form-label[nzNoColon] 的默认值booleanfalse
[nzTooltipIcon]配置 nz-form-label[nzTooltipIcon] 的默认值string | { type: string; theme: ThemeType }{ type: 'question-circle', theme: 'outline' }
[nzLabelAlign]配置 nz-form-label[nzLabelAlign] 的默认值'left' | 'right''right'
[nzLabelWrap]配置 nz-form-label[nzLabelWrap] 的默认值booleanfalse

nz-form-item#

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

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

nz-form-label#

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

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

参数说明类型默认值
[nzRequired]当前项是否为必填,仅影响样式booleanfalse
[nzNoColon]是否不显示 label 后面的冒号booleanfalse
[nzFor]label 标签的 for 属性string-
[nzTooltipTitle]配置提示信息string | TemplateRef<void>-
[nzTooltipIcon]配置提示信息的图标string | NzFormTooltipIcon-
[nzLabelAlign]标签文本对齐方式'left' | 'right''right'
[nzLabelWrap]label 标签的文本换行方式booleanfalse

nz-form-control#

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

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

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

参数说明类型默认值
[nzValidateStatus]会根据传入的 FormControlNgModel 自动生成校验状态,也可以直接指定状态,不传入时默认值为 nz-form-control 中包裹的第一个 FormControlNgModel'success' | 'warning' | 'error' | 'validating' | FormControl | NgModelnz-form-control 中包裹的第一个 FormControlNgModel
[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-split#

用于显示分隔符 -

nz-form-text#

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