Popover API 如何实现点击外部关闭：popover、beforetoggle 与无障碍焦点验收

做帮助菜单时，最容易留下两个小问题：用户点到页面空白处，菜单还挂着；按下 Esc 之后，焦点也不知道回到哪里。原生 Popover API 已经把“显示在顶层、点击外部关闭、按键退出”这些基础行为交给浏览器，关键是把入口元素、状态事件和焦点验收接好。

把弹层设置为 popover="auto"，用 popovertarget 建立按钮关联，再用 beforetoggle 做打开前准备、用 toggle 做关闭后的清理，最后用键盘路径检查焦点是否回到触发按钮。

先把按钮和 popover 组成一条可验收的路径

这次示例只做一个“字段说明”帮助菜单。按钮负责打开，弹层内部放说明文字和关闭按钮；用户点击页面其他区域或按 Esc 时，浏览器负责关闭。下面这组节点就是后面配图和验收要追踪的真实路径：button → popover → light dismiss。

字段说明


  
订单号
  
订单号用于查询物流和售后记录。
  关闭

popovertarget 的值必须和目标元素的 id 完全一致。这里没有手动监听按钮的 click，也没有给页面加一层遮罩；popover="auto" 使浏览器知道这是一个可以被 light dismiss 的弹层。

什么时候不要把 popover 当成模态对话框

字段说明、筛选提示、操作菜单适合 Popover。需要阻止用户操作背景、要求完成确认或填写表单的场景，更接近

用 beforetoggle 和 toggle 分开处理状态

弹层的状态变化有两个观察点。beforetoggle 在变化前发生，事件里的 newState 可以告诉我们即将进入 open 还是 closed；toggle 在变化完成后发生，适合记录最终状态或清理一次性的内容。

const help = document.querySelector('#field-help');
const helpButton = document.querySelector('#help-button');

help.addEventListener('beforetoggle', (event) => {
  if (event.newState === 'open') {
    help.dataset.openedAt = String(Date.now());
  }
});

help.addEventListener('toggle', (event) => {
  if (event.newState === 'closed') {
    delete help.dataset.openedAt;
    helpButton.focus();
  }
});

这里的 beforetoggle 只做打开前准备，不在其中再次调用 showPopover() 或 hidePopover()；状态还在切换中时重复触发显示隐藏操作，会造成无效状态或异常。toggle 看到 closed 后再清除临时字段，并把焦点交还给 helpButton，这一步是键盘用户能否继续操作的关键。

焦点验收要覆盖三条关闭路径

用鼠标点按钮打开后，先点击弹层外部，确认弹层消失且焦点回到 helpButton。再用 Tab 聚焦按钮，按 Enter 打开，按 Esc 关闭，观察焦点是否仍在触发按钮。最后从弹层内的“关闭”按钮触发隐藏，检查清理逻辑不会让焦点掉到页面最前面。

• 打开：按钮可获得焦点，弹层进入 :popover-open 状态。
• 外部关闭：popover="auto" 触发 light dismiss，弹层从顶层移除。
• 键盘关闭：Esc 能结束弹层，焦点回到 helpButton。

常见误区：为什么自己写 document click 反而更脆

手写 document click 时，通常要判断点击目标是否在弹层内、是否来自打开按钮、弹层是否已经销毁，还要补 Esc 和焦点回退。Popover API 已经处理了 light dismiss 的基础规则，业务代码只需保留真正属于业务的状态同步。

另一个误区是把所有逻辑塞进 beforetoggle。这个事件发生在状态变化前，适合校验或准备；依赖“已经关闭”的结果时，应放在 toggle 中。若要做动画，也要遵守事件期间不能递归切换同一弹层的约束。

把这组检查放进组件验收

组件交付前，可以按下面顺序手工走一遍：按钮能否用 Tab 找到；Enter 是否打开；点击外部是否关闭；Esc 是否关闭；关闭后焦点是否回到按钮；弹层重新打开时，临时状态是否重新初始化。浏览器开发者工具里还可以检查目标元素是否出现 :popover-open，避免只凭视觉判断。

相关问题

popover="auto" 和 popover="manual" 有什么区别？

auto 允许 light dismiss，并参与浏览器管理的自动关闭规则；manual 不会因为点击外部自动关闭，适合需要多弹层并存或完全自行管理的场景。

beforetoggle 和 toggle 应该怎么选？

需要在状态变化前准备、阻止或安排动画时看 beforetoggle；需要读取最终状态、清理临时数据或同步外部状态时看 toggle。

为什么关闭后要显式调用 focus？

弹层关闭后，如果焦点没有明确回到触发按钮，键盘用户可能失去当前位置。把焦点返回 helpButton 是一个简单且可验证的组件约定。

小结

这类帮助菜单的最小实现并不复杂：用 popovertarget 连接按钮和 popover，用 auto 获得 light dismiss，再把准备逻辑放进 beforetoggle、把关闭后的清理和焦点回退放进 toggle。真正上线前，按鼠标、Esc、Tab 和内部关闭按钮四条路径复查一次，通常比继续堆 document click 判断更可靠。