PrimeNG <p-dialog>组件焦点无法锁定至弹窗内问题求助

我之前也碰到过这个一模一样的问题！而且确实PrimeNG官网的示例也存在这个焦点逃逸的情况——打开弹窗后按Tab键，焦点会直接跑到弹窗后面的页面元素上，哪怕设置了modal属性也没用。

其实PrimeNG早期版本的modal属性只是负责添加遮罩层阻止点击，并没有实现**焦点锁定（focus trap）**这个无障碍特性，这也是很多UI组件库的常见问题。下面分享两种可行的解决方案：

解决方案1：用PrimeNG原生的focusTrap属性（推荐） #

如果你的PrimeNG版本是14及以上，官方已经添加了focusTrap输入属性，直接开启就能解决问题：

• 在<p-dialog>上添加[focusTrap]="true"，同时保留[modal]="true"和必要的appendTo设置：

<p-dialog 
  header="示例弹窗" 
  [(visible)]="display" 
  [modal]="true" 
  [focusTrap]="true"
  [appendTo]="'body'"
>
  <!-- 弹窗内的可交互元素 -->
  <input type="text" placeholder="测试输入框">
  <button pButton label="确认" (click)="display=false"></button>
  <button pButton label="取消" (click)="display=false" class="p-button-secondary"></button>
</p-dialog>

这个属性会自动把焦点锁定在弹窗内部，按Tab时循环切换弹窗内的可聚焦元素，不会跑到外面。

解决方案2：手动实现焦点锁定（旧版本兼容） #

如果你的项目没法升级PrimeNG版本，那就得自己写代码实现焦点 trap：

步骤： #

1. 弹窗打开时，获取内部所有可聚焦元素（按钮、输入框、链接等）
2. 监听Tab键事件，当焦点在第一个元素按Shift+Tab时跳转到最后一个，在最后一个元素按Tab时跳转到第一个
3. 弹窗关闭时移除事件监听

代码示例（Angular组件）： #

首先在组件里获取弹窗实例，然后处理显示/隐藏事件：

import { Component, ViewChild } from '@angular/core';
import { Dialog } from 'primeng/dialog';

@Component({
  selector: 'app-dialog-demo',
  templateUrl: './dialog-demo.component.html'
})
export class DialogDemoComponent {
  display = false;
  @ViewChild('myDialog') myDialog!: Dialog;
  private focusableElements: HTMLElement[] = [];
  private firstFocusable!: HTMLElement;
  private lastFocusable!: HTMLElement;

  onDialogShow() {
    // 等待弹窗渲染完成再获取元素
    setTimeout(() => {
      // 筛选所有可聚焦的元素
      this.focusableElements = Array.from(
        this.myDialog.el.nativeElement.querySelectorAll(
          'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
        )
      ) as HTMLElement[];

      if (this.focusableElements.length) {
        this.firstFocusable = this.focusableElements[0];
        this.lastFocusable = this.focusableElements.at(-1)!;
        // 默认聚焦第一个元素
        this.firstFocusable.focus();
        // 添加键盘事件监听
        document.addEventListener('keydown', this.handleTabNavigation.bind(this));
      }
    }, 100);
  }

  onDialogHide() {
    // 移除事件监听，避免内存泄漏
    document.removeEventListener('keydown', this.handleTabNavigation.bind(this));
  }

  private handleTabNavigation(event: KeyboardEvent) {
    if (event.key !== 'Tab') return;

    // 处理Shift+Tab（反向切换）
    if (event.shiftKey) {
      if (document.activeElement === this.firstFocusable) {
        event.preventDefault();
        this.lastFocusable.focus();
      }
    } else {
      // 处理正向Tab
      if (document.activeElement === this.lastFocusable) {
        event.preventDefault();
        this.firstFocusable.focus();
      }
    }
  }
}

对应的HTML：

<p-dialog 
  #myDialog
  header="手动焦点锁定弹窗" 
  [(visible)]="display" 
  [modal]="true"
  [appendTo]="'body'"
  (onShow)="onDialogShow()"
  (onHide)="onDialogHide()"
>
  <input type="text" placeholder="第一个可聚焦元素">
  <input type="text" placeholder="第二个可聚焦元素">
  <div class="p-dialog-footer">
    <button pButton label="取消" (click)="display=false"></button>
    <button pButton label="确认" (click)="display=false" class="p-button-primary"></button>
  </div>
</p-dialog>

<button pButton label="显示弹窗" (click)="display=true"></button>

额外注意点 #

• 确保弹窗的appendTo设置为'body'，避免弹窗嵌套在有overflow: hidden或者其他定位的容器里导致焦点异常。
• 如果弹窗内有动态加载的内容，要在内容加载完成后重新获取可聚焦元素，不然会漏掉新增的元素。

很多开发者都遇到过这个问题，尤其是在做无障碍适配的项目中，官方后来才补上了focusTrap这个属性，所以如果能升级版本的话，优先用官方方案最省心。

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