Vue开发H5项目中基于栈的弹窗管理

背景

在移动端 H5 应用开发中，尤其是嵌入到原生 App 的场景下，弹窗管理是一个常见但棘手的问题。当用户触发返回手势时，我们需要：

• 正确关闭当前弹窗而不是直接返回上一页
• 处理多个弹窗叠加的场景
• 支持某些重要弹窗禁止返回关闭
• 统一管理所有弹窗状态

本文介绍一个基于栈（Stack）数据结构的弹窗管理方案，使用 Vue 3 + Vuex 4 实现。

核心设计思路

1. 栈结构管理

采用**后进先出（LIFO）**的栈结构管理弹窗，这与用户的操作预期一致：

• 最后打开的弹窗应该最先关闭
• 返回手势总是关闭最上层的弹窗

2. 统一注册机制

所有弹窗组件通过 mixin 自动注册到 Vuex 中：

• 弹窗打开时自动入栈
• 弹窗关闭时自动出栈
• 无需手动管理状态

3. 灵活的配置选项

每个弹窗可以配置：

• preventBack: 是否允许返回关闭
• priority: 优先级
• group: 分组管理
• beforeClose: 关闭前的钩子函数

技术实现

1. Vuex Store 模块

// store/modules/popup.js
export default {
  namespaced: true,
  
  state: {
    popupStack: [], // 弹窗栈
    popupMap: {}    // 弹窗映射表，用于快速查找
  },
  
  mutations: {
    // 添加弹窗到栈顶
    PUSH_POPUP(state, popup) {
      state.popupStack.push(popup);
      state.popupMap[popup.id] = popup;
    },
    
    // 从栈顶移除弹窗
    POP_POPUP(state) {
      const popup = state.popupStack.pop();
      if (popup) {
        delete state.popupMap[popup.id];
      }
      return popup;
    },
    
    // 移除特定弹窗
    REMOVE_POPUP(state, id) {
      const index = state.popupStack.findIndex(p => p.id === id);
      if (index > -1) {
        const [popup] = state.popupStack.splice(index, 1);
        delete state.popupMap[id];
        return popup;
      }
      return null;
    },
    
    // 清空所有弹窗
    CLEAR_POPUPS(state) {
      state.popupStack = [];
      state.popupMap = {};
    }
  },
  
  actions: {
    // 注册弹窗
    registerPopup({ commit }, popupInfo = {}) {
      const popup = {
        id: popupInfo.id || `popup_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`,
        type: popupInfo.type || 'popup',
        component: popupInfo.component || 'Unknown',
        props: popupInfo.props || {},
        closeHandler: popupInfo.closeHandler || null,
        preventBack: popupInfo.preventBack || false,
        priority: popupInfo.priority || 0,
        group: popupInfo.group || 'default',
        beforeClose: popupInfo.beforeClose || null,
        timestamp: Date.now()
      };
      
      commit('PUSH_POPUP', popup);
      return popup.id;
    },
    
    // 处理返回手势
    async handleBackGesture({ state, commit }) {
      const topPopup = state.popupStack[state.popupStack.length - 1];
      
      if (!topPopup) {
        return false; // 没有弹窗
      }
      
      // 检查是否阻止返回关闭
      if (topPopup.preventBack) {
        return true; // 已处理但不关闭
      }
      
      // 执行关闭前的钩子
      if (topPopup.beforeClose) {
        try {
          const shouldClose = await topPopup.beforeClose();
          if (!shouldClose) {
            return true; // 阻止关闭
          }
        } catch (error) {
          console.error('Popup beforeClose hook error:', error);
        }
      }
      
      // 执行关闭处理器
      if (topPopup.closeHandler) {
        try {
          topPopup.closeHandler();
        } catch (error) {
          console.error('Popup closeHandler error:', error);
        }
      }
      
      // 从栈中移除
      commit('POP_POPUP');
      return true;
    }
  },
  
  getters: {
    activePopupCount: state => state.popupStack.length,
    topPopup: state => state.popupStack[state.popupStack.length - 1] || null,
    hasPopups: state => state.popupStack.length > 0,
    getPopupById: state => id => state.popupMap[id] || null
  }
};

2. 弹窗 Mixin

// mixins/popupMixin.js
export const popupMixin = {
  props: {
    popupId: {
      type: String,
      default: ''
    },
    preventBack: {
      type: Boolean,
      default: false
    },
    popupPriority: {
      type: Number,
      default: 0
    },
    popupGroup: {
      type: String,
      default: 'default'
    }
  },
  
  data() {
    return {
      _popupId: null,
      _isRegistered: false
    };
  },
  
  computed: {
    isTopPopup() {
      const topPopup = this.$store.getters['popup/topPopup'];
      return topPopup && topPopup.id === this._popupId;
    }
  },
  
  beforeUnmount() {
    this.unregisterPopup();
  },
  
  methods: {
    // 注册弹窗
    async registerPopup() {
      this._popupId = await this.$store.dispatch('popup/registerPopup', {
        id: this.popupId || undefined,
        type: this.getPopupType(),
        component: this.$options.name || 'UnknownPopup',
        props: this.$props,
        closeHandler: () => this.handleClose(),
        preventBack: this.preventBack,
        priority: this.popupPriority,
        group: this.popupGroup,
        beforeClose: this.beforeClose ? () => this.beforeClose() : null
      });
    },
    
    // 注销弹窗
    unregisterPopup() {
      if (this._popupId) {
        const popup = this.$store.state.popup.popupMap[this._popupId];
        if (popup) {
          this.$store.commit('popup/REMOVE_POPUP', this._popupId);
        }
      }
    },
    
    // 获取弹窗类型（子组件可重写）
    getPopupType() {
      const name = this.$options.name || '';
      if (name.toLowerCase().includes('dialog')) return 'dialog';
      if (name.toLowerCase().includes('toast')) return 'toast';
      if (name.toLowerCase().includes('modal')) return 'modal';
      if (name.toLowerCase().includes('popup')) return 'popup';
      return 'popup';
    },
    
    // 处理关闭（子组件可重写）
    handleClose() {
      this.$emit('close');
      if ('modelValue' in this.$props) {
        this.$emit('update:modelValue', false);
      }
      if ('visible' in this.$props) {
        this.$emit('update:visible', false);
      }
      if ('show' in this.$props) {
        this.$emit('update:show', false);
      }
    },
    
    // 关闭前的钩子（子组件可重写）
    beforeClose() {
      return true;
    },
    
    // 主动关闭弹窗
    close() {
      if (this._popupId) {
        this.$store.dispatch('popup/closePopup', this._popupId);
      }
    }
  }
};

3. 通用弹窗组件

<!-- components/base/BaseDialog.vue -->
<template>
  <van-dialog
    v-model:show="visible"
    v-bind="dialogProps"
    @confirm="handleConfirm"
    @cancel="handleCancel"
    :class="['base-dialog', customClass]"
  >
    <slot>
      <div class="dialog-content">
        {{ message }}
      </div>
    </slot>
  </van-dialog>
</template>

<script>
import { popupMixin } from '@/mixins/popupMixin';

export default {
  name: 'BaseDialog',
  mixins: [popupMixin],
  
  props: {
    modelValue: {
      type: Boolean,
      default: false
    },
    title: String,
    message: String,
    // ... 其他 props
  },
  
  data() {
    return {
      visible: false,
      _isRegistered: false
    };
  },
  
  watch: {
    modelValue: {
      immediate: true,
      handler(val) {
        this.visible = val;
      }
    },
    visible(val) {
      this.$emit('update:modelValue', val);
      
      // 弹窗打开时注册，关闭时注销
      if (val && !this._isRegistered) {
        this.registerPopup();
        this._isRegistered = true;
      } else if (!val && this._isRegistered) {
        this.unregisterPopup();
        this._isRegistered = false;
      }
    }
  },
  
  methods: {
    getPopupType() {
      return 'dialog';
    },
    
    handleClose() {
      this.visible = false;
      this.$emit('update:modelValue', false);
      this.$emit('close');
    },
    
    handleConfirm() {
      this.$emit('confirm');
      if (!this.beforeClose) {
        this.visible = false;
      }
    },
    
    handleCancel() {
      this.$emit('cancel');
      if (!this.beforeClose) {
        this.visible = false;
      }
    }
  }
};
</script>

使用方法

1. 注册 Store 模块

// store/index.js
import { createStore } from 'vuex';
import popup from './modules/popup';

export default createStore({
  modules: {
    popup
  }
});

2. 使用弹窗组件

<template>
  <div>
    <van-button @click="showDialog = true">打开弹窗</van-button>
    
    <BaseDialog
      v-model="showDialog"
      title="确认操作"
      message="这是一个支持返回手势关闭的弹窗"
      @confirm="handleConfirm"
      @cancel="handleCancel"
    />
    
    <!-- 禁止返回关闭的弹窗 -->
    <BaseDialog
      v-model="showImportantDialog"
      title="重要操作"
      message="这个弹窗不能通过返回手势关闭"
      :prevent-back="true"
    />
  </div>
</template>

<script>
import BaseDialog from '@/components/base/BaseDialog.vue';

export default {
  components: {
    BaseDialog
  },
  
  data() {
    return {
      showDialog: false,
      showImportantDialog: false
    };
  }
};
</script>

3. 处理返回手势

// App 通信桥接
class AppBridge {
  constructor(store) {
    this.store = store;
    this.initBackHandler();
  }
  
  initBackHandler() {
    // 监听 App 发送的返回事件
    window.addEventListener('appBackGesture', this.handleAppBack.bind(this));
    
    // 如果使用 JSBridge
    if (window.JSBridge) {
      window.JSBridge.onBackPressed = this.handleAppBack.bind(this);
    }
  }
  
  async handleAppBack() {
    // 调用 store 处理返回
    const handled = await this.store.dispatch('popup/handleBackGesture');
    
    // 告诉 App 是否已处理
    if (window.JSBridge) {
      window.JSBridge.setBackHandled(handled);
    }
    
    return handled;
  }
}

高级特性

1. 弹窗分组

// 按组清空弹窗
this.$store.dispatch('popup/clearPopupsByGroup', 'login');

2. 关闭前确认

export default {
  mixins: [popupMixin],
  
  methods: {
    async beforeClose() {
      // 返回 false 阻止关闭
      if (this.hasUnsavedChanges) {
        const confirmed = await this.$dialog.confirm({
          message: '有未保存的更改，确定要关闭吗？'
        });
        return confirmed;
      }
      return true;
    }
  }
};

3. 弹窗优先级

<BaseDialog
  v-model="show"
  title="高优先级弹窗"
  :popup-priority="10"
/>

注意事项

1. 避免弹窗泄露

确保弹窗组件只在真正显示时才注册到栈中：

watch: {
  visible(val) {
    if (val && !this._isRegistered) {
      this.registerPopup();
      this._isRegistered = true;
    } else if (!val && this._isRegistered) {
      this.unregisterPopup();
      this._isRegistered = false;
    }
  }
}

2. 防止事件冲突

在处理键盘事件时，使用事件捕获和阻止冒泡：

window.addEventListener('keydown', async (e) => {
  if (e.key === 'Escape') {
    if (hasPopups) {
      e.preventDefault();
      e.stopPropagation();
      e.stopImmediatePropagation();
      
      await this.$store.dispatch('popup/handleBackGesture');
    }
  }
}, true); // 使用捕获阶段

3. 多入口应用支持

在多入口应用中，每个入口应该有独立的 store 实例，确保弹窗栈隔离：

// entry1/main.js
const store1 = createStore({ modules: { popup } });

// entry2/main.js
const store2 = createStore({ modules: { popup } });

最佳实践

1. 统一使用基础组件：创建 BaseDialog、BasePopup 等基础组件，确保所有弹窗都集成了 popupMixin。

2. 合理设置 preventBack：只在真正需要阻止返回的场景使用，如支付确认、重要数据提交等。

3. 提供视觉反馈：当弹窗不能通过返回关闭时，可以添加轻微的抖动动画提示用户。

4. 调试工具：在开发环境提供弹窗栈查看功能：

showPopupStack() {
  const count = this.$store.getters['popup/activePopupCount'];
  const topPopup = this.$store.getters['popup/topPopup'];
  console.log(`弹窗栈数量: ${count}, 栈顶: ${topPopup?.component}`);
}

总结

这个基于栈的弹窗管理方案具有以下优势：

• ✅ 符合直觉：后进先出的关闭顺序符合用户预期
• ✅ 易于集成：通过 mixin 实现，对现有组件改动最小
• ✅ 功能完整：支持阻止关闭、分组管理、优先级等高级特性
• ✅ 性能良好：使用映射表实现 O(1) 的查找效率
• ✅ 可扩展性：易于添加新功能，如动画过渡、持久化等

通过这个方案，我们可以优雅地处理移动端 H5 应用中的弹窗管理问题，提供更好的用户体验。

相关资源

• Vue 3 文档
• Vuex 4 文档
• Vant 组件库

---

本文基于 Vue 3.x + Vuex 4.x + Vant 4.x 实现，其他版本可能需要适当调整。