cic

简单易用的iframe通信库

索引

• 浏览器兼容性
• 使用方法
• 库引入方法
• API
• 示例代码

浏览器兼容性

• 兼容IE8+

使用方法

1. 在parent和iframe中都使用var connection = createConnection():Connection初始化连接对象
2. 为connection实例添加监听方法:onMessage,onConnect,onDisconnect
3. 接下来需要其中一方发起通信连接请求connection.connect(domWindow)
4. 注意
   1. **onConnection**在回调执行后，才可以connection.sendMsg(msg)进行消息传输
   2. 或者在执行connection.sendMsg(msg)前判断connection.connected为true
5. 如果通信连接已建立
   1. 那么iframe窗口内部页面刷新或者跳转到新的url地址之前，都会出发disconnect事件
6. 主动断开连接或收到断开连接事件后，如果重新连接，需要其中一方再次主动调用connection.connect(domWindow)方法

库引入方法

引入库代库后执行一个工厂方法，生产一个Connection类的实例

第一种 直接全局引入cic.js文件

<script src="https://unpkg.com/cic@2.0.10/dist/cic.min.js" type="text/script"></script>

<script type="text/script">
  var connection = window.Cic.createConnection();
</script>

第二种 module形式引入

import { createConnection } from 'cic';
var connection = createConnection();

API

1. 静态工厂方法Cic.createConnection():Connection

返回一个Connection类实例

2. Connection 类

2.1 实例属性connection.connected:Boolean

跨iframe通信是否已连通

2.2 实例属性connection.destroyed:Boolean

如果实例已销毁，那么当前实例不可再次发起连接请求

2.3 connection.onConnect(callback)

添加通信连接成功时的回调方法

2.4 connection.offConnect(callback)

移除通信连接成功时的回调方法

注意：**其中callback和传入onConnect的回调方法是同一个。**如果无法理解可参考addEventListener

2.5 connection.onDisconnect(callback)

添加通信断开连接时的回调方法

2.6 connection.offDisconnect(callback)

移除通信断开连接时的回调方法

注意：**其中callback和传入onDisconnect的回调方法是同一个。**如果无法理解可参考addEventListener

2.7 connection.onMessage(callback:(msg:any)=>void)

添加接收消息的回调方法

2.8 connection.offMessage(callback:(msg:any)=>void)

移除接收消息的回调方法。

注意：**其中callback和传入onMessage的回调方法是同一个。**如果无法理解可参考addEventListener

2.9 connection.destroy()

资源回收。如果连接已建立那么触发disconnect事件，通知对方连接断开

2.10 connection.connect(domWindow)

• 说明：发起连接请求
• 参数：domWindow表示需要连接的window对象
• parent或iframe内部都可以主动建立连接，主动建立连接的一方需要传入domWindow

2.11 connection.sendMsg(msg:any)

• 说明：发送消息
• 参数：msg可以是任意对象
• 注意：发送消息前需要确定在onConnect回调执行以后

示例代码

parent窗口代码，文件名index.html

<iframe id="iframeWindow" src="./inside.html"></iframe>
<script type="text/javascript" src="https://unpkg.com/cic@2.0.10/dist/cic.js"></script>
<script type="text/javascript">
    var connection = window.Cic.createConnection();

    connection.onMessage(function(dataFromIframe) {
        console.log('< parent: dataFromIframe =');
        console.log(dataFromIframe);
        if (dataFromIframe.text === 'world') {
            //console.log('< 外层窗口 主动发起断开连接');
            //connection.disconnect();
        }
    });

    connection.onConnect(function() {
        connection.sendMsg({
            text: 'hello'
        })
    });

    connection.onDisconnect(function() {
        console.log('内部断开链接，可能是内部网址发生变化。');
        
    });

    // 发起连接
    connection.connect(document.getElementById('iframeWindow'));
</script>

iframe窗口代码，文件名inside.html

  <script type="text/javascript" src="https://unpkg.com/cic@2.0.10/dist/cic.js"></script>
  <script type="text/javascript">
  // 用setTimeout故意延迟几秒，等待重试连接
  setTimeout(function() {
    var connection = window.Cic.createConnection();

    connection.onConnect(function() {
      console.log('> 连接已建立');
    });

    connection.onMessage(function(dataFromParent) {
      console.log('> dataFromParent =');
      console.log(dataFromParent);

      if (dataFromParent.text === 'hello') {
        connection.sendMsg({
          text: 'world'
        });
      }
    });

    connection.onDisconnect(function() {
      console.log('> iframe 收到断开链接的请求。然后执行链接销毁功能');
      connection.destroy();
    });
  }, 1000);

  setTimeout(function() {
    location.href = "https://baidu.com";
  }, 3000);
  </script>