Angular CDKcdkTrapFocus焦点陷阱指令完全指南原理、配置与实战【免费下载链接】componentsComponent infrastructure and Material Design components for Angular项目地址: https://gitcode.com/GitHub_Trending/co/componentscdkTrapFocus是 Angular CDKComponent Dev KitA11yModule提供的一条核心无障碍指令它可以把Tab键的焦点循环严格限制在某个容器元素内部是构建模态对话框modal dialog、抽屉drawer、内联弹层等“焦点必须被约束”的交互组件的基础设施。本文以本仓库co/componentsAngular Material 与 CDK 源码仓库中 focus-trap.md 为骨架结合 focus-trap.ts 等核心实现与测试用例完整讲解cdkTrapFocus的用法、输入属性、编程式 API、底层锚点机制以及更高级的ConfigurableFocusTrap与焦点陷阱管理器帮助你彻底理解并正确使用这一机制。一、为什么需要焦点陷阱背景与适用场景cdkTrapFocus指令的作用是在一个元素内部“困住”Tab/ShiftTab的焦点循环。其官方设计意图是为诸如模态对话框这类“焦点必须被约束”的组件创建可访问的体验——当对话框打开时用户按Tab不应把焦点移到对话框背后的页面内容上否则键盘用户会迷失在不可见的背景元素中屏幕阅读器用户也会失去上下文。典型场景包括模态对话框WAI-ARIA APG 的 dialog-modal 模式焦点必须在对话框内循环关闭后归还给触发元素底部弹层bottom sheet、菜单、内联编辑器等临时性浮层任何“打开期间背景内容不应被键盘焦点触及”的交互组件。仓库中的 Material 组件大量使用了这一机制例如mat-dialog底层由CdkDialog依赖 focus trap 实现约束这正是 CDK 将“无障碍交互原语”下沉为独立模块、供上层组件与业务代码复用的体现。二、最小用法一行指令完成焦点约束使用cdkTrapFocus指令非常简单把它加到需要约束焦点的容器元素上即可div classmy-inner-dialog-content cdkTrapFocus !-- 在此容器内按 Tab / Shift Tab焦点不会跳出该元素。 -- /divdiv classmy-inner-dialog-content cdkTrapFocus !-- Tab 和 Shift Tab 都不会离开这个元素。 -- /div当用户在该容器内按Tab到达最后一个可聚焦元素后继续按焦点会回到第一个可聚焦元素在第一个元素上按ShiftTab焦点会跳到最后一个可聚焦元素形成闭环。要使用这条指令需要在组件或模块中导入CdkTrapFocus指令本身是 standalone 的它由A11yModule统一导出。导入方式import {CdkTrapFocus} from angular/cdk/a11y;或直接导入整个无障碍模块该模块在 a11y-module.ts 中声明了CdkTrapFocus的导入与导出import {A11yModule} from angular/cdk/a11y;NgModule({ imports: [A11yModule], }) export class MyModule {}从 focus-trap.ts 可以看到指令的声明Directive({ selector: [cdkTrapFocus], exportAs: cdkTrapFocus, }) export class CdkTrapFocus implements OnDestroy, AfterContentInit, OnChanges, DoCheck { ... }exportAs: cdkTrapFocus意味着你还可以通过模板引用变量拿到指令实例div cdkTrapFocus #trapcdkTrapFocus cdkTrapFocusAutoCapture ... button (click)trap.focusTrap.focusFirstTabbableElement()聚焦第一个元素/button /div三、输入属性cdkTrapFocus与cdkTrapFocusAutoCapture指令暴露了两个输入均使用booleanAttribute转换因此支持写为cdkTrapFocusfalse这类属性字符串形式。3.1enabled属性别名cdkTrapFocus控制焦点陷阱是否激活。默认值为true。将其设为false后锚点的tabindex会被移除见 focus-trap.tsTab焦点可以自由进出该区域重新设为true则恢复约束。div [cdkTrapFocus]isDialogOpen !-- isDialogOpen 为 true 时焦点被约束为 false 时放行 -- /div注意源码实现中的一个细节切换状态时是移除tabindex属性而不是设为-1因为如果元素带有tabindex用户仍可能通过方向键arrow keys导航到它见 focus-trap.ts 的注释说明。3.2autoCapture属性别名cdkTrapFocusAutoCaptureautoCapture: boolean false默认关闭。开启后指令会在初始化完成后自动把焦点移入陷阱区域内的初始目标元素并在指令销毁时把焦点归还给之前获得焦点的元素。div cdkTrapFocus cdkTrapFocusAutoCapture !-- 打开时自动聚焦区域内元素关闭时焦点回到触发按钮 -- /div其实现位于 focus-trap.ts_captureFocus先用_getFocusedElementPierceShadowDom()记录当前获得焦点的元素该方法来自 CDK Platform可穿透 Shadow DOM 边界获取真实焦点元素随后调用focusTrap.focusInitialElementWhenReady()等待 Angular 区域稳定后再聚焦。销毁阶段ngOnDestroy见 focus-trap.ts则将焦点还给_previouslyFocusedElement。当autoCapture在运行时被动态切换为true非首次变更时ngOnChanges也会触发一次_captureFocus见 focus-trap.ts。3.3 结合使用button (click)open true打开对话框/button div classdialog cdkTrapFocus cdkTrapFocusAutoCapture *ngIfopen button (click)open false关闭/button a href#链接一/a button确定/button /div这里*ngIf动态创建容器指令通过ngAfterContentInit与ngDoCheck的重复检查见 focus-trap.ts确保锚点能被正确挂载——这正是构造函数中deferAnchors true延迟创建锚点存在的意义当使用*ngIf等指令导致元素在构造时尚未进入 DOM 时锚点需要在内容初始化后手动附加。四、焦点目标标记控制焦点“落到哪里”FocusTrap提供三个用于指定焦点落点的方法对应三个 HTML 标记属性标记属性对应方法作用cdkFocusInitialfocusInitialElement()指定陷阱初始化时应该聚焦的元素优先于“第一个可聚焦元素”cdkFocusRegionStartfocusFirstTabbableElement()指定区域内“第一个”焦点元素Tab 循环的起点cdkFocusRegionEndfocusLastTabbableElement()指定区域内“最后一个”焦点元素Tab 循环的终点div cdkTrapFocus button取消/button button cdkFocusInitial确认初始化时聚焦这里/button a href#了解更多/a /div源码实现位于 focus-trap.ts 与 focus-trap.ts_getRegionBoundary(start | end)会在陷阱区域内查找[cdkFocusRegionStart]/[cdkFocusRegionEnd]标记若找不到标记则退化为查找区域内的第一个 / 最后一个可聚焦元素递归遍历子节点且要求同时满足isFocusable与isTabbable。focusInitialElement()优先查找[cdkFocusInitial]标记若标记元素不可聚焦会尝试聚焦其第一个可聚焦子元素开发模式下若标记元素不可聚焦还会输出console.warn(Element matching [cdkFocusInitial] is not focusable.)警告。旧版写法cdk-focus-initial、cdk-focus-region-start/cdk-focus-region-end、cdk-focus-start/cdk-focus-end仍在兼容期内代码中标注了 8.0.0 的 breaking change 计划但会打印废弃警告应统一使用新驼峰写法。此外focusInitialElement/focusFirstTabbableElement/focusLastTabbableElement均接受标准FocusOptions如{preventScroll: true}并透传给原生element.focus(options)测试 focus-trap.spec.ts 验证了这一行为。五、编程式使用FocusTrapFactory与FocusTrap实例除指令外CDK 还提供了工厂服务适合在指令不便使用的场景例如需要动态创建陷阱、或在服务层控制下以编程方式创建焦点陷阱。import {FocusTrap, FocusTrapFactory} from angular/cdk/a11y; import {inject} from angular/core; Component({...}) export class MyDialog { private _focusTrapFactory inject(FocusTrapFactory); private _focusTrap!: FocusTrap; open() { const container document.querySelector(.dialog) as HTMLElement; this._focusTrap this._focusTrapFactory.create(container); this._focusTrap.focusInitialElementWhenReady(); } close() { this._focusTrap.destroy(); } }FocusTrapFactory定义于 focus-trap.tscreate(element, deferCaptureElements false)接受目标元素并返回FocusTrap实例。核心 API 汇总方法说明attachAnchors(): boolean向 DOM 插入前后锚点目标元素不在 DOM 中时返回falsefocusInitialElement(options?): boolean聚焦初始目标cdkFocusInitial或第一个可聚焦元素成功返回truefocusFirstTabbableElement(options?): boolean聚焦区域起点focusLastTabbableElement(options?): boolean聚焦区域终点focusInitialElementWhenReady(): Promiseboolean等 Angular 区域稳定后执行聚焦内部用afterNextRender见 focus-trap.tsfocusFirstTabbableElementWhenReady()/focusLastTabbableElementWhenReady()同上对应首/尾元素enabled: boolean读取/切换陷阱激活状态hasAttached(): boolean锚点是否已成功挂载destroy()移除监听器与锚点清理现场见 focus-trap.tsdestroy()会removeEventListener并调用remove()删除两个锚点元素因此由指令创建的陷阱会在组件销毁时自动清理编程式创建的则需要手动调用。六、底层原理锚点机制如何“困住”焦点FocusTrap采用“锚点anchor”策略实现焦点循环整体流程如下插入锚点attachAnchors()见 focus-trap.ts在目标元素的前后各插入一个div锚点锚点带有cdk-visually-hidden视觉隐藏、cdk-focus-trap-anchor样式类与aria-hiddentrue并通过tabindex0使其可被 Tab 命中整个插入过程运行在runOutsideAngular中避免触发不必要的变更检测。监听循环当用户 Tab 到“末尾锚点”时endAnchorListener触发调用focusLastTabbableElement()把焦点拉回区域末尾焦点落到“起始锚点”时startAnchorListener调用focusFirstTabbableElement()把焦点拉回区域开头见 focus-trap.ts。空区域兜底若区域内没有任何可聚焦元素但根元素本身可聚焦如设置了tabindex-1则直接聚焦根元素见 focus-trap.ts 与测试 focus-trap.spec.ts。源码注释focus-trap.ts也诚实指出该机制的假设前提它假定 Tab 顺序等同于 DOM 顺序。这意味着tabindex 0的元素、使用 flexorder重排的元素、以及 Shadow DOM 都可能导致两者不一致在实际复杂布局中需要注意。测试 focus-trap.spec.ts 从行为层面验证了上述机制从起点聚焦“第一个可聚焦元素”input成功返回true从终点聚焦“最后一个可聚焦元素”buttoniOS 上由于按钮不可 Tab 则回退为input区域内无可聚焦元素时返回false锚点默认tabindex0、aria-hiddentrue禁用后锚点不再持有tabindexfocus-trap.spec.ts销毁后两个cdk-visually-hidden锚点被清理focus-trap.spec.ts。七、进阶ConfigurableFocusTrap、焦点陷阱管理器与惰性策略除了基础的FocusTrapCDK 还提供了“可配置”的变体用于处理多个陷阱共存、弹层叠加等复杂场景。7.1 策略模式与FOCUS_TRAP_INERT_STRATEGYFocusTrapInertStrategy定义于 focus-trap-inert-strategy.ts定义了两个方法preventFocus(focusTrap)让陷阱区域外的元素全部不可聚焦allowFocus(focusTrap)撤销上述限制。默认实现是EventListenerFocusTrapInertStrategy见 event-listener-inert-strategy.ts它在document 上以 capture 阶段注册 focus 监听器同样运行于runOutsideAngular一旦发现焦点事件的目标在陷阱之外且不属于div.cdk-overlay-pane避免误伤与区域内元素关联的mat-select等 CDK Overlay 弹层就通过setTimeout延迟确认后调用focusFirstTabbableElement()把焦点“拽”回来。延迟是为了兼容旧版用法中“销毁前先聚焦页面其他元素”的逻辑——如果在此期间焦点已被放回陷阱内则不再干预。你可以通过注入令牌FOCUS_TRAP_INERT_STRATEGY提供自定义策略见 focus-trap-inert-strategy.ts 与 configurable-focus-trap-factory.tsimport {FOCUS_TRAP_INERT_STRATEGY, FocusTrapInertStrategy, ConfigurableFocusTrap} from angular/cdk/a11y; class MyInertStrategy implements FocusTrapInertStrategy { preventFocus(focusTrap: ConfigurableFocusTrap): void { /* 自定义实现 */ } allowFocus(focusTrap: ConfigurableFocusTrap): void { /* 自定义实现 */ } } providers: [ {provide: FOCUS_TRAP_INERT_STRATEGY, useClass: MyInertStrategy}, ]7.2FocusTrapManager栈式管理多个陷阱focus-trap-manager.ts 中的FocusTrapManager维护一个_focusTrapStack栈保证同一时刻只有最近启用的陷阱处于激活状态register(focusTrap)先停用当前栈顶陷阱再把新陷阱入栈并启用deregister(focusTrap)停用并移除该陷阱然后重新启用新的栈顶陷阱。这让“嵌套弹层”如对话框内再打开菜单成为可能最内层弹层激活时外层陷阱被临时停用内层关闭后外层自动恢复。ConfigurableFocusTrap见 configurable-focus-trap.ts正是通过FocusTrapManagerFocusTrapInertStrategy的组合来实现这一行为其enabled的 setter 会同步注册/注销到管理器。7.3ConfigurableFocusTrapFactory与FocusTrapFactory对应的可配置版本import {ConfigurableFocusTrap, ConfigurableFocusTrapFactory} from angular/cdk/a11y; import {inject} from angular/core; const factory inject(ConfigurableFocusTrapFactory); const trap: ConfigurableFocusTrap factory.create(containerElement, {defer: false}); trap.focusInitialElementWhenReady();create(element, config)的配置项ConfigurableFocusTrapConfig目前只有一个布尔字段defer见 configurable-focus-trap-config.ts含义与FocusTrapFactory.create的deferCaptureElements一致为true时延迟创建聚焦捕获元素交由使用者后续手动调用attachAnchors()。八、使用建议与注意事项综合文档与源码实际使用时请留意以下几点确保区域内有可聚焦元素否则按Tab会直接跳出根元素可聚焦时则聚焦根元素。对容器设置tabindex-1可以让根元素参与兜底聚焦且不破坏 Tab 顺序。*ngIf/ 动态内容指令已通过ngAfterContentInitngDoCheck处理锚点延迟挂载但如果内容在渲染后才异步出现建议结合focusInitialElementWhenReady系列方法等待区域稳定。autoCapture与焦点归还开启cdkTrapFocusAutoCapture后指令销毁时自动把焦点还给先前元素这是实现“对话框关闭后焦点回落到触发按钮”的最简做法。配合 ARIA 语义焦点陷阱只是无障碍体验的一部分对话框还应配合roledialog、aria-modaltrue、aria-labelledby等属性使用WAI-ARIA APG 的 dialog-modal 模式是设计参考基准。已知边界锚点机制基于“Tab 顺序 ≈ DOM 顺序”的假设tabindex 0、flexorder、Shadow DOM 场景可能产生偏差ConfigurableFocusTrap的默认惰性策略会避开cdk-overlay-pane若你的自定义弹层使用其他类名需要留意该判定。九、进一步阅读官方入门文档getting-started.md无障碍设计指南guides/bidirectionality.md核心实现源码src/cdk/a11y/focus-trap/focus-trap.ts可配置变体src/cdk/a11y/focus-trap/configurable-focus-trap.ts管理器与惰性策略src/cdk/a11y/focus-trap/focus-trap-manager.ts、src/cdk/a11y/focus-trap/event-listener-inert-strategy.ts单元测试含边界行为验证src/cdk/a11y/focus-trap/focus-trap.spec.ts【免费下载链接】componentsComponent infrastructure and Material Design components for Angular项目地址: https://gitcode.com/GitHub_Trending/co/components创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Angular CDKcdkTrapFocus焦点陷阱指令完全指南原理、配置与实战【免费下载链接】componentsComponent infrastructure and Material Design components for Angular项目地址: https://gitcode.com/GitHub_Trending/co/componentscdkTrapFocus是 Angular CDKComponent Dev KitA11yModule提供的一条核心无障碍指令它可以把Tab键的焦点循环严格限制在某个容器元素内部是构建模态对话框modal dialog、抽屉drawer、内联弹层等“焦点必须被约束”的交互组件的基础设施。本文以本仓库co/componentsAngular Material 与 CDK 源码仓库中 focus-trap.md 为骨架结合 focus-trap.ts 等核心实现与测试用例完整讲解cdkTrapFocus的用法、输入属性、编程式 API、底层锚点机制以及更高级的ConfigurableFocusTrap与焦点陷阱管理器帮助你彻底理解并正确使用这一机制。一、为什么需要焦点陷阱背景与适用场景cdkTrapFocus指令的作用是在一个元素内部“困住”Tab/ShiftTab的焦点循环。其官方设计意图是为诸如模态对话框这类“焦点必须被约束”的组件创建可访问的体验——当对话框打开时用户按Tab不应把焦点移到对话框背后的页面内容上否则键盘用户会迷失在不可见的背景元素中屏幕阅读器用户也会失去上下文。典型场景包括模态对话框WAI-ARIA APG 的 dialog-modal 模式焦点必须在对话框内循环关闭后归还给触发元素底部弹层bottom sheet、菜单、内联编辑器等临时性浮层任何“打开期间背景内容不应被键盘焦点触及”的交互组件。仓库中的 Material 组件大量使用了这一机制例如mat-dialog底层由CdkDialog依赖 focus trap 实现约束这正是 CDK 将“无障碍交互原语”下沉为独立模块、供上层组件与业务代码复用的体现。二、最小用法一行指令完成焦点约束使用cdkTrapFocus指令非常简单把它加到需要约束焦点的容器元素上即可div classmy-inner-dialog-content cdkTrapFocus !-- 在此容器内按 Tab / Shift Tab焦点不会跳出该元素。 -- /divdiv classmy-inner-dialog-content cdkTrapFocus !-- Tab 和 Shift Tab 都不会离开这个元素。 -- /div当用户在该容器内按Tab到达最后一个可聚焦元素后继续按焦点会回到第一个可聚焦元素在第一个元素上按ShiftTab焦点会跳到最后一个可聚焦元素形成闭环。要使用这条指令需要在组件或模块中导入CdkTrapFocus指令本身是 standalone 的它由A11yModule统一导出。导入方式import {CdkTrapFocus} from angular/cdk/a11y;或直接导入整个无障碍模块该模块在 a11y-module.ts 中声明了CdkTrapFocus的导入与导出import {A11yModule} from angular/cdk/a11y;NgModule({ imports: [A11yModule], }) export class MyModule {}从 focus-trap.ts 可以看到指令的声明Directive({ selector: [cdkTrapFocus], exportAs: cdkTrapFocus, }) export class CdkTrapFocus implements OnDestroy, AfterContentInit, OnChanges, DoCheck { ... }exportAs: cdkTrapFocus意味着你还可以通过模板引用变量拿到指令实例div cdkTrapFocus #trapcdkTrapFocus cdkTrapFocusAutoCapture ... button (click)trap.focusTrap.focusFirstTabbableElement()聚焦第一个元素/button /div三、输入属性cdkTrapFocus与cdkTrapFocusAutoCapture指令暴露了两个输入均使用booleanAttribute转换因此支持写为cdkTrapFocusfalse这类属性字符串形式。3.1enabled属性别名cdkTrapFocus控制焦点陷阱是否激活。默认值为true。将其设为false后锚点的tabindex会被移除见 focus-trap.tsTab焦点可以自由进出该区域重新设为true则恢复约束。div [cdkTrapFocus]isDialogOpen !-- isDialogOpen 为 true 时焦点被约束为 false 时放行 -- /div注意源码实现中的一个细节切换状态时是移除tabindex属性而不是设为-1因为如果元素带有tabindex用户仍可能通过方向键arrow keys导航到它见 focus-trap.ts 的注释说明。3.2autoCapture属性别名cdkTrapFocusAutoCaptureautoCapture: boolean false默认关闭。开启后指令会在初始化完成后自动把焦点移入陷阱区域内的初始目标元素并在指令销毁时把焦点归还给之前获得焦点的元素。div cdkTrapFocus cdkTrapFocusAutoCapture !-- 打开时自动聚焦区域内元素关闭时焦点回到触发按钮 -- /div其实现位于 focus-trap.ts_captureFocus先用_getFocusedElementPierceShadowDom()记录当前获得焦点的元素该方法来自 CDK Platform可穿透 Shadow DOM 边界获取真实焦点元素随后调用focusTrap.focusInitialElementWhenReady()等待 Angular 区域稳定后再聚焦。销毁阶段ngOnDestroy见 focus-trap.ts则将焦点还给_previouslyFocusedElement。当autoCapture在运行时被动态切换为true非首次变更时ngOnChanges也会触发一次_captureFocus见 focus-trap.ts。3.3 结合使用button (click)open true打开对话框/button div classdialog cdkTrapFocus cdkTrapFocusAutoCapture *ngIfopen button (click)open false关闭/button a href#链接一/a button确定/button /div这里*ngIf动态创建容器指令通过ngAfterContentInit与ngDoCheck的重复检查见 focus-trap.ts确保锚点能被正确挂载——这正是构造函数中deferAnchors true延迟创建锚点存在的意义当使用*ngIf等指令导致元素在构造时尚未进入 DOM 时锚点需要在内容初始化后手动附加。四、焦点目标标记控制焦点“落到哪里”FocusTrap提供三个用于指定焦点落点的方法对应三个 HTML 标记属性标记属性对应方法作用cdkFocusInitialfocusInitialElement()指定陷阱初始化时应该聚焦的元素优先于“第一个可聚焦元素”cdkFocusRegionStartfocusFirstTabbableElement()指定区域内“第一个”焦点元素Tab 循环的起点cdkFocusRegionEndfocusLastTabbableElement()指定区域内“最后一个”焦点元素Tab 循环的终点div cdkTrapFocus button取消/button button cdkFocusInitial确认初始化时聚焦这里/button a href#了解更多/a /div源码实现位于 focus-trap.ts 与 focus-trap.ts_getRegionBoundary(start | end)会在陷阱区域内查找[cdkFocusRegionStart]/[cdkFocusRegionEnd]标记若找不到标记则退化为查找区域内的第一个 / 最后一个可聚焦元素递归遍历子节点且要求同时满足isFocusable与isTabbable。focusInitialElement()优先查找[cdkFocusInitial]标记若标记元素不可聚焦会尝试聚焦其第一个可聚焦子元素开发模式下若标记元素不可聚焦还会输出console.warn(Element matching [cdkFocusInitial] is not focusable.)警告。旧版写法cdk-focus-initial、cdk-focus-region-start/cdk-focus-region-end、cdk-focus-start/cdk-focus-end仍在兼容期内代码中标注了 8.0.0 的 breaking change 计划但会打印废弃警告应统一使用新驼峰写法。此外focusInitialElement/focusFirstTabbableElement/focusLastTabbableElement均接受标准FocusOptions如{preventScroll: true}并透传给原生element.focus(options)测试 focus-trap.spec.ts 验证了这一行为。五、编程式使用FocusTrapFactory与FocusTrap实例除指令外CDK 还提供了工厂服务适合在指令不便使用的场景例如需要动态创建陷阱、或在服务层控制下以编程方式创建焦点陷阱。import {FocusTrap, FocusTrapFactory} from angular/cdk/a11y; import {inject} from angular/core; Component({...}) export class MyDialog { private _focusTrapFactory inject(FocusTrapFactory); private _focusTrap!: FocusTrap; open() { const container document.querySelector(.dialog) as HTMLElement; this._focusTrap this._focusTrapFactory.create(container); this._focusTrap.focusInitialElementWhenReady(); } close() { this._focusTrap.destroy(); } }FocusTrapFactory定义于 focus-trap.tscreate(element, deferCaptureElements false)接受目标元素并返回FocusTrap实例。核心 API 汇总方法说明attachAnchors(): boolean向 DOM 插入前后锚点目标元素不在 DOM 中时返回falsefocusInitialElement(options?): boolean聚焦初始目标cdkFocusInitial或第一个可聚焦元素成功返回truefocusFirstTabbableElement(options?): boolean聚焦区域起点focusLastTabbableElement(options?): boolean聚焦区域终点focusInitialElementWhenReady(): Promiseboolean等 Angular 区域稳定后执行聚焦内部用afterNextRender见 focus-trap.tsfocusFirstTabbableElementWhenReady()/focusLastTabbableElementWhenReady()同上对应首/尾元素enabled: boolean读取/切换陷阱激活状态hasAttached(): boolean锚点是否已成功挂载destroy()移除监听器与锚点清理现场见 focus-trap.tsdestroy()会removeEventListener并调用remove()删除两个锚点元素因此由指令创建的陷阱会在组件销毁时自动清理编程式创建的则需要手动调用。六、底层原理锚点机制如何“困住”焦点FocusTrap采用“锚点anchor”策略实现焦点循环整体流程如下插入锚点attachAnchors()见 focus-trap.ts在目标元素的前后各插入一个div锚点锚点带有cdk-visually-hidden视觉隐藏、cdk-focus-trap-anchor样式类与aria-hiddentrue并通过tabindex0使其可被 Tab 命中整个插入过程运行在runOutsideAngular中避免触发不必要的变更检测。监听循环当用户 Tab 到“末尾锚点”时endAnchorListener触发调用focusLastTabbableElement()把焦点拉回区域末尾焦点落到“起始锚点”时startAnchorListener调用focusFirstTabbableElement()把焦点拉回区域开头见 focus-trap.ts。空区域兜底若区域内没有任何可聚焦元素但根元素本身可聚焦如设置了tabindex-1则直接聚焦根元素见 focus-trap.ts 与测试 focus-trap.spec.ts。源码注释focus-trap.ts也诚实指出该机制的假设前提它假定 Tab 顺序等同于 DOM 顺序。这意味着tabindex 0的元素、使用 flexorder重排的元素、以及 Shadow DOM 都可能导致两者不一致在实际复杂布局中需要注意。测试 focus-trap.spec.ts 从行为层面验证了上述机制从起点聚焦“第一个可聚焦元素”input成功返回true从终点聚焦“最后一个可聚焦元素”buttoniOS 上由于按钮不可 Tab 则回退为input区域内无可聚焦元素时返回false锚点默认tabindex0、aria-hiddentrue禁用后锚点不再持有tabindexfocus-trap.spec.ts销毁后两个cdk-visually-hidden锚点被清理focus-trap.spec.ts。七、进阶ConfigurableFocusTrap、焦点陷阱管理器与惰性策略除了基础的FocusTrapCDK 还提供了“可配置”的变体用于处理多个陷阱共存、弹层叠加等复杂场景。7.1 策略模式与FOCUS_TRAP_INERT_STRATEGYFocusTrapInertStrategy定义于 focus-trap-inert-strategy.ts定义了两个方法preventFocus(focusTrap)让陷阱区域外的元素全部不可聚焦allowFocus(focusTrap)撤销上述限制。默认实现是EventListenerFocusTrapInertStrategy见 event-listener-inert-strategy.ts它在document 上以 capture 阶段注册 focus 监听器同样运行于runOutsideAngular一旦发现焦点事件的目标在陷阱之外且不属于div.cdk-overlay-pane避免误伤与区域内元素关联的mat-select等 CDK Overlay 弹层就通过setTimeout延迟确认后调用focusFirstTabbableElement()把焦点“拽”回来。延迟是为了兼容旧版用法中“销毁前先聚焦页面其他元素”的逻辑——如果在此期间焦点已被放回陷阱内则不再干预。你可以通过注入令牌FOCUS_TRAP_INERT_STRATEGY提供自定义策略见 focus-trap-inert-strategy.ts 与 configurable-focus-trap-factory.tsimport {FOCUS_TRAP_INERT_STRATEGY, FocusTrapInertStrategy, ConfigurableFocusTrap} from angular/cdk/a11y; class MyInertStrategy implements FocusTrapInertStrategy { preventFocus(focusTrap: ConfigurableFocusTrap): void { /* 自定义实现 */ } allowFocus(focusTrap: ConfigurableFocusTrap): void { /* 自定义实现 */ } } providers: [ {provide: FOCUS_TRAP_INERT_STRATEGY, useClass: MyInertStrategy}, ]7.2FocusTrapManager栈式管理多个陷阱focus-trap-manager.ts 中的FocusTrapManager维护一个_focusTrapStack栈保证同一时刻只有最近启用的陷阱处于激活状态register(focusTrap)先停用当前栈顶陷阱再把新陷阱入栈并启用deregister(focusTrap)停用并移除该陷阱然后重新启用新的栈顶陷阱。这让“嵌套弹层”如对话框内再打开菜单成为可能最内层弹层激活时外层陷阱被临时停用内层关闭后外层自动恢复。ConfigurableFocusTrap见 configurable-focus-trap.ts正是通过FocusTrapManagerFocusTrapInertStrategy的组合来实现这一行为其enabled的 setter 会同步注册/注销到管理器。7.3ConfigurableFocusTrapFactory与FocusTrapFactory对应的可配置版本import {ConfigurableFocusTrap, ConfigurableFocusTrapFactory} from angular/cdk/a11y; import {inject} from angular/core; const factory inject(ConfigurableFocusTrapFactory); const trap: ConfigurableFocusTrap factory.create(containerElement, {defer: false}); trap.focusInitialElementWhenReady();create(element, config)的配置项ConfigurableFocusTrapConfig目前只有一个布尔字段defer见 configurable-focus-trap-config.ts含义与FocusTrapFactory.create的deferCaptureElements一致为true时延迟创建聚焦捕获元素交由使用者后续手动调用attachAnchors()。八、使用建议与注意事项综合文档与源码实际使用时请留意以下几点确保区域内有可聚焦元素否则按Tab会直接跳出根元素可聚焦时则聚焦根元素。对容器设置tabindex-1可以让根元素参与兜底聚焦且不破坏 Tab 顺序。*ngIf/ 动态内容指令已通过ngAfterContentInitngDoCheck处理锚点延迟挂载但如果内容在渲染后才异步出现建议结合focusInitialElementWhenReady系列方法等待区域稳定。autoCapture与焦点归还开启cdkTrapFocusAutoCapture后指令销毁时自动把焦点还给先前元素这是实现“对话框关闭后焦点回落到触发按钮”的最简做法。配合 ARIA 语义焦点陷阱只是无障碍体验的一部分对话框还应配合roledialog、aria-modaltrue、aria-labelledby等属性使用WAI-ARIA APG 的 dialog-modal 模式是设计参考基准。已知边界锚点机制基于“Tab 顺序 ≈ DOM 顺序”的假设tabindex 0、flexorder、Shadow DOM 场景可能产生偏差ConfigurableFocusTrap的默认惰性策略会避开cdk-overlay-pane若你的自定义弹层使用其他类名需要留意该判定。九、进一步阅读官方入门文档getting-started.md无障碍设计指南guides/bidirectionality.md核心实现源码src/cdk/a11y/focus-trap/focus-trap.ts可配置变体src/cdk/a11y/focus-trap/configurable-focus-trap.ts管理器与惰性策略src/cdk/a11y/focus-trap/focus-trap-manager.ts、src/cdk/a11y/focus-trap/event-listener-inert-strategy.ts单元测试含边界行为验证src/cdk/a11y/focus-trap/focus-trap.spec.ts【免费下载链接】componentsComponent infrastructure and Material Design components for Angular项目地址: https://gitcode.com/GitHub_Trending/co/components创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
![Retrospective: [Sprint N / Milestone Name]](http://pic.xiahunao.cn/yaotu/Retrospective: [Sprint N / Milestone Name])
)
)
