Angular Material List 组件 API 全解析从 mat-list 到 SelectionList 的完整开发指南【免费下载链接】componentsComponent infrastructure and Material Design components for Angular项目地址: https://gitcode.com/GitHub_Trending/co/components本篇技术指南以 Angular Materialco/components 仓库中angular/material/list的 API 报告文件为核心骨架系统讲解mat-list、mat-nav-list、mat-action-list、mat-selection-list四大列表变体的组件与指令 API、源码实现原理、无障碍实践以及官方测试 Harness 的完整用法。读完本文你将掌握列表项内容分区指令Title/Line/Meta、选择列表的ControlValueAccessor双向绑定机制、单选/多选切换与hideSingleSelectionIndicator全局配置并能用 Component Harness 编写可跨测试框架复用的列表测试。一、文档定位什么是 API Golden 文件仓库中的 goldens/material/list/index.api.md 是由 API Extractor记录angular/material/list/testing的 Harness 测试 API。真正的使用文档位于 src/material/list/list.md实现源码位于 src/material/list 目录。下面我们把三者结合起来逐层剖析。二、列表家族总览四种容器组件API 报告中清晰给出了四个公开容器组件它们都继承自内部基类MatListBase见 src/material/list/list-base.ts组件选择器用途默认 roleMatListmat-list基础列表纯展示无行为无装饰性MatNavListmat-nav-list导航列表每个项是锚点navigationMatActionListmat-action-list操作列表每个项是按钮groupMatSelectionListmat-selection-list选择列表项为可选中选项listbox从源码看四种容器的差异非常精简list.ts 中的MatList模板仅有ng-content/ng-contentMatListBase中_isNonInteractive true即默认纯装饰、无任何交互。nav-list.ts 与 action-list.ts 都将_isNonInteractive覆盖为false让列表项进入交互模式——源码注释说明了原因MDC 规范下交互列表的项只通过键盘可达而导航/操作列表希望每个项都能用 Tab 键直接聚焦因此没有继承交互基类而是让所有项均可通过 Tab 到达。2.1 基础列表与列表项最简单的用法是纯文本单行列表mat-list mat-list-itemPepper/mat-list-item mat-list-itemSalt/mat-list-item mat-list-itemPaprika/mat-list-item /mat-listMatListItem的选择器同时支持元素形式和属性形式mat-list-item, a[mat-list-item], button[mat-list-item]见 list.ts因此锚点与按钮可以直接复用列表项样式。2.2 导航列表MatNavList导航列表用于每一项都是跳转到其他 URL 的锚点的场景。简单导航列表可直接在a上使用mat-list-item属性mat-nav-list for (link of list; track link) { a mat-list-item href... [activated]link.isActive{{ link }}/a } /mat-nav-listactivated是MatListItem的输入属性用于标记当前激活页见 list.ts。它经由coerceBooleanProperty做布尔强制转换并驱动aria-current属性当宿主元素是a且activated为真时返回page否则返回null见 list.ts同时通过 host 绑定添加mdc-list-item--activated样式类。复杂导航列表如每个条目有多个目标则把锚点包进mat-list-item再用内容分区指令组织mat-nav-list for (link of links; track link) { mat-list-item [activated]link.isActive a matListItemTitle href...{{ link }}/a button matIconButton (click)showInfo(link) matListItemMeta mat-iconinfo/mat-icon /button /mat-list-item } /mat-nav-list2.3 操作列表MatActionList每个条目执行某种动作的列表使用mat-action-list条目是buttonmat-action-list button mat-list-item (click)save()Save/button button mat-list-item (click)undo()Undo/button /mat-action-listMatListItemBase构造器list-base.ts会自动为没有显式type属性的宿主button补上typebutton避免表单提交副作用。三、列表项内容分区指令核心 APIAPI 报告与 list-item-sections.ts 共同定义了五个内容分区指令是构建多行列表的关键指令说明对应 CSS 类matListItemTitle列表项标题多行列表必须全文不换行每项只能一个mdc-list-item__primary-textmatListItemLine列表项内的一行文本最多两个mdc-list-item__secondary-textmatListItemIcon通常置于列表项开头的图标mat-mdc-list-item-iconmatListItemAvatar通常置于列表项开头的头像图片mat-mdc-list-item-avatarmatListItemMeta在列表项末尾的 meta 区插入内容图标、按钮等mdc-list-item__end其中MatListItemIcon与MatListItemAvatar继承自_MatListItemGraphicBase见 list-item-sections.ts它根据列表项中复选框/单选钮的位置自动应用mdc-list-item__start或mdc-list-item__end类在普通列表项中图形默认对齐到开头在MatListOption中仅当复选框/单选钮位于末尾togglePosition after时图形才对齐到开头。3.1 多行列表写法两行列表标题 一行描述mat-list for (message of messages; track message) { mat-list-item h3 matListItemTitle{{message.from}}/h3 p matListItemLine span{{message.subject}}/span span classdemo-2 -- {{message.content}}/span /p /mat-list-item } /mat-list三行列表标题 两行描述mat-list for (message of messages; track message) { mat-list-item h3 matListItemTitle{{message.from}}/h3 p matListItemLine{{message.subject}}/p p matListItemLine classdemo-2{{message.content}}/p /mat-list-item } /mat-list注意标题标签类型应按 DOM 层级语义自由选择不必拘泥于示例中的h3。3.2 行数推断与lines输入列表项的行数支持自动推断与显式声明两种方式。list-base.ts 的_inferLinesFromContent按标题数 行数 (有无未分区文本 ? 1 : 0)推断list-base.ts 的lines输入则通过coerceNumberProperty显式指定行数可激活文本换行并预留更多空间。按 Material Design 规范列表项最多支持三行list-base.ts。在开发模式下list-base.ts 的sanityCheckListItemContent会给出四条一致性警告一个列表项不能有多个标题有行文本必须有标题无标题时不能声明超过一行的换行内容最多三行。这些检查位于顶层函数中生产构建可被 Terser 死代码消除。3.3 图标、头像与 Meta 区图标列表使用matListItemIconmat-list for (message of messages; track message) { mat-list-item mat-icon matListItemIconfolder/mat-icon h3 matListItemTitle{{message.from}}/h3 p matListItemLine span{{message.subject}}/span span classdemo-2 -- {{message.content}}/span /p /mat-list-item } /mat-listMeta 区末尾放置图标或其他内容使用matListItemMetamat-list for (message of messages; track message) { mat-list-item div matListItemMeta mat-iconfolder/mat-icon /div h3 matListItemTitle{{message.from}}/h3 p matListItemLine span{{message.subject}}/span span classdemo-2 -- {{message.content}}/span /p /mat-list-item } /mat-list头像列表img matListItemAvatar src... alt...即可在开头显示头像图片。当既有前导图形又有尾部 meta 时宿主元素会获得mat-mdc-list-item-both-leading-and-trailing工具类list.ts便于样式统一处理。3.4 分组小标题与分隔线API 报告中的MatListSubheaderCssMatStyler对应[mat-subheader], [matSubheader]选择器用于给列表分组加小标题MatDividermat-divider提供vertical与inset两个布尔输入。组合示例mat-list h3 matSubheaderFolders/h3 for (folder of folders; track folder) { mat-list-item mat-icon matListIconfolder/mat-icon h4 matListItemTitle{{folder.name}}/h4 p matListItemLine classdemo-2 {{folder.updated}} /p /mat-list-item } mat-divider/mat-divider h3 matSubheaderNotes/h3 for (note of notes; track note) { mat-list-item mat-icon matListIconnote/mat-icon h4 matListItemTitle{{note.name}}/h4 p matListItemLine classdemo-2 {{note.updated}} /p /mat-list-item } /mat-list四、选择列表MatSelectionList与MatListOption选择列表是最复杂的变体API 报告围绕它列出了最多的公开符号MatSelectionList、MatListOption、MatSelectionListChange、MatListOptionTogglePosition、SelectionList接口、SELECTION_LIST令牌、MAT_SELECTION_LIST_VALUE_ACCESSOR。4.1 基本用法与事件mat-selection-list提供一个选择值的界面每个mat-list-option是一个选项mat-selection-list [(ngModel)]selectedOptions mat-list-option value1 [selected]trueOption 1/mat-list-option mat-list-option value2Option 2/mat-list-option /mat-selection-list选项变化通过selectionChange事件发出载荷为MatSelectionListChange包含source源MatSelectionList与options发生变化的MatListOption[]两个字段selection-list.ts。重要约束选择列表的选项内部不应再嵌套任何交互控件按钮、锚点等因为整个列表是一个复合组件其键盘与焦点行为由列表统一管理。4.2 关键输入属性MatSelectionList的输入属性均可从 API 报告与 selection-list.ts 验证属性类型默认值说明multiplebooleantrue是否允许多选默认多选显示复选框设为false切换为单选显示单选钮。初始化后不可再修改否则抛错selection-list.tscolorThemePaletteaccent复选/单选钮的主题色。仅 M2 主题生效M3 无效果selection-list.tscompareWith(o1, o2) boolean比较判断选项值与选中值是否相等决定哪些选项显示为选中selection-list.tshideSingleSelectionIndicatorbooleanfalse单选模式下是否隐藏指示器。可从MAT_LIST_CONFIG全局配置默认值selection-list.tsdisabledbooleanfalse禁用整个列表禁用时所有选项移出 Tab 顺序tabindex-1并设置aria-disabledMatListOption的输入属性属性类型默认值说明valueany—选项的值ngModel/formControl读到的就是选中项的值数组selectedbooleanfalse选中状态支持双向绑定[(selected)]配合selectedChange事件togglePositionbefore \| afterMatListOptionTogglePositionafter复选框/单选钮出现在文本之前还是之后colorThemePalette继承列表的color未显式设置时回退到所属列表的颜色list-option.tsMatListOption还提供toggle()、focus()、getLabel()等公开方法getLabel()用于列表的 typeahead 打字过滤——优先取标题元素的文本无标题时回退到未分区文本list-option.ts。4.3 ControlValueAccessor 与表单集成MatSelectionList实现了ControlValueAccessorselection-list.ts通过MAT_SELECTION_LIST_VALUE_ACCESSOR内部常量NG_VALUE_ACCESSOR提供器接入 Angular 表单体系因此可无缝用于ngModel、formControlName与响应式表单writeValue(values: string[])把模型值写回视图通过compareWith匹配选项并设置选中态selection-list.ts。_reportValueChange()收集选中选项的值数组_getSelectedOptionValues并回调_onChange实现视图到模型的同步selection-list.ts。setDisabledState(isDisabled)同步表单禁用状态到组件。registerOnChange/registerOnTouched注册模型更新与失焦回调。公开的selectAll()/deselectAll()返回发生变化的选项数组selectedOptions是SelectionModelMatListOption可直接编程操作选中集合。4.4 键盘交互与焦点管理MatSelectionList采用 WAI-ARIA 的 listbox 交互模式通过FocusKeyManager实现漫游 Tabindexroving tabindex管理selection-list.tsArrowUp/ArrowDown在选项间移动焦点Home/End跳到首/末选项withHomeAndEnd连续输入字符触发 typeahead 过滤withTypeAhead焦点到达边界时循环withWrapEnter/Space切换当前活动选项的选中状态_toggleOnInteraction跳过禁用项多选模式下Ctrl/Cmd A全选/取消全选selection-list.ts。值得注意的细节skipPredicate(() false)表示禁用选项也保留在 Tab 顺序中——源码注释引用了 WAI-ARIA APG 键盘接口实践明确指出 listbox 中的禁用选项应保持可聚焦selection-list.ts。MatListOption的选中状态与指示器位置联动多选时在指定位置渲染复选框_hasCheckboxAt单选且未隐藏指示器时渲染单选钮_hasRadioAt并据此应用mdc-list-item--with-leading-checkbox/radio等 MDC 类list-option.ts。五、全局默认配置MAT_LIST_CONFIGAPI 报告中的MatListConfig接口只有一个可选字段hideSingleSelectionIndicator配套的MAT_LIST_CONFIG注入令牌定义在 tokens.ts。它的作用是提供列表模块的全局默认选项providers: [ {provide: MAT_LIST_CONFIG, useValue: {hideSingleSelectionIndicator: true}}, ]在 list-base.ts 中MatListBase通过inject(MAT_LIST_CONFIG, {optional: true})注入该配置MatSelectionList在初始化hideSingleSelectionIndicator时以_defaultOptions?.hideSingleSelectionIndicator ?? false作为默认值selection-list.ts实现全局默认 实例覆盖的两级配置。另外API 报告还公开了三个 DI 令牌用于解耦类引用、避免元数据滞留MAT_LISTlist.ts、MAT_NAV_LISTnav-list.ts、SELECTION_LISTlist-option.ts后者还用于避免MatListOption与MatSelectionList之间的循环依赖。六、模块组织MatListModuleAPI 报告中的MatListModuleNgModule 声明与导出揭示了依赖关系模块内部导入了ObserversModule内容变更观察用于行数自动更新、MatRippleModule波纹反馈与MatPseudoCheckboxModule伪复选框对外导出BidiModule、四类列表、MatDividerModule及所有内容分区指令index.api.md。模块的导入方式import {MatListModule} from angular/material/list; NgModule({ imports: [MatListModule], }) export class MyModule {}七、无障碍实践官方文档 list.md 对不同列表变体的无障碍要求做了明确划分导航列表根元素自动设置rolenavigation必须通过aria-label或aria-labelledby提供可访问标签。为获得最佳屏幕阅读器体验建议用ulli包裹锚点mat-nav-list aria-labelSelect a folder ul for (link of list; track link) { li a mat-list-item href... [activated]link.isActive{{ link }}/a /li } /ul /mat-nav-list操作列表给mat-action-list添加rolelist与aria-label并用li包裹每个按钮mat-action-list rolelist aria-labelPost actions li button mat-list-item (click)save()Save/button /li li button mat-list-item (click)undo()Undo/button /li /mat-action-list选择列表使用rolelistbox交互模式键盘输入与焦点管理全部由组件处理同样必须提供aria-label或aria-labelledby描述选择内容。文档特别提醒hideSingleSelectionIndicator会降低可访问性——用户将更难甚至无法通过视觉识别选中项因此默认保持显示单选指示器。自定义场景默认的mat-list是纯装饰性的不设置任何 role、ARIA 属性或键盘快捷键等同于页面上一组div。若用于展示非交互内容列表应手动为列表添加rolelist、为每个列表项添加rolelistitem。八、测试 Harness APIangular/material/list/testinggoldens/material/list/testing/index.api.md 完整记录了官方测试 Harness。它构建在angular/cdk/testing之上ComponentHarness、HarnessPredicate、ContentContainerComponentHarness因此同一套测试代码可运行于 Karma真实浏览器与 Protractor 等不同测试环境。8.1 Harness 一览Harness 类对应组件主要方法MatListHarnessmat-list通过with()过滤getItems()等MatActionListHarnessmat-action-list获取MatActionListItemHarnessMatNavListHarnessmat-nav-list获取MatNavListItemHarnessMatSelectionListHarnessmat-selection-listselectItems()、deselectItems()、isDisabled()MatListItemHarnessmat-list-item文本断言、blur/focus/isFocusedMatListOptionHarnessmat-list-optionselect/deselect/toggle、isSelected、getCheckboxPosition/getRadioPositionMatSubheaderHarnessmat-subheadergetText()8.2 过滤器Harness Filters列表项过滤器BaseListItemHarnessFilters提供了丰富的文本匹配维度interface BaseListItemHarnessFilters extends BaseHarnessFilters { fullText?: string | RegExp; // 完整文本 secondaryText?: string | RegExp | null; tertiaryText?: string | RegExp | null; title?: string | RegExp; text?: string | RegExp; // 已废弃 }ListOptionHarnessFilters额外支持selected?: booleanNavListItemHarnessFilters额外支持activated?: boolean与href?: string | RegExp | nullSubheaderHarnessFilters支持text?: string | RegExp。8.3 枚举MatListItemSection.CONTENT .mdc-list-item__content列表项内容区块的 CSS 选择器可用于定位文本区域。MatListItemType单行ONE_LINE_ITEM 0、两行TWO_LINE_ITEM 1、三行THREE_LINE_ITEM 2三种行数类型。8.4 测试示例import {MatSelectionListHarness} from angular/material/list/testing; const list await loader.getHarness(MatSelectionListHarness); const options await list.getItems({selected: true}); expect(options.length).toBe(1); // 通过文本选中某个选项 await list.selectItems({title: /Pepper/});MatListHarnessBase泛型设计如MatSelectionListHarness extends MatListHarnessBasetypeof MatListOptionHarness, MatListOptionHarness, ListOptionHarnessFilters使得四种列表 Harness 共享同一套取列表、取选项、过滤的基础逻辑只在具体选项类型上分叉。九、总结angular/material/list通过一个基类 四种容器 五类内容分区指令的组合覆盖了展示、导航、操作、选择四大列表场景。其中选择列表是 API 最密集的组件ControlValueAccessor表单集成、SelectionModel状态管理、listbox 键盘交互与 roving tabindex 均由组件内置。API golden 文件与源码 src/material/list、官方文档 list.md 三者相互印证是开发者查阅公共契约、理解实现细节与编写测试的权威依据。更多进阶内容如 M3 主题下的颜色定制可继续研读仓库中的主题样式文件 src/material/list/_list-theme.scss 与 src/material/list/_m3-list.scss。【免费下载链接】componentsComponent infrastructure and Material Design components for Angular项目地址: https://gitcode.com/GitHub_Trending/co/components创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考