antd Modal.destroyAll 详解：在路由切换时自动销毁确认对话框

Modal.destroyAll() 是 Ant Design Modal 提供的静态方法，用于一次性销毁所有通过命令式 API（Modal.confirm / Modal.info / Modal.success / Modal.error / Modal.warning）弹出的确认窗。本文围绕官方 Demo「销毁确认对话框」展开，从使用场景、示例代码到 destroyFns 调度队列的源码实现逐层拆解，帮助你理解为什么路由前进/后退时残留的确认框能够被自动清理，以及它与返回的 modal.destroy() 到底有何区别。读完本文，你将掌握在 React Router 等路由监听或 useEffect 清理逻辑中正确接入 Modal.destroyAll() 的完整方案。

一、问题背景：路由切换时残留的确认对话框

1.1 命令式确认窗是"离屏"渲染的

调用 Modal.confirm(...)、Modal.info(...) 等静态方法时，Ant Design 会在当前 React 组件树之外动态创建并挂载一个独立的弹层实例——官方文档 FAQ 中明确说明：调用 Modal 静态方法时 antd 通过动态渲染创建 React 实例，其上下文与调用处所在组件树不同（详见 index.en-US.md FAQ）。

因此，这些确认窗并不受你的页面路由组件生命周期管理。当你点击按钮触发一次 confirm，紧接着跳转路由，弹层依旧悬挂在页面上不会自动卸载。React Router 官方 Demo 示例（react-router）中曾用 browserHistory.listen 配合 Modal.destroyAll() 解决此问题，官方文档保留了这一写法（index.en-US.md）：

import { browserHistory } from 'react-router';

// router change
browserHistory.listen(() => {
  Modal.destroyAll();
});

1.2 为什么不用返回值逐实例关闭

Modal.confirm(...) 会返回一个 { destroy, update } 句柄，其中 destroy 用于主动关闭当前实例。文档明确指出：在"路由被动切换"这种场景下，若要逐个保存句柄再逐一调用 destroy 会非常繁琐且容易遗漏（index.zh-CN.md）。Modal.destroyAll() 正是为此设计的"一揽子"清理入口。

二、官方 Demo 精读：点击一次清空全部确认窗

官方 Demo「confirm-router.tsx」演示了 Modal.destroyAll() 的核心用法：连续弹出 3 个确认窗，再通过其中任意一个窗体内的按钮把所有确认窗一次性全部销毁。

import React from 'react';
import { ExclamationCircleOutlined } from '@ant-design/icons';
import { Button, Modal } from 'antd';

const { confirm } = Modal;

const destroyAll = () => {
  Modal.destroyAll();
};

const showConfirm = () => {
  for (let i = 0; i < 3; i += 1) {
    setTimeout(() => {
      confirm({
        icon: <ExclamationCircleOutlined />,
        content: <Button onClick={destroyAll}>Click to destroy all</Button>,
        onOk() {
          console.log('OK');
        },
        onCancel() {
          console.log('Cancel');
        },
      });
    }, i * 500);
  }
};

const App: React.FC = () => <Button onClick={showConfirm}>Confirm</Button>;

export default App;

这段示例的几个关键细节值得注意：

• const { confirm } = Modal; 解构出静态方法，等价于 Modal.confirm(...)；
• showConfirm 用 setTimeout(..., i * 500) 依次（间隔 500ms）弹出 3 个确认窗，模拟"短时间内有多个确认窗叠加在屏幕上"的真实场景；
• 每个确认窗的 content 内都放了一个触发 Modal.destroyAll() 的按钮，因此无论点击哪一个，都能清空全部 3 个弹窗；
• onOk / onCancel 为占位的回调，实际路由场景中可替换为具体的提交或跳转逻辑。

对应文档原文强调的核心结论即（confirm-router.md）：Modal.destroyAll() 可以销毁弹出的确认窗，通常用于路由监听中，处理路由前进、后退时确认对话框无法被自动销毁的问题。

三、源码剖析：destroyAll 是如何"团灭"所有确认窗的

要真正理解 Modal.destroyAll() 的边界（比如它管不到普通 <Modal> 组件），需要从三层源码看起。

3.1 第一层：模块级销毁队列 destroyFns

destroyFns.ts 维护了一个模块级数组，它是静态弹层实例的"注册表"：

const destroyFns: Array<() => void> = [];
export default destroyFns;

每个通过命令式 API 弹出的确认窗，在创建时都会把自己的关闭函数 close 注册进这个数组。

3.2 第二层：确认窗的注册与注销

在 confirm.tsx 中，confirm() 函数负责创建弹窗并完成注册：

• 函数内部定义 close(...args)，将配置改为 open: false 并触发 afterClose 回调后在 afterClose 中真正执行 destroy（confirm.tsx）；
• 在弹窗调度渲染后，将 close 压入队列：destroyFns.push(close);（confirm.tsx）；
• 而 destroy(...args) 中会先遍历队列，把当前实例对应的 close 从 destroyFns 中 splice 移除，再对渲染容器执行卸载（confirm.tsx）。

因此队列中始终只保留"还活着"的弹窗关闭函数；每当你调用某个实例返回的 modal.destroy()，它就会从 destroyFns 中"销户"。

3.3 第三层：Modal.destroyAll 的循环清空

最终在 components/modal/index.tsx 中，静态方法被挂载到 Modal 上：

Modal.destroyAll = function destroyAllFn() {
  while (destroyFns.length) {
    const close = destroyFns.pop();
    if (close) {
      close();
    }
  }
};

实现非常直白：从队尾不断 pop 出关闭函数并依次调用，直到队列清空。由于每个 close 被调用后会走 afterClose -> destroy 路径、把自身从队列移除并卸载对应 DOM，所以这个 while 循环是安全的终止式清空。

同样，通过 Modal.useModal() + contextHolder 创建的确认窗也会把关闭函数推入同一个 destroyFns 队列（见 useModal/index.tsx），因此 Modal.destroyAll() 同样能作用于 hooks 模式下创建的弹窗——这一行为被测试用例 destroyAll works with contextHolder 显式验证（hook.test.tsx）。

3.4 destroyAll 与实例 destroy 的分工

官方文档将两者定位区分得很清楚（index.zh-CN.md）：

方式	定位	适用场景
modal.destroy()	主动、精确地关闭单个确认窗	用户主动操作、代码按需关闭某一个弹窗
Modal.destroyAll()	被动、批量地清空所有确认窗	路由前进/后退、应用卸载等需要"团灭"的场景

二者底层共享同一套 close -> destroyFns 注销 -> unmount 链路：实例 destroy 只注销自己（confirm.tsx），而 destroyAll 会把队列整体清空。

四、测试验证：destroyAll 的销毁行为有据可查

仓库测试为我们印证了上述机制：

• 覆盖全部四种类型：could be Modal.destroyAll 用例先分别弹出 info / success / warning / error 四种确认窗，断言每种只渲染 1 个（.ant-modal-confirm-${type}），随后调用 Modal.destroyAll() 并断言数量归零（confirm.test.tsx）；
• 队列随实例销毁收缩：destroyFns should reduce when instance.destroy 用例先调用 Modal.destroyAll() 清空队列，再依次创建 4 个实例并逐个 instance.destroy()，每销毁一个就断言 destroyFns.length 递减 1（confirm.test.tsx）；
• Demo 冒烟快照：渲染 confirm-router.tsx 后，快照表明首屏仅输出一个名为 "Confirm" 的按钮（demo.test.tsx.snap），说明所有确认窗都是点击后才动态渲染出来的，进一步印证了其"游离于组件树之外"的特性。

五、实战接入：在路由监听中清理确认窗

5.1 官方文档给出的路由接入模式

将 Demo 的能力与路由事件结合，即可得到文档推荐的完整写法：

import { browserHistory } from 'react-router';

browserHistory.listen(() => {
  // 路由任意变化时清空所有命令式确认窗
  Modal.destroyAll();
});

它的语义是：无论路由是前进还是后退，一旦发生跳转，就把用户可能遗留的确认对话框全部销毁，避免弹窗"跟着单页应用一直存活"。

5.2 在主流路由库中落地

文档示例基于 react-router 的历史监听 API。你可以将该思路迁移到当前主流路由体系，例如：

• react-router v6 / v5：在页面级组件中监听路由变化（如 useLocation() + useEffect），或使用更高层的路由事件订阅（如 history.listen）在 location 变化时调用 Modal.destroyAll()；
• 数据流驱动：无论使用何种路由库，只要把"路由 change"事件汇聚到一个统一监听器，在其中调用 Modal.destroyAll() 即可，这与 antd 无关、只关心调用时机。

需要提醒的是：具体历史对象如何获取取决于你使用的路由库版本，示例中的 browserHistory.listen 仅用于说明"在路由切换事件里调用 Modal.destroyAll()"这一模式本身。

六、注意事项与延伸

1. 只作用于命令式弹窗：Modal.destroyAll() 的清理范围是注册进 destroyFns 的确认窗（confirm | info | success | error | warning），不包含受控渲染的 <Modal open={...}> 组件弹窗——后者的显隐由你的 state 决定，需要自己在路由清理逻辑中同步置为关闭。
2. 会触发关闭回调：清空时依次调用的是 close，弹窗会以"正常关闭"路径退出，因此若你在 onOk / onCancel 中做了提交逻辑，需评估路由切换时静默清理是否会造成副作用（路由场景下通常建议用纯展示内容、不绑定提交动作）。
3. 与 Modal.useModal 协同：hooks 创建弹窗同样进入 destroyFns（useModal/index.tsx），若你在路由跳转时发现 hooks 弹窗未被清理，可确认清理时机是否正确调用了全局的 Modal.destroyAll()。
4. 定位参考：该 Demo 在官方文档中位于 index.zh-CN.md「销毁确认对话框」 与 index.en-US.md「destroy confirmation modal dialog」 小节，更多弹窗命令式 API（update、destroy、hooks then 链等）可查阅 Modal 组件总文档。

总结

Modal.destroyAll() 用最简洁的调用解决了 SPA 路由切换场景下确认对话框残留的实际痛点。通过阅读源码可以看到，它的能力边界源自 destroyFns.ts 这个全局注册表——确认窗创建时注册、销毁时注销，destroyAll 则负责在路由事件中"一键清空"。理解了这层调度机制，你就能准确判断在什么时候调用它、它能清理哪些弹窗，以及何时应该改用实例返回的 modal.destroy()。