表单字段 Form field

form-field 的 API

Angular Material form-field API 参考文档

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

要在表单字段下方显示的单个错误消息。

Single error message to be shown underneath the form field.

选择器: mat-error
属性
名称 描述
@Input()

id: string

表单控件的容器,用来应用 Material Design 的样式和行为。

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

选择器: mat-form-field
导出为: matFormField
属性
名称 描述
@Input()

appearance: MatFormFieldAppearance

表单字段的外观样式。

The form-field appearance style.

@Input()

color: ThemePalette

Theme color palette for the component.

@Input()

floatLabel: FloatLabelType

标签是否应该始终是浮动的、永远不会浮动或根据用户的输入浮动。

Whether the label should always float, never float or float as the user types.

注意:只有旧版外观支持 never 选项。 never 原本添加为让浮动标签模仿标准输入占位符行为的方法。但是,表单字段现在同时支持浮动标签和占位符。因此,在非遗留应用的外观中,只为了作为占位符使用的 never 选项已被禁用。

Note: only the legacy appearance supports the never option. never was originally added as a way to make the floating label emulate the behavior of a standard input placeholder. However the form field now supports both floating labels and placeholders. Therefore in the non-legacy appearances the never option has been disabled in favor of just using the placeholder.

@Input()

hideRequiredMarker: boolean

是否应隐藏必填项标记。

Whether the required marker should be hidden.

@Input()

hintLabel: string

表单字段提示的文本。

Text for the form field hint.

defaultColor: ThemePalette | undefined

Default color to fall back to if no value is set.

已弃用

underlineRef: ElementRef

方法
getConnectedOverlayOrigin

获取一个 ElementRef 元素,它为附加到表单字段上的浮层提供相对于该元素定位。

Gets an ElementRef for the element that a overlay attached to the form-field should be positioned relative to.

返回值

Returns

ElementRef
getLabelId

获取 label 元素的 id。如果没有 label,则返回 null

Gets the id of the label element. If no label is present, returns null.

返回值

Returns

string | null
updateOutlineGap

更新轮廓中间隙的宽度和位置。只与轮廓外观有关。

Updates the width and position of the gap in the outline. Only relevant for the outline appearance.

提示文本显示在表单字段控件的下方。

Hint text to be shown underneath the form field control.

选择器: mat-hint
属性
名称 描述
@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.

MatFormField 的占位符文本。

The placeholder text for an MatFormField.

选择器: mat-placeholder
已弃用

要放在表单字段前面的前缀。

Prefix to be placed in front of the form field.

选择器: [matPrefix]

后缀放在表单字段的末尾。

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

选择器: [matSuffix]

mat-form-field 的浮动标签。

The floating label for a mat-form-field.

选择器: mat-label

本接口允许控件工作在 MatFormField 中。

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

属性
名称 描述

autofilled: boolean

本输入框当前是否处于自动填充状态。如果控件上没有此属性,则认为它是 false。

Whether the input is currently in an autofilled state. If property is not present on the control it is assumed to be false.

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.

shouldLabelFloat: boolean

MatFormField 标签是否应该尝试浮动。

Whether the MatFormField label should try to float.

stateChanges: Observable<void>

每当控件的状态发生变化时就会发出的流,这样一来父 MatFormField 就要运行变更检测。

Stream that emits whenever the state of the control changes such that the parent MatFormField needs to run change detection.

userAriaDescribedBy: string

aria-describedby 的值应该和由 form-field 所设置的各个 described-by id 合并。

Value of aria-describedby that should be merged with the described-by ids which are set by the form-field.

value: T | null

控件的值。

The value of the control.

方法
onContainerClick

处理此控件的容器上的点击事件。

Handles a click on the control's container.

参数

Parameters

event

MouseEvent
setDescribedByIds

设置当前描述该控件的元素 ID 列表。

Sets the list of element IDs that currently describe this control.

参数

Parameters

ids

string[]

表示可通过 MAT_FORM_FIELD_DEFAULT_OPTIONS 令牌配置的表单字段的默认选项。

Represents the default options for the form field that can be configured using the MAT_FORM_FIELD_DEFAULT_OPTIONS injection token.

属性
名称 描述

appearance: MatFormFieldAppearance

floatLabel: FloatLabelType

表单字段的标签默认应该是 alwaysnever 还是 auto(只在必要时)。

Whether the label for form-fields should by default float always, never, or auto (only when necessary).

hideRequiredMarker: boolean

表单字段可能的外观样式。

Possible appearance styles for the form field.

type MatFormFieldAppearance = 'legacy' | 'standard' | 'fill' | 'outline';

表单字段输入属性 “floatLabel” 的可用值。

Possible values for the "floatLabel" form-field input.

type FloatLabelType = 'always' | 'never' | 'auto';

这个注入令牌可以用来引用 MatError 实例。它可以作为实际 MatError 类的备用令牌,直接使用实际类可能导致该类及其元数据无法被优化掉。

Injection token that can be used to reference instances of MatError. It serves as alternative token to the actual MatError class which could cause unnecessary retention of the class and its directive metadata.

const MAT_ERROR: InjectionToken<MatError>;

注入令牌,可以用来配置应用中所有表单字段的默认选项。

Injection token that can be used to configure the default options for all form field within an app.

const MAT_FORM_FIELD_DEFAULT_OPTIONS: InjectionToken<MatFormFieldDefaultOptions>;

这个注入令牌可以用来注入一个 MatFormField 的实例。它可以作为实际 MatFormField 类的备用令牌,使用实际类会导致 MatFormField 类及其组件元数据无法优化掉。

Injection token that can be used to inject an instances of MatFormField. It serves as alternative token to the actual MatFormField class which would cause unnecessary retention of the MatFormField class and its component metadata.

const MAT_FORM_FIELD: InjectionToken<MatFormField>;

这个注入令牌可以用来引用 MatPrefix 实例。它可以作为实际 MatPrefix 类的备用令牌,直接使用实际类可能导致该类及其元数据无法被优化掉。

Injection token that can be used to reference instances of MatPrefix. It serves as alternative token to the actual MatPrefix class which could cause unnecessary retention of the class and its directive metadata.

const MAT_PREFIX: InjectionToken<MatPrefix>;

这个注入令牌可以用来引用 MatSuffix 实例。它可以作为实际 MatSuffix 类的备用令牌,直接使用实际类可能导致该类及其元数据无法被优化掉。

Injection token that can be used to reference instances of MatSuffix. It serves as alternative token to the actual MatSuffix class which could cause unnecessary retention of the class and its directive metadata.

const MAT_SUFFIX: InjectionToken<MatSuffix>;

Angular Material form-field-testing API 参考文档

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

Harness for interacting with a standard Material form-field's in tests.

方法
异步
getAppearance

Gets the appearance of the form-field.

返回值

Returns

Promise<'legacy' | 'standard' | 'fill' | 'outline'>
异步
getControl

Gets the harness of the control that is bound to the form-field. Only default controls such as "MatInputHarness" and "MatSelectHarness" are supported.

返回值

Returns

Promise<FormFieldControlHarness | null>
异步
getControl

Gets the harness of the control that is bound to the form-field. Searches for a control that matches the specified harness type.

参数

Parameters

type

ComponentHarnessConstructor<X>

返回值

Returns

Promise<X | null>
异步
getControl

Gets the harness of the control that is bound to the form-field. Searches for a control that matches the specified harness predicate.

参数

Parameters

type

HarnessPredicate<X>

返回值

Returns

Promise<X | null>
异步
getLabel

Gets the label of the form-field.

返回值

Returns

Promise<string | null>
异步
getPrefixText

Gets the text inside the prefix element.

返回值

Returns

Promise<string>
异步
getSuffixText

Gets the text inside the suffix element.

返回值

Returns

Promise<string>
异步
getTextErrors

Gets error messages which are currently displayed in the form-field.

返回值

Returns

Promise<string[]>
异步
getTextHints

Gets hint messages which are currently displayed in the form-field.

返回值

Returns

Promise<string[]>
异步
getThemeColor

Gets the theme color of the form-field.

返回值

Returns

Promise<'primary' | 'accent' | 'warn'>
异步
hasErrors

Whether the form-field has errors.

返回值

Returns

Promise<boolean>
异步
hasLabel

Whether the form-field has a label.

返回值

Returns

Promise<boolean>
异步
host

获取一个代表该组件宿主元素的 TestElementPromise

Gets a Promise for the TestElement representing the host element of the component.

返回值

Returns

Promise<TestElement>
异步
isAutofilled

Whether the form-field is currently autofilled.

返回值

Returns

Promise<boolean>
异步
isControlDirty

Whether the form control is dirty. Returns "null" if no form control is set up.

返回值

Returns

Promise<boolean | null>
异步
isControlPending

Whether the form control is pending validation. Returns "null" if no form control is set up.

返回值

Returns

Promise<boolean | null>
异步
isControlTouched

Whether the form control has been touched. Returns "null" if no form control is set up.

返回值

Returns

Promise<boolean | null>
异步
isControlValid

Whether the form control is valid. Returns "null" if no form control is set up.

返回值

Returns

Promise<boolean | null>
异步
isDisabled

Whether the form-field is disabled.

返回值

Returns

Promise<boolean>
异步
isLabelFloating

Whether the label is currently floating.

返回值

Returns

Promise<boolean>
已弃用
异步
getHarnessLoaderForPrefix

Gets a reference to the container element which contains all projected prefixes of the form-field.

返回值

Returns

Promise<TestElement | null>
已弃用
异步
getHarnessLoaderForSuffix

Gets a reference to the container element which contains all projected suffixes of the form-field.

返回值

Returns

Promise<TestElement | null>

A set of criteria that can be used to filter a list of MatFormFieldHarness instances.

属性
名称 描述

floatingLabelText: string | RegExp

Filters based on the text of the form field's floating label.

hasErrors: boolean

Filters based on whether the form field has error messages.

Possible harnesses of controls which can be bound to a form-field.

type FormFieldControlHarness = MatInputHarness | MatSelectHarness;