一句话导读:一个没有框架、没有构建链的多页静态后台,二十来个页面文件里散落着八十处左右的
alert()和二十余处confirm()。接口出错时,使用者看到的是一个标题被浏览器写成「域名 显示」的灰色方块,正文是一句没有任何信息量的兜底文案——既不知道哪里出了问题,也没法让它自己消失,还把浏览器自动化彻底卡死。这篇文章讲为什么要用两个 JS 文件、一套样式把这些调用换掉,为什么最终形态是「全局单例浮层」,以及单例方案的代价与落地细节。

图 0:同一个提示,交给浏览器和交给自己,是两种产品体验。
一块灰色方块引发的重构
先交代站点的形态,因为它决定了后面所有的选择。这是一个传统意义上的多页静态站:每个页面都是手写的 HTML,页面之间靠 <a> 跳转;脚本一部分抽在公共文件里,一部分内联在页面底部;样式只有一份公共 CSS,再叠加各页零散规则。没有构建链,没有 npm,没有组件库,浏览器拿到什么就执行什么。
这种结构在业务简单时非常省心——改一行代码,刷新就能看到效果;但当页面涨到二十来个、每个页面都要承载表格、表单与批量操作时,「临时补一个提示」就变成了往同一口锅里加料:有人写 alert,有人在 alert 后接 return,有人在同一个函数里连写三个,每一处单独看都成立。
重构的触发点是一次很普通的点击。某列表页点某条记录的「详情」,接口返回 500——后端某个字段取不到值,序列化时直接抛了异常,res.msg 是空的。前端那行代码本身写得很「稳妥」:
alert(res.msg || '数据加载失败');
兜底文案生效了,于是弹出原生对话框。标题栏由浏览器写死为当前页面地址,成了「域名 显示」;正文只有一句「系统繁忙,请稍后再试」。使用者唯一能做的就是截图发给开发者,而开发者从中能推断出的信息量为零:不知道哪个接口、哪个页面、什么错误码,也不知道他之前点了什么。
更麻烦的是它挡住了页面:模态状态下,点「确定」之前页面不响应任何点击、滚动和键盘操作;它也不会自己消失,没有超时、没有关闭按钮。同一个人连续触发三次,就得点三次。对一天要点上百次的列表页来说,这是每天都会遇到的摩擦。
真正让人下决心的是自动化。巡检脚本跑到这个页面就停在那里——原生对话框中断了 Playwright 和 Puppeteer 的执行流,拿不到句柄,后面的断言和截图都不执行,最后以一个语焉不详的超时结束。这已经不是「样式不好看」,而是会同时伤害三方的结构性问题:使用者拿不到信息,页面失去控制,工具无法工作。
目标是:换掉它,但不引入框架;把提示变成全站共享的能力,而不是每个页面各自的临时补丁。最终落下来的东西很少——两个 JS 文件、一段 CSS、一批机械替换。
原生对话框到底哪里不对
把 alert() 的问题一条条拆开,会发现它们几乎都源自同一个事实:这个对话框不属于页面,它属于浏览器。浏览器只提供了「弹一个框」的能力,没有提供任何关于这个框的控制权——不能改样式、不能设超时、不能分级、不能拿到它的 DOM、也不能在它出现时继续执行脚本。
它是阻塞式模态。 alert() 执行时 JavaScript 主线程被挂起,页面停止渲染和响应,连 CSS 动画都会冻结。使用者在点掉它之前,既不能滚动表格,也不能继续填下一个字段。而绝大多数提示——保存成功、复制成功、校验不通过——不需要任何决策。用必须点击的模态框承载不需要回应的信息,是工具的错配。
样式完全不可控。 字体、圆角、间距、按钮位置、阴影全由浏览器和操作系统决定。同一个产品在 Windows 上是方角灰按钮,在 macOS 上是圆角蓝色按钮。更尴尬的是它和页面的视觉体系毫无关系:页面里的弹层都是圆角卡片加半透明遮罩,中间突然插进来一个九十年代的系统框,像从另一个软件里掉出来的。
标题被浏览器写死。 标题永远是「域名 显示」,占着最显眼的位置,却只传达了一个使用者早就知道的信息:我在哪个网站上。真正的信息——哪个接口失败、为什么失败、要不要重试——被挤到正文里,还要跟前端那句兜底文案抢位置。这个标题不只是无用,它是负资产:本该显示「数据加载失败」的位置,被浪费在了一个域名上。
无法自动消失。 原生对话框没有超时机制。一句「已保存」也要使用者亲自点掉,在这期间页面是冻结的。连续录入、批量操作时,这种「必须点一下」的累积成本非常可观:一个上午保存三十次,就是三十次强制中断。
无法分级。 成功、失败、提醒、警告,四种语义共用同一张脸。使用者无法从外观判断「这是不是出事了」,只能逐字读文案。而后台使用者是扫读的——一个需要停下来读的提示,等于没有提示。
打断心流。 这是前几条的合力。注意力本来在表格的某一行上,弹框出现后被迫移到屏幕中央,点掉之后再回到原来那一行,还得重新确认刚才看到哪了。每次提示都是一次上下文切换,而切换是有成本的。
对自动化与无头浏览器不友好。 原生对话框在无头环境里的行为依赖浏览器实现:有的直接拒绝,有的挂起等待,有的需要提前注册 dialog 事件处理器并显式 accept()。它不是 DOM 的一部分,选择器抓不到、样式改不了,截图里还会出现一块与页面无关的系统 UI。对靠脚本做回归的项目来说,这等于在流程中间埋了一颗随机引爆的雷。
多语言与无障碍不可控。 标题里的「显示」、按钮上的「确定」,语言跟随浏览器而不是产品;播报顺序、焦点落点也无从干预。看起来它「天生支持无障碍」,但那是浏览器的无障碍,不是产品的无障碍——它读不出业务语义,也无法和页面里其他的 aria-* 属性协同。
把这八条收拢,其实只有一句话:你把「怎么跟使用者说话」的权力交了出去,换回来的只是一个能弹出来的框。而这个权力一旦交出去就拿不回来——你无法在不改浏览器的情况下,让那个框变成你想要的样子。
换掉之前,先算一笔账
动手前先做了一次全目录盘点。没有清单,「换完了」就只能靠感觉,而感觉在二十来个文件、上百处调用面前是靠不住的。
盘点方法很土:用 grep 把所有调用点捞出来,重定向成一份文本清单,然后人工逐条标注语义——这条是成功回执,那条是失败兜底,另一条其实是校验拦截。标完之后,数量级就清楚了。
| 项目 | 替换前 | 替换后 |
|---|---|---|
| 页面文件 | 二十余个 | 未新增页面 |
原生 alert() |
八十处左右 | 0 处 |
原生 confirm() |
二十余处 | 0 处 |
| 全局组件文件 | 0 个 | 2 个(toast.js / dialog.js) |
| 样式文件 | 一份公共 CSS | 同一份文件追加一段规则 |
| 轻提示层级 | 由浏览器决定 | z-index: 4000 |
| 确认弹窗层级 | 由浏览器决定 | z-index: 4200 |
| 业务表单弹窗层级 | 100 上下 | 未改动 |
平均下来每个页面四五处,但这个平均数掩盖了不均:问题集中在列表页、详情页、表单页这三类高频页面上,各自都是十几处的量级,剩下的页面只有一两处。
再按语义拆开看,alert 的构成大致是这样:
| 语义 | 占比 | 典型原文 | 替换后 |
|---|---|---|---|
| 成功回执 | 四成左右 | alert('保存成功') |
Toast.success(...) |
| 失败兜底 | 四成左右 | alert(res.msg || '加载失败') |
Toast.error(...) |
| 校验拦截 | 一成多 | alert('请先选择一条记录') |
Toast.error(...) |
| 纯说明 | 少量 | alert('该操作会覆盖现有配置') |
Toast.info(...) |
成功回执最刺眼:信息量极低,却全部是阻塞式弹窗——使用者每保存一次,就要为一条「我知道了」点一次鼠标。失败兜底的文案高度同质(「系统繁忙」「操作失败」),几乎不携带可排查的信息,而它们本该是最需要信息的地方。
confirm 的构成简单得多,基本只有三类:删除、状态变更、退出登录。前两类占绝大多数,都是不可逆或半不可逆操作——这正是后面「哪些操作必须用确认框」那条规则的来源。
盘点还顺带发现了两个没人注意到的事实:有两处 alert 是调试残留(alert(JSON.stringify(data))),线上一直没人点开过;同一句「请先选择一条记录」在三个页面里出现了三次,文案还不完全一样。它们说明了一件事:
这些调用不是上百个独立问题,而是上百次重复决策。每一处都在问「要不要提示、提示什么、怎么提示」,而工具只有 alert 时,答案只能收敛成同一个形状。真正的收益不是换了个更好看的框,而是把提示从临时判断变成一套有语义的约定。
四种方案,为什么选最不起眼的那种
替换方向上有四条路,逐条掂量过。
| 方案 | 主要问题 | 适用场景 | 结论 |
|---|---|---|---|
| 引入成熟 UI 组件库 | 需要构建链或整包引入,数百 KB,样式体系与手写页面冲突 | 有构建链、组件需求多的项目 | 不划算 |
| 每个页面写一份内联提示 | 二十多份实现,位置、时长各自漂移 | 单页或一次性页面 | 长期维护灾难 |
| 自研全局单例浮层 | 无障碍、焦点与边界情况要自己处理 | 多页静态站、无构建 | 采用 |
| 保留原生对话框 | 阻塞、样式不可控、自动化不友好 | 没有合适的场景 | 放弃 |
引入成熟组件库是很多人的第一反应,但对这个站点不成立。没有构建链,就得先决定是 CDN 全量引入还是补一套打包流程;即便引入,我们只需要两个组件,却要承担整个库的样式重置、图标字体和主题变量。站内样式是「手写加局部覆盖」,和组件库的 BEM 结构、box-sizing 基线、字号阶梯都会打架,最后大概率演变成「每页再写一层覆盖」。
页面内联提示看起来最省事:每页写一个 showTip(),插一个 div,setTimeout 三秒删掉。但它注定漂移——二十来个页面就是二十来份实现,位置和时长各不相同,改一个圆角要改二十个文件。站内此前的业务弹窗就出现过这种漂移:两个页面的「取消」按钮一个灰一个白,只是当初复制粘贴时漏改了一行。
自研全局单例浮层是最后选的。本质是把提示从页面里抽出来,变成和页面平级、全站共享的能力:两个 JS 文件定义行为,一段 CSS 定义外观,每个页面只负责引入。扔掉也不影响业务逻辑——删掉引入的两行,剩下的调用会变成 Toast is not defined,一眼就能找到。
选它的核心理由不是「自己写的更可控」,而是站点的组织方式:多页、无构建、每页独立加载。能被 <script src> 直接带入、不依赖任何运行时的东西才最合适——组件库需要构建,内联实现需要复制,只有「一个全局对象加一段样式」能同时满足零构建和单一实现。
另外它足够小:任何人接手都能在半小时内读完。换成组件库,出问题时要面对几万行别人的代码和一个陌生的构建产物。
为什么坚持「一个 DOM」
很多人做提示组件时,习惯在触发位置 appendChild 一个节点,用完删掉;或者在每个页面容器里各放一个提示区。这里的做法相反:整个提示体系在任一时刻只对应极少量的固定 DOM。

图 1:业务弹窗停在 100 上下,提示与确认在 4000 / 4200,中间隔着一个数量级。
一个容器,避免重复节点与内存泄漏。 Toast 首次被调用时才创建容器,之后所有提示都往这个容器里追加子节点,节点在动画结束后 remove()。没有常驻的无主 DOM,也没有「每次提示都新建容器、忘了删」的泄漏路径。confirm 更严格:全局同一时刻只允许存在一个遮罩实例,新调用会先把旧实例按取消关闭。这样做还有个隐性好处:容器的存在是可预期的,调试器里永远能找到它,或者确认它确实还没创建。
样式只维护一份,不会各页漂移。 位置、圆角、阴影、图标、动画时长全部集中在那份公共 CSS 里,改一次,所有页面同时生效;每页各写一份,就得接受「两个页面的提示框长得不一样」这种慢性病。改一个圆角、加一个「关闭」按钮时,差别就出来了:一次改动对二十次改动加二十次回归。
挂在 body 末尾,跳出业务容器的层叠上下文。 这一点经常被低估,也是最想强调的。position: fixed 并不永远相对视口定位:只要祖先元素上有 transform、filter、perspective 或 will-change,这个祖先就会成为新的包含块,fixed 会退化成相对它定位,滚动时提示会跟着容器一起跑;祖先上的 overflow: hidden 还会把溢出部分直接裁掉,提示「弹出来了但看不见」。而业务页面里这类属性到处都是——卡片悬浮动画、列表滚动容器、will-change: transform 的优化。把节点挂成 body 的直接子级,就绕开了所有这些坑:它不属于任何业务容器,也就不受那些容器的层叠上下文、裁剪规则和变换影响。
层级可以提前规划。 节点在 body 顶层,z-index 的比较对象就是根层叠上下文,数字可预期。toast 定在 4000、confirm 定在 4200,业务弹窗通常在 100 上下——相差一个数量级,意味着以后业务弹窗即使加到 500、800,也盖不住提示。「留一个数量级」比「比现有最大值大 1」稳得多:后者每加一个弹窗就要重数一遍全站最大值,前者只要保证新东西别越过 4000。
行为统一。 停留时长、进出场过渡、三种图标、按钮文案、键盘响应全部在一处定义。要统一改成 2500ms,改一个常量即可。无障碍属性同理:role、aria-live、aria-modal 这些如果散落在上百个调用点里几乎必然漏掉,集中在一处才有可能补齐并持续维护。
可观测。 全局对象,调试时直接在控制台敲 Toast.error('test'),不用构造上下文、不用点按钮、不用等接口返回。排查「提示没出来」时,这一步能先确认组件是活的,再去怀疑调用点和脚本加载顺序。
性能上是零成本。 没有提示时,DOM 里只有一个空容器,甚至因为懒创建连容器都没有。容器上的 pointer-events: none 让它在覆盖页面顶部的同时不拦截点击——忘了它,提示区域就会变成一块透明的「死区」,点那里什么都不会发生,且很难排查。
把这七条收拢成一句话:提示应该是一个全局的、单例的、脱离页面结构的能力,而不是页面里的一个局部零件。只要它还依附于某个业务容器,就一定会被那个容器的样式、层级和生命周期绑架。
单例不是免费的:缺点与风险
好处是真实的,代价同样真实。只讲优点,这篇文章就变成了推销。
并发与时序。 连续两次 Toast.error() 会得到两条提示,按调用顺序堆叠、各自计时。视觉上可接受,但如果两次调用间隔极短(比如循环里报错、或一个请求触发了两层 .catch),使用者会看到一叠几乎一样的提示快速闪动,像故障灯。问题不在组件而在调用点:规则是循环内不提示,批量操作只在结束后汇总一条;网络层统一提示,业务层不再重复提示。
堆叠策略要提前想清楚。 这里没做消息去重。站点提示频率很低,去重反而会让使用者以为「点了没反应」——连点两次保存,第二次没有新提示,他会怀疑是不是没点上。但在高频场景下,正确做法是按 message 去重并重置计时器,或者把重复合并成「操作失败(3 次)」。这是可配置项而非默认行为,因为两种策略的适用场景完全相反。
全局类名污染。 这是真实踩到的坑,也是这套方案最疼的一处。同一个域名下往往不止一个子站:某个后台子站有自己的主题样式表,里面早就有一份同名的 .toast 规则,走深色配色,而且不加载这份公共 CSS。新组件一旦引入,两条规则会互相覆盖——背景被新规则染成浅色、文字还是旧的浅灰,对比度低到几乎看不清。所以那两处保留原生实现,没有强行接入。这不是偷懒,而是承认成本:修一处冲突要动两个子站,收益远小于风险。
样式依赖宿主页面。 行为在 JS 里,外观却在公共 CSS 里。页面只要漏引 <link>,组件就会「裸奔」——没有定位、没有遮罩、没有过渡,提示以纯文本落在文档流末尾。迁移中真出现过两次,还是「本地看着好好的,换台机器就没了」,因为那台机器的缓存里还留着旧样式。
iframe 与多实例页面。 每个 document 有自己的一套 body 和全局对象,父页面的 Toast 调不到 iframe 内部;反过来,iframe 里的提示也只出现在它自己的视口里,位置会偏。一个页面里若有多个独立应用实例,共享容器就意味着共享同一条队列——A 模块的错误提示可能出现在 B 模块的区域上方。这类页面没有 iframe,所以这不是当下的问题,但它决定了组件不能原样搬到别的系统。
打印与截图。 position: fixed 的元素在打印时行为依浏览器而异,可能出现在每一页的同一位置,也可能只出现第一页。生成 PDF 时更麻烦:如果提示还没消失就点了打印,它会被一起印进去。有打印需求的页面要用 @media print 把它彻底隐藏。
可访问性要自己补。 原生 alert() 由浏览器负责播报,屏幕阅读器一定会读,还会把焦点移过去——这是它唯一值得羡慕的地方。自研组件不会自动获得这个能力:role="status" 只是声明,真正播报依赖 aria-live 区域和正确的更新时机(先插入空区域再写文本,否则部分读屏软件不播报)。confirm 还要管焦点:打开时移进弹窗,关闭时还回触发元素,否则键盘使用者会在页面里「丢失」,只能从头 Tab 一遍。
短暂提示会被忽略。 三秒后自动消失,使用者正在看别处或打字,就完全错过了这条信息。对「保存成功」这类低风险反馈无所谓,甚至更好——它不打断人;但涉及删除、停用、退出这类不可逆操作,必须用确认框兜底,而不能只发一条 toast 假装完成了沟通。
还有一条隐性成本:它是一份要自己维护的基础设施。 组件库的无障碍、焦点管理、边界情况都有人替你测过、修过;自研就意味着这些都要自己想到。两个文件很小,但要做对,需要的细节并不少——后半部分讲的就是这些。
两个文件、一套样式
结构很简单:行为拆成两个文件,外观追加进已有的公共样式表,业务页面只多两行引用。
web/
├─ css/
│ ├─ base.css # 全站公共样式,追加 .toast-box / .dialog-mask
│ └─ page.css # 各页零散规则
├─ js/
│ ├─ toast.js # 全局轻提示
│ ├─ dialog.js # 全局确认弹窗
│ └─ app.js # 业务脚本
└─ pages/
├─ list.html
└─ detail.html
引入顺序很重要:样式与两个组件脚本在前,业务脚本在后。页面底部的内联脚本执行时 Toast 和 dialog 必须已经存在,否则第一行调用就会抛 undefined。
对外只暴露四个入口:
| API | 参数 | 返回 | 用途 |
|---|---|---|---|
Toast.success(msg) |
文本 | 无 | 保存、提交成功 |
Toast.error(msg) |
文本 | 无 | 接口失败、校验不通过 |
Toast.info(msg) |
文本 | 无 | 纯说明、引导 |
dialog.confirm(options) |
{ title, message, okText, cancelText, danger } |
Promise<boolean> |
删除、停用、退出等二次确认 |
Toast 的懒创建与自动移除
// js/toast.js —— 全局轻提示
const Toast = (function () {
let box = null;
const ICONS = { success: '✓', error: '!', info: 'i' };
function ensureBox() {
if (box) return box; // 已创建过,直接复用
box = document.createElement('div');
box.className = 'toast-box';
box.setAttribute('role', 'status');
box.setAttribute('aria-live', 'polite');
document.body.appendChild(box); // 直接挂到 body,避开业务容器
return box;
}
function show(type, msg) {
const el = document.createElement('div');
el.className = 'toast toast-' + type;
const icon = document.createElement('span');
icon.className = 'toast-icon';
icon.textContent = ICONS[type] || '';
const text = document.createElement('span');
text.className = 'toast-text';
text.textContent = String(msg == null ? '' : msg); // 只写文本
el.append(icon, text);
ensureBox().appendChild(el);
requestAnimationFrame(() => el.classList.add('in')); // 下一帧再加,过渡才生效
setTimeout(() => {
el.classList.remove('in');
setTimeout(() => el.remove(), 200); // 等过渡走完再摘节点
}, 3000);
}
return {
success: (m) => show('success', m),
error: (m) => show('error', m),
info: (m) => show('info', m)
};
})();
requestAnimationFrame 不是为了「性能」,而是让浏览器先完成一次布局:如果在创建节点的同一个任务里加 .in,初始状态和结束状态会被合并成一次样式计算,过渡根本不会触发。同理,移除前先摘掉 .in 让它淡出,再等过渡结束 remove()。
dialog.confirm 的 Promise、单实例守卫与只结算一次
// js/dialog.js —— 全局确认弹窗
const dialog = (function () {
let current = null; // 全局唯一实例
function close(instance, result) {
if (instance !== current) return; // 已经收过尾,忽略重复调用
current = null; // 先置空,保证只结算一次
document.removeEventListener('keydown', instance.onKey);
instance.mask.classList.remove('in');
instance.resolve(result);
setTimeout(() => instance.mask.remove(), 160);
}
function confirm(opts) {
const o = Object.assign({
title: '请确认', message: '',
okText: '确定', cancelText: '取消', danger: false
}, opts || {});
if (current) close(current, false); // 单实例守卫:旧实例按取消处理
return new Promise((resolve) => {
const mask = document.createElement('div');
mask.className = 'dialog-mask' + (o.danger ? ' is-danger' : '');
mask.innerHTML = [
'<div class="dialog-box" role="dialog" aria-modal="true">',
' <h3 class="dialog-title"></h3>',
' <p class="dialog-msg"></p>',
' <div class="dialog-actions">',
' <button type="button" data-role="cancel"></button>',
' <button type="button" data-role="ok"></button>',
' </div>',
'</div>'
].join('');
// 骨架用模板,使用者可见的文本一律 textContent
mask.querySelector('.dialog-title').textContent = o.title;
mask.querySelector('.dialog-msg').textContent = o.message;
mask.querySelector('[data-role="ok"]').textContent = o.okText;
mask.querySelector('[data-role="cancel"]').textContent = o.cancelText;
const done = (v) => close(current, v);
mask.querySelector('[data-role="ok"]').onclick = () => done(true);
mask.querySelector('[data-role="cancel"]').onclick = () => done(false);
mask.addEventListener('click', (e) => { if (e.target === mask) done(false); });
function onKey(e) {
if (e.key === 'Escape') { e.preventDefault(); done(false); }
if (e.key === 'Enter') { e.preventDefault(); done(true); }
}
document.addEventListener('keydown', onKey);
current = { mask, resolve, onKey };
document.body.appendChild(mask);
requestAnimationFrame(() => mask.classList.add('in'));
});
}
return { confirm };
})();
三个保护点必须同时存在,缺一个都会出问题:
if (current) close(current, false)—— 防止弹窗堆积。使用者连点两次删除,第二次调用会把第一个实例按「取消」关掉,页面上永远只有一层。if (instance !== current) return—— 防止重复收尾。确定按钮、遮罩、ESC 可能在同一帧内都被触发,没有这道判断就会remove()两次、resolve()两次。current = null写在resolve之前 —— 让状态先于回调生效。resolve之后业务代码可能立刻发起下一次确认,此时current必须已经是空的。
为什么是 textContent 而不是 innerHTML
提示文案最常见的来源是后端返回的 res.msg。用 innerHTML 写入,消息里任何一段 <img src=x onerror=...> 都会被当成 DOM 解析执行——标准的 XSS 入口,而且藏在「只是显示个提示」的组件里,最容易被忽略。规则是:结构可以拼模板,数据一律用 textContent。上面的 confirm 只在骨架里用 innerHTML,标题、正文、按钮文案全部 textContent;Toast 更彻底,整条提示都是 createElement 拼的。
CSS 的三个关键点
/* 轻提示:顶部居中、纵向堆叠、不拦截点击 */
.toast-box {
position: fixed;
top: 20px;
left: 50%;
transform: translateX(-50%);
z-index: 4000;
display: flex;
flex-direction: column;
align-items: center;
gap: 8px;
pointer-events: none;
}
.toast {
display: flex;
align-items: center;
gap: 8px;
max-width: 60vw;
padding: 10px 16px;
border-radius: 6px;
background: #1f2421;
color: #faf8f4;
font-size: 14px;
opacity: 0;
transform: translateY(-8px);
transition: opacity .2s ease, transform .2s ease;
}
.toast.in { opacity: 1; transform: translateY(0); }
/* 确认弹窗:全屏半透明遮罩 + 居中卡片 */
.dialog-mask {
position: fixed;
inset: 0;
z-index: 4200;
display: flex;
align-items: center;
justify-content: center;
background: rgba(31, 36, 33, .45);
opacity: 0;
transition: opacity .16s ease;
}
.dialog-mask.in { opacity: 1; }
fixed 让它相对视口定位、不随页面滚动;z-index 让它永远在最上层;transition 只作用于 opacity 和 transform,由合成器处理,不触发布局重排。遮罩用半透明而非纯色,是为了让使用者仍能看见底下的页面,不至于产生「跳到了另一个页面」的错觉。

图 2:提示容器常驻复用,确认遮罩一次只有一个。

图 3:toast 是「插入—淡入—等待—淡出—移除」,confirm 是三个出口收敛到同一个 close()。
迁移路线:一批调用是怎么换完的
这部分可直接复用:先盘点再动手。
第一步,grep 盘点。 固定检索范围并排除第三方库,把 alert( 和 confirm( 的结果落成一份清单,改一处划一处。注意 confirm( 会同时命中 window.confirm(,替换时容易变成 window.dialog.confirm(。
第二步,按语义分类映射。 这一步决定替换质量。同一个 alert 可能承担好几种职责:
| 原调用 | 语义 | 替换为 |
|---|---|---|
alert(res.msg || '加载失败') |
失败 | Toast.error(...) |
alert('保存成功') |
成功 | Toast.success(...) |
alert('请先选择一条记录') |
校验不通过 | Toast.error(...) |
alert('该操作会覆盖现有配置') |
纯说明 | Toast.info(...) |
confirm('确定删除?') |
危险确认 | await dialog.confirm({ danger: true }) |
规则只有三句:失败与校验用 error,成功用 success,纯说明用 info;删除、停用、退出加 danger: true,按钮变红。
第三步,alert 机械替换。 可以整批做,因为签名兼容——都是「传一个字符串,返回 undefined」。
第四步,confirm 改成 async + await。 工作量最大的一步,核心是「最小改动」:不改调用结构,只在返回值前加 await,再给宿主函数补 async。
// 改前:成功提示
alert('保存成功');
// 改后
Toast.success('保存成功');
// 改前:二次确认
function handleDelete(id) {
if (!confirm('确定删除该记录?')) return;
doDelete(id);
}
// 改后:宿主函数补 async,条件改成 await 取反
async function handleDelete(id) {
const ok = await dialog.confirm({
title: '删除记录',
message: '删除后不可恢复,确定继续?',
okText: '删除',
danger: true
});
if (!ok) return;
doDelete(id);
}
对于 const x = confirm(...) ? a : b 这类表达式,用括号包住 await 即可,语义不变:const label = (await dialog.confirm({ message: '确定停用该记录?' })) ? '已停用' : '已取消';
宿主函数如果是被 onclick="handleDelete(1)" 直接调用的,加 async 不影响任何行为——返回值本来就没人接收。但如果某个调用点依赖「点完立刻同步继续」,需要先确认那段逻辑没有假设弹窗是同步的。
第五步,补 <link> 与 <script> 引用。 页面逐个补上,放在业务脚本之前。这一步最容易漏:有几个页面用模板片段拼接 <head>,只在其中一处加了引用。
第六步,静态检查。 grep 复查,「应当为零」的结果必须真的是零(第三方库除外);再把每页的内联 <script> 交给 node --check。await 写在非 async 函数里是语法错误,但浏览器只在执行到那行时才报,静态检查能一次抓出来。
第七步,浏览器冒烟。 挑四条路径逐个点:列表页删除一条记录(取消后记录仍在)、表单页保存失败(红色 toast,三秒后消失)、顶部「退出」(取消后仍留在当前页)、详情页加载失败(不再弹阻塞框)。四条覆盖了 confirm 的三种出口和 toast 的三种类型。
踩过的坑
原生对话框会让自动化彻底卡死。 这个问题替换前一直存在,只是没人把它和「提示组件」联系起来。Playwright 遇到 alert 时执行流会停住,直到注册 dialog 处理器;巡检脚本里加 page.on('dialog') 只能止血,真正的解法是让它根本不出现。
\n 在自定义弹窗里不换行。 原来有些文案写成 '第一行\n第二行',原生 alert 渲染成两行;换成 toast 后,\n 只是普通字符,默认的 white-space: normal 把它折叠成空格,两句挤成一行。要么改写文案(这里选了这个),要么给 .toast-text 加 white-space: pre-line。
函数没加 async,await 直接语法报错。 批量替换时最容易出的事故,表现是整页脚本不执行,控制台一行 Uncaught SyntaxError: await is only valid in async functions。这也是静态检查必须做的原因——等浏览器里点出来,往往已经改了几十处。
子站没加载公共样式,组件「裸奔」。 某个后台子站自带主题样式表,既没引入公共 CSS,里面又有一份同名的 .toast(深色配色)。提示以纯文本插在文档流末尾,位置和样式全错;补上引用,两套规则也会打架。那两处最终保留原生实现。
window.confirm 和 confirm 都要换。 只按 confirm( 替换,会把 window.confirm(...) 改成 window.dialog.confirm(...),运行时直接 window.dialog is undefined。正确顺序是先把 window.confirm 整体换成 dialog.confirm,再处理裸的 confirm。
还有一条更隐蔽的:if (dialog.confirm(...)) 永远为真。 原生 confirm 返回布尔值,Promise 返回对象,对象在条件判断里恒为真——于是「取消」也会走进删除分支,而且不报任何错。这是整个迁移里最危险的一处,只能靠人工复查条件表达式来兜。
延伸:三类提示的选型矩阵
把这次替换里的判断抽出来,其实是三类控件各管一段:
| 场景 | 控件 | 是否阻塞 | 停留时长 | 典型例子 |
|---|---|---|---|---|
| 操作结果的即时反馈 | Toast | 否 | 3000ms 自动消失 | 保存成功、校验失败、接口报错 |
| 不可逆操作的二次确认 | dialog.confirm |
是(逻辑上等待) | 直到使用者选择 | 删除、停用、退出登录 |
| 需要输入更多信息 | 业务表单弹窗 | 是 | 直到提交或关闭 | 新增一条记录、编辑配置项 |
分界线是**「使用者需要付出多少」**。零付出——用 toast,别打断他;一次点击——用 confirm,让他明确表态;需要输入——用表单弹窗,因为 confirm 装不下字段。
两个常见错误都是越界使用:用 alert('保存成功') 是拿阻塞换反馈,使用者被迫为一件不需要决策的事点一次鼠标;用 toast 承载「确定要删除吗」则是拿非阻塞换确认,提示还没看清就消失了,而删除已经执行。不可逆的操作,永远要阻塞到使用者表态。
结语
这次重构没有引入任何新框架,落下来的只有两个 JS 文件、一段 CSS 和一批机械替换,但改变的东西比代码量要大:提示从「每个页面各自决定的临时操作」,变成了「全站共享的一套语言」——成功是绿色的勾,失败是红色的叹号,危险操作是红色按钮,三秒后自己走开。
原生对话框的问题从来不是丑,而是它把「怎么跟使用者说话」这件事交给了浏览器决定。提示是产品语言的一部分,这句话该由我们自己说。
本次改动仅涉及前端静态资源,未修改任何后端接口与业务逻辑。
评论 (0)
还没有评论,来抢沙发。