深入解读 Angular Material Tree 公共 API从指令结构到扁平/嵌套数据源实现【免费下载链接】componentsComponent infrastructure and Material Design components for Angular项目地址: https://gitcode.com/GitHub_Trending/co/componentsmat-tree是 Angular Material 提供的数据层级展示组件它建立在 CDK Tree 的基础上用 Material Design 风格封装了一套完整、可无障碍访问的树形控件。本篇文章以仓库中由 API Extractor 自动生成的 goldens/material/tree/index.api.md 为骨架结合 src/material/tree 的源码实现与 src/material/tree/tree.md 使用文档逐项解析angular/material_tree的完整公开 API组件、指令、数据源、模块声明以及levelAccessor/childrenAccessor带来的新一代无障碍实现路径。读完后你将能准确理解每个公开类型的能力边界与弃用状态并能在自己的 Angular 项目中正确选用扁平树或嵌套树方案。一、API 报告概览一个包裹 CDK Tree 的 Material 封装层angular/material_tree的 API 报告由 API Extractor 自动生成文件头明确标注 Do not edit this file. It is a report generated by API Extractor它精确刻画了包的公开导出面。从报告的 import 列表可以看出整个 Material Tree 的几乎所有功能都来源于对 CDK 树形基础设施的复用CdkTree、CdkTreeNode、CdkNestedTreeNode、CdkTreeNodeDef、CdkTreeNodePadding、CdkTreeNodeToggle、CdkTreeNodeOutlet均来自angular/cdk/treeDataSource、CollectionViewer来自angular/cdk/collectionsFlatTreeControl、TreeControl来自angular/cdk/tree运行期还依赖angular/cdk/bidiBidiModule用于 RTL 布局支持。报告的 public-api.ts 将 7 个源文件全部重新导出node、padding、tree、tree-module、toggle、outlet以及data-source下的扁平/嵌套两个数据源。这 7 个模块对应了报告中的 8 个公开类公开类声明位置继承自职责MatTreetree.tsCdkTree树容器组件mat-treeMatTreeNodenode.tsCdkTreeNode扁平树节点mat-tree-nodeMatNestedTreeNodenode.tsCdkNestedTreeNode嵌套树节点mat-nested-tree-nodeMatTreeNodeDefnode.tsCdkTreeNodeDef节点模板定义[matTreeNodeDef]MatTreeNodePaddingpadding.tsCdkTreeNodePadding层级缩进[matTreeNodePadding]MatTreeNodeToggletoggle.tsCdkTreeNodeToggle展开/收起开关[matTreeNodeToggle]MatTreeNodeOutletoutlet.tsCdkTreeNodeOutlet子节点渲染出口[matTreeNodeOutlet]MatTreeModuletree-module.ts—NgModule 聚合声明这种“薄封装”的设计意味着Material Tree 与 CDK Tree 使用完全相同的接口与数据流区别只在于选择器前缀由cdk-换成mat-并叠加了 Material 的视觉样式与无障碍增强。二、MatTree组件树的容器MatTreeT, K T是树的容器组件继承CdkTreeT, K。其源码tree.ts揭示了几个关键实现细节选择器与导出名selector: mat-treeexportAs: matTree模板ng-container matTreeNodeOutlet/ng-container即根节点由树模板中的matTreeNodeOutlet出口渲染样式与封装styleUrl: tree.cssencapsulation: ViewEncapsulation.None类名为mat-tree变更检测注释明确指出沿用CdkTree的默认变更检测策略ChangeDetectionStrategy.Eager因为树的数据流复杂不适合 OnPush 下的局部更新假设DI 提供providers: [{provide: CdkTree, useExisting: MatTree}]——这是理解整个封装的钥匙任何通过CdkTree注入的依赖在mat-tree中都会解析到MatTree实例CDK 的内部逻辑原封不动地跑在 Material 组件上。组件内部只声明了一个ViewChild(MatTreeNodeOutlet, {static: true}) _nodeOutlet字段作为数据节点插入的出口引用。三、三种节点指令模板、扁平节点与嵌套节点3.1MatTreeNodeDef节点模板定义[matTreeNodeDef]指令node.ts用于捕获一个节点的模板并支持matTreeNodeDefWhen谓词对应 CDK 的when输入当数据节点满足条件时选择该模板。它还暴露了一个matTreeNode输入把节点数据导出到模板上下文中供模板内的绑定使用mat-tree-node *matTreeNodeDeflet node {{node.key}}: {{node.value}} /mat-tree-node同一个树中可以存在多个节点模板运行时按when谓词逐条匹配tree.md 中的“Conditional template”示例展示了如何为特殊节点渲染不同外观。3.2MatTreeNode扁平树节点mat-tree-node是扁平树的节点元素继承CdkTreeNode。其 host 绑定node.ts集中体现了无障碍与交互逻辑[attr.aria-expanded]动态反映节点的展开状态[attr.aria-level]level 1用层级渲染出 ARIA level[attr.aria-posinset]/[attr.aria-setsize]节点在兄弟集合中的位置与集合大小(click)_focusItem()点击时聚焦节点[tabindex]_getTabindexAttribute()由TreeKeyManager统一管理焦点。API 报告中标记的两个弃用成员也在这段源码里得到印证deprecatedbreaking-change 21.0.0移除tabIndexInputBinding别名tabIndex源码注释说明默认情况下MatTreeNode通过TreeKeyManager管理焦点直接设置 tabIndex 会让键盘管理器进入意外状态因此建议避免使用node.tsdisableddisabled只是isDisabled的别名源码注释同样标记为 21.0.0 移除node.ts。另外ngAcceptInputType_disabled与ngAcceptInputType_tabIndexInputBinding两个静态字段是 Angular 编译器生成的类型收窄标记用于把模板中的字符串输入安全转换为boolean/number。3.3MatNestedTreeNode嵌套树节点mat-nested-tree-node用于嵌套树继承CdkNestedTreeNode并实现了AfterContentInit、OnInit、OnDestroy三个生命周期接口。它与扁平节点最大的区别是子节点在 DOM 中直接嵌套在父节点内部因此父节点的模板必须包含一个matTreeNodeOutlet出口mat-nested-tree-node *matTreeNodeDeflet node {{node.value}} ng-container matTreeNodeOutlet/ng-container /mat-nested-tree-node源码中还值得注意 DI 提供关系node.tsMatNestedTreeNode同时把自己注册为CdkNestedTreeNode、CdkTreeNode与CDK_TREE_NODE_OUTLET_NODE这使得嵌套节点的子节点出口能拿到父节点引用。3.4 生命周期钩子重写的来历MatTreeNode和MatNestedTreeNode都重写了ngOnInit/ngAfterContentInit/ngOnDestroy并仅调用super。源码注释解释了原因这是对 Angular 两个历史 issue#23091、#19145的规避——AOT 编译下父类的生命周期钩子不会被自动调用因此需要子类显式桥接。四、交互与布局指令Toggle、Padding、Outlet4.1MatTreeNodeToggle展开/收起开关[matTreeNodeToggle]指令toggle.ts是CdkTreeNodeToggle的空包装暴露matTreeNodeToggleRecursive输入。将其附着在按钮上点击或键盘激活即可触发树的展开/收起设为true时递归展开/收起整棵子树mat-tree-node *matTreeNodeDeflet node button matTreeNodeToggle aria-labeltoggle tree node [matTreeNodeToggleRecursive]true mat-iconexpand/mat-icon /button {{node.value}} /mat-tree-node文档特别提醒toggle 应挂在button元素上以保证键盘可达若使用图标按钮必须提供aria-labeltree.md Adding expand/collapse 一节。4.2MatTreeNodePadding扁平树专属缩进[matTreeNodePadding]padding.ts仅用于扁平树因为扁平树的所有节点在 DOM 中是同级兄弟无法用 CSS 的嵌套结构表达层级必须靠缩进呈现深度level别名matTreeNodePadding节点深度源码注释明确说明padding 为level * indent像素并通过numberAttribute做输入转换indent别名matTreeNodePaddingIndent每级缩进量默认 40px注释注明取自 Material Design 菜单子菜单规范。嵌套树不需要该指令——它的 DOM 天然嵌套缩进直接用 CSS 实现即可。4.3MatTreeNodeOutlet子节点渲染出口[matTreeNodeOutlet]outlet.ts实现了CdkTreeNodeOutlet通过inject(ViewContainerRef)拿到出口位置的视图容器并把CDK_TREE_NODE_OUTLET_NODE即宿主嵌套节点可选注入_node字段。它在MatTree模板与嵌套节点模板中标记子节点的插入位置是嵌套树 DOM 结构成立的基础。五、数据源扁平化与嵌套数据的两种接入方式5.1MatTreeNestedDataSourceT嵌套数据源嵌套数据源nested-data-source.ts内部用一个BehaviorSubjectT[]持有根节点数组。connect(collectionViewer)合并viewChange与数据流直接返回this.data。它的设计哲学在注释中写得很清楚嵌套数据源不需要考虑扁平化也不需要处理展开/收起的数据重组——这些交给TreeControl和各非叶节点即可。5.2MatTreeFlattenerT, F, K扁平化引擎MatTreeFlattenerflat-data-source.ts负责把嵌套结构T转换为带层级信息的扁平结构F。构造器接收四个函数参数类型作用transformFunction(node: T, level: number) F节点转换附加expandable、level等字段getLevel(node: F) number读取扁平节点的层级isExpandable(node: F) boolean判断节点是否可展开getChildren(node: T) ObservableT[] \| T[] \| undefined \| null取出节点的子节点支持同步数组或 Observable其核心算法是三个方法_flattenNode先变换当前节点并压入结果数组若可展开则取出子节点同步数组直接递归Observable 则pipe(take(1))订阅一次后再递归flat-data-source.ts_flattenChildren遍历子节点并维护parentMap记录每层是否是最后一个兄弟供树状连线等场景使用flat-data-source.tsexpandFlattenedNodes结合TreeControl的展开状态把扁平节点过滤成当前可见列表flat-data-source.ts。文件头部的注释给出了一个直观示例{key: Fruits, children: [...]}会被展开成{key: Fruits, expandable: true, level: 1}、{key: Apple, expandable: false, level: 2}等扁平节点。5.3MatTreeFlatDataSourceT, F, K扁平数据源MatTreeFlatDataSourceflat-data-source.ts在内部维护三个BehaviorSubject_data、_flattenedData、_expandedData设置data时依次触发更新_data→ 用 flattener 生成全量扁平节点 → 同步到treeControl.dataNodesflat-data-source.tsconnect合并三个信号源collectionViewer.viewChange滚动/视图变化、treeControl.expansionModel.changed展开状态变化、_flattenedData数据变更每次重算可见节点并推送给树flat-data-source.ts。这套机制的优点是滚动友好由于输出永远是单层数组可以无缝配合虚拟滚动等场景。API 报告与源码都将MatTreeFlattener、MatTreeFlatDataSource标记为deprecated建议改用childrenAccessor方式预计 21.0.0 移除。5.4 新一代接入方式levelAccessor与childrenAccessortree.md 明确给出了两种推荐的接入方式levelAccessor传入一个函数给定数据项返回其所在层级。数据源输出的是已扁平化的单数组数据源需要监听(expansionChange)事件并在展开/收起时重新提供可见节点数组childrenAccessor传入一个函数给定数据项返回其子节点。此时数据源只需提供根节点数组树的层级关系由该访问器即时解析trackBy与ngFor的trackBy类似告诉树如何唯一标识节点用于在数据更新时高效复用 DOM 节点mat-tree [dataSource]dataSource [treeControl]treeControl [trackBy]trackByFn5.5 无障碍Accessibilitymat-tree实现了 WAI-ARIA APG 的 tree widget 模式tree.md Accessibility 一节包含键盘导航、正确的 roles 与 ARIA 属性。新无障碍特性要求使用levelAccessor/childrenAccessor使用旧式treeControl的树因向后兼容原因无法实现正确的无障碍行为。两个关键点isExpandable所有可展开的mat-tree-node/mat-nested-tree-node必须设置该属性树才能正确判断节点可展开性(activation)事件树节点通过键盘激活时会触发activation输出可用于执行与点击等价的操作mat-tree-node *matTreeNodeDeflet node (click)performAction(node) (activation)performAction($event) /mat-tree-node这里$event携带节点数据与matTreeNodeDef隐式导出的数据一致。对应地MatTreeNode与MatNestedTreeNode的指令声明中都声明了outputs: [activation, expandedChange]node.tsAPI 报告里也能看到这两个事件。六、MatTreeModule模块声明与使用方式MatTreeModuletree-module.ts的ɵmod声明揭示了完整的依赖图importsCdkTreeModule 7 个 Material 指令MatNestedTreeNode、MatTreeNodeDef、MatTreeNodePadding、MatTreeNodeToggle、MatTree、MatTreeNode、MatTreeNodeOutletexportsBidiModule提供 RTL 方向支持 同样的 7 个指令。因此在实际项目中使用树功能只需在模块中导入MatTreeModule即可无需额外导入 CDK Tree 模块或 Bidi 模块import {MatTreeModule} from angular/material/tree; NgModule({ imports: [MatTreeModule], }) export class MyModule {}由于MatTree、MatTreeNode等均通过providers: [{provide: CdkXxx, useExisting: MatXxx}]覆盖了 CDK 的注入令牌即便同时导入了CdkTreeModule也不会产生重复逻辑。七、进一步探索从 API 报告到源码与测试API 报告是了解angular/material_tree公开面的最快入口但要真正掌握行为细节建议继续阅读仓库内以下资源使用文档src/material/tree/tree.md——包含扁平/嵌套树模板、toggle、padding、条件模板、数据源接入、无障碍等完整示例核心实现tree.ts、node.ts、padding.ts、toggle.ts、outlet.ts数据源flat-data-source.ts、nested-data-source.ts测试用例tree.spec.ts、tree-using-tree-control.spec.ts、tree-using-legacy-key-manager.spec.ts分别覆盖新式访问器、treeControl与旧式键盘管理器三条路径测试 Harnesstesting/tree-harness.ts 与 testing/tree-harness.spec.ts可用于组件测试中定位树节点、读取展开状态等样式与主题tree.scss、_tree-theme.scss、_m2-tree.scss 与 _m3-tree.scssM2/M3 双主题实现Golden 基准goldens/material/tree/index.api.md 本身即公开 API 的权威基准仓库通过 API Extractor 校验源码与基准的一致性任何 API 变更都会在此文件中体现。总结angular/material_tree的公开 API 高度凝练7 个指令/组件加上 2 个其中一个已弃用的数据源与 1 个扁平化工具类全部建立在 CDK Tree 之上。通过 API 报告可以清晰分辨出当前推荐使用的MatTreeMatTreeNodelevelAccessor/childrenAccessor/isExpandable新式组合与已标记弃用的MatTreeFlatDataSource/MatTreeFlattener/tabIndex/disabled计划在 21.0.0 移除。理解这份 API 报告就掌握了这一组件的全部能力边界与演进方向——这正是一份由 API Extractor 生成的 API 报告相较于普通使用文档的独特价值所在。【免费下载链接】componentsComponent infrastructure and Material Design components for Angular项目地址: https://gitcode.com/GitHub_Trending/co/components创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
