easy-iframe

1. 介绍

iframe信息交互开发包

2. 更新日志

2025-08-12 v1.1.0 服务端注册路由响应函数支持参数校验

2025-08-08 v1.0.2 更新readme中客户端初始化方法

2025-08-08 v1.0.1 修复外部页面无法将键盘操作传入iframe的问题

2025-08-07 v1.0.0 初始化开发包

3. 安装教程

yarn add @xhymf1992/easy-iframe 或 npm i @xhymf1992/easy-iframe

4. 使用说明

4.1 iframe嵌入的页面端

4.1.1 初始化

先在项目的起始位置（如vue工程的main.js）导入工具包，并初始化服务端类

{
    import { WndMsgServer } from '@xhymf1992/easy-iframe'

    window.wndMsgServer = new WndMsgServer({
        MESSAGE_TYPE_REQUEST: "REQUEST", // iframe系统能识别的外部消息类型，可选，默认为 REQUEST，建议自定义类型，以便区分其他系统
        MESSAGE_TYPE_RESPONSE: "RESPONSE", // iframe系统完成外部消息后的返回消息类型，可选，默认为 RESPONSE，建议自定义类型，以便区分其他系统
        MESSAGE_TYPE_BROADCAST: "BROADCAST" // iframe系统自发向外部系统发送的消息类型，可选，默认为 BROADCAST，建议自定义类型，以便区分其他系统
    });
}

4.1.2 主动发送消息

WndMsgServer提供了主动发送消息函数send，其定义如下

{
    /**
     * 主动对外发送消息
     * @param path 消息路由
     * @param data 消息数据，JSON格式
     */
    send(path: string, data: object)
}

可用于在合适的位置向外部系统分发消息，下面提供了2个案例

{
    // demo1: iframe页面加载完成时，向外部系统发送消息
    // /xxx/loaded 表示消息路由，类似于后端的url，用来定位消息
    // {loaded: true} 表示发送的数据，可自定义
    window.addEventListener("load", () => {
        window.wndMsgServer.send("/xxx/loaded", {loaded: true});
    })

    // demo2: iframe页面向外部发送坐标
    window.wndMsgServer.send("/function/pick/pisition", {x: 1.0, y: 1.0, z: 1.0});
}

4.1.3 被动响应消息

WndMsgServer提供了被动发送消息函数addRouter，类似于后端的router，WndMsgServer支持定义路径函数，其定义如下

{
    /**
     * 添加路由，用于被动接收请求并返回结果
     * @param path 路由路径
     * @param func 路由响应函数
     * @param validation 路由响应函数的参数校验，可选，默认为空
     */
    addRouter(path: string, func: Function, validation: {[key:string]: ParamModel} | undefined = undefined)

    
}

其中validation为路由响应函数的参数校验规则，支持校验参数的类型、默认值和是否必须。当该参数被设置后，系统会在回调函数执行前对传入的参数进行校验，如果不符合设定，如参数类型不符、缺少必须的字段，系统会统一返回字段校验错误，回调函数将不会执行，此功能可简化回调函数的实现，减少参数校验

validation的结构为对象，键为字段名称，值为参数校验规则，其数据结构如下

// 参数校验模型
ParamModel {
    /**
     * 参数数据类型："boolean", "number", "string", "array", "object", 必填
     */
    type: string

    /**
     * 参数默认值，可选
     */
    default?: boolean | number | string | object

    /**
     * 参数是否必须，必填
     */
    required: boolean
}

可用于在合适的位置注册路径函数，用来响应外部的请求，下面提供1个案例

{
    // demo: 接收到 /api/user/query 的路由时，返回指定的用户信息
    // /api/user/query 表示消息路由，类似于后端的url，用来定位消息
    // data 表示请求附带的参数，类似于后端post的参数
    let fakeDB = {
        1: {
            name: "张三",
            age: 18
        },
        2: {
            name: "李四",
            age: 20
        }
    };
    window.wndMsgServer.addRouter(
        "/api/user/query", 
        (data) => {
            // 由于加了参数校验，此处无需再判断，可直接使用参数进行处理
            if(data.id in fakeDB) {
                return fakeDB[data.id]; // 返回消息可被外部系统接收
            }
        },
        {
            id: {
                type: "number",
                required: true
            } // 用户id，数据类型为数字，必填，无默认值
        } // 定义响应函数的参数
    )
}

4.2 使用iframe的页面端

4.2.1 初始化

先在包含iframe的页面中导入工具包，并在页面DOM挂载完成后初始化客户端类

{
    import { onMounted } from 'vue';
    import { WndMsgClient } from '@xhymf1992/easy-iframe'

    // 在iframe元素挂载后进行客户端初始化
    onMounted(() => {
        window.wndMsgClient = new WndMsgClient({
            id: "iframe", // iframe元素的id，必填
            targetOrigin: "*", // iframe src的源，可选，默认为"*"
            MESSAGE_TYPE_REQUEST: "REQUEST", // iframe系统能识别的外部消息类型，必须与服务端    的设置一致，否则无法通信，可选，默认为 REQUEST
            MESSAGE_TYPE_RESPONSE: "RESPONSE", // iframe系统完成外部消息后的返回消息类型，必    须与服务端的设置一致，否则无法通信，可选，默认为 RESPONSE
            MESSAGE_TYPE_BROADCAST: "BROADCAST" // iframe系统自发向外部系统发送的消息类型，    必须与服务端的设置一致，否则无法通信，可选，默认为 BROADCAST
        });
    })
    
}

4.2.2 被动接收消息

WndMsgClient提供了被动接收iframe主动发送的消息的函数addRouter，其定义如下

{
    /**
     * 添加路由，用于被动接收请求
     * @param path 路由路径
     * @param func 路由响应函数
     */
    addRouter(path: string, func: Function)
}

可用于在合适的位置接收iframe的消息，并进行自定义处理，下面提供1个案例

{
    // demo: 外部系统接收iframe发送过来的坐标
    // /function/pick/position 表示消息路由，类似于后端的url，用来定位消息，由服务端定义
    // data 表示跟路由一起传过来的数据，结构由服务端定义
    window.wndMsgClient.addRouter("/function/pick/position", (data) => {
        console.log(data); // 此处与4.1.2节呼应，接收到的data为{x: 1.0, y: 1.0, z: 1.0}

        // TODO: 对接收到的坐标做后续的自定义处理
    })
}

4.2.3 主动发送消息

WndMsgClient提供了主动发送消息的函数send，其定义如下

{
    /**
     * 向iframe发送消息
     * @param router 消息路由
     * @param data 消息数据，JSON格式
     * @param callbackFunc 消息完成后的回调函数，可选，默认为空
     * @returns 
     */
    send(router: string, data: object, callbackFunc: undefined | Function = undefined)
}

可用于在合适的位置向iframe发送消息，并对返回值进行自定义处理，下面提供1个案例

{
    // demo: 向iframe发送请求，查询id为1的用户的信息
    // /api/user/query 表示消息路由，类似于后端的url，用来定位消息，由服务端定义
    // { id: 1 } 表示跟路由一起传给iframe的参数，结构由服务端定义
    // res 表示服务端处理完消息后的返回数据体
    window.wndMsgClient.send("/api/user/query", { id: 1 }, async (res) => {
        console.log(res); // 此处与4.1.3节呼应，接收到的 res 为 {name: "张三", age: 18}

        // TODO: 对查询到的用户信息做后续的自定义处理
    })
}