<mat-form-field> 是一个组件,用于把几个 Angular Material 组件包装在一起,并应用上常见的文本输入框样式,比如下划线、浮动标签和提示信息。

该文档中,"表单字段"(form field)是指包装组件 <mat-form-field>,而 "表单字段控件"(form field control)是指被 <mat-form-field> 包装的组件(如文本框、多行文本框、选择框等)。

在设计上,下列 Angular Material 组件可用在 <mat-form-field> 中:

mat-form-field 支持两种不同的外观变体,可以通过输入属性 appearance 进行设置:filloutlinefill 外观显示的表单字段除了下划线之外还带有填充的背景。 outline 外观会显示一个带四周边框的表单字段,而不仅有下划线。

开箱即用的情况下,如果你没有为 <mat-form-field> 指定 appearance,它将默认为 legacy。但是,这可以使用全局的提供者进行配置,为你的应用程序选择不同的默认外观。

@NgModule({
  providers: [
    {provide: MAT_FORM_FIELD_DEFAULT_OPTIONS, useValue: {appearance: 'outline'}}
  ]
})

当控件不包含任何文本时,显示在表单字段控件顶部的那个文本标签就叫做浮动标签。 默认情况下,如果存在文本,则浮动标签将显示在表单字段控件的上方。 可以通过添加 mat-label 元素来为表单字段指定浮动标签。

如果表单字段控件带有 required 属性,则该标签会带有一个星号后缀,以表明该字段是必填的。 如果不希望显示星号,则可以通过为 <mat-form-field> 添加 hideRequiredMarker 属性来禁止显示它。

<mat-form-field>floatLabel 属性可以用来修改默认的浮动行为。它可以设置为 never,以便当表单字段控件中有文本时隐藏该标签,而不是浮起它。也可以设置为 always,以便当表单字段控件中没有文本时也仍然浮起该标签。 它也可以设置为 auto 来恢复默认行为。

浮动标签的行为可以通过在应用的根模块中通过注入令牌 MAT_LABEL_GLOBAL_OPTIONS 进行全局性调整。 就像 floatLabel 输入框一样,该选项可以设为 alwaysneverauto 之一。

@NgModule({
  providers: [
    {provide: MAT_FORM_FIELD_DEFAULT_OPTIONS, useValue: {floatLabel: 'always'}}
  ]
})

提示标签是显示在表单字段下划线下方的额外的描述性文本。<mat-form-field> 最多能有两个提示标签: 一个向开始处对齐(LTR 语言下向左,RTL 语言下向右 —— 如阿拉伯语),一个向末尾处对齐。

提示标签可以用两种方式指定:<mat-form-field>hintLabel 属性或在表单字段中添加一个 <mat-hint> 元素。 当通过 hintLabel 属性添加提示时,它会被视为开始提示。通过 <mat-hint> 元素添加提示时,可以把它的 align 属性设置为 startend 来控制放在哪一侧。试图往同一侧添加多个提示将会引发错误。

通过往表单字段中添加 mat-error 元素,就可以在表单字段的下划线下方显示错误信息。 错误信息最初是隐藏的,在用户与元素进行过交互或提交了父表单后,无效表单字段上的错误信息就会显示出来。 由于错误信息和提示信息占用相同的空间,因此在显示错误时就会隐藏提示。

如果表单字段可以有多个错误状态,则由使用者来切换应该显示哪些消息。这可以通过 CSS、 @if@switch 来完成。如果需要,可以同时显示多个错误消息,但 <mat-form-field> 每次只保留足够的空间来显示一条错误消息。确保有足够的空间来显示多个错误由用户负责。

自定义内容可以作为前缀或后缀加在输入框标记之前或之后。根据 Material 规范,它要位于包裹着表单控件的视觉容器内部。

matPrefix 指令添加到 <mat-form-field> 内的某个元素上就会把该元素用作前缀,而 matSuffix 会把它用作后缀。

如果前缀/后缀的内容是完全基于文本的,建议使用 matTextPrefixmatTextSuffix 指令,它们可以确保此文本与表单控件对齐。

除了 Angular Material 提供的表单字段控件之外,也同样可以创建能和 <mat-form-field> 协同工作的自定义表单字段控件。 欲知详情,参见创建自定义 mat-form-field 控件

<mat-form-field> 有一个 color 属性,它可以设置为 primaryaccentwarn。 这将会根据应用的主题颜色来设置表单字段的下划线和浮动标签的颜色。

就其本身而言, MatFormField 不会对控件应用任何额外的无障碍性处理。但是,表单字段的一些可选特性会与表单字段中包含的控件交互。

当你通过 <mat-label> 提供标签时, MatFormField 会通过原生 <label> 元素自动将此标签与字段的控件相关联,使用 for 属性来引用控件的 ID。

如果指定了浮动标签,它就会自动用作表单字段控件的标签。如果没有指定浮动标签,用户就应该使用 aria-labelaria-labelledby<label for=...> 来给表单字段控件提供标签。

当你通过 <mat-hint><mat-error> 来提供信息文本时, MatFormField 会自动将这些元素的 ID 添加到控件的 aria-describedby 属性中。此外, MatError 会应用 aria-live="polite" ,这样辅助技术就会在错误出现时播报这些错误。

该错误会在你往同一侧添加了多个提示信息时出现。记住,hintLabel 属性会在开始侧添加一个提示信息。

该错误会在你没有往表单字段中添加过表单字段控件时出现。如果你的表单字段包含了原生的 <input><textarea> 元素, 请确保你往它们上添加过 matInput 指令,并且导入过 MatInputModule。 可以充当表单字段控件的其它组件包括 <mat-select><mat-chip-list> 以及你创建的任何自定义表单字段控件。