原生 dialog 确认器:取消、重入与焦点返回实战

用原生 dialog 与可测试控制器实现本地删除确认,处理 Esc、旧结果污染、重复调用和组件销毁,明确焦点工作流、服务端边界及十项模型测试的验证范围。

点击“删除”之后,遮罩出现了,按钮也能点,并不意味着确认流程已经正确。用户可能按 Esc,可能连点两次,可能确认后列表被刷新,还可能在对话框未关闭时切换页面。视觉上只有一个窗口,代码里却可能留下两个等待中的 Promise,或者把上一次的确认结果带到下一次。

本文用原生 dialog 做一个本地列表删除确认器。重点不是画出弹窗,而是划清三条边界:浏览器负责模态交互,控制器负责一次请求的一次结算,业务代码负责确认后的操作和焦点去向。示例只删除当前页面节点,不请求服务器;不要把这个演示误认为有权限校验的生产删除接口。资料核对日期为 2026 年 11 月 17 日。

先选择原生行为,再决定自己管理什么

这里选择 showModal,而不是给普通 div 加定位与遮罩。原生模态对话框进入顶层,并使窗口之外的页面内容不可交互。open 属性本身并不等于模态打开,CSS 显示也不能替代对应 API。标准行为可查阅 HTML dialog 定义。

另一种方案是采用经过浏览器和辅助技术测试的组件库。它适合已经有统一设计系统、复杂动画和多层浮窗的应用。自制 div 方案看似更自由,却把键盘循环、背景隔离、滚动、层叠、恢复焦点全部变成团队负担。本文的窄场景没有足够理由承担这些工作,也不另外写一套 Tab 拦截器去和浏览器竞争。

但原生元素不能替你决定业务。删除谁、哪个结果代表同意、重复请求怎么办、离开页面时如何释放等待者,都必须有明确契约。本文规定同一时刻只接受一项请求,忙时返回 false,而不是悄悄替换当前内容。只有确切的 confirm 字符串被当作同意;取消、未知值和初始化失败都返回 false。false 在这个接口里代表“不执行”,不一定代表用户主动拒绝。如果业务需要区分失败原因,应把布尔结果扩展成枚举,而不是从日志猜测。

一份能直接使用的页面

在同一目录保存 index.html、app.mjs、confirm.mjs。静态页用 HTTP 打开,例如运行 python3 -m http.server 8080 后访问 localhost 的 8080 端口;不需要安装前端依赖。浏览器必须支持 HTMLDialogElement.showModal。代码不使用近期增加的声明式命令或轻触关闭属性,因此并不把这些新特性的支持情况混入基础示例。

下面的 index.html 包含完整结构。初始按钮禁用,只有脚本成功初始化后才启用,避免 JavaScript 失效时留下一个看似能工作、实际无响应的危险入口。无脚本环境显示说明;更成熟的系统可以给出独立确认页面,但不能在检测失败时直接执行删除。

<!doctype html>
<html lang="zh-CN">
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>本地列表确认演示</title>
<style>
body { font: 1rem/1.6 system-ui; max-width: 48rem; margin: 2rem auto; padding: 1rem; }
dialog { max-width: min(28rem, 85vw); border: 2px solid; padding: 1.5rem; }
dialog::backdrop { background: rgb(0 0 0 / 55%); }
button { font: inherit; padding: .5rem 1rem; margin: .25rem; }
:focus-visible { outline: 3px solid #075dcc; outline-offset: 3px; }
</style>
<h1>本地列表</h1>
<h2 id="list-title" tabindex="-1">待办条目</h2>
<ul><li id="row">演示条目 <button id="remove" disabled>删除条目</button></li></ul>
<p id="status" role="status">正在准备确认功能。</p>
<noscript>请启用 JavaScript;当前不会执行删除。</noscript>
<dialog id="confirm" aria-labelledby="confirm-title" aria-describedby="message">
  <h2 id="confirm-title">删除当前条目?</h2>
  <p id="message"></p>
  <form method="dialog">
    <button value="cancel" autofocus>保留条目</button>
    <button value="confirm">删除条目</button>
  </form>
</dialog>
<script type="module" src="./app.mjs"></script>
</html>

这里的标题提供对话框名称,描述只是一句短提示,不把整块复杂内容塞进描述关系。取消按钮首先获得焦点,是本例对误删成本的选择,不是所有对话框都应遵循的固定顺序。对于需要从头阅读的长文,应另行设计初始阅读位置。关闭后也不能永远把焦点送回触发器,因为删除操作可能已经移除了它。WAI 对话框模式说明了初始焦点、键盘范围和返回位置应结合工作流考虑。

表单的 dialog 方法只用于关闭对话框并提供返回值,不会向服务端提交删除。两个按钮必须明确区分动作,不能都写“确定”。本例保留显式取消按钮和 Esc 路径;没有添加点击遮罩删除、长按确认或自动倒计时等行为。对于这么短的确认,额外花样只会扩大需要验证的交互面。

把所有关闭路径汇入一个结算点

将下面内容保存为 confirm.mjs。控制器只依赖传入的对话框及消息节点,不读取列表,也不发网络请求。这样同一套业务状态逻辑可以用轻量替身测试,而浏览器原生能力仍然需要另外验收。

export function createConfirm(dialog, message) {
  let pending = null;
  let disposed = false;
  function settle(value) {
    const resolve = pending;
    pending = null;
    resolve?.(value);
  }
  function onClose() { settle(dialog.returnValue === 'confirm'); }
  function onCancel(event) {
    event.preventDefault();
    dialog.close('cancel');
  }
  dialog.addEventListener('close', onClose);
  dialog.addEventListener('cancel', onCancel);
  return {
    ask(text) {
      if (disposed || pending || dialog.open) return Promise.resolve(false);
      message.textContent = text;
      dialog.returnValue = '';
      return new Promise(resolve => {
        pending = resolve;
        try { dialog.showModal(); }
        catch { settle(false); }
      });
    },
    dispose() {
      disposed = true;
      dialog.removeEventListener('close', onClose);
      dialog.removeEventListener('cancel', onCancel);
      if (dialog.open) dialog.close('cancel');
      settle(false);
    }
  };
}

pending 同时充当忙标记与当前请求的完成回调。它在窗口打开之前设置,因此同步抛错也有确定的清理路径。settle 先清空标记,再交付结果,允许后续业务在得到结果后开始新的请求。每次打开之前清空 returnValue,是为了避免旧确认值成为新请求的默认答案。

cancel 与 close 不是一回事。cancel 表示取消请求,可以阻止默认行为;close 是窗口已经关闭后的通知。本例在 cancel 上阻止默认关闭,再显式用 cancel 值关闭,把 Esc 纳入同一条结果路径。按钮通过表单关闭时也会抵达 onClose。不要同时在按钮点击、取消和关闭三个地方执行删除,否则一个动作很容易被重复处理。两个事件的接口分别见 cancel 与 close。

close 通知可能排队到后续任务才到达。于是窗口刚消失而通知尚未处理的短间隙里,pending 仍然存在;新的 ask 会得到 false,而不是开启下一项请求后被旧通知误结算。这是一种保守的并发策略。如果产品确实需要连续处理一批确认,应在上一次 Promise 完成后由调用者排队,不能仅凭 open 已经为 false 就抢先复用窗口。

dispose 是组件卸载的出口:移除监听器、关闭窗口,并把尚未完成的请求结算为 false。离开页面不是确认,因此释放资源不能隐式产生同意。控制器销毁之后不允许重新使用。

重新挂载时,仅创建新控制器还不够:本例要求同时使用新的 dialog DOM 节点,不要立即复用旧节点。旧节点的 close 事件可能仍在队列中,包括 dispose 之前已经排队的关闭;如果新实例在事件到达前接管同一节点并打开窗口,旧事件可能把新请求结算为 false,而新窗口仍保持打开。确需复用节点时,应另行设计并测试关闭通知的交接协议,不能只检查 open 或等待一个微任务。

这里也没有把 dialog 从 DOM 移除,因为节点所有权在页面或框架组件,控制器不应擅自处理不属于自己的结构。

业务层负责结果,不让控制器猜测列表

下面保存为 app.mjs。成功后删除节点,并将焦点放到仍然存在的列表标题上;取消时保留条目,回到原按钮。标题使用负 tabindex,只为了程序化焦点定位,不把静态标题额外加入正常 Tab 顺序。

import {createConfirm} from './confirm.mjs';
const dialog = document.querySelector('#confirm');
const remove = document.querySelector('#remove');
const status = document.querySelector('#status');
const heading = document.querySelector('#list-title');
if (typeof dialog.showModal !== 'function') {
  status.textContent = '当前浏览器不支持此确认功能,未执行任何操作。';
} else {
  const confirm = createConfirm(dialog, document.querySelector('#message'));
  let busy = false;
  remove.disabled = false;
  status.textContent = '这是本地演示,不会修改服务器数据。';
  remove.addEventListener('click', async () => {
    if (busy) return;
    busy = true;
    const ok = await confirm.ask('只移除当前页面中的演示条目,刷新后恢复。');
    if (ok) {
      document.querySelector('#row')?.remove();
      status.textContent = '已移除本地条目。';
      heading.focus();
    } else if (remove.isConnected) {
      status.textContent = '未删除条目。';
      remove.focus();
    }
    busy = false;
  });
  // SPA 在组件卸载时调用 confirm.dispose()。
}

调用层的 busy 并不是多余的。控制器拒绝重复请求可以保护窗口,但若调用者仍根据那次 false 执行焦点恢复,就可能在原确认尚未完成时干扰当前交互。外层忙标记先阻止整个业务回调重入,内层则守住公共确认器的契约。它们保护的是不同边界,不应把其中一个当作另一个的替代品。

此处没有在等待期间禁用触发按钮,因为真正模态打开后背景已不可交互,而且禁用触发器可能影响关闭后的原生焦点恢复。业务回调仍检查 busy,处理程序化重复调用;结果交付后再决定焦点。若组件在等待期间被卸载,实际应用除了 dispose,还应让回调检查组件是否仍挂载,避免对已经切换的页面更新状态。示例是不会切换路由的静态页,因此没有声称实现完整 SPA 生命周期。

从本地删除接到服务器时,必须增加另一套状态

确认结果不是授权令牌。生产接口仍需验证登录身份、资源归属以及当前记录是否允许删除。页面上显示的名字也可能已经过期;服务端拒绝时应保留条目并解释当前状态,而不是为了让界面看起来顺畅,先永久隐藏记录再吞掉错误。

更重要的是把“已确认”与“已完成”拆开。可以先关闭确认框,在列表上显示提交状态,等服务端明确成功后移除节点;也可以让对话框进入提交中状态,但必须说明取消是否仅关闭窗口、是否中止等待,以及服务器操作能否真正撤销。浏览器取消网络等待不代表后端事务回滚。没有幂等键、操作记录或结果查询协议时,断线后盲目重试可能造成重复副作用。本文不提供假装完整的删除 API,正是因为这些约束属于具体业务,不能由一个通用弹窗组件替你决定。

错误反馈也有不同级别。输入缺失应回到相应控件;权限被收回需要告诉用户为何不能继续;提交结果未知应呈现“正在核对”,而非写成失败。焦点跟随用户下一步可做的事情,而不是机械返回最后一个按钮。在包含多行数据的界面,可以选择相邻条目的操作按钮作为成功后的目的地;当列表变空时,列表标题或新增入口更合理。

十项测试通过,但这不是浏览器合格证

本地验证使用 Node.js v24.22.1,执行 node --test test.mjs,十项测试全部通过。测试对象是控制器,不是原生浏览器:测试替身继承 EventTarget,提供 open、returnValue、showModal 和 close;close 通过微任务派发事件,以便覆盖延迟结算。实际覆盖确认值、取消值、空值、未知值、忙时拒绝、Esc 重置旧值、打开异常、销毁与拒绝复用、文本赋值、外部已打开状态。

补充检查使用原控制器和显式任务队列替身复现了上述两种跨实例时序,但仍未执行真实浏览器验证。原先十项控制器测试不覆盖这一集成边界。

其中一个重要反例是先让 returnValue 等于 confirm,再执行新的 ask 和取消。预期结果仍然必须为 false。另一个反例是连续 ask 两次,第二项立即返回 false,而第一项仍然可以独立确认。这两项检验的是跨请求污染,比只测“点击一次能够返回 true”更接近组件复用时的风险。

这些测试没有检验真实焦点、Tab 循环、屏幕阅读器播报、手机系统返回键或背景滚动。本文没有运行真实浏览器与辅助技术测试,也没有以 DOM 替身冒充无障碍认证。上线前应至少在实际支持的 Chromium、Firefox、Safari 版本上逐项检查:仅键盘进入、反向 Tab、Esc、取消后重复打开、确认后触发器被删除,以及窗口缩放后的内容可达性。

视觉测试还应覆盖高对比环境和窄屏。焦点边框不能被裁切,按钮不能只靠颜色区分,对话框内容较长时应能滚动且关闭入口可达。本例没有动画,因而不需要处理过渡动画中途退出的状态;一旦产品增加缩放或滑动效果,就必须另外考虑减少动态效果偏好以及动画结束前关闭或卸载的行为。

最终验收不是“所有浏览器都没报错”,而是每条终止路径都得到明确结果,用户始终知道自己正在操作什么,并能继续下一步。原生 dialog 降低了模态交互的基础成本,但只有请求结算、业务提交和焦点工作流分别有人负责,这个确认器才不会成为隐藏的并发入口。

集成时容易漏掉的三个所有权问题

首先,对话框元素只能由一个控制器实例管理。若框架每次渲染都重新调用 createConfirm,却没有销毁旧实例,同一个 close 事件会唤醒多份监听器。旧实例可能仍握着旧页面的回调。正确做法是在组件挂载时建立实例,在卸载时释放;渲染更新只改需要展示的数据。监听器数量是否随反复进入页面增长,是比截图更有价值的集成检查。

其次,消息节点只接收文本,不接收任意 HTML。资源名称来自用户输入时,用 innerHTML 拼接“确定删除某条记录吗”会把确认界面变成注入入口。本文用 textContent,使标记符号按文字显示。不过这只处理消息展示位置,不自动保护整页所有输出,也不保证服务端日志、邮件模板或导出内容同样安全。

最后,不应把同一个对话框同时交给表单库、路由库和业务代码随意设置 open。控制器只对自己接受的请求负责,外部直接移除属性会绕开预期关闭路径,等待者可能无法结算。约定所有正常关闭都经过原生 close 或表单关闭;组件卸载经过 dispose。遇到第三方插件必须接管节点时,先解除旧控制器,并遵守前述节点交接约束,而不是让两套状态系统互相纠正。

这三个约束都能写进组件接口文档,并在代码评审里检查。它们不是对浏览器缺陷的补丁,而是应用自己的资源管理规则。只有节点、监听器和异步请求有明确归属,单元测试里的简单控制器才有机会在真实页面中保持同样的含义。

相关文章

评论

登录后即可参与讨论

暂无评论。