LWC 模态框焦点陷阱：除了 keydown 手动管理，还有哪些选择？

在 LWC (Lightning Web Components) 中构建模态框（Modal）或对话框（Dialog）时，一个关键的无障碍（Accessibility, a11y）要求是实现“焦点陷阱”（Focus Trap）。这意味着当模态框打开时，用户的键盘焦点（通常通过 Tab 键切换）应该被限制在模态框内部的可聚焦元素之间循环，而不能意外地“逃逸”到模态框后面的页面内容上。最常见的方法是监听 keydown 事件，手动判断 Tab 或 Shift+Tab，然后查询模态框内所有可聚焦元素，并手动调用 focus() 方法。但这种方法，尤其是在模态框内容动态变化时，维护起来可能变得繁琐且容易出错。那么，除了这种“经典”方法，还有没有其他更优雅或更健壮的技术或模式呢？我们来探讨几种可能性。

方法一：keydown 事件监听与手动焦点管理 (基准方案)

这是大家最熟悉的方式。核心逻辑通常放在模态框组件的 JavaScript 文件中。

// Inside your LWC component's JS file
import { LightningElement, api } from 'lwc';
 
export default class Modal extends LightningElement {
    @api isOpen = false;
    _focusableElements = [];
 
    renderedCallback() {
        if (this.isOpen && !this.template.querySelector('.modal-content')) {
            // Wait for modal content to render
            // eslint-disable-next-line @lwc/lwc/no-async-operation
            setTimeout(() => this.trapFocus(), 0);
        }
    }
 
    openModal() {
        this.isOpen = true;
        // Defer focus trapping until modal is rendered
    }
 
    closeModal() {
        this.isOpen = false;
        // Potentially return focus to the element that opened the modal
    }
 
    trapFocus() {
        const modalContent = this.template.querySelector('.modal-content'); // Assuming a container element
        if (!modalContent) return;
 
        // Query all focusable elements within the modal
        this._focusableElements = Array.from(
            modalContent.querySelectorAll(
                'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
            )
        ).filter(el => !el.disabled && el.offsetParent !== null); // Filter out disabled or hidden elements
 
        if (this._focusableElements.length > 0) {
            // Focus the first focusable element initially
            this._focusableElements[0].focus();
 
            // Add keydown listener to the modal container
            modalContent.addEventListener('keydown', this.handleKeyDown.bind(this));
        }
    }
 
    handleKeyDown(event) {
        if (event.key !== 'Tab') return;
 
        const firstElement = this._focusableElements[0];
        const lastElement = this._focusableElements[this._focusableElements.length - 1];
        const currentFocus = this.template.activeElement;
        const currentIndex = this._focusableElements.indexOf(currentFocus);
 
        event.preventDefault(); // Prevent default tab behavior
 
        if (event.shiftKey) {
            // Shift + Tab
            if (currentFocus === firstElement || currentIndex === -1) {
                // If focus is on the first element or somehow outside, wrap to the last
                lastElement.focus();
            } else {
                // Move focus to the previous element
                this._focusableElements[currentIndex - 1].focus();
            }
        } else {
            // Tab
            if (currentFocus === lastElement || currentIndex === -1) {
                // If focus is on the last element or somehow outside, wrap to the first
                firstElement.focus();
            } else {
                // Move focus to the next element
                this._focusableElements[currentIndex + 1].focus();
            }
        }
    }
    
    // Remember to remove the event listener when the modal is closed or destroyed!
    disconnectedCallback() {
       const modalContent = this.template.querySelector('.modal-content');
       if (modalContent) {
           modalContent.removeEventListener('keydown', this.handleKeyDown.bind(this));
       }
    }
}

优点:

• 原生、无依赖: 完全使用 LWC 和标准 Web API 实现，不需要引入外部库。
• 概念直接: 逻辑相对容易理解，控制流清晰。

缺点:

• 手动管理: 需要精确地查询所有可聚焦元素。查询选择器可能需要根据具体内容调整 ('button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])')。
• 动态内容: 如果模态框内的元素（如按钮、输入框）是动态添加或删除的，_focusableElements 列表需要被手动更新。这通常意味着需要在每次内容变化后重新调用 trapFocus 或类似逻辑，增加了复杂性。
• 可见性/禁用状态: 过滤逻辑 (!el.disabled && el.offsetParent !== null) 需要仔细处理，确保只包括实际用户可以交互的元素。
• 代码冗余: 如果项目中有多个模态框，这段逻辑可能需要在多处重复或进行抽象封装。

方法二：结合 MutationObserver 动态维护焦点列表

为了解决 keydown 方法在处理动态内容时的痛点，我们可以引入 MutationObserver。它的作用是观察 DOM 树的变化。当模态框内部结构发生改变（例如，添加/删除了一个按钮，或者某个元素的 disabled 状态改变）时，MutationObserver 会得到通知，此时我们可以重新计算可聚焦元素列表。

// Inside your LWC component's JS file (extending Method 1)
import { LightningElement, api } from 'lwc';
 
export default class ModalWithObserver extends LightningElement {
    // ... (isOpen, openModal, closeModal, handleKeyDown - mostly same as Method 1) ...
    _focusableElements = [];
    _observer = null;
 
    renderedCallback() {
        if (this.isOpen && !this.template.querySelector('.modal-content')) {
            // eslint-disable-next-line @lwc/lwc/no-async-operation
            setTimeout(() => this.initializeFocusTrap(), 0);
        }
    }
 
    initializeFocusTrap() {
        const modalContent = this.template.querySelector('.modal-content');
        if (!modalContent) return;
 
        // Initial population of focusable elements
        this.updateFocusableElements();
 
        if (this._focusableElements.length > 0) {
            this._focusableElements[0].focus();
            modalContent.addEventListener('keydown', this.handleKeyDown.bind(this));
 
            // Setup MutationObserver
            this.setupMutationObserver(modalContent);
        }
    }
 
    updateFocusableElements() {
        const modalContent = this.template.querySelector('.modal-content');
        if (!modalContent) {
            this._focusableElements = [];
            return;
        }
        
        this._focusableElements = Array.from(
            modalContent.querySelectorAll(
                'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
            )
        ).filter(el => !el.disabled && el.offsetParent !== null);
        console.log('Focusable elements updated:', this._focusableElements);
    }
 
    setupMutationObserver(targetNode) {
        const config = { childList: true, subtree: true, attributes: true, attributeFilter: ['disabled', 'hidden', 'style', 'class'] }; // Observe relevant changes
 
        const callback = (mutationsList, observer) => {
            // Simple approach: recalculate on any observed mutation
            // More optimized: Check mutationsList details if performance is critical
            console.log('DOM changed, re-evaluating focusable elements...');
            this.updateFocusableElements();
            // Note: If the currently focused element is removed/disabled,
            // you might need additional logic to shift focus appropriately.
            // This basic example just updates the list for the *next* Tab press.
        };
 
        this._observer = new MutationObserver(callback);
        this._observer.observe(targetNode, config);
    }
 
    handleKeyDown(event) {
       // ... (Same logic as Method 1, but uses the dynamically updated _focusableElements) ...
        if (event.key !== 'Tab') return;
 
        // Ensure the list is up-to-date right before using it
        // (Could be slightly redundant if observer callback just ran, but safer)
        // this.updateFocusableElements(); // Optional: uncomment if strict timing is needed
 
        if (this._focusableElements.length === 0) return; // No focusable elements
 
        const firstElement = this._focusableElements[0];
        const lastElement = this._focusableElements[this._focusableElements.length - 1];
        // ... rest of the Tab/Shift+Tab logic ...
        const currentFocus = this.template.activeElement;
        const currentIndex = this._focusableElements.indexOf(currentFocus);
 
        event.preventDefault(); 
 
        if (event.shiftKey) { 
            if (currentFocus === firstElement || currentIndex === -1 || this._focusableElements.length === 1) {
                lastElement.focus();
            } else {
                this._focusableElements[Math.max(0, currentIndex - 1)].focus();
            }
        } else { 
            if (currentFocus === lastElement || currentIndex === -1 || this._focusableElements.length === 1) {
                firstElement.focus();
            } else {
                this._focusableElements[Math.min(this._focusableElements.length - 1, currentIndex + 1)].focus();
            }
        }
    }
 
    disconnectedCallback() {
        if (this._observer) {
            this._observer.disconnect();
            this._observer = null;
        }
        const modalContent = this.template.querySelector('.modal-content');
        if (modalContent) {
            modalContent.removeEventListener('keydown', this.handleKeyDown.bind(this));
        }
    }
}

优点:

• 动态适应: 能自动响应模态框内部 DOM 的变化，无需手动干预更新焦点列表。
• 更健壮: 对于包含条件渲染 (if:true/if:false) 或迭代 (for:each) 的复杂模态框内容，此方法更可靠。

缺点:

• 增加复杂度: 引入了 MutationObserver，需要理解其配置和回调机制。
• 潜在性能开销: 如果模态框内部 DOM 变化非常频繁，MutationObserver 的回调和随后的 querySelectorAll 可能带来微小的性能影响。但在典型的模态框场景下，这通常不是问题。
• 仍依赖 keydown: 核心的焦点捕获逻辑（阻止 Tab 移出、循环焦点）仍然依赖 keydown 事件监听器。
• 焦点管理细节: 当当前焦点元素被移除或禁用时，需要额外的逻辑来决定焦点应该移动到哪里（例如，移动到前一个或后一个元素），上述示例未完全处理此边缘情况。

方法三：利用 Shadow DOM 的边界 (相关考量)

LWC 使用 Shadow DOM 来封装组件的内部结构。这本身并不直接提供焦点陷阱功能，但它影响着焦点如何在组件内部以及如何查询元素。

• 内部循环: 如果焦点已经在 Shadow Root 内部，并且没有外部脚本或浏览器行为强制将焦点移出，Tab 键通常会在该 Shadow Root 内的自然 Tab 顺序中循环。但是，一旦到达最后一个可聚焦元素，默认行为仍然是尝试将焦点移出 Shadow Root 到文档的下一个元素。所以，Shadow DOM 本身不能防止焦点“逃逸”。
• 元素查询: 在 LWC 组件内部，this.template.querySelector 和 this.template.querySelectorAll 是在组件的 Shadow Root 中查询。这对于查找模态框内的元素很方便。但如果模态框使用了 slot 来接收外部传入的内容，查询这些“被投射”进来的元素会稍微复杂些，可能需要结合 this.querySelector（查询 Light DOM 子元素）或 this.template.querySelector('slot').assignedNodes() 来检查 slot 中的内容。

思考: Shadow DOM 的封装性有助于管理组件内部的焦点流，但它不是一个焦点陷阱的解决方案。你仍然需要上述的 keydown 监听（可能结合 MutationObserver）来强制将焦点限制在模态框组件（及其 Shadow Root）的边界内。

方法四：尝试集成轻量级 JS 库 (如 focus-trap)

社区中有一些成熟的、专门用于处理焦点陷阱的 JavaScript 库，例如 focus-trap (https://github.com/focus-trap/focus-trap)。能否在 LWC 中使用它们呢？

挑战:

1. Locker Service / Lightning Web Security: Salesforce 的安全架构会限制 JavaScript 代码对全局对象（如 document）的直接访问，并可能修改某些 DOM API 的行为。库如果依赖不受限制的全局访问或特定的 DOM 行为，可能会不兼容。
2. Shadow DOM: 库通常在全局 document 上操作。它们需要能够正确地查询到 LWC 组件 Shadow Root 内的元素，并能将事件监听器正确附加。

可能的集成方式:

1. 静态资源: 将库的 UMD 或 ES 模块版本上传为 Salesforce 静态资源。
2. 加载与初始化: 在 LWC 组件的 renderedCallback 或连接逻辑中，使用 loadScript 从静态资源加载库。
3. 传递 LWC 元素: 关键在于初始化库时，需要将 LWC 模态框的根元素（通常是 this.template.querySelector('.modal-container') 或类似的选择器选中的元素）传递给库。focus-trap 库就支持一个 elements 选项或直接传入一个容器元素。

// Conceptual Example - Requires 'focus-trap' library loaded as static resource
import { LightningElement, api } from 'lwc';
import { loadScript } from 'lightning/platformResourceLoader';
import focusTrapResource from '@salesforce/resourceUrl/focusTrap'; // Assume library is uploaded
 
export default class ModalWithLibrary extends LightningElement {
    @api isOpen = false;
    _trap = null;
    _isLibLoaded = false;
 
    renderedCallback() {
        if (this.isOpen && this._isLibLoaded && !this._trap) {
            const modalElement = this.template.querySelector('.modal-container');
            if (modalElement) {
                // Check if the library's global object exists (e.g., window.focusTrap)
                if (window.focusTrap) { 
                    this._trap = window.focusTrap(modalElement, {
                        // Library specific options might be needed here
                        // e.g., initialFocus: false, // Maybe handle initial focus manually
                        // escapeDeactivates: false, // Let LWC handle close
                        // allowOutsideClick: true, // If needed
                        // onActivate: () => { console.log('Trap activated'); },
                        // onDeactivate: () => { console.log('Trap deactivated'); }
                    });
                    this._trap.activate();
                    // Manually focus the first element if library doesn't handle it
                    // Or configure the library to do so
                    const firstFocusable = modalElement.querySelector('button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])');
                    if (firstFocusable) firstFocusable.focus();
                }
            }
        } else if (!this.isOpen && this._trap) {
            this._trap.deactivate();
            this._trap = null;
        }
 
        if (!this._isLibLoaded) {
            loadScript(this, focusTrapResource + '/focus-trap.min.js') // Adjust path as needed
                .then(() => {
                    this._isLibLoaded = true;
                    console.log('Focus trap library loaded.');
                    // Trigger re-render or check if modal should be activated now
                    if (this.isOpen) {
                        this.renderedCallback(); // Re-run logic to activate trap
                    }
                })
                .catch(error => {
                    console.error('Error loading focus trap library:', error);
                });
        }
    }
 
    openModal() { this.isOpen = true; }
    closeModal() { this.isOpen = false; }
 
    disconnectedCallback() {
        if (this._trap) {
            this._trap.deactivate();
            this._trap = null;
        }
    }
}

优点:

• 重用成熟逻辑: 利用了社区验证过的、处理了各种边缘情况的库代码。
• 减少自定义代码: 大幅减少自己编写 keydown 监听和焦点管理逻辑的需要。
• 可能更健壮: 库通常对动态内容、隐藏元素等有更好的内置处理。

缺点:

• 外部依赖: 引入了第三方库，增加了项目的依赖管理和潜在的维护负担。
• 兼容性风险: 需要仔细测试库在 LWC 的 Locker Service/LWS 和 Shadow DOM 环境下的兼容性。可能需要库本身支持或允许传入 Shadow Root 作为上下文，或者需要一些适配代码。
• Payload 大小: 增加了需要下载的 JavaScript 文件大小。
• 调试: 如果库内部出现问题，调试可能比调试自己的原生代码更困难。

对比与选择

如何选择？

• 简单、静态内容的模态框: 基础的 keydown 手动管理方法可能足够了，简单直接。
• 内容动态变化、复杂的模态框: keydown + MutationObserver 是一个纯 LWC 的健壮解决方案，能很好地处理动态性，但需要多写一些代码。
• 追求简洁、愿意引入依赖: 如果能找到一个与 LWC 兼容良好（或稍加适配即可）的轻量级焦点陷阱库，这可能是代码量最少、功能最完善的选择。但务必充分测试其在 Locker Service/LWS 和 Shadow DOM 下的行为。
• 团队熟悉度: 选择团队成员更熟悉和更容易维护的技术栈。

总结:

实现 LWC 模态框的焦点陷阱，基础的 keydown 手动管理是起点。当面临动态内容时，结合 MutationObserver 可以显著提高鲁棒性。而引入外部库则提供了一条潜在的捷径，但也带来了依赖和兼容性的考量。理解这些方法的原理、优缺点和适用场景，能帮助你为具体的 LWC 应用选择最合适的焦点陷阱实现策略，最终提升应用的可访问性和用户体验。记住，无论选择哪种方法，彻底的测试都是必不可少的！