Angular Components 无障碍 Tabs 组件angular/aria_tabs公开 API 完全解析【免费下载链接】componentsComponent infrastructure and Material Design components for Angular项目地址: https://gitcode.com/GitHub_Trending/co/components本文以仓库中 API Extractor 生成的黄金报告 goldens/aria/tabs/index.api.md 为骨架深入解析 Angular Components 项目中angular/aria无障碍标签页组件ARIA Tabs Pattern的完整公开 API 表面。这份报告并非手写文档而是由 API Extractor 自动生成的类型级契约逐条列出了一个指令模块对外暴露的全部类、信号输入、输出与注入令牌。阅读本文后你将能够理解ngTabs/ngTabList/ngTab/ngTabPanel/ngTabContent五个指令的职责划分与协作方式掌握每个输入信号orientation、focusMode、selectionMode、wrap、softDisabled、selectedTab等的取值与默认值并透过 src/aria/private/tabs/tabs.ts 的 UI Pattern 实现看清无障碍交互焦点管理、键盘导航、选区在底层是如何被封装与驱动的。文档定位一份自动生成的 API 契约goldens/aria/tabs/index.api.md的文件头明确声明Do not edit this file. It is a report generated by API Extractor.这意味着该文档是对src/aria/tabs/包公开导出内容的机器可读快照任何对公开 API 的改动都会使该黄金报告与源码不一致从而在 CIapprove-api-golden类检查中暴露。因此这份文档本身就是公开 API 边界的最权威索引凡是在其中出现的符号都是消费者可以稳定依赖的接口凡是标注(undocumented)的成员如ngOnInit、ngOnDestroy、_pattern等则属于框架生命周期或内部实现细节不应作为公共契约使用。对照 src/aria/tabs/public-api.ts 可以看到该包公开导出了 7 个符号5 个指令Tabs、TabList、Tab、TabPanel、TabContent与 2 个注入令牌TABS、TAB_LIST另外通过ɵɵDeferredContent/ɵɵDeferredContentAware复导出内部的延迟内容基础指令。下文按报告中的出现顺序逐一展开。指令矩阵五个指令如何分工从 API 报告与源码看标签页交互被拆分为五个互相配合的指令形成三层结构指令选择器导出声明职责Tabs[ngTabs]ngTabs顶层容器协调 TabList 与 TabPanel 的注册与配对TabList[ngTabList]ngTabList管理 Tab 集合、焦点移动、选择策略、方向与键盘导航Tab[ngTab]ngTab单个可选中标签暴露选中/激活状态与open()TabPanel[ngTabPanel]ngTabPanel存放标签对应内容的面板负责可见性与inertTabContentng-template[ngTabContent]ngTabContent结构型指令实现内容的懒加载渲染从源码结构推断三者的注入关系是Tabs通过TABS令牌暴露自身src/aria/tabs/tabs.tsTabList注入TABS并在ngOnInit时调用_register(this)注册自己TabList又通过TAB_LIST令牌暴露自身Tab注入TAB_LIST完成注册。TabPanel直接注入TABS在ngOnInit时向 Tabs 的内容集合注册。TABS与TAB_LIST两个令牌定义于 src/aria/tabs/tab-tokens.ts。TabsngTabs容器与配对枢纽Tabs类本身只实现OnDestroy公开成员非常精简element: HTMLElement—— 宿主元素引用_collection: SortedCollectionTabPanel—— 按 DOM 顺序维护的 TabPanel 有序集合_tabList: WritableSignalTabList | undefined—— 当前注册的 TabList_panelMap/_tabMap/_tabPatterns/_tabPanelPatterns—— 一组computed信号把值 → 底层 Pattern的映射关系响应式地暴露给子指令_register(child: TabList)/_unregister()—— 由 TabList 在生命周期中调用维护_tabList信号。从源码可以看到Tabs通过afterNextRender启动SortedCollection的 DOM 观察startObserving并维护_panelMap——这是Tab校验自己的 value 是否有对应面板的数据来源src/aria/tabs/tab.ts。典型的模板用法如下示例源自 src/aria/tabs/tabs.tsdiv ngTabs ul ngTabList [(selectedTab)]selectedTabValue li ngTab valuetab1Tab 1/li li ngTab valuetab2Tab 2/li li ngTab valuetab3Tab 3/li /ul div ngTabPanel valuetab1 ng-template ngTabContentContent for Tab 1/ng-template /div div ngTabPanel valuetab2 ng-template ngTabContentContent for Tab 2/ng-template /div div ngTabPanel valuetab3 ng-template ngTabContentContent for Tab 3/ng-template /div /divTabListngTabList输入信号最密集的控制核心TabList是输入选项最多的指令全部输入均为 Angular 信号输入input()/model()在 API 报告中体现为InputSignal/ModelSignal类型。下表汇总每个输入的含义、类型与默认值依据 src/aria/tabs/tab-list.ts 与 API 报告输入类型默认值说明orientationhorizontal \| verticalhorizontal标签列表方向映射为宿主aria-orientationwrapboolean经booleanAttribute转换true焦点移动是否在两端循环softDisabledboolean转换truetrue时禁用项仍可聚焦但不可交互false时导航直接跳过禁用项focusModeroving \| activedescendantroving焦点策略roving通过tabindex移动焦点到激活标签activedescendant焦点停留在容器用aria-activedescendant指示selectionModefollow \| explicitfollow选择策略follow聚焦即选中explicit需用户显式操作点击或空格才选中selectedTabstring \| undefinedmodelundefined双向绑定的当前选中标签 value输出别名为selectedTabChangedisabledboolean转换false是否整体禁用标签列表报告中selectedTab的声明带有输出{ selectedTab: selectedTabChange }即模板中应写作[(selectedTab)]value或[selectedTab]value (selectedTabChange)handler($event)。公开方法open与findTabopen(value: string): boolean—— 按 value 打开对应标签面板返回是否成功findTab(value?: string): Tab | undefined—— 在有序集合中按 value 查找Tab。宿主行为TabList的宿主绑定将交互事件转发给底层的TabListPatternsrc/aria/tabs/tab-list.tsroletablist、aria-disabled、aria-orientation、aria-activedescendant、tabindex均由_pattern计算得出(keydown)、(click)、(focusin)统一交由_pattern.onKeydown/onClick/onFocusIn处理实现方向键导航、Home/End、空格/回车选择等无障碍键盘交互。值得注意的实现细节selectedTab模型与内部选中 Pattern 之间通过linkedSignal双向同步并在afterRenderEffect的write阶段回写src/aria/tabs/tab-list.ts这保证了外部绑定 value ↔ 内部选中项始终一致。TabngTab可选项的输入与状态Tab的公开 APIsrc/aria/tabs/tab.ts成员类型说明idInputSignalstring全局唯一标识默认由 CDK 的_IdGenerator生成前缀ng-tab-disabledInputSignalWithTransformboolean, unknown是否禁用经booleanAttribute转换valueInputSignalstring必填唯一值用于关联对应ngTabPanelAPI 报告中required: trueactiveSignalboolean只读是否为当前焦点项映射到宿主data-activeselectedSignalboolean只读是否被选中映射到aria-selectedelementHTMLElement宿主元素引用open()方法打开该标签等价于调用底层TabPattern.open()宿主属性roletab、tabindex、aria-controls、aria-disabled均由_pattern派生aria-controls指向关联 TabPanel 的 idaria-disabled与禁用状态同步。两个工程细节值得注意按钮防表单提交构造函数中若宿主是button且未显式设置type会自动补上typebutton避免误触发表单提交src/aria/tabs/tab.ts。开发期校验在ngDevMode下通过afterRenderEffect检查ngTab的 value 是否有对应ngTabPanel无匹配时向控制台报告违规reportViolations。TabPanelngTabPanel可见性与延迟内容TabPanelsrc/aria/tabs/tab-panel.ts成员类型说明idInputSignalstring全局唯一标识默认由_IdGenerator生成前缀ng-tab-panel-valueInputSignalstring必填与ngTab的 value 匹配visibleSignalboolean只读面板是否可见computed(() !this._pattern.hidden())宿主绑定体现了 ARIA 与隐藏语义的结合src/aria/tabs/tab-panel.tsroletabpanel、tabindex、aria-labelledby指向控制它的标签 id隐藏时设置inert属性[attr.inert]: !visible() ? true : null将隐藏面板从可访问性树中彻底移除源码注释明确说明视觉隐藏仍需额外 CSS 配合。TabPanel还通过hostDirectives挂载了DeferredContentAware输入preserveContent并在afterRenderEffect的write阶段把visible()同步给延迟内容机制——这正是懒加载内容的接入点。开发期同样有两条违规校验面板内必须存在ngTabContent结构指令面板的 value 必须有对应ngTab。TabContentng-template[ngTabContent]懒加载内容TabContent是纯声明式指令src/aria/tabs/tab-content.ts选择器为ng-template[ngTabContent]内部仅通过hostDirectives: [DeferredContent]复用 CDK/私有包中的延迟内容机制内容只有在标签首次激活时才会渲染lazy loading激活后渲染结果被缓存复用。配合TabPanel的preserveContent输入开发者可以控制内容在切换后是否保留在 DOM 中。注入令牌TABS 与 TAB_LISTAPI 报告中的两个常量TABS: InjectionTokenTabs—— 向子指令暴露 Tabs 容器Tabs指令在providers中useExisting提供TAB_LIST: InjectionTokenTabList—— 向子指令暴露 TabListTabList指令的providers中提供。这套令牌体系src/aria/tabs/tab-tokens.ts允许Tab以inject(TAB_LIST)拿到父级列表、再经_tabsParent间接访问 Tabs 的映射形成清晰的依赖方向也便于测试中替换。底层原理UI Pattern 架构与 Behavior 组合API 报告中所有_pattern成员都指向src/aria/private/tabs/tabs.ts中的三个纯 TypeScript 类不依赖 Angular 运行时TabPattern—— 维护id、disabled、active、selected、tabIndex、controls关联面板 id等派生信号expanded用linkedSignal与 TabList 的选中项同步TabPanelPattern——hidden、tabIndex隐藏时为 -1、labelledByTabListPattern—— 组合ListFocus、ListNavigation、ListExpansion等 Behavior 类实现焦点管理、方向键导航含 wrap/softDisabled 语义、选中与展开联动。这正是 src/aria/private/ui-pattern-rules.md 描述的架构理念无障碍模式Accessibility Patterns→ Behavior 类封装导航、选择等通用行为→ UI Pattern 类组合 Behavior 实现完整模式。可以推断aria/private/tabs/tabs.spec.ts即是对这些 Pattern 行为的单元测试而指令层只是将信号输入与宿主 DOM/ARIA 绑定接到 Pattern 上。测试与 Harness 支持src/aria/tabs/目录提供了完整测试设施src/aria/tabs/tabs.spec.ts —— 指令级组件测试src/aria/tabs/testing/tabs-harness.ts 与 tabs-harness.spec.ts、tabs-harness-filters.ts —— 基于 CDK Component Harness 的测试工具供使用者在自己的测试中通过TabsHarness定位标签、读取选中状态、触发打开操作无需直接操作 DOM 细节。这与 Angular Components 一贯的 harness 测试风格一致angular/cdk/testing体系。组合实战示例综合全部 API一个可运行的最小完整示例含显式选择模式与回调div ngTabs ul ngTabList [(selectedTab)]current orientationhorizontal focusModeroving selectionModeexplicit wraptrue (selectedTabChange)onTabChanged($event) li ngTab valueoverview概览/li li ngTab valuedocs [disabled]docsDisabled文档/li /ul div ngTabPanel valueoverview ng-template ngTabContent p概览内容——首次激活时才渲染。/p /ng-template /div div ngTabPanel valuedocs preserveContent ng-template ngTabContent p文档内容——切换后保留在 DOM。/p /ng-template /div /div对应组件类import {Component} from angular/core; Component({...}) export class TabsDemo { current: string | undefined overview; docsDisabled false; onTabChanged(value: string | undefined) { console.log(selected:, value); } }要点回顾selectedTab是唯一支持双向绑定的输入输出名selectedTabChangevalue是ngTab与ngTabPanel建立关联的键必须唯一且相互匹配否则开发模式下会收到reportViolations输出的控制台警告键盘与 ARIA 属性role、aria-selected、aria-controls、aria-activedescendant、inert等全部由指令自动管理无需手写。小结angular/aria_tabs的公开 API 表面在 goldens/aria/tabs/index.api.md 中被完整、精确地固化为契约五个指令各司其职两个注入令牌完成层级通信信号输入覆盖方向、焦点、选择、禁用与换行等全部 WAI-ARIA Tabs Pattern 关键维度底层则以 src/aria/private/tabs/tabs.ts 的 UI Pattern 类承载所有交互逻辑将无障碍实现从 Angular 指令层解耦兼顾了可测试性与可复用性。对于希望构建无障碍标签页界面的开发者直接依据上文表格与示例使用ngTabs系列指令即可获得符合 ARIA 规范的开箱即用能力。【免费下载链接】componentsComponent infrastructure and Material Design components for Angular项目地址: https://gitcode.com/GitHub_Trending/co/components创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考