Angular ng-bootstrap模态框出现aria-hidden警告的解决求助

问题分析 #

你遇到的警告Blocked aria-hidden on an element because its descendant retained focus，本质是带有aria-hidden="true"的元素的后代（可聚焦的关闭按钮）获得了焦点——aria-hidden会让辅助技术忽略元素及其后代，但焦点元素绝对不能被忽略，否则会影响屏幕阅读器等工具的正常使用。

看你提供的代码，按钮内的<span aria-hidden="true">&times;</span>本身是合理的：它只是隐藏视觉叉号给辅助技术，按钮的语义已经由aria-label="Close"明确。问题大概率出在模态框打开时，页面其他内容被错误标记了aria-hidden，或者焦点管理不符合可访问性规范。

具体解决方案 #

1. 清理冗余代码 #

你的关闭按钮重复写了两次aria-label="Close"，先删掉一个，避免属性冲突：

<div class="modal-header">
  <h4 class="modal-title">Serial Number</h4>
  <button type="button" class="btn-close" aria-label="Close" (click)="popupClose(false)">
    <span aria-hidden="true">&times;</span>
  </button>
</div>

2. 用inert替代页面非模态内容的aria-hidden #

浏览器原生的inert属性可以让元素及其后代无法获取焦点，同时被辅助技术忽略，完美替代警告里提到的不合适的aria-hidden用法。ng-bootstrap没有直接封装这个功能，你可以手动实现：

• 在组件类中获取页面主容器的DOM元素，模态框打开时给容器加inert，关闭时移除：

import { ElementRef, ViewChild } from '@angular/core';
import { NgbModal } from '@ng-bootstrap/ng-bootstrap';

export class YourComponent {
  // 给页面主容器加模板引用
  @ViewChild('mainContent') mainContent!: ElementRef<HTMLElement>;

  constructor(private modalService: NgbModal) {}

  openModal(modalContent: any) {
    const modalRef = this.modalService.open(modalContent);
    // 打开模态框时，让主内容区惰性化
    this.mainContent.nativeElement.inert = true;

    // 模态框关闭后，恢复主内容区的可访问性
    modalRef.closed.subscribe(() => {
      this.mainContent.nativeElement.inert = false;
    });
  }
}

• 在模板中给页面主内容区添加模板引用：

<!-- 页面主内容 -->
<main #mainContent>
  <!-- 你的页面内容 -->
</main>

<!-- 模态框模板 -->
<ng-template #modalContent let-modal>
  <div class="modal-header">
    <h4 class="modal-title">Serial Number</h4>
    <button type="button" class="btn-close" aria-label="Close" (click)="popupClose(false)">
      <span aria-hidden="true">&times;</span>
    </button>
  </div>
  <!-- 模态框其他内容 -->
</ng-template>

3. 确保模态框的焦点管理正确 #

ng-bootstrap默认会在模态框打开时自动聚焦到框内第一个可聚焦元素，但如果你的模态框结构特殊，可以手动指定焦点目标，避免焦点落到被inert或aria-hidden标记的区域：

openModal(modalContent: any) {
  const modalRef = this.modalService.open(modalContent);
  this.mainContent.nativeElement.inert = true;

  // 模态框完全显示后，聚焦到关闭按钮
  modalRef.shown.subscribe(() => {
    const closeBtn = modalRef.nativeElement.querySelector('.btn-close');
    if (closeBtn) {
      closeBtn.focus();
    }
  });

  modalRef.closed.subscribe(() => {
    this.mainContent.nativeElement.inert = false;
  });
}

4. 排查自定义的aria-hidden设置 #

如果你自己给模态框的某个父元素添加了aria-hidden="true"，一定要立刻移除——模态框本身是需要被辅助技术识别的，焦点在模态框内时，其祖先绝对不能有aria-hidden标记。

总结 #

按钮内的<span aria-hidden="true">是合理的视觉装饰隐藏，不需要改动；核心是用inert替代对页面非模态内容的aria-hidden标记，确保焦点所在的模态框区域完全暴露给辅助技术，同时做好焦点的自动管理，就能解决这个警告问题。

内容的提问来源于stack exchange，提问作者user28119788