如何避免Focus-Trap在模态框鼠标打开时自动聚焦？

报错原因分析 #

你设置initialFocus: 'false'时出现报错，是因为focus-trap会将字符串类型的initialFocus值当作CSS选择器去查找DOM元素，而页面中不存在选择器为false的元素，因此抛出错误。正确的布尔值写法应该是initialFocus: false（不带引号）。

不过仅修改为布尔值false只能解决报错，还无法实现「鼠标打开不聚焦、键盘打开自动聚焦」的需求，以下是两种可行方案：

方案一：通过触发方式动态配置initialFocus #

核心思路是跟踪模态框的打开触发源（鼠标/键盘），根据触发方式设置initialFocus，并在用户后续切换为键盘操作时手动补全焦点：

1. 跟踪触发方式状态（React示例） #

import { useState } from 'react';
import FocusTrap from 'focus-trap-react';

function Modal({ isOpen, onClose }) {
  const [isKeyboardTriggered, setIsKeyboardTriggered] = useState(false);

  // 绑定到打开按钮的onClick和onKeyDown事件
  const handleOpenTrigger = (e) => {
    // 判断触发源：键盘事件（Enter/Space）或键盘触发的点击事件（e.detail === 0）
    const isKeyboard = e.type === 'keydown' || (e.type === 'click' && e.detail === 0);
    setIsKeyboardTriggered(isKeyboard);
    // 此处添加打开模态框的逻辑（如setIsOpen(true)）
  };

  return (
    isOpen && (
      <FocusTrap
        focusTrapOptions={{
          // 键盘触发时保持默认自动聚焦，鼠标触发时不自动聚焦
          initialFocus: isKeyboardTriggered ? undefined : false,
          onDeactivate: onClose,
          // 鼠标打开后，监听第一次键盘操作，手动聚焦到模态框内第一个可聚焦元素
          onPostActivate: (trap) => {
            if (!isKeyboardTriggered) {
              const handleFirstKeydown = (e) => {
                const firstFocusable = trap.firstFocusableElement;
                if (firstFocusable) firstFocusable.focus();
                document.removeEventListener('keydown', handleFirstKeydown);
              };
              document.addEventListener('keydown', handleFirstKeydown);
            }
          }
        }}
      >
        <div className="modal">
          <button onClick={onClose}>关闭</button>
          <button>确认操作</button>
        </div>
      </FocusTrap>
    )
  );
}

方案二：用CSS控制聚焦环显示（更简洁推荐） #

不需要修改focus-trap的配置，直接通过CSS的:focus-visible伪类实现「仅键盘操作显示聚焦环」的效果，这也是W3C推荐的可访问性实践：

全局CSS样式 #

/* 鼠标触发的聚焦不显示轮廓 */
:focus:not(:focus-visible) {
  outline: none;
}

/* 键盘触发的聚焦保留自定义轮廓样式 */
:focus-visible {
  outline: 2px solid #005FCC;
  outline-offset: 2px;
}

这种方案的优势：

• 无需额外跟踪触发状态，代码更简洁
• 符合可访问性标准：键盘用户仍能看到清晰的聚焦反馈，鼠标用户不会被多余的聚焦环干扰
• 现代浏览器原生支持:focus-visible，如需兼容旧浏览器可引入focus-visible polyfill

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