Angular 模态框焦点警告处理

问题核心
在 Angular 应用中使用模态框时出现警告：
⚠️ Blocked aria-hidden on an element because its descendant retained focus

该警告表示：当模态框打开时，应用根组件（如 <app-root>）被添加了 aria-hidden="true" 属性，但触发模态框的按钮却仍保持焦点状态。这会导致焦点元素位于不可见区域，违反无障碍规范。

<!-- 示例中触发警告的代码片段 -->
<button (click)="openModal()">打开模态框</button>

<!-- 模态框打开后 -->
<app-root aria-hidden="true"> <!-- 此时内部的按钮仍保持焦点 -->
  <button focused>打开模态框</button>
</app-root>

---

最佳解决方案

✅ 方案一：移除触发元素的焦点 (推荐)

在打开模态框前强制移除按钮焦点：

import { NgbModal } from '@ng-bootstrap/ng-bootstrap';

openModal() {
  // 获取当前焦点元素并移除焦点
  (document.activeElement as HTMLElement)?.blur();
  
  // 打开模态框
  this.modalService.open(ModalComponent);
}

✅ 方案二：自定义模态服务 (全局解决方案)

创建继承 NgbModal 的服务，自动处理焦点问题：

// custom-modal.service.ts
import { NgbModal, NgbModalOptions, NgbModalRef } from '@ng-bootstrap/ng-bootstrap';

export class AccessibilityModalService extends NgbModal {
  override open(content: any, options?: NgbModalOptions): NgbModalRef {
    // 打开前移除焦点
    (document.activeElement as HTMLElement)?.blur(); 
    return super.open(content, options);
  }
}

注册到全局模块：

// app.module.ts
providers: [
  { provide: NgbModal, useClass: AccessibilityModalService }
]

✅ 方案三：指令式处理 (组件级方案)

创建自动移除焦点的指令：

// blur-on-click.directive.ts
import { Directive, ElementRef, HostListener } from '@angular/core';

@Directive({ selector: '[blurOnClick]' })
export class BlurOnClickDirective {
  constructor(private el: ElementRef) {}

  @HostListener('click')
  onClick() {
    this.el.nativeElement.blur();
  }
}

在模板中使用：

<button blurOnClick (click)="openModal()">打开模态框</button>

---

问题根源与解决原理

1. 发生时机
   ng-bootstrap 打开模态框时，会自动为 <app-root> 添加 aria-hidden="true"
   但触发按钮的焦点未被移除，形成冲突

2. 焦点处理流程

3. blur() 的作用
   通过移除原按钮焦点，确保焦点直接转移到模态框内部

---

备选方案对比

方案	优点	缺点
直接调用 blur()	简单快速	需在每个打开操作中添加
自定义服务	一劳永逸	需要重写服务
指令处理	声明式语法	需为每个按钮添加指令

---

⚠️ 不推荐的修复方法

1. 强行移除 aria-hidden 属性

   // 错误示例：破坏无障碍支持
   document.querySelector('app-root')?.removeAttribute('aria-hidden');

   • 会破坏屏幕阅读器对模态模式的支持

2. 使用 inert 替代方案

   <!-- 实验性方案，浏览器兼容性不佳 -->
   <app-root inert>

   • 目前 Safari 和旧版浏览器支持不足

---

完整实现示例

// 最佳实践：服务+指令组合方案
import { Component } from '@angular/core';
import { NgbModal } from '@ng-bootstrap/ng-bootstrap';

@Component({
  template: `
    <button blurOnClick (click)="openModal()">
      打开模态框
    </button>
  `
})
export class AppComponent {
  constructor(private modalService: NgbModal) {}
  
  openModal() {
    // 自定义服务已自动处理焦点
    this.modalService.open(ModalContent);
  }
}

关键提示：
该解决方案确保：

1. 满足 WCAG 2.1 无障碍标准
2. 兼容所有现代浏览器
3. 保持模态框的焦点管理机制完整
4. 消除控制台警告

通过正确处理焦点转移，您将同时提升应用的无障碍体验和代码健壮性。