frame-bus

Vue 2/3 跨 iframe 通信总线，提供安全、高效、易用的跨窗口通信解决方案。

功能特性

核心功能

• ✅ 跨 iframe 安全通信
• ✅ 支持父子窗口和兄弟窗口通信
• ✅ 自动注册和发现机制
• ✅ 事件驱动的通信模式
• ✅ 共享状态管理
• ✅ 消息确认机制
• ✅ 深度合并和增量更新

优化特性

• 🔒 安全性：改进了 targetOrigin 处理，添加了 origin 验证
• ⚡ 性能：使用 Map 存储事件监听器，减少内存使用
• 📈 效率：共享状态增量更新，避免不必要的消息广播
• 🔄 可靠性：消息确认机制，确保消息送达
• 🎯 易用性：支持 Promise API，简化异步通信
• 🔀 兼容性：同时支持 Vue 2 和 Vue 3

安装

NPM

npm install frame-bus --save

Yarn

yarn add frame-bus

CDN

<!-- 非压缩版本 -->
<script src="https://unpkg.com/frame-bus/lib/frame-bus.js"></script>

<!-- 压缩版本 -->
<script src="https://unpkg.com/frame-bus/lib/frame-bus.min.js"></script>

快速开始

Vue 2

import Vue from 'vue'
import frameBus from 'frame-bus'

Vue.use(frameBus, {
  // 配置选项
  allowedOrigins: ['https://example.com'], // 允许的来源
  logLevel: 'warn', // 日志级别
})

// 在组件中使用
export default {
  methods: {
    // 自动注册为事件监听器（onFrame 开头的方法）
    onFrameUserLogin(payload) {
      console.log('用户登录:', payload)
    },

    // 发送消息到父窗口
    sendMessageToParent() {
      this.$frameBus.emit(
        'user-action',
        { type: 'click', target: 'button' },
        'parent'
      )
    },

    // 发送消息到所有窗口
    broadcastMessage() {
      this.$frameBus.emit('global-event', { message: 'Hello world' })
    },
  },

  created() {
    // 手动监听事件
    this.$frameBus.on('custom-event', (payload) => {
      console.log('收到自定义事件:', payload)
    })
  },

  beforeDestroy() {
    // 清理事件监听器
    this.$frameBus.off('custom-event')
  },
}

Vue 3

import { createApp } from 'vue'
import App from './App.vue'
import frameBus from 'frame-bus'

const app = createApp(App)
app.use(frameBus, {
  allowedOrigins: ['https://example.com'],
  logLevel: 'warn',
})
app.mount('#app')

// 在组件中使用（Composition API）
export default {
  setup() {
    // 获取 frameBus 实例
    const frameBus = inject('frameBus')

    // 监听事件
    onMounted(() => {
      frameBus.on('user-login', (payload) => {
        console.log('用户登录:', payload)
      })
    })

    // 发送消息
    const sendMessage = () => {
      frameBus.emit('user-action', { type: 'click' })
    }

    return {
      sendMessage,
    }
  },
}

原生 JavaScript

// 引入 frame-bus（UMD 模式）
const frameBus = window.FrameBus

// 初始化
frameBus.updateOptions({
  allowedOrigins: ['https://example.com'],
})

// 监听事件
frameBus.on('custom-event', (payload) => {
  console.log('收到事件:', payload)
})

// 发送消息
frameBus.emit('send-message', { data: 'Hello' })

API 文档

核心方法

emit(type, payload, target = '*', options = {})

发送事件到指定目标

• 参数:

  • type: 事件类型（字符串）
  • payload: 事件数据（任意类型）
  • target: 目标窗口（可选）
    • '*': 所有窗口（默认）
    • 'parent': 父窗口
    • 'children': 所有子窗口
    • 特定窗口 ID: 单个窗口
  • options: 配置选项（可选）
    • requiresAck: 是否需要确认（布尔值）
    • timeout: 超时时间（毫秒）

• 返回值:

  • 如果 requiresAck 为 true，返回 Promise；否则返回 undefined

on(type, callback)

监听指定事件

• 参数:
  • type: 事件类型（字符串）
  • callback: 回调函数，接收 payload 和 meta 参数

off(type, callback)

取消监听事件

• 参数:
  • type: 事件类型（字符串）
  • callback: 回调函数（可选，不提供则移除所有该类型的监听器）

once(type, callback)

监听事件一次

• 参数:
  • type: 事件类型（字符串）
  • callback: 回调函数

共享状态

setSharedData(key, value)

设置共享数据

• 参数:
  • key: 数据键（字符串）或数据对象
  • value: 数据值（任意类型，当 key 为字符串时）

getSharedData(key)

获取共享数据

• 参数:

  • key: 数据键（字符串，可选，不提供则返回所有共享数据）

• 返回值:

  • 指定键的共享数据或所有共享数据

配置选项

| 选项 | 类型 | 默认值 | 说明 | | ---------------- | ---------- | -------- | -------------------------------------------------- | | allowedOrigins | string[] | [] | 允许通信的来源列表 | | maxRetries | number | 3 | 消息重试次数 | | retryInterval | number | 1000 | 重试间隔（毫秒） | | maxQueueSize | number | 100 | 消息队列最大长度 | | logLevel | string | 'warn' | 日志级别：'error', 'warn', 'info', 'debug' |

自动事件注册

组件中以 onFrame 开头的方法会自动注册为事件监听器：

methods: {
  // 自动注册为 'user-login' 事件监听器
  onFrameUserLogin(payload) {
    console.log('用户登录:', payload)
  },

  // 自动注册为 'data-updated' 事件监听器
  onFrameDataUpdated(data) {
    console.log('数据更新:', data)
  }
}

注意事项

1. ES6 特性支持

   • 项目中需确保已提供 Map、Set 等 ES6 特性的 polyfill
   • 推荐使用 babel-polyfill 或 core-js

2. 安全性

   • 始终设置 allowedOrigins 以限制通信来源
   • 避免在消息中传输敏感信息
   • 对接收到的消息进行验证

3. 性能优化

   • 避免发送过大的消息
   • 合理使用消息确认机制
   • 及时清理事件监听器

4. Vue 版本兼容性

   • 支持 Vue 2.5+ 和 Vue 3.0+
   • Vue 3 中推荐使用 Composition API

浏览器支持

• Chrome 60+
• Firefox 55+
• Safari 12+
• Edge 79+

开发和构建

安装依赖

npm install

开发模式

npm run dev

构建

npm run build

类型检查

npm run typecheck

贡献

欢迎提交 Issue 和 Pull Request！

开发流程

1. Fork 项目
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 打开 Pull Request

许可证

MIT License - 详见 LICENSE 文件

联系

如有问题或建议，请提交 Issue 或发送邮件。

Enjoy coding! 🚀