检查框 Checkbox

checkbox 的 API

Angular Material checkbox API 参考文档

import {MatCheckboxModule} from '@angular/material/checkbox';

一种 Material Design 复选框。支持 HTML5 复选框的所有功能,并公开类似的 API。 MatCheckbox 可以是选定、未选定、未决或禁用的。请注意,该组件会处理所有其它无障碍属性,因此无需自行提供。但是,如果你想省略一个标签并仍然让该复选框满足无障碍性,你可以提供一个 [aria-label] 输入属性。请参阅:https://material.io/design/components/selection-controls.html

A material design checkbox component. Supports all of the functionality of an HTML5 checkbox, and exposes a similar API. A MatCheckbox can be either checked, unchecked, indeterminate, or disabled. Note that all additional accessibility attributes are taken care of by the component, so there is no need to provide them yourself. However, if you want to omit a label and still have the checkbox be accessible, you may supply an [aria-label] input. See: https://material.io/design/components/selection-controls.html

选择器: mat-checkbox
导出为: matCheckbox
属性
名称 描述
@Input('aria-describedby')

ariaDescribedby: string

'aria-describedby' 属性是在该元素的标签和字段类型之后读取的。

The 'aria-describedby' attribute is read after the element's label and field type.

@Input('aria-label')

ariaLabel: string

附加在宿主元素的 aria-label 属性上。在大多数情况下,aria-labelledby 优先,所以这个可以省略。

Attached to the aria-label attribute of the host element. In most cases, aria-labelledby will take precedence so this may be omitted.

@Input('aria-labelledby')

ariaLabelledby: string | null

用户可以指定 aria-labelledby 属性,它会被转发到 input 元素

Users can specify the aria-labelledby attribute which will be forwarded to the input element

@Input()

checked: boolean

是否勾选了复选框。

Whether the checkbox is checked.

@Input()

color: ThemePalette

Theme color palette for the component.

@Input()

disableRipple: boolean

Whether ripples are disabled.

@Input()

disabled: any

该复选框是否已被禁用。这完全取代了 mixinDisabled 提供的实现,但 mixin 仍然是必需的,因为 mixinTabIndex 需要它。

Whether the checkbox is disabled. This fully overrides the implementation provided by mixinDisabled, but the mixin is still required because mixinTabIndex requires it.

@Input()

id: string

复选框的唯一 ID。如果没有提供,它就会自动生成。

A unique id for the checkbox input. If none is supplied, it will be auto-generated.

@Input()

indeterminate: boolean

该复选框是否未决。这也称为“混合”模式,用于表示带有三种状态的复选框,例如一个嵌套着其它复选框列表的复选框。请注意,只要手动点击复选框,就会立即将未决状态设为 false。

Whether the checkbox is indeterminate. This is also known as "mixed" mode and can be used to represent a checkbox with three states, e.g. a checkbox that represents a nested list of checkable items. Note that whenever checkbox is manually clicked, indeterminate is immediately set to false.

@Input()

labelPosition: 'before' | 'after'

标签位于复选框之后还是之前。默认为 'after'

Whether the label should appear after or before the checkbox. Defaults to 'after'

@Input()

name: string | null

如果存在,name 值就会被应用到 input 元素中

Name value will be applied to the input element if present

@Input()

required: boolean

是否需要该复选框。

Whether the checkbox is required.

@Input()

value: string

原生输入元素的 value 属性

The value attribute of the native input element

@Output()

change: EventEmitter<MatCheckboxChange>

checked 值发生变化时会发出本事件。

Event emitted when the checkbox's checked value changes.

@Output()

indeterminateChange: EventEmitter<boolean>

indeterminate 值发生变化时会发出本事件。

Event emitted when the checkbox's indeterminate value changes.

defaultColor: ThemePalette | undefined

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

defaultTabIndex: number

Tabindex to which to fall back to if no value is set.

inputId: string

返回不可见输入框的唯一 id。

Returns the unique id for the visual hidden input.

ripple: MatRipple

引用复选框的涟漪对象实例。

Reference to the ripple instance of the checkbox.

方法
focus

聚焦此复选框。

Focuses the checkbox.

参数

Parameters

origin?

FocusOrigin

options?

FocusOptions
toggle

切换 checked 状态。

Toggles the checked state of the checkbox.

一个验证器,用于验证 Material 复选框在模板驱动复选框中的必填属性。目前 CheckboxRequiredValidator 只能用于 input type=checkbox ,而且不能用于 mat-checkbox

Validator for Material checkbox's required attribute in template-driven checkbox. Current CheckboxRequiredValidator only work with input type=checkbox and does not work with mat-checkbox.

选择器: mat-checkbox[required][formControlName] mat-checkbox[required][formControl] mat-checkbox[required][ngModel]
属性
名称 描述

required: boolean | string

@description Tracks changes to the required attribute bound to this directive.

方法
registerOnValidatorChange

Registers a callback function to call when the validator inputs change. @nodoc

参数

Parameters

fn

() => void
validate

Method that validates whether or not the checkbox has been checked. Returns the validation result if enabled, otherwise null. @nodoc

参数

Parameters

control

AbstractControl

返回值

Returns

ValidationErrors | null

MatCheckbox 发出的“更改”事件对象。

Change event object emitted by MatCheckbox.

属性
名称 描述

checked: boolean

该复选框的新 checked 值。

The new checked value of the checkbox.

source: MatCheckbox

该事件的来源 MatCheckbox。

The source MatCheckbox of the event.

默认的 mat-checkbox 选项,可以改写它们。

Default mat-checkbox options that can be overridden.

属性
名称 描述

clickAction: MatCheckboxClickAction

color: ThemePalette

当用户点击 input 元素时,复选框会处理点击动作。 noop:不要切换为勾选或未决。 check:只切换勾选状态,忽略未决状态。 check-indeterminate:切换勾选状态,未决状态设为 false。默认行为。 undefined:与 check-indeterminate 相同。

Checkbox click action when user click on input element. noop: Do not toggle checked or indeterminate. check: Only toggle checked status, ignore indeterminate. check-indeterminate: Toggle checked status, set indeterminate to false. Default behavior. undefined: Same as check-indeterminate.

type MatCheckboxClickAction = 'noop' | 'check' | 'check-indeterminate' | undefined;

这个注入令牌用来改写 mat-checkbox 的默认选项。

Injection token to be used to override the default options for mat-checkbox.

const MAT_CHECKBOX_DEFAULT_OPTIONS: InjectionToken<MatCheckboxDefaultOptions>;
const MAT_CHECKBOX_REQUIRED_VALIDATOR: Provider;

Angular Material checkbox-testing API 参考文档

import {MatCheckboxHarness} from '@angular/material/checkbox/testing';

Harness for interacting with a standard mat-checkbox in tests.

方法
异步
blur

失焦复选框。

Blurs the checkbox.

返回值

Returns

Promise<void>

Promise that resolves when the action completes.

异步
check

如果当前未勾选复选框,则把复选框置于已勾选状态;如果复选框已勾选,则不执行任何操作。

Puts the checkbox in a checked state by toggling it if it is currently unchecked, or doing nothing if it is already checked.

注意:这会尝试通过单击该复选框来勾选复选框。因此,如果你使用 MAT_CHECKBOX_DEFAULT_OPTIONS 改变过单击的行为,那么调用这个方法可能产生预料之外的效果。

Note: This attempts to check the checkbox as a user would, by clicking it. Therefore if you are using MAT_CHECKBOX_DEFAULT_OPTIONS to change the behavior on click, calling this method might not have the expected result.

返回值

Returns

Promise<void>

Promise that resolves when the action completes.

异步
focus

聚焦复选框。

Focuses the checkbox.

返回值

Returns

Promise<void>

Promise that resolves when the action completes.

异步
getAriaLabel

获取复选框的 aria-label。

Gets the checkbox's aria-label.

返回值

Returns

Promise<string | null>
异步
getAriaLabelledby

获取复选框的 aria-labelledby。

Gets the checkbox's aria-labelledby.

返回值

Returns

Promise<string | null>
异步
getLabelText

获取复选框的标签文本。

Gets the checkbox's label text.

返回值

Returns

Promise<string>
异步
getName

获取复选框的名字。

Gets the checkbox's name.

返回值

Returns

Promise<string | null>
异步
getValue

获取复选框的值。

Gets the checkbox's value.

返回值

Returns

Promise<string | null>
异步
host

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

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

返回值

Returns

Promise<TestElement>
异步
isChecked

是否勾选了复选框。

Whether the checkbox is checked.

返回值

Returns

Promise<boolean>
异步
isDisabled

该复选框是否已被禁用。

Whether the checkbox is disabled.

返回值

Returns

Promise<boolean>
异步
isFocused

该复选框是否拥有焦点。

Whether the checkbox is focused.

返回值

Returns

Promise<boolean>
异步
isIndeterminate

该复选框是否处于未决状态。

Whether the checkbox is in an indeterminate state.

返回值

Returns

Promise<boolean>
异步
isRequired

该复选框是否必填的。

Whether the checkbox is required.

返回值

Returns

Promise<boolean>
异步
isValid

该复选框是否有效。

Whether the checkbox is valid.

返回值

Returns

Promise<boolean>
异步
toggle

返回值

Returns

Promise<void>

Promise that resolves when the action completes.

异步
uncheck

如果复选框当前是勾选的,则把它切换到未勾选状态,如果复选框已经是未勾选的,则不做任何操作。

Puts the checkbox in an unchecked state by toggling it if it is currently checked, or doing nothing if it is already unchecked.

注意:这会尝试通过单击该复选框来取消勾选该复选框。因此,如果你使用 MAT_CHECKBOX_DEFAULT_OPTIONS 改变过单击时的行为,那么调用这个方法可能产生预料之外的效果。

Note: This attempts to uncheck the checkbox as a user would, by clicking it. Therefore if you are using MAT_CHECKBOX_DEFAULT_OPTIONS to change the behavior on click, calling this method might not have the expected result.

返回值

Returns

Promise<void>

Promise that resolves when the action completes.

一组可以用来过滤 MatCheckboxHarness 实例列表的条件。

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

属性
名称 描述

label: string | RegExp

只查找标签与指定值匹配的实例。

Only find instances whose label matches the given value.

name: string

只查找 name 属性为指定值的实例。

Only find instances whose name attribute is the given value.