Angular Material

Angular Material form-field API 参考文档

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

指令

`MatError`

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

Single error message to be shown underneath the form field.

选择器： mat-error

属性

名称	描述
@Input() `id: string`

`MatFormField`

表单控件的容器，用来应用 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`	@deprecated @breaking-change 8.0.0

方法

getConnectedOverlayOrigin

getConnectedOverlayOrigin
获取一个 ElementRef 元素，它为附加到表单字段上的浮层提供相对于该元素定位。 Gets an ElementRef for the element that a overlay attached to the form-field should be positioned relative to.
`ElementRef`

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

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

返回值

Returns

ElementRef

getLabelId

getLabelId
获取 label 元素的 id。如果没有 label，则返回 `null` 。 Gets the id of the label element. If no label is present, returns `null`.
`string \| null`

获取 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.

updateOutlineGap

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

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

`MatHint`

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

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.

@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 placeholder text for an MatFormField.

选择器： mat-placeholder

已弃用

`MatPrefix`

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

Prefix to be placed in front of the form field.

选择器： [matPrefix]

`MatSuffix`

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

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

选择器： [matSuffix]

`MatLabel`

mat-form-field 的浮动标签。

The floating label for a mat-form-field.

选择器： mat-label

类

`MatFormFieldControl`

本接口允许控件工作在 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

onContainerClick
处理此控件的容器上的点击事件。 Handles a click on the control's container.
event `MouseEvent`

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

Handles a click on the control's container.

参数

Parameters

event

MouseEvent

setDescribedByIds

setDescribedByIds
设置当前描述该控件的元素 ID 列表。 Sets the list of element IDs that currently describe this control.
ids `string[]`

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

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

参数

Parameters

ids

string[]

接口

`MatFormFieldDefaultOptions`

表示可通过 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`	表单字段的标签默认应该是 `always`、`never` 还是 `auto`（只在必要时）。 Whether the label for form-fields should by default float `always`, `never`, or `auto` (only when necessary).
`hideRequiredMarker: boolean`

appearance: MatFormFieldAppearance

floatLabel: FloatLabelType

表单字段的标签默认应该是 always、never 还是 auto（只在必要时）。

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

hideRequiredMarker: boolean

类型别名

`MatFormFieldAppearance`

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

Possible appearance styles for the form field.

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

`FloatLabelType`

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

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

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

常量

`MAT_ERROR`

这个注入令牌可以用来引用 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>;

`MAT_FORM_FIELD_DEFAULT_OPTIONS`

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

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>;

`MAT_FORM_FIELD`

这个注入令牌可以用来注入一个 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>;

`MAT_PREFIX`

这个注入令牌可以用来引用 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>;

`MAT_SUFFIX`

这个注入令牌可以用来引用 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';

类

`MatFormFieldHarness`

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

方法

异步 getAppearance
Gets the appearance of the form-field.
`Promise<'legacy' \| 'standard' \| 'fill' \| 'outline'>`

异步

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.
`Promise<ControlHarness \| null>`

异步

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<ControlHarness | 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.
`Promise<string \| null>`

异步

getLabel

Gets the label of the form-field.

返回值

Returns

Promise<string | null>

异步 getPrefixText
Gets the text inside the prefix element.
`Promise<string>`

异步

getPrefixText

Gets the text inside the prefix element.

返回值

Returns

Promise<string>

异步 getSuffixText
Gets the text inside the suffix element.
`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.
`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.
`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.
`Promise<'primary' \| 'accent' \| 'warn'>`

异步

getThemeColor

Gets the theme color of the form-field.

返回值

Returns

Promise<'primary' | 'accent' | 'warn'>

异步 hasErrors
Whether the form-field has errors.
`Promise<boolean>`

异步

hasErrors

Whether the form-field has errors.

返回值

Returns

Promise<boolean>

异步 hasLabel
Whether the form-field has a label.
`Promise<boolean>`

异步

hasLabel

Whether the form-field has a label.

返回值

Returns

Promise<boolean>

异步 host
获取一个代表该组件宿主元素的 `TestElement` 型 `Promise`。 Gets a `Promise` for the `TestElement` representing the host element of the component.
`Promise<TestElement>`

异步

host

获取一个代表该组件宿主元素的 TestElement 型 Promise。

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

返回值

Returns

Promise<TestElement>

异步 isAutofilled
Whether the form-field is currently autofilled.
`Promise<boolean>`

异步

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.
`Promise<boolean \| null>`

异步

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.
`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.
`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.
`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.
`Promise<boolean>`

异步

isDisabled

Whether the form-field is disabled.

返回值

Returns

Promise<boolean>

异步 isLabelFloating
Whether the label is currently floating.
`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. @deprecated Use `getPrefixText` instead. @breaking-change 11.0.0
`Promise<TestElement \| null>`

已弃用

异步

getHarnessLoaderForPrefix

Gets a reference to the container element which contains all projected prefixes of the form-field. @deprecated Use getPrefixText instead. @breaking-change 11.0.0

返回值

Returns

Promise<TestElement | null>

已弃用异步 getHarnessLoaderForSuffix
Gets a reference to the container element which contains all projected suffixes of the form-field. @deprecated Use `getSuffixText` instead. @breaking-change 11.0.0
`Promise<TestElement \| null>`

已弃用

异步

getHarnessLoaderForSuffix

Gets a reference to the container element which contains all projected suffixes of the form-field. @deprecated Use getSuffixText instead. @breaking-change 11.0.0

返回值

Returns

Promise<TestElement | null>

接口

`FormFieldHarnessFilters`

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.

类型别名

`FormFieldControlHarness`

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

type FormFieldControlHarness = MatInputHarness | MatSelectHarness | MatDatepickerInputHarness | MatDateRangeInputHarness;

Testing

Angular Material form-field API 参考文档

link 指令

link MatError

属性

link MatFormField

属性

方法

link MatHint

属性

link MatPlaceholder

link MatPrefix

link MatSuffix

link MatLabel

link 类

link MatFormFieldControl

属性

方法

link 接口

link MatFormFieldDefaultOptions

属性

link 类型别名

link MatFormFieldAppearance

link FloatLabelType

link 常量

link MAT_ERROR

link MAT_FORM_FIELD_DEFAULT_OPTIONS

link MAT_FORM_FIELD

link MAT_PREFIX

link MAT_SUFFIX

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

link 类

link MatFormFieldHarness

方法

link 接口

link FormFieldHarnessFilters

属性

link 类型别名

link FormFieldControlHarness

指令

`MatError`

`MatFormField`

`MatHint`

`MatPlaceholder`

`MatPrefix`

`MatSuffix`

`MatLabel`

类

`MatFormFieldControl`

接口

`MatFormFieldDefaultOptions`

类型别名

`MatFormFieldAppearance`

`FloatLabelType`

常量

`MAT_ERROR`

`MAT_FORM_FIELD_DEFAULT_OPTIONS`

`MAT_FORM_FIELD`

`MAT_PREFIX`

`MAT_SUFFIX`

类

`MatFormFieldHarness`

接口

`FormFieldHarnessFilters`

类型别名

`FormFieldControlHarness`