Angular Material 芯片组件的 API 参考

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

指令

`MatChip`

Material Design 风格的纸片基础组件。在 MatChipSet 组件内部使用。

由 MatChipOption 和 MatChipRow 扩展用于不同的交互模式。

选择器： mat-basic-chip [mat-basic-chip] mat-chip [mat-chip]

Exported as: matChip

属性

名称	描述
@Input('aria-description') `ariaDescription: string \| null`	纸片内容的 ARIA 描述。
@Input('aria-label') `ariaLabel: string \| null`	纸片内容的 ARIA 标签。
@Input() `color: string \| null`	芯片的主题颜色调色板。
@Input({ transform: booleanAttribute }) `disableRipple: boolean`	是否已禁用涟漪效果。
@Input({ transform: booleanAttribute }) `disabled: boolean`	纸片是否已禁用了。
@Input({ transform: booleanAttribute }) `highlighted: boolean`	为纸片着色以表强调，就好像它已被选中一样。
@Input() `id: string`	纸片的唯一 ID。如果没有提供，它将自动生成。
@Input({ transform: booleanAttribute }) `removable: boolean`	确定该纸片是否显示移除样式并发出 (removed) 事件。
@Input() `role: string \| null`	用作纸片的根。
@Input() `value: any`	纸片的值。默认为 `mat-mdc-chip-action-label` 元素内的内容。
@Output() `destroyed: EventEmitter<MatChipEvent>`	当该纸片被销毁时会触发。
@Output() `removed: EventEmitter<MatChipEvent>`	当要移除某个纸片时会触发。
`basicChipAttrName: 'mat-basic-chip'`	此组件的无样式纸片选择器。
`leadingIcon: MatChipAvatar`	纸片的主要图标。
`primaryAction: MatChipAction`	接收主要用户交互集的操作。
`removeIcon: MatChipRemove`	纸片的尾随删除图标。
`trailingIcon: MatChipTrailingIcon`	该纸片的尾部图标。
Deprecated `ripple: MatRipple`	对芯片的 MatRipple 实例的引用。

方法

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

remove
允许以编程方式移除芯片。通知任何监听器这个删除请求。但不会从 DOM 中移除纸片。

remove

允许以编程方式移除芯片。

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

`MatChipOption` 继承自 MatChip

支持纸片选择的 MatChip 组件的扩展。与 MatChipListbox 一起使用。

与其他纸片不同，用户可以专注于 MatChipListbox 中禁用的纸片选项。用户不能单击已禁用的纸片。

选择器： mat-basic-chip-option [mat-basic-chip-option] mat-chip-option [mat-chip-option]

属性

名称	描述
@Input('aria-description') `ariaDescription: string \| null`	纸片内容的 ARIA 描述。
@Input('aria-label') `ariaLabel: string \| null`	纸片内容的 ARIA 标签。
@Input() `color: string \| null`	芯片的主题颜色调色板。
@Input({ transform: booleanAttribute }) `disableRipple: boolean`	是否已禁用涟漪效果。
@Input({ transform: booleanAttribute }) `disabled: boolean`	纸片是否已禁用了。
@Input({ transform: booleanAttribute }) `highlighted: boolean`	为纸片着色以表强调，就好像它已被选中一样。
@Input() `id: string`	纸片的唯一 ID。如果没有提供，它将自动生成。
@Input({ transform: booleanAttribute }) `removable: boolean`	确定该纸片是否显示移除样式并发出 (removed) 事件。
@Input() `role: string \| null`	用作纸片的根。
@Input({ transform: booleanAttribute }) `selectable: boolean`	纸片是否可选。当一个纸片不可选择时，对其选定状态的改变总是被忽略。默认情况下，选项纸片是可选的，如果其父纸片列表不可选，则该可选纸片变为不可选。
@Input({ transform: booleanAttribute }) `selected: boolean`	纸片是否被选定。
@Input() `value: any`	纸片的值。默认为 `mat-mdc-chip-action-label` 元素内的内容。
@Output() `destroyed: EventEmitter<MatChipEvent>`	当该纸片被销毁时会触发。
@Output() `removed: EventEmitter<MatChipEvent>`	当要移除某个纸片时会触发。
@Output() `selectionChange: EventEmitter<MatChipSelectionChange>`	该纸片被选定或取消选定时会触发。
`ariaSelected: string \| null`	将 ARIA selected 应用于此纸片。遵循列表框交互模式的 WAI ARIA 最佳实践。来自 WAI ARIA Listbox 作者实践指南： “如果选择了任何选项，则每个选定选项的 aria-selected 或 aria-checked 都设置为 true。所有可选择但未选定的选项的 aria-selected 或 aria-checked 都设置为 false。” 在可选择的未选择列表框选项上设置 `aria-selected="false"` 以修复 VoiceOver 将每个选项读取为“selected”的问题(#25736)。
`basicChipAttrName: 'mat-basic-chip-option'`	此组件的无样式纸片选择器。
`chipListSelectable: boolean`	芯片列表是否可选。
`leadingIcon: MatChipAvatar`	纸片的主要图标。
`primaryAction: MatChipAction`	接收主要用户交互集的操作。
`removeIcon: MatChipRemove`	纸片的尾随删除图标。
`trailingIcon: MatChipTrailingIcon`	该纸片的尾部图标。
Deprecated `ripple: MatRipple`	对芯片的 MatRipple 实例的引用。

方法

deselect
取消选择该纸片。

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

remove
允许以编程方式移除芯片。通知任何监听器这个删除请求。但不会从 DOM 中移除纸片。

remove

允许以编程方式移除芯片。

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

select
选择该纸片。

selectViaInteraction
选择此纸片并发出 userInputSelection 事件

toggleSelected
切换当前纸片的选定状态。
参数
isUserInput `boolean = false`
返回值
`boolean`

`MatChipRow` 继承自 MatChip

与 MatChipGrid 和 matChipInputFor 指令一起使用的 MatChip 组件的扩展。

选择器： mat-chip-row [mat-chip-row] mat-basic-chip-row [mat-basic-chip-row]

属性

名称	描述
@Input('aria-description') `ariaDescription: string \| null`	纸片内容的 ARIA 描述。
@Input('aria-label') `ariaLabel: string \| null`	纸片内容的 ARIA 标签。
@Input() `color: string \| null`	芯片的主题颜色调色板。
@Input({ transform: booleanAttribute }) `disableRipple: boolean`	是否已禁用涟漪效果。
@Input({ transform: booleanAttribute }) `disabled: boolean`	纸片是否已禁用了。
@Input() `editable: boolean`
@Input({ transform: booleanAttribute }) `highlighted: boolean`	为纸片着色以表强调，就好像它已被选中一样。
@Input() `id: string`	纸片的唯一 ID。如果没有提供，它将自动生成。
@Input({ transform: booleanAttribute }) `removable: boolean`	确定该纸片是否显示移除样式并发出 (removed) 事件。
@Input() `role: string \| null`	用作纸片的根。
@Input() `value: any`	纸片的值。默认为 `mat-mdc-chip-action-label` 元素内的内容。
@Output() `destroyed: EventEmitter<MatChipEvent>`	当该纸片被销毁时会触发。
@Output() `edited: EventEmitter<MatChipEditedEvent>`	编辑纸片时发出。
@Output() `removed: EventEmitter<MatChipEvent>`	当要移除某个纸片时会触发。
`basicChipAttrName: 'mat-basic-chip-row'`
`contentEditInput: MatChipEditInput`	投影进来的纸片编辑输入框。
`defaultEditInput: MatChipEditInput`	如果没有投影到此纸片行，则使用默认的纸片编辑输入框。
`leadingIcon: MatChipAvatar`	纸片的主要图标。
`primaryAction: MatChipAction`	接收主要用户交互集的操作。
`removeIcon: MatChipRemove`	纸片的尾随删除图标。
`trailingIcon: MatChipTrailingIcon`	该纸片的尾部图标。
Deprecated `ripple: MatRipple`	对芯片的 MatRipple 实例的引用。

方法

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

remove
允许以编程方式移除芯片。通知任何监听器这个删除请求。但不会从 DOM 中移除纸片。

remove

允许以编程方式移除芯片。

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

`MatChipSet`

此 MatChip 组件的基本容器组件。

由 MatChipListbox 和 MatChipGrid 扩展，用于不同的交互模式。

选择器： mat-chip-set

属性

名称	描述
@Input({ transform: booleanAttribute }) `disabled: boolean`	此纸片组是否已禁用。
@Input() `role: string \| null`	应用于此纸片组的 ARIA 角色。
`chipDestroyedChanges: Observable<MatChipEvent>`	所有子芯片的销毁事件的组合流。
`chipFocusChanges: Observable<MatChipEvent>`	所有子纸片的焦点事件的组合流。
`chipRemovedChanges: Observable<MatChipEvent>`	所有子纸片的移除事件的组合流。
`empty: boolean`	此纸片列表是否包含纸片。
`focused: boolean`	该纸片组内是否有任何纸片拥有焦点。

方法

focus
子类要覆盖的虚拟方法。纸片组基类无法获得焦点。

`MatChipListbox` 继承自 MatChipSet

支持纸片选择的 MatChipSet 组件的扩展。与 MatChipOption 纸片一起使用。

选择器： mat-chip-listbox

属性

名称	描述
@Input('aria-orientation') `ariaOrientation: 'horizontal' \| 'vertical'`	纸片列表的方向。
@Input() `compareWith: (o1: any, o2: any) => boolean`	用来比较选项值和当前选择的函数。第一个参数是选项的值，第二个选定的值。应该返回一个布尔值。
@Input({ transform: booleanAttribute }) `disabled: boolean`	此纸片组是否已禁用。
@Input({ transform: booleanAttribute }) `hideSingleSelectionIndicator: boolean`	是否隐藏单选选项的复选标记指示器。
@Input({ transform: booleanAttribute }) `multiple: boolean`	是否允许用户选择多个纸片。
@Input({ transform: booleanAttribute }) `required: boolean`	此纸片列表框是否必要的。
@Input() `role: string \| null`	应用于此纸片组的 ARIA 角色。
@Input({ transform: booleanAttribute }) `selectable: boolean`	此纸片列表框是否可选。当纸片列表框不可选时，纸片列表框内所有纸片的选定状态总是被忽略。
@Input() `value: any`	此列表框的值，即所选定纸片的组合值。
@Output() `change: EventEmitter<MatChipListboxChange>`	当用户更改了所选定纸片列表框值时发出的事件。
`chipBlurChanges: Observable<MatChipEvent>`	所有子纸片的失焦事件的组合流。
`chipDestroyedChanges: Observable<MatChipEvent>`	所有子芯片的销毁事件的组合流。
`chipFocusChanges: Observable<MatChipEvent>`	所有子纸片的焦点事件的组合流。
`chipRemovedChanges: Observable<MatChipEvent>`	所有子纸片的移除事件的组合流。
`chipSelectionChanges: Observable<MatChipSelectionChange>`	所有子纸片的选定状态更改事件的组合流。
`empty: boolean`	此纸片列表是否包含纸片。
`focused: boolean`	该纸片组内是否有任何纸片拥有焦点。
`selected: MatChipOption[] \| MatChipOption`	纸片列表框中已选定纸片的数组。

方法

focus
聚焦此纸片列表框中第一个选定的纸片，或者在没有选定纸片时聚焦第一个未禁用的纸片。

`MatChipGrid` 继承自 MatChipSet

与 MatChipRow 纸片和 matChipInputFor 指令一起使用的 MatChipSet 组件的扩展。

选择器： mat-chip-grid

属性

名称	描述
@Input() `errorStateMatcher: ErrorStateMatcher`	用于控制何时显示错误信息的对象。
@Input() `role: string \| null`	应用于此纸片组的 ARIA 角色。
@Output() `change: EventEmitter<MatChipGridChange>`	当用户更改纸片网格的值时发出。
`chipBlurChanges: Observable<MatChipEvent>`	所有子纸片的失焦事件的组合流。
`chipDestroyedChanges: Observable<MatChipEvent>`	所有子芯片的销毁事件的组合流。
`chipFocusChanges: Observable<MatChipEvent>`	所有子纸片的焦点事件的组合流。
`chipRemovedChanges: Observable<MatChipEvent>`	所有子纸片的移除事件的组合流。
`errorState: boolean`	芯片网格是否处于错误状态。
`focused: boolean`	这是任意纸片还是纸片网格中具有焦点的 matChipInput。
`ngControl: NgControl`

方法

focus
聚焦此纸片网格中的第一个纸片，或在没有符合条件的纸片时聚焦关联的输入。

registerInput
将 HTML input 元素与此纸片网格相关联。
参数
inputElement `MatChipTextControl`

updateErrorState
刷新芯片网格的错误状态。

`MatChipInput`

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

选择器： input[matChipInputFor]

Exported as: matChipInput, matChipInputFor

属性

名称	描述
@Input({ alias: 'matChipInputAddOnBlur', transform: booleanAttribute }) `addOnBlur: boolean`	当输入失焦时，是否会发出 chipEnd 事件。
@Input('matChipInputFor') `chipGrid: MatChipGrid`	注册纸片列表的输入框
@Input({ transform: booleanAttribute }) `disabled: boolean`	输入框是否已禁用。
@Input() `id: string`	该输入框的唯一 ID。
@Input() `placeholder: string`	输入框的占位符文本。
@Input('matChipInputSeparatorKeyCodes') `separatorKeyCodes: readonly number[] \| ReadonlySet<number>`	会触发 chipEnd 事件的键盘代码列表。默认为 `[ENTER]`。
@Output('matChipInputTokenEnd') `chipEnd: EventEmitter<MatChipInputEvent>`	当要添加纸片时会触发。
`empty: boolean`	输入框是否为空。
`focused: boolean`	控件是否有焦点。
`inputElement: HTMLInputElement`	该指令所附属的原生输入框元素。

方法

clear
清除输入

focus
让输入框获得焦点。

setDescribedByIds
参数
ids `string[]`

`MatChipAvatar`

纸片内的头像图像。

选择器： mat-chip-avatar [matChipAvatar]

`MatChipTrailingIcon`

纸片中的非交互式尾随图标。

选择器： mat-chip-trailing-icon [matChipTrailingIcon]

属性

名称	描述
@Input({ transform: booleanAttribute }) `disabled: boolean`	此动作是否被禁用。
`isInteractive: false`	MDC 将所有尾随操作视为删除图标，但我们支持非交互式尾随图标。

方法

focus

`MatChipRemove`

用于在单击尾随图标或按下 ENTER 键时删除父纸片的指令。

建议与 Material Design “取消” 图标一起使用，可在 https://material.io/icons/#ic_cancel 获取。

示例：

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

选择器： [matChipRemove]

属性

名称	描述
@Input({ transform: booleanAttribute }) `disabled: boolean`	此动作是否被禁用。
@Input() `isInteractive: true`	此动作是否交互。

方法

focus

`MatChipEditInput`

该指令能让某个 span 可编辑并暴露一些函数以修改和检索元素内容。

选择器： span[matChipEditInput]

方法

getNativeElement
返回值
`HTMLElement`

getValue
返回值
`string`

initialize
参数
initialValue `string`

setValue
参数
value `string`

类

`MatChipSelectionChange`

当选择或取消选择时由 MatChipOption 发出的事件对象。

属性

名称	描述
`isUserInput: false`	此选中结果的变化是否由用户交互导致的。
`selected: boolean`	发出此事件的纸片是否已选中。
`source: MatChipOption`	到发出此事件的the chip的引用。

`MatChipListboxChange`

纸片列表框值更改时发出的更改事件对象。

属性

名称	描述
`source: MatChipListbox`	发出事件的芯片列表框。
`value: any`	发出事件时芯片列表框的值。

`MatChipGridChange`

纸片网格值的更改时发出的更改事件对象。

属性

名称	描述
`source: MatChipGrid`	发出事件的芯片网格。
`value: any`	发出事件时芯片网格的值。

接口

`MatChipEvent`

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

属性

名称	描述
`chip: MatChip`	触发该事件的纸片。

`MatChipEditedEvent`

表示当单个 mat-chip 被编辑时触发的事件。

属性

名称	描述
`value: string`	最终的编辑值。

`MatChipInputEvent`

表示 matChipInput 上的输入事件。

属性

名称	描述
`chipInput: MatChipInput`	对发出事件的纸片输入的引用。
`value: string`	输入框的值。
Deprecated `input: HTMLInputElement`	触发该事件的原生 `<input>`。

`MatChipsDefaultOptions`

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

属性

名称	描述
`hideSingleSelectionIndicator: boolean`	是否应隐藏单选的图标指示器。
`separatorKeyCodes: readonly number[] \| ReadonlySet<number>`	会触发 chipEnd 事件的键盘代码列表。

`MatChipTextControl`

文本控件的接口，用于驱动与 mat-chip-list 的交互。

属性

名称	描述
`empty: boolean`	文本控件是否为空。
`focused: boolean`	文本控件是否具有浏览器焦点。
`id: string`	文本控件的唯一标识符。
`placeholder: string`	文本控件的占位符文本。

方法

focus
让文本控件获得焦点。

setDescribedByIds
设置描述输入框的 ID 列表。
参数
ids `string[]`

常量

`MAT_CHIPS_DEFAULT_OPTIONS`

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

const MAT_CHIPS_DEFAULT_OPTIONS: InjectionToken<MatChipsDefaultOptions>;

`MAT_CHIP_AVATAR`

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

const MAT_CHIP_AVATAR: InjectionToken<unknown>;

`MAT_CHIP_TRAILING_ICON`

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

const MAT_CHIP_TRAILING_ICON: InjectionToken<unknown>;

`MAT_CHIP_REMOVE`

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

const MAT_CHIP_REMOVE: InjectionToken<unknown>;

`MAT_CHIP`

此注入令牌用于避免 MatChip 和 MatChipAction 之间的循环依赖。

const MAT_CHIP: InjectionToken<unknown>;

Angular Material 芯片组件的 API 参考

指令

MatChip

属性

方法

MatChipOption 继承自 MatChip

属性

方法

MatChipRow 继承自 MatChip

属性

方法

MatChipSet

属性

方法

MatChipListbox 继承自 MatChipSet

属性

方法

MatChipGrid 继承自 MatChipSet

属性

方法

MatChipInput

属性

方法

MatChipAvatar

MatChipTrailingIcon

属性

方法

MatChipRemove

属性

方法

MatChipEditInput

方法

类

MatChipSelectionChange

属性

MatChipListboxChange

属性

MatChipGridChange

属性

接口

MatChipEvent

属性

MatChipEditedEvent

属性

MatChipInputEvent

属性

MatChipsDefaultOptions

属性

MatChipTextControl

属性

方法

常量

MAT_CHIPS_DEFAULT_OPTIONS

MAT_CHIP_AVATAR

MAT_CHIP_TRAILING_ICON

MAT_CHIP_REMOVE

MAT_CHIP

`MatChip`

`MatChipOption` 继承自 MatChip

`MatChipRow` 继承自 MatChip

`MatChipSet`

`MatChipListbox` 继承自 MatChipSet

`MatChipGrid` 继承自 MatChipSet

`MatChipInput`

`MatChipAvatar`

`MatChipTrailingIcon`

`MatChipRemove`

`MatChipEditInput`

`MatChipSelectionChange`

`MatChipListboxChange`

`MatChipGridChange`

`MatChipEvent`

`MatChipEditedEvent`

`MatChipInputEvent`

`MatChipsDefaultOptions`

`MatChipTextControl`

`MAT_CHIPS_DEFAULT_OPTIONS`

`MAT_CHIP_AVATAR`

`MAT_CHIP_TRAILING_ICON`

`MAT_CHIP_REMOVE`

`MAT_CHIP`