网页弹窗按 ESC 怎么统一关闭：CloseWatcher 与 dialog 的回退边界

网页里同时放着

把真正的收尾动作集中到 close 事件，把脏数据确认放在 cancel 事件；关闭按钮也调用 requestClose() 走同一条链路。这样 ESC、系统返回和按钮关闭才不会各写一套清理逻辑。

CloseWatcher 解决的是关闭责任链

原生 dialog 和 popover 可以获得浏览器提供的关闭行为，但自定义侧边栏、命令面板或日期选择器没有同样的设备语义。桌面端常见的是 ESC，移动端可能是系统返回动作；如果每个组件分别监听键盘事件，层级一多就会互相抢事件。

可以把它看成一条很短的责任链：

• 设备或按钮提出关闭请求；
• cancel 判断是否有未保存内容、上传任务或二次确认；
• 没有被阻止时执行 close，统一隐藏组件、恢复焦点并销毁 watcher。

这里的关键不是替换所有 keydown，而是让“是否允许关闭”和“关闭后的清理”分开。

最小实现：按钮和 ESC 共享 requestClose

function mountPicker(picker, returnFocus) {
  if (!('CloseWatcher' in window)) {
    return mountEscFallback(picker, returnFocus);
  }

  const watcher = new CloseWatcher();
  let dirty = false;

  watcher.addEventListener('cancel', (event) => {
    if (dirty && !window.confirm('还有未保存内容，确定关闭吗？')) {
      event.preventDefault();
    }
  });

  watcher.addEventListener('close', () => {
    picker.hidden = true;
    picker.setAttribute('aria-hidden', 'true');
    watcher.destroy();
    returnFocus?.focus();
  });

  picker.querySelector('[data-close]').addEventListener('click', () => {
    watcher.requestClose();
  });

  picker.hidden = false;
  picker.setAttribute('aria-hidden', 'false');
  picker.querySelector('input, button, [tabindex="0"]')?.focus();

  return {
    markDirty(value) { dirty = value; },
    closeNow() { watcher.close(); }
  };
}

按钮不直接设置 hidden，而是调用 requestClose()，因此它和设备关闭动作都会经过同一个确认点。close() 留给“已经确认过”的路径，例如保存成功后强制收起面板。

cancel 和 close 的边界不能倒置

cancel 是阻止关闭的地方。监听器里调用 preventDefault() 后，后续 close 不会发生；如果在 close 里才弹确认框，组件已经进入关闭流程，焦点和遮罩清理很容易变成半完成状态。

watcher.addEventListener('cancel', (event) => {
  if (uploading) {
    event.preventDefault();
    showToast('文件上传完成后才能关闭');
  }
});

watcher.addEventListener('close', () => {
  stopPreview();
  restoreScrollLock();
  triggerButton.focus();
});

一个实用判断是：凡是“关闭前还可能改变决定”的逻辑放 cancel；凡是“不管由谁关闭都必须做”的逻辑放 close。

嵌套组件要按关闭层级管理 watcher

页面可能先打开抽屉，再在抽屉里打开 picker。关闭请求应该优先交给最内层组件，picker 关闭后下一次 ESC 才轮到抽屉。不要让每个组件都额外注册全局 keydown，否则一次按键可能同时改变两个可见状态。

每次打开自定义组件时创建一个 watcher，每次完成关闭时调用 close() 或 destroy()。特别是定时器、路由切换和组件卸载路径，也要调用销毁函数，避免一个已经不可见的组件继续参与关闭分组。

CloseWatcher 不支持时的回退

MDN 目前将 CloseWatcher 标为 Limited availability，因此能力检测不能省。回退监听必须限定在当前打开的组件，并且只处理 ESC；手机系统返回、原生 dialog 的默认行为不能简单假装成完全等价。

function mountEscFallback(picker, returnFocus) {
  const onKeydown = (event) => {
    if (event.key !== 'Escape') return;
    event.preventDefault();
    picker.dispatchEvent(new CustomEvent('fallback-close-request', {
      cancelable: true
    }));
  };

  document.addEventListener('keydown', onKeydown);
  picker.addEventListener('fallback-close-request', (event) => {
    if (picker.dataset.dirty === 'true' && !confirm('放弃未保存内容？')) {
      event.preventDefault();
      return;
    }
    picker.hidden = true;
    document.removeEventListener('keydown', onKeydown);
    returnFocus?.focus();
  }, { once: true });
}

这个回退示例只覆盖键盘路径。若产品必须支持系统返回，需要结合目标浏览器和平台的导航能力单独验收，不要把一次桌面端测试结果当成移动端事实。

常见反例：close 了但 watcher 还活着

调用 picker.hidden = true 并不会自动销毁自定义 watcher。下次页面再创建一个 watcher 时，旧实例可能仍然参与关闭请求，表现为按一次 ESC 关闭两个层级，或者第一次按键没有作用。

另一个反例是同时创建多个没有用户激活来源的 watcher。规范和 MDN 都提示这类 watcher 可能被分组，一次关闭请求会一起关闭它们。实际工程里，嵌套层级最好只有一个组件负责当前的设备关闭请求，子组件通过父组件提供的关闭函数退出。

上线前检查关闭链路

相关问题

CloseWatcher 能替代 dialog 的 cancel 事件吗？

不能简单替代。原生 dialog 已有自己的模态和关闭语义；CloseWatcher 更适合补给抽屉、picker 等自定义可关闭组件。两者混用时要明确谁拥有当前最外层关闭责任。

为什么 requestClose 后 close 没有触发？

先检查 cancel 是否调用了 preventDefault()，再检查 watcher 是否已经被 close() 或 destroy() 停用。关闭请求不是永久事件，watcher 生命周期结束后不会继续接收。

旧浏览器应该直接放弃这个 API 吗？

不必。把 CloseWatcher 当增强路径，用能力检测接入；核心组件仍应有按钮关闭、焦点恢复和受作用域限制的 ESC 回退。对系统返回这类平台差异，要在目标设备矩阵中单独确认。

弹窗关闭做得稳，靠的不是给每层都加一个 ESC 监听，而是把请求、拦截、收尾和销毁排成一条可追踪的链。CloseWatcher 能减少自定义组件与设备行为之间的胶水代码，但它的兼容性和 watcher 生命周期仍然需要工程化验收。