Porthole 库技术文档

Porthole 是一个小型库，用于安全地进行跨域 iFrame 通信。以下将详细介绍如何安装和使用 Porthole，以及如何通过其 API 进行交互。

1. 安装指南

Porthole 库可以通过以下方式引入到您的项目中：

<script type="text/javascript" src="porthole.min.js"></script>

确保将上述代码片段添加到您的 HTML 文件中以包含 Porthole 库。

2. 使用说明

在页面中创建一个 iFrame 元素，用于承载其他域的内容，并为该 iFrame 分配一个名称。

<iframe id="guestFrame" name="guestFrame" src="http://other-domain.com/">
</iframe>

定义一个事件处理函数，以便接收消息。

function onMessage(messageEvent) {  
    // messageEvent.origin: 消息的协议和域来源
    // messageEvent.data: 消息本身
    // messageEvent.source: 窗口代理对象，用于发送响应
}

在主页面中创建一个窗口代理对象。

var windowProxy;
window.onload = function() {
    // 在主页面中创建一个代理窗口，用于发送和接收 iFrame 的消息
    windowProxy = new Porthole.WindowProxy(
        'http://other-domain.com/proxy.html', 'guestFrame');

    // 注册事件处理函数以接收消息
    windowProxy.addEventListener(onMessage);
};

在 iFrame 中创建一个窗口代理对象。

var windowProxy;
window.onload = function() {
    // 在 iFrame 中创建一个代理窗口，用于发送和接收父页面的消息
    windowProxy = new Porthole.WindowProxy(
        'http://parent-domain.com/proxy.html');

    // 注册事件处理函数以接收消息
    windowProxy.addEventListener(function(event) { 
        // 处理事件
    });
};

发送消息。

windowProxy.post({'action': 'supersizeme'});

请注意，如果您有多个 iFrame，您可以创建所需数量的 WindowProxy 对象。

3. 项目 API 使用文档

Porthole 库提供了一个 WindowProxy 类，用于实现跨域通信。以下是其主要方法的简要描述：

• new Porthole.WindowProxy(url, [iframeElementId]): 构造函数接受代理页面的 URL 和一个可选的 iFrame ID。
• addEventListener(eventHandler): 注册一个事件处理函数，以便在接收到消息时被调用。
• post(message): 向代理窗口发送一个消息。

4. 项目安装方式

目前 Porthole 库的安装方式主要是通过直接将 JavaScript 文件链接到 HTML 页面中。未来可能支持 npm 或其他包管理工具的安装方式。

以上是对 Porthole 库的简要技术文档。如需进一步了解或查看演示，请参考项目自述文件或相关文档。