弹窗代码常见问题：处理重复打开、滚动锁定与键盘关闭

弹窗看起来只是一个遮罩层和一块内容，但实际容易出现一组互相关联的问题：用户连续点击导致弹窗重复打开；弹窗打开时背景页面仍能滚动；关闭后页面滚动位置丢失；按 Escape 没有反应；关闭弹窗后键盘焦点跑到页面开头。这些问题在确认框、登录框、图片预览和移动端菜单中都很常见。

本文使用浏览器原生的 <dialog> 实现一个可运行的模态弹窗，再单独处理页面滚动锁定。原生模态对话框能提供模态语义、焦点管理和 Escape 关闭等基础行为，适合不需要高度定制的弹窗。示例同时加入重复调用保护，以及可处理多个弹窗的滚动锁管理。若项目需要支持较老浏览器，应先确认目标浏览器对 <dialog> 的支持情况，必要时再引入经过维护的兼容方案。

先区分“打开”与“显示”

原生 <dialog> 有两种常见打开方式：

• dialog.show() 或直接添加 open 属性：显示非模态对话框，页面其他部分仍可交互。
• dialog.showModal()：将对话框放入浏览器的顶层模态层，页面其余内容在模态期间不可交互，并由浏览器执行相应的焦点管理。

本文的确认框使用 showModal()。不要用添加 open 属性来代替它：两者的交互语义不同，模态行为也不同。反过来，如果只是一个允许背景继续操作的提示面板，直接使用模态对话框也可能不合适。

可运行示例

下面的代码可以作为独立示例放进页面中运行。弹窗默认关闭，按钮打开弹窗；弹窗中的关闭按钮和 Escape 键都能关闭它。页面滚动锁使用固定定位保存滚动位置，并通过锁定标识避免同一个弹窗重复增加锁定计数。

<style>
  body {
    min-height: 180vh;
    font-family: sans-serif;
  }

  dialog {
    width: min(32rem, calc(100vw - 2rem));
    border: 0;
    border-radius: 0.75rem;
    padding: 1.5rem;
    box-shadow: 0 1rem 3rem rgb(0 0 0 / 25%);
  }

  dialog::backdrop {
    background: rgb(0 0 0 / 55%);
  }

  .dialog-actions {
    display: flex;
    justify-content: flex-end;
    gap: 0.75rem;
  }
</style>

<button id="open-dialog" type="button">打开确认框</button>

<dialog id="confirm-dialog" aria-labelledby="dialog-title">
  <h2 id="dialog-title">确认操作</h2>
  <p>确定要继续吗？这只是示例，不会提交数据。</p>
  <div class="dialog-actions">
    <button id="close-dialog" type="button" autofocus>取消</button>
    <button id="confirm-action" type="button">确定</button>
  </div>
</dialog>

<script>
  const dialog = document.querySelector("#confirm-dialog");
  const openButton = document.querySelector("#open-dialog");
  const closeButton = document.querySelector("#close-dialog");
  const confirmButton = document.querySelector("#confirm-action");

  // 管理所有持有滚动锁的弹窗。
  const scrollLock = (() => {
    const holders = new Set();
    let saved = null;

    function setInlineStyle(element, property, value, priority) {
      if (value) {
        element.style.setProperty(property, value, priority);
      } else {
        element.style.removeProperty(property);
      }
    }

    function lock(holder) {
      if (holders.has(holder)) return;
      holders.add(holder);

      // 只有第一个弹窗负责保存页面状态并锁定页面。
      if (holders.size !== 1) return;

      const body = document.body;
      const root = document.documentElement;
      const y = window.scrollY;
      const scrollbarGap = Math.max(0, window.innerWidth - root.clientWidth);
      const computedPaddingRight =
        parseFloat(getComputedStyle(body).paddingRight) || 0;

      const properties = [
        "position", "top", "left", "right", "width",
        "overflow", "padding-right"
      ];

      saved = {
        y,
        styles: Object.fromEntries(
          properties.map((property) => [
            property,
            [
              body.style.getPropertyValue(property),
              body.style.getPropertyPriority(property)
            ]
          ])
        )
      };

      body.style.setProperty("position", "fixed");
      body.style.setProperty("top", `-${y}px`);
      body.style.setProperty("left", "0");
      body.style.setProperty("right", "0");
      body.style.setProperty("width", "100%");
      body.style.setProperty("overflow", "hidden");

      // 补偿滚动条消失造成的横向位移，并保留原有内边距。
      if (scrollbarGap > 0) {
        body.style.setProperty(
          "padding-right",
          `${computedPaddingRight + scrollbarGap}px`
        );
      }
    }

    function unlock(holder) {
      if (!holders.delete(holder)) return;
      if (holders.size !== 0 || saved === null) return;

      const body = document.body;
      const state = saved;
      saved = null;

      for (const [property, [value, priority]] of Object.entries(state.styles)) {
        setInlineStyle(body, property, value, priority);
      }

      window.scrollTo(0, state.y);
    }

    return { lock, unlock };
  })();

  let opening = false;
  let returnFocusTo = null;

  function openDialog() {
    // 连续点击或重复调用时，不再次 showModal，也不重复锁定页面。
    if (opening || dialog.open) return;

    opening = true;
    returnFocusTo = document.activeElement;

    try {
      scrollLock.lock(dialog);
      dialog.showModal();
    } catch (error) {
      // 例如弹窗未连接到文档，或浏览器拒绝打开时，撤销滚动锁。
      scrollLock.unlock(dialog);
      throw error;
    } finally {
      opening = false;
    }
  }

  function closeDialog() {
    if (dialog.open) dialog.close();
  }

  openButton.addEventListener("click", openDialog);
  closeButton.addEventListener("click", closeDialog);
  confirmButton.addEventListener("click", () => {
    // 实际项目可在这里执行业务操作；操作完成后关闭。
    closeDialog();
  });

  dialog.addEventListener("close", () => {
    // 无论是按钮、Escape，还是其他代码调用 close()，都会走到这里。
    scrollLock.unlock(dialog);

    if (returnFocusTo instanceof HTMLElement &&
        returnFocusTo.isConnected) {
      returnFocusTo.focus();
    }
    returnFocusTo = null;
  });

  // 点击原生 backdrop 时，事件目标通常是 dialog 本身。
  // 通过坐标判断点击是否在对话框矩形之外。
  dialog.addEventListener("click", (event) => {
    if (event.target !== dialog) return;

    const rect = dialog.getBoundingClientRect();
    const outside =
      event.clientX < rect.left ||
      event.clientX > rect.right ||
      event.clientY < rect.top ||
      event.clientY > rect.bottom;

    if (outside) closeDialog();
  });
</script>

示例中的遮罩点击关闭是可选行为。若弹窗包含不可撤销操作、表单填写或复杂步骤，通常应避免用户误点遮罩就丢失内容，可以删除这段点击判断，只保留明确的关闭按钮和 Escape 行为。

问题一：重复打开为什么会报错

对同一个 <dialog> 再次调用 showModal()，并不是可靠的“确保打开”操作；对已经处于打开状态的对话框重复调用，可能抛出异常。常见诱因包括按钮连点、事件绑定了两次、异步请求返回后再次打开，或打开方法被多个组件重复调用。

关键是让打开逻辑具备幂等性：弹窗已经打开，或者正在执行打开流程时，直接返回。示例中的 dialog.open 检查处理已打开状态，opening 则挡住同一轮同步流程里的重复调用。异常处理会在打开失败时撤销刚申请的滚动锁，避免页面永久无法滚动。

不要只通过禁用按钮解决重复打开。禁用按钮可以改善交互反馈，但不能覆盖程序调用、重复监听或异步竞态。也不要在每次打开时都无条件给页面添加“禁止滚动”样式，或在每次关闭时都移除该样式：多个弹窗同时存在时，一个弹窗关闭就可能错误地解除另一个弹窗所需的锁。

问题二：滚动锁定不等于设置一个 overflow

桌面浏览器常见做法是打开弹窗时给 body 设置 overflow: hidden，关闭时再移除。但这会遇到几种边界：

• 页面滚动条消失后，可用内容宽度改变，页面可能发生横向位移。示例通过测量视口与文档宽度的差值，补偿滚动条占用的空间；如果当前布局没有滚动条，补偿值为零。
• 移动端浏览器的根滚动区域和视口行为并不完全一致，仅设置 overflow: hidden 未必能阻止背景滚动。示例使用 position: fixed 固定 body，并记录 scrollY，解锁后恢复原位置。
• 锁定时应保留页面原有的行内样式。示例保存相关 CSS 属性原值及优先级，在最后一个持有者释放时还原，而不是粗暴清空整个 style 属性。
• 如果页面在锁定期间发生内容高度变化，恢复滚动位置时可能受到新布局影响；长页面、动态内容和移动端虚拟键盘场景都应在实际设备上验证。

锁定管理器用 Set 记录持有者。一个弹窗重复调用 lock() 不会重复登记；只有第一个持有者到来时才锁页面，最后一个持有者释放后才恢复页面。示例只有一个弹窗，但这避免了简单计数器常见的失衡问题：同一个弹窗误调用两次加锁、只调用一次解锁，页面就会一直被锁住。

这段实现针对示例所需的页面级滚动锁，不是适用于所有布局的通用滚动库。若弹窗内容本身需要滚动，应把可滚动区域放在弹窗内部，并为它设置合适的高度和 overflow: auto；不要让整个页面和弹窗内容争抢同一个滚动区域。复杂的嵌套弹窗、侧边抽屉和手势滚动，还需要针对目标浏览器测试。

问题三：Escape、关闭事件与焦点

使用 showModal() 打开的原生对话框通常能通过 Escape 触发取消并关闭。示例没有拦截 cancel 事件，因此保留了这一默认行为。关闭按钮调用 dialog.close()；无论通过按钮、Escape 还是其他代码关闭，后续清理都集中在 close 事件中，避免遗漏解锁操作。

如果业务要求用户必须先保存或确认，不能直接关闭，可以监听 cancel 并调用 event.preventDefault() 阻止默认关闭，再向用户提供明确的下一步。但不建议没有理由地屏蔽 Escape：键盘用户习惯用它退出临时界面，禁用后必须确保仍有清晰可达的关闭方式。

原生模态对话框负责相应的模态焦点行为；示例通过 autofocus 将初始焦点放到“取消”按钮，并在关闭后尝试把焦点还给打开弹窗的元素。保存并恢复焦点时检查了 isConnected，因为原触发按钮可能已被页面更新移除。实际页面还应检查焦点恢复目标是否仍可见、可交互。若关闭弹窗后界面状态发生变化，把焦点移到新内容的标题或操作控件可能比返回原按钮更合适。

不应把 aria-modal="true" 当成实现模态行为的开关。ARIA 属性用于辅助技术理解界面语义，不会替代遮挡背景交互、管理焦点或锁定滚动。使用原生 showModal() 时，优先依靠其原生语义；若自己实现非原生弹窗，则需要完整处理键盘操作、焦点约束、焦点恢复和背景不可交互等事项，而不只是添加几个 ARIA 属性。

常见错误检查表

• 给每个打开请求都创建一个遮罩。 应先判断当前弹窗状态；确实需要多个弹窗时，明确管理层级、焦点和滚动锁，而不是任由多个打开流程互相覆盖。
• 在打开时锁滚动，却只在某个按钮点击时解锁。 用户按 Escape 或代码调用 close() 时会漏掉清理。把清理放在统一的关闭事件或可靠的生命周期入口中。
• 关闭时直接清空 body 样式。 这可能破坏页面原有的定位、宽度和滚动设置。保存并恢复自己修改的属性，或使用隔离良好的样式管理方案。
• 只处理鼠标点击，不考虑键盘。 提供可聚焦的关闭控件，保留合理的 Escape 行为，并验证打开和关闭后的焦点位置。
• 把遮罩点击关闭当作固定需求。 这是产品交互选择，不是弹窗的必备行为。输入未保存内容时，误点遮罩可能造成数据丢失。
• 认为示例中的弹窗能代替安全校验。 弹窗只是界面交互，不是权限控制或输入验证机制。

安全边界：弹窗不是安全控制

模态对话框让页面其他部分在交互上不可用，但它不会保护后端接口，也不会阻止用户通过开发者工具、脚本或直接请求绕过前端限制。需要授权的操作必须由服务端验证权限；表单字段必须按业务规则在服务端校验。涉及删除、支付或账号变更时，弹窗里的“确认”只是交互步骤，不是可信的安全凭证。

插入弹窗内容时也要区分可信结构与外部数据。示例把标题和文字直接写在 HTML 中；若内容来自用户输入或接口数据，优先使用 textContent 设置文本，不要未经清理就拼进 innerHTML，否则可能引入跨站脚本风险。对于可能被动态替换的弹窗节点，还要确保事件监听不会因重复初始化而重复绑定。

示例中的 Set、dialog.open 和样式保存逻辑，不是浏览器提供的参数限制，也不代表弹窗可打开次数、文本长度或内容类型有统一上限。具体限制取决于浏览器、页面实现和业务规则；不要把某个示例的实现细节描述成平台保证。对于大体量内容，应在产品层面决定分页、滚动区域或加载方式，并对目标设备进行测试。

落地前的验证步骤

1. 快速连续点击打开按钮，确认只有一个对话框，且控制台没有异常。
2. 打开弹窗后滚动页面，再分别通过关闭按钮和 Escape 关闭，确认页面恢复到原滚动位置。
3. 检查弹窗打开时背景是否还能操作，弹窗内部内容是否能按预期滚动。
4. 用键盘打开弹窗，确认初始焦点合理、Tab 操作可用，关闭后焦点回到合适位置。
5. 在目标移动端浏览器、长页面和页面滚动条始终显示或始终隐藏的布局中复测滚动锁与横向位移。

处理弹窗问题时，优先选择语义合适的原生能力，再把重复调用保护、滚动锁生命周期和焦点恢复补齐。把打开与清理设计成一对明确的状态转换，往往比不断增加临时的 CSS 修补更可靠。