iframe-bridge-sdk/README.md

Universal iframe communication SDK - unified package for host and guest applications

# Iframe Bridge SDK

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

## 功能特性

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

## 本地安装

### 1. 构建包

```bash
# 安装依赖
npm install

# 构建包
npm run build
```

### 2. 创建本地包

```bash
# 创建本地npm包
npm pack
```

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

### 3. 在项目中使用

#### 方法一：直接安装本地包

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

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

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

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

## 使用方法

### Host SDK (宿主应用)

```typescript
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内部)

```typescript
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

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

### GuestConfig

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

### 事件系统

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

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

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

### 请求-响应系统

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

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

## 开发

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

# 清理构建文件
npm run clean

# 构建
npm run build
```

## 许可证

MIT License

## 贡献

欢迎提交 Issue 和 Pull Request！