@bugfix2019/iframe-bridge


一个通用的 iframe JavaScript Bridge，用于浏览器环境下基于 postMessage 的安全通信。

> 注意：不支持 SSR，仅支持浏览器环境。

✨ 特性

- 🎯 100% TypeScript - 完整类型定义
- ✅ 测试覆盖率 - Vitest + v8 coverage，覆盖率按文件统计
- 🚀 简单 API - 支持方法调用与事件
- 🔒 Origin 校验 - 支持 allowedOrigins 白名单
- 🔧 React Hook - 子路径导出 @bugfix2019/iframe-bridge/react

📦 安装

``bash


npm

`ts
import { createParentBridge } from '@bugfix2019/iframe-bridge';

const iframe = document.getElementById('myIframe') as HTMLIFrameElement;
const bridge = createParentBridge(iframe, 'https://child-domain.com', {
debug: true,
timeout: 5000,
allowedOrigins: ['https://child-domain.com']
});

bridge.registerMethod('getUserInfo', async () => ({ id: 1, name: 'John Doe' }));

bridge.on('userAction', (data) => {
console.log('userAction:', data);
});

const result = await bridge.call('childMethod', { param: 'value' });
console.log('child result:', result);

bridge.emit('parentEvent', { message: 'Hello from parent' });
`

子窗口（iframe 内）：

`ts
import { createChildBridge } from '@bugfix2019/iframe-bridge';

const bridge = createChildBridge('https://parent-domain.com', { debug: true });

bridge.registerMethod('childMethod', async (params) => {
console.log('childMethod params:', params);
return { ok: true };
});

const userInfo = await bridge.call('getUserInfo');
console.log('userInfo:', userInfo);

bridge.on('parentEvent', (data) => console.log('parentEvent:', data));
bridge.emit('userAction', { action: 'click', target: 'button' });
`

React Hook：

`ts
import { useIframeBridge } from '@bugfix2019/iframe-bridge/react';
`

⚙️ 配置选项

BridgeOptions：

`ts
export interface BridgeOptions {
allowedOrigins?: string[];
timeout?: number;
debug?: boolean;
messageValidator?: (message: any) => boolean;
}
`

Hook 参数：

- mode: 'child'：在 iframe 内自动连接 window.parent
- mode: 'parent'：需要传入 iframe 元素以连接 iframe.contentWindow

🧪 测试覆盖率

本仓库已配置 Vitest 覆盖率（@vitest/coverage-v8），输出目录为 coverage/。

运行测试：
`bash
npm test
`

查看覆盖率报告：
`bash
npm run test:coverage
`

覆盖率（按文件）：

| 文件 | 语句覆盖率 | 分支覆盖率 | 函数覆盖率 | 行覆盖率 |
|------|-----------|-----------|-----------|---------|
| src/bridge.ts | 90.32% | 77.08% | 100% | 90.32% |
| src/index.ts | 100% | 100% | 100% | 100% |
| src/react/useIframeBridge.ts | 84.14% | 88.88% | 100% | 84.14% |
| src/react/index.ts | 100% | 100% | 100% | 100% |
| 总计 | 89.12% | 82.19% | 100% | 89.12% |

纯类型文件 src/types.ts 不参与覆盖率统计。

🛠️ 开发

`bash


安装依赖

`bash


1. 确保构建成功

`
iframe-bridge/
├── src/
│ ├── __test__/
│ │ ├── iframeBridge.__test__.ts
│ │ └── useIframeBridge.__test__.ts
│ ├── react/
│ │ ├── useIframeBridge.ts
│ │ └── index.ts
│ ├── bridge.ts
│ ├── types.ts
│ └── index.ts
├── dist/ # 构建输出
├── coverage/ # 运行 test:coverage 后生成
├── package.json
├── tsconfig.json
├── tsup.config.ts
├── vitest.config.ts
└── README.md
`

🤝 贡献

如需贡献：

1. 修改/新增功能
2. 增加/更新单元测试
3. 运行 npm test 与 npm run test:coverage
4. 更新 README

📄 许可证

MIT

👥 贡献者

感谢以下贡献者对本项目的贡献：

Polaris


_{📧 ts02315607@gmail.com}

🔗 相关链接

- GitHub 仓库
- Window.postMessage
- Vitest

❓ 常见问题

$3

A: 不支持。该库依赖 window 与 postMessage，仅支持浏览器环境。

$3

A: 在 BridgeOptions.allowedOrigins 里设置白名单（推荐始终设置）。

$3

A: 在不再需要通信时调用 destroy()`；React 中使用 Hook 时，组件卸载会自动清理。

---
Made with ❤️ by Polaris