Vue2 项目中的全局自动弹窗队列设计

很多业务项目做到一定阶段，都会碰到一个看起来不大、但非常影响体验的问题：页面一打开，系统公告想弹，活动通知想弹，绑定手机号提醒也想弹，新手引导还想弹。每个弹窗都觉得自己"现在就该出现"，结果就是多个弹窗抢着上场，顺序乱、层级乱、关闭之后也接不上。

刚开始时，大家通常会在各自组件里直接写：

js 复制代码

this.visible = true;

短期看很直接，长期看却会越来越混乱。因为这类问题从来都不是"某一个弹窗怎么写"，而是"多个自动弹窗如何统一调度"。

所以这篇文章想聊的，不是某个具体业务里的一个小技巧，而是一套很适合 Vue 2 项目的通用方案：全局自动弹窗队列。

它的核心思路很简单：

所有自动弹窗统一注册
所有待弹弹窗进入同一个队列
队列按优先级排序
同一时刻只展示一个弹窗
当前弹窗关闭后，自动展示下一个

如果你正在被"多个自动弹窗互相打架"的问题困扰，这套方案基本可以正面解决。

一、为什么自动弹窗会越来越难管

自动弹窗在项目初期通常不多，可能只有一个欢迎提示。这时候每个组件自己控制显示，看起来并没有问题。

但随着业务增长，弹窗会越来越多，比如：

欢迎通知
系统公告
强制绑定手机号提醒
新手引导
活动礼包弹窗
风险确认弹窗

这些弹窗通常分散在不同模块里，由不同同学开发。每个人都只关心自己的弹窗逻辑，很少有人会在写的时候顺便考虑：

当前页面是不是已经有别的弹窗在显示
自己是不是应该排在后面
当前弹窗关闭后，后面的弹窗怎么接上
页面初始化阶段如果多个弹窗同时满足条件，最终顺序该怎么定

于是问题就会慢慢出现。

1. 多个弹窗同时显示

最常见的情况就是两个弹窗都设置了可见，最后要么遮罩层叠在一起，要么只看到后出现的那个，前一个实际上已经进了异常状态。

2. 同一个页面，每次弹窗顺序都不一样

你会发现某次先弹公告，某次先弹绑定手机号，某次又先弹活动通知。根本原因通常不是代码随机，而是顺序受到以下因素影响：

组件挂载顺序
异步请求返回顺序
业务条件判断完成的时机

3. 优先级要求很难真正落地

产品会说："实名认证提醒一定要优先于活动弹窗。"

但如果没有统一调度机制，这句话很容易只停留在需求描述里，落不到代码行为上。

4. 关闭后没有续播机制

哪怕第一个弹窗已经正常展示了，如果关闭时只是把自己 visible = false，而没有通知一个统一调度中心，后面的弹窗根本不知道现在轮到自己了。

所以说，自动弹窗的问题，从来不是单个弹窗组件的问题，而是缺少一个全局队列。

二、什么是"全局自动弹窗队列"

可以把它理解成一个调度器。

页面上所有"自动弹出的弹窗"，都不再自己决定什么时候出现，而是统一把自己注册到一个全局系统里。这个系统负责做 4 件事：

收集所有待展示的弹窗
按优先级排序
同一时刻只展示一个
当前弹窗关闭后自动切换到下一个

为了让这个系统稳定一点，我们通常还会加一个"收集窗口"。

为什么要加？

因为页面刚打开时，很多组件会在几百毫秒内几乎同时执行。如果谁先注册就谁先弹，那顺序依旧是不稳定的。所以更合理的做法是：先给一个很短的收集时间，把这一波候选弹窗都收进来，再统一排序，然后再开始展示。

这就是"全局自动弹窗队列"最核心的设计思想。

三、核心状态应该怎么设计

一套够用的状态其实不复杂，下面这个结构就足够支撑整个调度过程：

js 复制代码

autoModalState: {
  modalQueue: [],
  currentModal: null,
  isCollectingModals: true,
  collectTimer: null,
}

别看字段不多，每一个都很关键。

1. `modalQueue`

这是待展示弹窗的队列。

队列里的每一项不是"弹窗实例"，而是一份弹窗配置。通常会包含下面这些信息：

js 复制代码

{
  key: "bind-phone",
  priority: 3,
  show: () => {},
}

其中：

key 用来标识当前弹窗
priority 用来控制先后顺序，数字越小越先展示
show 是真正打开弹窗的函数

2. `currentModal`

这个字段表示当前正在展示的弹窗。

只要它不为空，就说明系统已经有弹窗在显示。后续即便还有新的弹窗进入队列，也应该继续排队等待，而不是立刻抢出来。

3. `isCollectingModals`

这个字段用来表示系统是不是还在"收集窗口"里。

true：说明当前只收集，不立即展示
false：说明收集结束，可以开始正式调度

它解决的是"首屏多个弹窗几乎同时注册，顺序不稳定"的问题。

4. `collectTimer`

这个字段保存收集阶段对应的定时器。

有了它之后，系统就可以做到：

只创建一个收集定时器
收集结束后清理引用
页面销毁或状态重置时主动清理

四、完整代码怎么写

下面给一套完整、独立、可直接理解的示例代码。为了方便阅读，拆成三部分：

store.js
modal.js
一个完整的弹窗组件示例

1. `store.js`

这个文件是整套弹窗调度机制的核心。

js 复制代码

import Vue from "vue";
import Vuex from "vuex";

Vue.use(Vuex);

export default new Vuex.Store({
  state: {
    autoModalState: {
      modalQueue: [],
      currentModal: null,
      isCollectingModals: true,
      collectTimer: null,
    },
  },

  mutations: {
    // 弹窗入队，并按优先级排序
    mModalEnqueue(state, modalConfig) {
      state.autoModalState.modalQueue.push(modalConfig);
      state.autoModalState.modalQueue.sort((a, b) => a.priority - b.priority);
    },

    // 记录收集定时器，避免重复创建
    mModalSetCollectTimer(state, timer) {
      state.autoModalState.collectTimer = timer;
    },

    // 收集阶段结束
    mModalFinishCollection(state) {
      state.autoModalState.isCollectingModals = false;
      state.autoModalState.collectTimer = null;
    },

    // 取出队列头部弹窗作为当前弹窗
    mModalShiftToCurrent(state) {
      state.autoModalState.currentModal = state.autoModalState.modalQueue.shift() || null;
    },

    // 清空当前弹窗
    mModalClearCurrent(state) {
      state.autoModalState.currentModal = null;
    },

    // 清空队列
    mModalClearQueue(state) {
      state.autoModalState.modalQueue = [];
    },

    // 重置整套状态
    mModalResetState(state) {
      state.autoModalState = {
        modalQueue: [],
        currentModal: null,
        isCollectingModals: true,
        collectTimer: null,
      };
    },
  },

  actions: {
    // 注册一个自动弹窗
    aModalAdd({ state, commit, dispatch }, modalConfig) {
      const config = {
        key: "",
        priority: 10,
        ...modalConfig,
      };

      commit("mModalEnqueue", config);

      // 首轮先只收集，不立即展示
      if (state.autoModalState.isCollectingModals) {
        if (!state.autoModalState.collectTimer) {
          const timer = setTimeout(() => {
            commit("mModalFinishCollection");

            if (!state.autoModalState.currentModal) {
              dispatch("aModalShowNext");
            }
          }, 1000);

          commit("mModalSetCollectTimer", timer);
        }

        return;
      }

      // 收集阶段结束后，如果当前没有弹窗，则立即展示
      if (!state.autoModalState.currentModal) {
        dispatch("aModalShowNext");
      }
    },

    // 展示下一个弹窗
    aModalShowNext({ state, commit }) {
      if (state.autoModalState.isCollectingModals) {
        return;
      }

      if (state.autoModalState.modalQueue.length === 0) {
        commit("mModalClearCurrent");
        return;
      }

      commit("mModalShiftToCurrent");

      if (state.autoModalState.currentModal && typeof state.autoModalState.currentModal.show === "function") {
        state.autoModalState.currentModal.show();
      }
    },

    // 关闭当前弹窗，并自动切到下一个
    aModalCloseCurrent({ state, commit, dispatch }) {
      if (!state.autoModalState.currentModal) {
        return;
      }

      commit("mModalClearCurrent");
      dispatch("aModalShowNext");
    },

    // 清空队列并关闭当前弹窗
    aModalClearQueue({ commit, dispatch }) {
      commit("mModalClearQueue");
      dispatch("aModalCloseCurrent");
    },

    // 页面销毁或退出登录时调用
    aModalReset({ state, commit }) {
      if (state.autoModalState.collectTimer) {
        clearTimeout(state.autoModalState.collectTimer);
      }

      commit("mModalResetState");
    },
  },
});

2. `modal.js`

这个文件的作用很简单，就是把"注册弹窗"这件事统一收口。

js 复制代码

import store from "./store";

export function registerModal({ key, priority = 10, show }) {
  store.dispatch("aModalAdd", {
    key,
    priority,
    show,
  });
}

这一步看起来很薄，但价值很大。因为统一入口之后，业务组件就不需要直接感知队列细节了。

3. 一个完整的组件示例

下面这个示例模拟了一个"绑定手机号提醒"弹窗。代码里包含了注册、打开和关闭的完整流程。

vue 复制代码

<template>
  <div v-if="visible" class="modal-mask">
    <div class="modal-panel">
      <h3 class="modal-title">绑定手机号提醒</h3>
      <p class="modal-desc">为了保障账号安全，请先绑定手机号。</p>

      <div class="modal-actions">
        <button class="btn btn-primary" @click="confirmBind">立即绑定</button>
        <button class="btn" @click="closeDialog">稍后再说</button>
      </div>
    </div>
  </div>
</template>

<script>
import { registerModal } from "./modal";

export default {
  name: "BindPhoneDialog",

  props: {
    priority: {
      type: Number,
      default: 3,
    },
  },

  data() {
    return {
      visible: false,
      userInfo: {
        phone: "",
      },
    };
  },

  mounted() {
    const shouldShow = !this.userInfo.phone;

    if (shouldShow) {
      registerModal({
        key: "bind-phone",
        priority: this.priority,
        show: this.openDialog,
      });
    }
  },

  methods: {
    openDialog() {
      this.visible = true;
    },

    async confirmBind() {
      await new Promise(resolve => setTimeout(resolve, 300));
      this.closeDialog();
    },

    closeDialog() {
      this.visible = false;
      this.$store.dispatch("aModalCloseCurrent");
    },
  },
};
</script>

<style scoped>
.modal-mask {
  position: fixed;
  inset: 0;
  display: flex;
  align-items: center;
  justify-content: center;
  background: rgba(0, 0, 0, 0.45);
}

.modal-panel {
  padding: 24px;
  width: 420px;
  background: #fff;
  border-radius: 8px;
  box-shadow: 0 12px 32px rgba(0, 0, 0, 0.18);
}

.modal-title {
  margin: 0 0 12px;
  font-size: 20px;
}

.modal-desc {
  margin: 0 0 20px;
  line-height: 1.6;
  color: #666;
}

.modal-actions {
  display: flex;
  gap: 12px;
}

.btn {
  padding: 8px 14px;
  border: 1px solid #dcdcdc;
  background: #fff;
  border-radius: 4px;
  cursor: pointer;
}

.btn-primary {
  color: #fff;
  background: #0052d9;
  border-color: #0052d9;
}
</style>

五、整套机制的执行流程

如果只看代码，容易觉得这就是一堆 state、mutation 和 action。但从流程角度看，其实非常清晰。

第一步：组件先注册，不自己直接弹

当组件判断自己满足条件时，先调用：

js 复制代码

registerModal({
  key: "bind-phone",
  priority: 3,
  show: this.openDialog,
});

这一刻，组件做的不是"显示自己"，而是"申请进入队列"。

第二步：Store 接收请求并入队排序

队列会做两件事：

js 复制代码

state.autoModalState.modalQueue.push(modalConfig);
state.autoModalState.modalQueue.sort((a, b) => a.priority - b.priority);

这样处理之后，优先级最小的弹窗就永远在最前面。

第三步：首轮进入收集窗口

页面刚打开时，系统不会马上展示，而是先等一小段时间，把这一批自动弹窗收集起来：

js 复制代码

if (state.autoModalState.isCollectingModals) {
  if (!state.autoModalState.collectTimer) {
    const timer = setTimeout(() => {
      commit("mModalFinishCollection");
      if (!state.autoModalState.currentModal) {
        dispatch("aModalShowNext");
      }
    }, 1000);
    commit("mModalSetCollectTimer", timer);
  }
  return;
}

这是这套机制最关键的一步。因为没有这一步，首屏弹窗顺序仍然会很依赖注册时机。

第四步：开始正式调度

收集阶段结束后，系统取出队列头部的弹窗，把它设成 currentModal，然后调用它的 show()：

js 复制代码

commit("mModalShiftToCurrent");
state.autoModalState.currentModal.show();

于是第一个真正应该出现的弹窗就展示出来了。

第五步：关闭当前弹窗，自动轮到下一个

当前弹窗关闭时，不只是把自己隐藏掉，还必须告诉 Store：

js 复制代码

closeDialog() {
  this.visible = false;
  this.$store.dispatch("aModalCloseCurrent");
}

接下来 Store 会清空当前弹窗，并自动尝试展示队列里的下一个。

这一步就是"自动续播"的来源。

六、用一个具体例子看执行顺序

假设一个页面同时命中了 3 个自动弹窗：

新手引导，优先级 1
绑定手机号，优先级 3
欢迎通知，优先级 10

系统实际的执行顺序会是这样：

页面初始化，3 个组件几乎同时调用 registerModal()
3 个弹窗全部进入 modalQueue
队列排序后变成 1 -> 3 -> 10
因为还在收集阶段，所以此时先不展示
1 秒后，收集阶段结束
系统取出优先级 1 的弹窗并展示
用户关闭第一个弹窗
Store 自动调度优先级 3 的弹窗
第二个关闭后，再展示优先级 10 的弹窗
所有弹窗都展示完，队列恢复为空

这一整套流程的最大价值，就是顺序稳定，而且行为可预期。

七、为什么这套设计更适合长期维护

因为它把职责切得很清楚。

业务组件只需要关心：

自己该不该弹
自己怎么打开
自己关闭时怎么通知系统

全局调度中心只需要关心：

收集弹窗
维护优先级
控制串行展示
清理状态

这样以后，每个弹窗都不需要再自己处理这些复杂问题：

有没有别的弹窗正在显示
自己应该排在第几位
关闭之后要不要手动去找下一个弹窗

所有这些"协调工作"，都由队列统一负责。

八、实际落地时有几个细节要注意

1. `show` 必须是一个可执行函数

因为真正展示时，系统会直接调用：

js 复制代码

state.autoModalState.currentModal.show();

所以注册进去的 show 必须能直接执行。

2. 关闭时一定要调 `aModalCloseCurrent`

如果只是：

js 复制代码

this.visible = false;

而没有：

js 复制代码

this.$store.dispatch("aModalCloseCurrent");

那么当前队列状态不会推进，后面的弹窗也就不会出现。

3. 收集窗口时间不是一成不变的

示例里写的是 1 秒：

js 复制代码

这个值只是经验值。页面初始化逻辑越复杂，越适合稍微放大一点；页面越轻量，也可以适当缩短。

4. 页面退出时记得重置

如果用户退出登录、切换租户或者销毁整页，建议执行：

js 复制代码

this.$store.dispatch("aModalReset");

这样可以避免残留定时器和历史状态影响下一次进入页面时的弹窗行为。

九、如果你只想快速接入，记住这三步

如果你已经理解了原理，但暂时不想看太多细节，那只要记住下面三件事就够了：

第一，在 Store 里维护一个这样的状态：

js 复制代码

{
  modalQueue: [],
  currentModal: null,
  isCollectingModals: true,
  collectTimer: null,
}

第二，提供统一的 registerModal()。

第三，每个弹窗在关闭时调用：

js 复制代码

this.$store.dispatch("aModalCloseCurrent");

做到这三点，这套全局自动弹窗机制基本就能运转起来。

十、总结

全局自动弹窗队列，本质上就是一个面向"多弹窗并发场景"的调度器。

它真正解决的，不是"如何写一个弹窗"，而是下面这些更关键的问题：

多个自动弹窗同时触发时如何避免冲突
弹窗展示顺序如何稳定
高优先级弹窗如何确保先展示
当前弹窗关闭后如何自动衔接下一个

把整套思路压缩成一句话，就是：

先统一注册，再统一收集，接着统一排序，最后串行展示。

这套方案并不复杂，但非常适合长期维护。如果你的项目已经开始出现多个自动弹窗互相抢占的问题，越早把它们纳入一个全局队列，后面越省心。

Vue2 项目中的全局自动弹窗队列设计

一、为什么自动弹窗会越来越难管

1. 多个弹窗同时显示

2. 同一个页面，每次弹窗顺序都不一样

3. 优先级要求很难真正落地

4. 关闭后没有续播机制

二、什么是"全局自动弹窗队列"

三、核心状态应该怎么设计

1. modalQueue

2. currentModal

3. isCollectingModals

4. collectTimer

四、完整代码怎么写

1. store.js

2. modal.js

3. 一个完整的组件示例

五、整套机制的执行流程

第一步：组件先注册，不自己直接弹

第二步：Store 接收请求并入队排序

第三步：首轮进入收集窗口

第四步：开始正式调度

第五步：关闭当前弹窗，自动轮到下一个

六、用一个具体例子看执行顺序

七、为什么这套设计更适合长期维护

八、实际落地时有几个细节要注意

1. show 必须是一个可执行函数

2. 关闭时一定要调 aModalCloseCurrent

3. 收集窗口时间不是一成不变的

4. 页面退出时记得重置

九、如果你只想快速接入，记住这三步

十、总结

1. `modalQueue`

2. `currentModal`

3. `isCollectingModals`

4. `collectTimer`

1. `store.js`

2. `modal.js`

1. `show` 必须是一个可执行函数

2. 关闭时一定要调 `aModalCloseCurrent`