Form field

Form field

[toc]

概述

OVERVIEW

<mat-form-field>是封装了一些Angular Material组件并应用了常见文本字段样式(例如下划线,浮动标签,提示信息等)的组件。

<mat-form-field> is a component used to wrap several Angular Material components and apply common Text field styles such as the underline, floating label, and hint messages.

在此文档中,“表单字段”代表封装组件<mat-form-field>,“表单字段控制”代表<mat-form-field>封装的组件(例如input,textarea,select等等)。

In this document, “form field” refers to the wrapper component <mat-form-field> and “form field control” refers to the component that the <mat-form-field> is wrapping (e.g. the input, textarea, select, etc.)

以下Angular Material组件可用于<mat-form-field>中:

The following Angular Material components are designed to work inside a <mat-form-field>:

浮动占位符

Floating placeholder

占位符是当表单字段控制没有文本时,在其上方展示的文本标签。当有文本时,默认浮动占位符的文本将浮在表单字段控制的上方。

The floating placeholder is a text label displayed on top of the form field control when the control does not contain any text. By default, when text is present the floating placeholder floats above the form field control.

输入框的占位符有两种设置方法:在表单字段控制中使用placeholder属性,或者在表单字段中使用<mat-placeholder>元素。两种方法只能用其一,同时使用将会导致错误。

Placeholder text can be specified using the placeholder property on the form field control, or by adding a <mat-placeholder> element inside the form field. Only one of these options should be used, specifying both will raise an error.

如果表单字段控制标记了一个required属性,占位符将会有一个星号,表示这是一个必须的字段。如果不想显示,可以在<mat-form-field>中设置hideRequiredMarker属性来关闭此功能。

If the form field control is marked with a required attribute, an asterisk will be appended to the placeholder to indicate the fact that it is a required field. If unwanted, this can be disabled by setting the hideRequiredMarker property on <mat-form-field>

<mat-form-field>floatPlaceholder属性可用来改变默认浮动的行为。设置为never可隐藏占位符,设置为always表示在表的那字段控制中没有文本的时候也浮动占位符,设置为auto则为默认行为。

The floatPlaceholder property of <mat-form-field> can be used to change this default floating behavior. It can set to never to hide the placeholder instead of float it when text is present in the form field control. It can be set to always to float the placeholder even when no text is present in the form field control. It can also be set to auto to restore the default behavior.

可以在你应用的root module中,设置MAT_PLACEHOLDER_GLOBAL_OPTIONS来全局设置占位符的全局设置。同样可取值为always, neverauto

Global default placeholder options can be specified by setting providing a value for MAT_PLACEHOLDER_GLOBAL_OPTIONS in your application’s root module. Like the property, the global setting can be either always, never, or auto.

@NgModule({
  providers: [
    {provide: MAT_PLACEHOLDER_GLOBAL_OPTIONS, useValue: {float: 'always'}}
  ]
})

提示标签

Hint labels

提示标签是显示在表单字段下的一个附加提示文本。一个<mat-form-field>最多可以有两个提示标签;一个在起始位置(在左边则为LTR,右边为RTL),一个在终止位置。

Hint labels are additional descriptive text that appears below the form field’s underline. A <mat-form-field> can have up to two hint labels; one start-aligned (left in an LTR language, right in RTL), and one end-aligned.

有两种方式设置提示标签:使用<mat-form-field>hintLabel属性,或在表单字段中增加<mat-hint>元素。当通过hintLabel属性增加提示时,默认为是起始位置的提示。通过<mat-hint>提示元素增加的提示,可以通过设置<mat-hint>中的align属性为startend,来设置提示的位置。在同一侧设置多个提示将会导致错误。

Hint labels are specified in one of two ways: either by using the hintLabel property of <mat-form-field>, or by adding a <mat-hint> element inside the form field. When adding a hint via the hintLabel property, it will be treated as the start hint. Hints added via the <mat-hint> hint element can be added to either side by setting the align property on <mat-hint> to either start or end. Attempting to add multiple hints to the same side will raise an error.

错误信息

Error messages

在表单字段中增加mat-error元素,可以在表单字段下方显示错误信息。错误信息默认不显示,当用户与元素有交互后或者父表单提交后,存在非法表单字段的情况下,将展示错误信息。如果错误信息与提示出现在相同位置,错误显示时,提示信息将会隐藏。

Error messages can be shown under the form field underline by adding mat-error elements inside the form field. Errors are hidden initially and will be displayed on invalid form fields after the user has interacted with the element or the parent form has been submitted. Since the errors occupy the same space as the hints, the hints are hidden when the errors are shown.

如果一个表单字段有多个错误状态,则由其消费者决定显示哪个错误信息。可使用CSS,ngIf或ngSwitch来解决。多个错误信息可以同时展示,但<mat-form-field>一次只提供展示一条错误信息的空间。需要用户来确保有足够的控件显示多个错误信息。

If a form field can have more than one error state, it is up to the consumer to toggle which messages should be displayed. This can be done with CSS, ngIf or ngSwitch. Multiple error messages can be shown at the same time if desired, but the <mat-form-field> only reserves enough space to display one error message at a time. Ensuring that enough space is available to display multiple errors is up to the user.

前缀与后缀

Prefix & suffix

自定义内容可以在输入框tag的前面或后面,即作为前缀或后缀。将作为Material的说明包含在封装表单控制的可视化容器中。

Custom content can be included before and after the input tag, as a prefix or suffix. It will be included within the visual container that wraps the form control as per the Material specification.

<mat-form-field>中的一个元素中添加matPrefix指令,指定其为前缀。相似的,用matSuffix指定后缀。

Adding the matPrefix directive to an element inside the <mat-form-field> will designate it as the prefix. Similarly, adding matSuffix will designate it as the suffix.

自定义表单字段控制

Custom form field controls

除了Angular Material提供的表单字段控制外,也可以创建自定义的表单字段控制,同样适用于<mat-form-field>。可查看创建自定义mat-form-field控制获取更多信息。

In addition to the form field controls that Angular Material provides, it is possible to create custom form field controls that work with <mat-form-field> in the same way. For additional information on this see the guide on Creating Custom mat-form-field Controls.

主题

Theming

<mat-form-field>color属性可以设置为primary, accent或者warn。通过设置可以基于应用的主题颜色来改变表单字段下划线和浮动占位符的颜色。

<mat-form-field> has a color property which can be set to primary, accent, or warn. This will set the color of the form field underline and floating placeholder based on the theme colors of your app.

<mat-form-field>继承父元素的font-size。可以使用CSS设置一个具体的值来复写它。建议至少一个元素+一个类。

<mat-form-field> inherits its font-size from its parent element. This can be overridden to an explicit size using CSS. We recommend a specificity of at least 1 element + 1 class.

mat-form-field.mat-form-field {
  font-size: 16px;
}

无障碍

Accessibility

如果指定了一个浮动占位符,将自动使用其作为表单字段控制的标签。如果没有指定,使用者需要使用aria-label, aria-labelledby或者<label for=...>来指定表单字段控制的标签。

If a floating placeholder is specified, it will be automatically used as the label for the form field control. If no floating placeholder is specified, the user should label the form field control themselves using aria-label, aria-labelledby or <label for=...>.

任何在表单字段中添加的错误或者提示将自动添加进表单字段控制的aria-describedby集合。

Any errors and hints added to the form field are automatically added to the form field control’s aria-describedby set.

错误定位

Troubleshooting

Error: Placeholder attribute and child element were both specified

如果你指定了两个冲突的占位符,将会导致这个错误。确定你在表单字段控制中没有同时引入placeholder属性和<mat-placeholder>元素。

This error occurs when you have specified two conflicting placeholders. Make sure that you haven’t included both a placeholder property on your form field control and a <mat-placeholder> element.

Error: A hint was already declared for align=”…”

如果在同一位置添加了多个提示,将会导致此错误。记住使用hintLabel属性会在起始端增加提示。

This error occurs if you have added multiple hints for the same side. Keep in mind that the hintLabel property adds a hint to the start side.

Error: mat-form-field must contain a MatFormFieldControl

当没有在表单字段中添加表单字段控制时,将会出现这个错误。如果表单字段中包含原生的<input>或者<textarea>元素,确定你在其中添加了matInput指令。其他包含如<mat-select>, <mat-chip-list>组件,或者你创建的自定义表单字段控制,都可作为表单字段控制。

This error occurs when you have not added a form field control to your form field. If your form field contains a native <input> or <textarea> element, make sure you’ve added the matInput directive to it. Other components that can act as a form field control include <mat-select>, <mat-chip-list>, and any custom form field controls you’ve created.

API

表单字段(form-field)的API参考

API reference for Angular Material form-field

import {MatFormFieldModule} from '@angular/material/form-field';

指令

Directives

MatError

在表单字段下方显示的单个错误信息

Single error message to be shown underneath the form field.

Selector: mat-error

属性

Properties

属性名 描述 Description
@Input()
id: string

MatFormField

包含应用了Material Design样式与行为的表单控制的容器。

Container for form controls that applies Material Design styling and behavior.

Selector: mat-input-container mat-form-field

Exported as: matFormField

属性

Properties

属性名 描述 Description
@Input()
color: ‘primary’ | ‘accent’ | ‘warn’
基于主题的表单字段下划线颜色。 Color of the form field underline, based on the theme.
@Input()
floatPlaceholder: FloatPlaceholderType
设置占位符是一直展示、从不展示、或者按用户类型展示。 Whether the placeholder should always float, never float or float as the user types.
@Input()
hideRequiredMarker: any
必需的标记是否隐藏。 Whether the required marker should be hidden.
@Input()
hintLabel: string
表单字段提示的文字。 Text for the form field hint.
underlineRef: ElementRef 表单字段的下划线元素的参考。 Reference to the form field’s underline element.
@Input()
Deprecated
dividerColor: ‘primary’ | ‘accent’ | ‘warn’

MatHint

表单字段控制下方的提示文字。

Hint text to be shown underneath the form field control.

Selector: mat-hint

属性

Properties

属性名 描述 Description
@Input()
align: ‘start’ | ‘end’
在线的开始还是末尾显示提示标签。 Whether to align the hint label at the start or end of the line.
@Input()
id: string
提示的唯一id。提供给表单字段控制的aria-describedby使用。 Unique ID for the hint. Used for the aria-describedby on the form field control.

MatPlaceholder

MatFormField的浮动占位符。

The floating placeholder for an MatFormField.

Selector: mat-placeholder

MatPrefix

表单字段前的前缀

Prefix to be placed the the front of the form field.

Selector: [matPrefix]

MatSuffix

表单字段后的后缀

Suffix to be placed at the end of the form field.

Selector: [matSuffix]

附件类

Additional classes

MatFormFieldControl

允许在MatFormField引入一个控制的接口。

An interface which allows a control to work inside of a MatFormField.

属性

Properties

属性名 描述 Description
controlType: string 控制类型的一个备选名称,用于基于控制类型来区分mat-form-field元素。表单控制将添加一个mat-form-field-type-{{controlType}}类到其根元素中。 An optional name for the control type that can be used to distinguish mat-form-field elements based on their control type. The form field will add a class, mat-form-field-type-{{controlType}} to its root element.
disabled: boolean 控制是否失效。 Whether the control is disabled.
empty: boolean 控制是否为空。 Whether the control is empty.
errorState: boolean 控制是否在一个错误状态。 Whether the control is in an error state.
focused: boolean 控制是否获得焦点。 Whether the control is focused.
id: string 控制的元素ID。 The element ID for this control.
ngControl: NgControl | null 获取控制的NgControl。 Gets the NgControl for this control.
placeholder: string 控制的占位符。 The placeholder for this control.
required: boolean 控制是否必须。 Whether the control is required.
shouldPlaceholderFloat: boolean MatFormField标签是否应为浮点型。 Whether the MatFormField label should try to float.
stateChanges: Observable 当控制改变状态时(例如父MatFormField须要检测此改变)传递的流。 Stream that emits whenever the state of the control changes such that the parent MatFormField needs to run change detection.
value: T | null 控制的value值。 The value of the control.

方法

Methods

方法名 参数 描述 Description
onContainerClick event: MouseEvent 处理一个在控制容器上的点击。 Handles a click on the control’s container.
setDescribedByIds ids: string[] 设置描述当前控制的元素ID列表。 Sets the list of element IDs that currently describe this control.

翻译部分版权归YahaCode团队所有。仅供学习研究之用,任何组织或个人不得私自以此用于任何形式的商业目的

你可能还想看看下面的内容?

发表评论