# PostmessageUtils
**Repository Path**: Tianyu201809/postmessage-utils
## Basic Information
- **Project Name**: PostmessageUtils
- **Description**: 父子页面传递消息的工具库
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-27
- **Last Updated**: 2025-11-27
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# PostMessageUtils
一个用于跨窗口通信的 PostMessage 工具库，支持消息发送、接收和响应机制。
## 特性
- ✅ 简单易用的 API
- ✅ 支持消息响应机制（类似请求-响应模式）
- ✅ 自动消息 ID 管理
- ✅ 兼容 ES5，支持 IE9+ 及所有现代浏览器
- ✅ UMD 格式，支持多种模块系统
## 安装
### 浏览器环境
直接引入打包后的文件：
```html
```
### Node.js 环境
```javascript
const PostMessageUtils = require('./dist/postmessage.umd.js');
```
### ES 模块
```javascript
import PostMessageUtils from './dist/postmessage.umd.js';
```
## API 文档
### setReceiver(callback)
设置接收消息的回调函数。当收到消息时，会自动调用此回调。
**参数：**
- `callback` (Function): 回调函数，接收三个参数：
- `origin` (string): 消息来源的 origin
- `messageData` (*): 消息数据
- `uid` (number): 消息的唯一标识符
**示例：**
```javascript
PostMessageUtils.setReceiver(function(origin, messageData, uid) {
console.log('收到来自 ' + origin + ' 的消息:', messageData);
console.log('消息 ID:', uid);
});
```
### sendMessage(targetWindow, targetOrigin, messageData, onResponse)
向目标窗口发送消息。
**参数：**
- `targetWindow` (Window): 目标窗口对象（例如：`iframe.contentWindow` 或 `window.open()` 返回的窗口）
- `targetOrigin` (string): 目标窗口的 origin（例如：`"https://example.com"` 或 `"*"`）
- `messageData` (*): 要发送的消息数据（可以是任何可序列化的数据）
- `onResponse` (Function, 可选): 当收到响应时的回调函数，接收响应数据作为参数
**示例：**
```javascript
// 简单发送消息（不需要响应）
var iframe = document.getElementById('myIframe');
PostMessageUtils.sendMessage(
iframe.contentWindow,
'https://example.com',
{ type: 'greeting', text: 'Hello!' }
);
// 发送消息并等待响应
PostMessageUtils.sendMessage(
iframe.contentWindow,
'https://example.com',
{ type: 'request', action: 'getData' },
function(response) {
console.log('收到响应:', response);
}
);
```
### respondToMessage(uid, responseMessage)
响应之前收到的消息。当收到一个需要响应的消息时，使用此方法发送响应。
**参数：**
- `uid` (number): 原始消息的唯一标识符（在 `setReceiver` 回调中获取）
- `responseMessage` (*): 响应数据（可以是任何可序列化的数据）
**示例：**
```javascript
PostMessageUtils.setReceiver(function(origin, messageData, uid) {
if (messageData.type === 'request') {
// 处理请求并发送响应
var response = { status: 'success', data: '处理结果' };
PostMessageUtils.respondToMessage(uid, response);
}
});
```
### receiveMessage(origin, payload, sourceWindow)
处理接收到的消息。通常由库内部自动调用，但也可以手动调用。
**参数：**
- `origin` (string): 消息来源的 origin
- `payload` (Object): 消息负载对象
- `sourceWindow` (Window): 来源窗口对象
## 使用示例
### 示例 1: 基本消息发送和接收
**父页面 (parent.html):**
```html
父页面
```
**子页面 (child.html):**
```html
子页面
子页面
```
### 示例 2: 请求-响应模式
**发送请求并等待响应：**
```javascript
// 发送请求
PostMessageUtils.sendMessage(
targetWindow,
'https://example.com',
{
type: 'getUserInfo',
userId: 123
},
function(response) {
// 处理响应
if (response.status === 'success') {
console.log('用户信息:', response.data);
} else {
console.error('获取失败:', response.error);
}
}
);
```
**接收请求并发送响应：**
```javascript
PostMessageUtils.setReceiver(function(origin, messageData, uid) {
if (messageData.type === 'getUserInfo') {
// 模拟异步处理
setTimeout(function() {
var userInfo = {
id: messageData.userId,
name: 'John Doe',
email: 'john@example.com'
};
// 发送响应
PostMessageUtils.respondToMessage(uid, {
status: 'success',
data: userInfo
});
}, 1000);
}
});
```
### 示例 3: 多窗口通信
```javascript
// 打开多个窗口
var window1 = window.open('page1.html', 'window1');
var window2 = window.open('page2.html', 'window2');
// 向所有窗口广播消息
function broadcastMessage(messageData) {
PostMessageUtils.sendMessage(window1, '*', messageData);
PostMessageUtils.sendMessage(window2, '*', messageData);
}
// 使用
broadcastMessage({ type: 'notification', text: '系统通知' });
```
## 注意事项
1. **Origin 安全**: 在生产环境中，建议使用具体的 origin 而不是 `"*"`，以提高安全性。
2. **消息格式**: 库会自动为消息添加 `uid`、`type` 和 `waitForResponse` 字段。你的 `messageData` 会被包装在 `payload.message` 中。
3. **响应处理**: 只有在调用 `sendMessage` 时提供了 `onResponse` 回调，才会等待响应。如果不需要响应，可以不提供该参数。
4. **消息 ID**: 每个消息都有唯一的 `uid`，用于匹配请求和响应。
5. **浏览器兼容性**: 库兼容 IE9+ 及所有现代浏览器，使用了 ES5 语法。
## 构建
```bash
# 安装依赖
npm install
# 构建
npm run build
```
构建后的文件位于 `dist/postmessage.umd.js`。
## 许可证
MIT