Iframe Bridge SDK

Universal iframe communication SDK - 用于宿主应用和访客应用之间通信的统一包。

功能特性

• 🚀 Host SDK: 在宿主应用中运行，创建iframe并与Guest SDK通信
• 🎯 Guest SDK: 在iframe内部运行，与Host SDK进行双向通信
• 📡 事件系统: 支持自定义事件和请求-响应模式
• 🔒 类型安全: 完整的TypeScript类型支持
• ⚡ 轻量级: 无外部依赖，体积小巧

本地安装

1. 构建包

# 安装依赖
npm install

# 构建包
npm run build

2. 创建本地包

# 创建本地npm包
npm pack

这将生成一个 .tgz 文件，例如：devo-iframe-bridge-1.0.0.tgz

3. 在项目中使用

方法一：直接安装本地包

# 在目标项目中安装本地包
npm install /path/to/devo-iframe-bridge-1.0.0.tgz

方法二：使用npm link（开发时推荐）

# 在SDK目录中创建全局链接
cd /path/to/sdk
npm link

# 在目标项目中链接包
cd /path/to/your-project
npm link @devo/iframe-bridge

使用方法

Host SDK (宿主应用)

import { HostSDK } from '@devo/iframe-bridge';

// 创建Host SDK实例
const hostSDK = new HostSDK({
  src: 'http://localhost:3000/guest.html',
  selector: '#iframe-container',
  width: '100%',
  height: '600px',
  timeout: 10000,
  allowedOrigins: ['http://localhost:3000'],
});

// 初始化
await hostSDK.init();

// 监听事件
hostSDK.on('custom-event', (data) => {
  console.log('收到自定义事件:', data);
});

// 发送请求
const response = await hostSDK.request('get-data', { id: 123 });
console.log('响应:', response);

// 发送事件
hostSDK.emit('update-data', { value: 'new data' });

Guest SDK (iframe内部)

import { GuestSDK } from '@devo/iframe-bridge';

// 创建Guest SDK实例
const guestSDK = new GuestSDK({
  timeout: 10000,
});

// 初始化
await guestSDK.init();

// 监听来自Host的事件
guestSDK.on('update-data', (data) => {
  console.log('收到更新:', data);
});

// 处理Host的请求
guestSDK.handleRequest('get-data', async (params) => {
  return { data: 'some data', params };
});

// 发送事件到Host
guestSDK.emit('data-changed', { timestamp: Date.now() });

// 发送请求到Host
const result = await guestSDK.request('save-data', { content: 'new content' });

API 参考

HostConfig

interface HostConfig {
  width?: string; // iframe宽度
  height?: string; // iframe高度
  src: string; // iframe源地址
  selector: string; // 容器选择器
  timeout?: number; // 超时时间(ms)
  allowedOrigins?: string[]; // 允许的源域名
}

GuestConfig

interface GuestConfig {
  timeout?: number; // 超时时间(ms)
}

事件系统

// 监听事件
sdk.on('event-name', (data) => {
  // 处理事件
});

// 发送事件
sdk.emit('event-name', data);

// 移除监听器
sdk.off('event-name', callback);

请求-响应系统

// 发送请求
const response = await sdk.request('method-name', params);

// 处理请求
sdk.handleRequest('method-name', async (params) => {
  // 处理请求并返回响应
  return { success: true, data: 'result' };
});

开发

# 开发模式（监听文件变化）
npm run dev

# 清理构建文件
npm run clean

# 构建
npm run build

许可证

MIT License

贡献

欢迎提交 Issue 和 Pull Request！