纸片 Chips

自动完成 Autocomplete
徽章 Badge
底部操作表 Bottom Sheet
按钮 Button
开关按钮 Button toggle
卡片 Card
检查框 Checkbox
纸片 Chips
日期选择器 Datepicker
对话框 Dialog
分割器 Divider
可展开面板 Expansion Panel
表单字段 Form field
网格列表 Grid list
图标 Icon
输入框 Input
列表 List
菜单 Menu
分页器 Paginator
进度条 Progress bar
进度圈 Progress spinner
单选按钮 Radio button
涟漪 Ripples
选择框 Select
侧边栏 Sidenav
滑块开关 Slide toggle
滑杆 Slider
快餐栏 Snackbar
排序头 Sort header
步进器 Stepper
表格 Table
选项卡 Tabs
工具栏 Toolbar
工具提示 Tooltip
树 Tree
chips 的 API

Angular Material chips API 参考文档

import {MatChipsModule} from '@angular/material/chips';

一种 Material Design 纸片组件（由于类似于 List 组件，因此得名 ChipList）。

A material design chips component (named ChipList for its similarity to the List component).

选择器： mat-chip-list
导出为： matChipList
属性
名称 描述
@Input('aria-orientation')

ariaOrientation: 'horizontal' | 'vertical'

纸片列表的方向。

Orientation of the chip list.
@Input()

compareWith: (o1: any, o2: any) => boolean

用来比较选项值和当前选择的函数。第一个参数是选项的值，第二个选定的值。应该返回一个布尔值。

A function to compare the option values with the selected values. The first argument is a value from an option. The second is a value from the selection. A boolean should be returned.
@Input()

errorStateMatcher: ErrorStateMatcher

用于控制何时显示错误信息的对象。

An object used to control when error messages are shown.
@Input()

multiple: boolean

是否允许用户选择多个纸片。

Whether the user should be allowed to select multiple chips.
@Input()

selectable: boolean

这个纸片列表是否可以选择。当纸片列表不可选时，纸片列表中所有纸片的选定状态总会被忽略。

Whether or not this chip list is selectable. When a chip list is not selectable, the selected states for all the chips inside the chip list are always ignored.
@Output()

change: EventEmitter<MatChipListChange>

当纸片列表当前选择被用户改变时发出的事件。

Event emitted when the selected chip list value has been changed by the user.

chipBlurChanges: Observable<MatChipEvent>

所有子纸片的失焦事件的组合流。

Combined stream of all of the child chips' blur change events.

chipFocusChanges: Observable<MatChipEvent>

所有子纸片的聚焦事件的组合流。

Combined stream of all of the child chips' focus change events.

chipRemoveChanges: Observable<MatChipEvent>

所有子纸片的删除事件的组合流。

Combined stream of all of the child chips' remove change events.

chipSelectionChanges: Observable<MatChipSelectionChange>

所有子纸片的选定状态更改事件的组合流。

Combined stream of all of the child chips' selection change events.

chips: QueryList<MatChip>

这个纸片列表中包含的纸片组件。

The chip components contained within this chip list.

errorState: boolean

focused: boolean

这个纸片列表中是否存在任何拥有焦点的纸片或 matChipInput。

Whether any chips or the matChipInput inside of this chip-list has focus.

role: string | null

ARIA 的角色，应用于纸片列表中。

The ARIA role applied to the chip list.

selected: MatChip[] | MatChip

纸片列表中选定纸片的数组。

The array of selected chips inside chip list.

stateChanges: Subject<void>

方法
focus

让这个纸片列表中的第一个非禁用纸片获得焦点，或在没有合格纸片时让其关联输入框获得焦点。

Focuses the first non-disabled chip in this chip list, or the associated input when there are no eligible chips.

参数

Parameters

options?

FocusOptions
registerInput

将 HTML 输入框元素与该纸片列表关联起来。

Associates an HTML input element with this chip list.

参数

Parameters

inputElement

MatChipTextControl
updateErrorState

Material Design 风格的纸片组件。在 MatChipList 组件中使用。

Material design styled Chip component. Used inside the MatChipList component.

选择器： mat-basic-chip [mat-basic-chip] mat-chip [mat-chip]
导出为： matChip
属性
名称 描述
@Input()

color: ThemePalette

Theme color palette for the component.
@Input()

disableRipple: boolean

Whether ripples are disabled.
@Input()

disabled: boolean

该纸片是否被禁用了。

Whether the chip is disabled.
@Input()

removable: boolean

确定该纸片是否显示移除样式并发出 (removed) 事件。

Determines whether or not the chip displays the remove styling and emits (removed) events.
@Input()

selectable: boolean

该纸片是否可以选择。当纸片不可选时，总会忽略对选定状态的更改。默认情况下，纸片是可选择的，如果它的父纸片列表不可选，它就会变得不可选。

Whether or not the chip is selectable. When a chip is not selectable, changes to its selected state are always ignored. By default a chip is selectable, and it becomes non-selectable if its parent chip list is not selectable.
@Input()

selected: boolean

该纸片是否被选定。

Whether the chip is selected.
@Input()

value: any

该纸片的值。默认为 <mat-chip> 标签中的内容。

The value of the chip. Defaults to the content inside <mat-chip> tags.
@Output()

destroyed: EventEmitter<MatChipEvent>

当该纸片被销毁时会触发。

Emitted when the chip is destroyed.
@Output()

removed: EventEmitter<MatChipEvent>

当要移除某个纸片时会触发。

Emitted when a chip is to be removed.
@Output()

selectionChange: EventEmitter<MatChipSelectionChange>

该纸片被选定或取消选定时会触发。

Emitted when the chip is selected or deselected.

ariaSelected: string | null

应用于该纸片的 ARIA 选定属性。

The ARIA selected applied to the chip.

avatar: MatChipAvatar

该纸片的头像

The chip avatar

chipListSelectable: boolean

纸片列表是否可选

Whether the chip list is selectable

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.

removeIcon: MatChipRemove

该纸片的移除切换器。

The chip's remove toggler.

trailingIcon: MatChipTrailingIcon

该纸片的尾部图标。

The chip's trailing icon.
方法
deselect

取消选择该纸片。

Deselects the chip.
focus

允许通过编程把该纸片设为焦点。

Allows for programmatic focusing of the chip.
remove

允许以编程方式移除该纸片。当按下 DELETE 或 BACKSPACE 键时，会由 MatChipList 调用。

Allows for programmatic removal of the chip. Called by the MatChipList when the DELETE or BACKSPACE keys are pressed.

通知任何监听器这个删除请求。但不会从 DOM 中移除纸片。

Informs any listeners of the removal request. Does not remove the chip from the DOM.
select

选择该纸片。

Selects the chip.
selectViaInteraction

选择这个纸片并发出 selected 事件

Select this chip and emit selected event
toggleSelected

切换当前纸片的选定状态。

Toggles the current selected state of this chip.

参数

Parameters

isUserInput

boolean = false

返回值

Returns
boolean

应用正确的（click）支持，并为 https://material.io/icons/#ic_cancel 提供的 Material Design “cancel” 图标添加样式。

Applies proper (click) support and adds styling for use with the Material Design "cancel" icon available at https://material.io/icons/#ic_cancel.

示例：

Example:

`<mat-chip>
  <mat-icon matChipRemove>cancel</mat-icon>
</mat-chip>`

你可以使用自定义图标，但是可能需要改写 mat-chip-remove 的定位样式，这样才能让图标在纸片内正确居中。

You may use a custom icon, but you may need to override the mat-chip-remove positioning styles to properly center the icon within the chip.

选择器： [matChipRemove]

该指令用于把纸片特有的行为添加到 <mat-form-field> 里面的输入框元素中。可以放在 <mat-chip-list> 的内部或外部。

Directive that adds chip-specific behaviors to an input element inside <mat-form-field>. May be placed inside or outside of an <mat-chip-list>.

选择器： input[matChipInputFor]
导出为： matChipInput, matChipInputFor
属性
名称 描述
@Input('matChipInputAddOnBlur')

addOnBlur: boolean

当输入失焦时，是否会发出 chipEnd 事件。

Whether or not the chipEnd event will be emitted when the input is blurred.
@Input('matChipInputFor')

chipList: MatChipList

注册纸片列表的输入框

Register input for chip list
@Input()

disabled: boolean

输入框是否被禁用。

Whether the input is disabled.
@Input()

id: string

该输入框的唯一 ID。

Unique id for the input.
@Input()

placeholder: string

输入框的占位符文本。

The input's placeholder text.
@Input('matChipInputSeparatorKeyCodes')

separatorKeyCodes: readonly number[] | ReadonlySet<number>

会触发 chipEnd 事件的键盘代码列表。

The list of key codes that will trigger a chipEnd event.

默认为 [ENTER] 。

Defaults to [ENTER].
@Output('matChipInputTokenEnd')

chipEnd: EventEmitter<MatChipInputEvent>

当要添加纸片时会触发。

Emitted when a chip is to be added.

empty: boolean

输入框是否为空。

Whether the input is empty.

focused: boolean

控件是否有焦点。

Whether the control is focused.

inputElement: HTMLInputElement

该指令所附属的原生输入框元素。

The native input element to which this directive is attached.
方法
clear

Clears the input
focus

让输入框获得焦点。

Focuses the input.

参数

Parameters

options?

FocusOptions

纸片列表的值发生变化时发出的事件对象。

Change event object that is emitted when the chip list value has changed.

属性
名称 描述

source: MatChipList

Chip list that emitted the event.

value: any

Value of the chip list when the event was emitted.

MatChip 在选定或取消选定时会发出本事件对象。

Event object emitted by MatChip when selected or deselected.

属性
名称 描述

isUserInput: false

Whether the selection change was a result of a user interaction.

selected: boolean

Whether the chip that emitted the event is selected.

source: MatChip

Reference to the chip that emitted the event.

表示单个 mat-chip 上触发的事件。

Represents an event fired on an individual mat-chip.

属性
名称 描述

chip: MatChip

触发该事件的纸片。

The chip the event was fired on.

表示 matChipInput 上的输入事件。

Represents an input event on a matChipInput.

属性
名称 描述

chipInput: MatChipInput

Reference to the chip input that emitted the event. @breaking-change 13.0.0 This property will be made required.

value: string

输入框的值。

The value of the input.
已弃用

input: HTMLInputElement

触发该事件的原生 <input>

The native <input> element that the event is being fired for.

@deprecated Use MatChipInputEvent#chipInput.inputElement instead. @breaking-change 13.0.0 This property will be removed.

纸片模块的默认选项，可以改写它们。

Default options, for the chips module, that can be overridden.

属性
名称 描述

separatorKeyCodes: readonly number[] | ReadonlySet<number>

会触发 chipEnd 事件的键盘代码列表。

The list of key codes that will trigger a chipEnd event.

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

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

const MAT_CHIP_REMOVE: InjectionToken<MatChipRemove>;

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

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

const MAT_CHIP_AVATAR: InjectionToken<MatChipAvatar>;

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

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

const MAT_CHIP_TRAILING_ICON: InjectionToken<MatChipTrailingIcon>;

注入令牌，用于改写纸片模块的默认选项。

Injection token to be used to override the default options for the chips module.

const MAT_CHIPS_DEFAULT_OPTIONS: InjectionToken<MatChipsDefaultOptions>;

Angular Material chips-testing API 参考文档

import {MatChipListHarness} from '@angular/material/chips/testing';

在测试中与标准纸片列表进行交互的测试工具。

Harness for interacting with a standard chip list in tests.

方法
异步
getChips

获取纸片列表中的纸片列表。

Gets the list of chips inside the chip list.

（可选项）用于过滤纸片。

@param filter Optionally filters which chips are included.

参数

Parameters

filter

ChipHarnessFilters = {}

返回值

Returns
Promise<MatChipHarness[]>
异步
getInput

获取纸片列表中的 MatChipInput

Gets the MatChipInput inside the chip list.

一个可选的过滤器，用于过滤纸片。。

@param filter Optionally filters which chip input is included.

参数

Parameters

filter

ChipInputHarnessFilters = {}

返回值

Returns
Promise<MatChipInputHarness>
getOrientation

获取纸片列表的方向。

Gets whether the orientation of the chip list.

返回值

Returns
Promise<'horizontal' | 'vertical'>
异步
host

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

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

返回值

Returns
Promise<TestElement>
isDisabled

获取纸片列表是否被禁用。

Gets whether the chip list is disabled.

返回值

Returns
Promise<boolean>
isInvalid

获取纸片列表是否无效。

Gets whether the chip list is invalid.

返回值

Returns
Promise<boolean>
isMultiple

获取纸片列表是否处于多选模式。

Gets whether the chip list is in multi selection mode.

返回值

Returns
Promise<boolean>
isRequired

获取纸片列表是否必填的。

Gets whether the chip list is required.

返回值

Returns
Promise<boolean>
已弃用
异步
selectChips

选定纸片列表中的纸片。

Selects a chip inside the chip list.

一个可选的过滤器，适用于子纸片。所有与过滤器匹配的纸片都会被选定。

@param filter An optional filter to apply to the child chips. All the chips matching the filter will be selected.

@deprecated Use MatChipListboxHarness.selectChips instead. @breaking-change 12.0.0

参数

Parameters

filter

ChipHarnessFilters = {}

返回值

Returns
Promise<void>

Promise that resolves when the action completes.

在测试中与标准可选 Angular Material 纸片的测试工具。

Harness for interacting with a standard selectable Angular Material chip in tests.

方法
异步
getRemoveButton

获取一个纸片里面的移除按钮。

Gets the remove button inside of a chip.

可选择过滤哪些纸片。

@param filter Optionally filters which chips are included.

参数

Parameters

filter

ChipRemoveHarnessFilters = {}

返回值

Returns
Promise<MatChipRemoveHarness>
异步
getText

获取该纸片的文本。

Gets the text of the chip.

返回值

Returns
Promise<string>
异步
host

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

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

返回值

Returns
Promise<TestElement>
异步
isDisabled

纸片是否被禁用了。

Whether the chip is disabled.

返回值

Returns
Promise<boolean>
异步
remove

移除指定的纸片。只有它可移除时才适用。

Removes the given chip. Only applies if it's removable.

返回值

Returns
Promise<void>

Promise that resolves when the action completes.
已弃用
异步
deselect

取消选定指定的纸片。仅当它可选时才适用。

Deselects the given chip. Only applies if it's selectable.

@deprecated Use MatChipOptionHarness.deselect instead. @breaking-change 12.0.0

返回值

Returns
Promise<void>

Promise that resolves when the action completes.
已弃用
异步
isSelected

纸片是否被选定。

Whether the chip is selected.

@deprecated Use MatChipOptionHarness.isSelected instead. @breaking-change 12.0.0

返回值

Returns
Promise<boolean>
已弃用
异步
select

选定指定的纸片。仅当它可选时才适用。

Selects the given chip. Only applies if it's selectable.

@deprecated Use MatChipOptionHarness.select instead. @breaking-change 12.0.0

返回值

Returns
Promise<void>

Promise that resolves when the action completes.
已弃用
异步
toggle

切换指定纸片的选定状态。仅当它可选时才适用。

Toggles the selected state of the given chip. Only applies if it's selectable.

@deprecated Use MatChipOptionHarness.toggle instead. @breaking-change 12.0.0

返回值

Returns
Promise<void>

Promise that resolves when the action completes.

在测试中用来与标准 Material 纸片组件交互的测试工具。

Harness for interacting with a standard Material chip inputs in tests.

方法
异步
blur

失焦输入框并返回一个 Promise，表明该动作什么时候完成。

Blurs the input and returns a promise that indicates when the action is complete.

返回值

Returns
Promise<void>

Promise that resolves when the action completes.
异步
focus

聚焦输入框并返回一个 Promise，表明该动作何时完成。

Focuses the input and returns a promise that indicates when the action is complete.

返回值

Returns
Promise<void>

Promise that resolves when the action completes.
异步
getPlaceholder

获取输入框的占位符。

Gets the placeholder of the input.

返回值

Returns
Promise<string>
异步
getValue

获取输入框的值。

Gets the value of the input.

返回值

Returns
Promise<string>
异步
host

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

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

返回值

Returns
Promise<TestElement>
异步
isDisabled

输入框是否被禁用。

Whether the input is disabled.

返回值

Returns
Promise<boolean>
异步
isFocused

输入框是否拥有焦点。

Whether the input is focused.

返回值

Returns
Promise<boolean>
异步
isRequired

输入框是否为必需的。

Whether the input is required.

返回值

Returns
Promise<boolean>
异步
sendSeparatorKey

向输入框元素发送一个纸片分隔键。

Sends a chip separator key to the input element.

参数

Parameters

key

string | TestKey

返回值

Returns
Promise<void>

Promise that resolves when the action completes.
异步
setValue

设置输入框的值。该值将通过模拟与指定值对应的按键进行设置。

Sets the value of the input. The value will be set by simulating keypresses that correspond to the given value.

参数

Parameters

newValue

string

返回值

Returns
Promise<void>

Promise that resolves when the action completes.

在测试过程中与标准 Material 纸片移除按钮交互的工具。

Harness for interacting with a standard Material chip remove button in tests.

方法
异步
click

点击“删除”按钮。

Clicks the remove button.

返回值

Returns
Promise<void>

Promise that resolves when the action completes.
异步
host

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

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

返回值

Returns
Promise<TestElement>
方法
异步
deselect

取消选择指定的纸片。仅当它可以选择时才适用。

Deselects the given chip. Only applies if it's selectable.

返回值

Returns
Promise<void>

Promise that resolves when the action completes.
异步
getRemoveButton

获取一个纸片里面的移除按钮。

Gets the remove button inside of a chip.

可选择过滤哪些纸片。

@param filter Optionally filters which chips are included.

参数

Parameters

filter

ChipRemoveHarnessFilters = {}

返回值

Returns
Promise<MatChipRemoveHarness>
异步
getText

获取该纸片的文本。

Gets the text of the chip.

返回值

Returns
Promise<string>
异步
host

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

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

返回值

Returns
Promise<TestElement>
异步
isDisabled

纸片是否被禁用了。

Whether the chip is disabled.

返回值

Returns
Promise<boolean>
异步
isSelected

纸片是否被选定。

Whether the chip is selected.

返回值

Returns
Promise<boolean>
异步
remove

移除指定的纸片。只有它可移除时才适用。

Removes the given chip. Only applies if it's removable.

返回值

Returns
Promise<void>

Promise that resolves when the action completes.
异步
select

选择指定的纸片。仅当它可以选择时才适用。

Selects the given chip. Only applies if it's selectable.

返回值

Returns
Promise<void>

Promise that resolves when the action completes.
异步
toggle

切换指定纸片的选定状态。

Toggles the selected state of the given chip.

返回值

Returns
Promise<void>

Promise that resolves when the action completes.

在测试中用来与标准可选纸片列表进行交互的测试工具。

Harness for interacting with a standard selectable chip list in tests.

方法
异步
getChips

获取纸片列表中的各个纸片。

Gets the list of chips inside the chip list.

可选择过滤哪些纸片。

@param filter Optionally filters which chips are included.

参数

Parameters

filter

ChipOptionHarnessFilters = {}

返回值

Returns
Promise<MatChipOptionHarness[]>
getOrientation

获取纸片列表的方向。

Gets whether the orientation of the chip list.

返回值

Returns
Promise<'horizontal' | 'vertical'>
异步
host

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

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

返回值

Returns
Promise<TestElement>
isDisabled

获取纸片列表是否被禁用。

Gets whether the chip list is disabled.

返回值

Returns
Promise<boolean>
isInvalid

获取纸片列表是否无效。

Gets whether the chip list is invalid.

返回值

Returns
Promise<boolean>
isMultiple

获取纸片列表是否处于多选模式。

Gets whether the chip list is in multi selection mode.

返回值

Returns
Promise<boolean>
isRequired

获取纸片列表是否必填的。

Gets whether the chip list is required.

返回值

Returns
Promise<boolean>
异步
selectChips

选择纸片列表中的纸片。

Selects a chip inside the chip list.

一个可选的过滤器，适用于子纸片。所有与过滤器匹配的纸片都会被选定。

@param filter An optional filter to apply to the child chips. All the chips matching the filter will be selected.

参数

Parameters

filter

ChipOptionHarnessFilters = {}

返回值

Returns
Promise<void>

Promise that resolves when the action completes.

一组可以用来过滤纸片实例列表的标准。

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

属性
名称 描述

text: string | RegExp

只查找文本与指定值匹配的实例。

Only find instances whose text matches the given value.
已弃用

selected: boolean

只查找选定状态与指定值匹配的纸片实例。

Only find chip instances whose selected state matches the given value.

@deprecated Use MatChipOptionHarness together with ChipOptionHarnessFilters. @breaking-change 12.0.0

一组可以用来过滤可选纸片实例列表的标准。

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

属性
名称 描述

selected: boolean

只查找选定状态与指定值匹配的纸片实例。

Only find chip instances whose selected state matches the given value.

一组可以用来过滤纸片列表实例的标准。

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

一组可用于过滤可选纸片列表实例的准则。

A set of criteria that can be used to filter selectable chip list instances.

一组标准，可以用来过滤 MatChipListInputHarness 实例列表。

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

属性
名称 描述

placeholder: string | RegExp

根据输入的占位符文本进行过滤。

Filters based on the placeholder text of the input.

value: string | RegExp

根据输入值过滤。

Filters based on the value of the input.

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

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

纸片 API 目录
Testing