HTML dialog 的 cancel 与 close 事件处理

HTML

里最容易混淆的地方，是把 cancel 和 close 都当成“弹窗关闭了”。更准确的分工是：cancel 表示用户或代码发起了关闭请求，可以用 preventDefault() 拦截；close 表示对话框已经关闭，只负责通知后续收尾。

先分清 cancel 是请求，close 是结果

我在给一个确认弹窗增加“未保存内容提醒”时，最初把提示和清理都写进了 close。结果是：用户按 Esc 后，代码已经收到了关闭通知，却没有机会在关闭前询问是否真的要放弃。原因不在监听器注册方式，而在事件语义不同。

cancel 是 dialog 收到关闭请求时发出的可取消事件，事件不会冒泡。常见请求入口包括桌面端按 Esc，以及调用 requestClose()。如果在这个事件里调用 event.preventDefault()，对话框保持打开；如果不拦截，浏览器继续完成关闭并发出 close。

close 则是关闭已经发生后的通知，同样不会冒泡，但它不可取消。它适合做状态同步、读取 returnValue、移除临时监听器等收尾工作，不适合再试图阻止关闭。

用 preventDefault() 处理真正的关闭请求

需要在关闭前确认时，把判断放到 cancel。下面的示例只拦截“还有草稿内容”的情况；用户确认放弃后，不调用 preventDefault()，浏览器会继续关闭并随后触发 close。

const dialog = document.querySelector("#edit-dialog");
const draft = document.querySelector("#draft");

dialog.addEventListener("cancel", (event) => {
  // cancel 是关闭请求；有未保存内容时先拦截默认关闭。
  if (draft.value.trim() !== "" && !window.confirm("放弃未保存内容吗？")) {
    event.preventDefault();
  }
});

dialog.addEventListener("close", () => {
  // close 只做关闭后的收尾，不再尝试阻止关闭。
  draft.value = "";
  console.log("dialog closed", dialog.returnValue);
});

这里的关键不是 confirm，而是“只在请求阶段拦截”。如果确认框返回 true，监听器自然结束，dialog 进入关闭状态；如果返回 false，preventDefault() 让用户回到编辑界面。

不同关闭入口应该监听哪一个事件

几个 API 的差异可以这样记：requestClose() 模拟一次可拦截的关闭请求，因此会给 cancel 留出处理机会；close() 是直接关闭，重点是之后的 close 通知。带有 method="dialog" 的表单提交也会关闭 dialog，结果处理仍然放在 close。

const dialog = document.querySelector("#settings-dialog");
const openButton = document.querySelector("#open-settings");
const requestButton = document.querySelector("#request-close");

openButton.addEventListener("click", () => {
  // showModal 只负责打开；关闭策略由下面的事件监听器决定。
  dialog.showModal();
});

requestButton.addEventListener("click", () => {
  // requestClose 会先产生 cancel，适合统一处理“关闭前确认”。
  dialog.requestClose("requested");
});

dialog.addEventListener("close", () => {
  // close()、method=dialog 或未拦截的 requestClose 都在这里汇合。
  console.log("returnValue:", dialog.returnValue);
});

如果要兼容不支持 requestClose() 的旧环境，应把兼容策略放在自己的关闭按钮逻辑中，并明确区分“需要确认的请求”与“确定后的直接关闭”。不要假设所有关闭入口都会触发 cancel。

把 returnValue 和清理动作放在 close

dialog 的 returnValue 是关闭时传递结果的小通道：调用 close("saved")，或让表单按钮提供对应值，关闭监听器就可以读取它。它适合表达“用户选了什么”，但不应该拿来代替关闭前的拦截判断。

场景	优先监听	处理职责
按 Esc 关闭	cancel	判断是否拦截；放行后再由 close 收尾
调用 requestClose()	cancel + close	前者确认，后者同步最终状态
调用 close()	close	读取 returnValue 并清理
method="dialog" 表单	close	按按钮值处理结果，不把提交当成普通页面跳转

还有一个容易漏掉的边界：cancel 和 close 都不冒泡，所以应该直接监听具体的

元素，而不是把监听器挂到外层容器上等待事件冒泡。若要同步遮罩、焦点或页面上的“当前弹窗”标记，也建议统一放在 close 中，避免多个关闭入口各写一套清理逻辑。

常见问题

调用 dialog.close() 会先触发 cancel 吗？

不会。close() 直接关闭并触发 close；需要关闭前拦截时，应使用能产生关闭请求的路径并监听 cancel。

close 事件里还能调用 preventDefault() 吗？

不能用它阻止已经完成的关闭。关闭前的确认、校验或阻止动作放在可取消的 cancel 中。

为什么在 document 上监听不到 dialog 的 cancel？

因为该事件不冒泡。把监听器直接注册到目标 dialog 元素，或者在创建组件时保存目标引用。