Skip to content
Provide some powerful & helpful functions for Two-way communication with postMessage
TypeScript JavaScript
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
dist
npm
src
.editorconfig
.gitignore
README.md
package.json
rollup.config.js
tsconfig.json

README.md

pmer

提供一些便捷的使用 postMessage 的一些辅助方法

安装

$ npm install pmer --save

背景

postMessage的使用本身已经非常简单了,但是实际应用中,由于postMessageaddEventListener('message')的强解耦,导致消息的 变得非常离散。

通过本项目提供的一些方法,可以更加简单的控制消息的监听与发送。

你可以发送消息,并监听是否收到回复;也可以主动监听指定的type消息,并且回复该消息。

使用

pmer目前提供了以下几个方法供使用:

postMessage

向目标窗口发送消息,返回一个 promise 对象。你可以通过该 promise 对象来判断是否成功发送了消息,并且如果目标窗口如果回复了该消息,你还可以通过 promise 回调收到传回来的数据。

/**
 * 发送消息
 * @param {Window} target 目标窗口, window.opener/window.parent/HTMLIFrameElement.contentWindow...
 * @param {string} type 消息类型
 * @param {any} payload 消息体
 * @param {string} 可选,targetOrigin
 * @param {Transferable[]} 可选,transfer
 *
 * @return {Promise<any>} 返回promise,如果有收到回复消息,将会触发promose回调
 */
export declare function postMessage(
    target: Window,
    type: string,
    payload?: any,
    targetOrigin?: string,
    transfer?: Transferable[]
): Promise<any>;

// 给父级窗口发送 DELETE_USER 消息
postMessage(window.parent, 'DELETE_USER', 123);

// 如果父级窗口有回复该消息,则可以通过promise监听结果
postMessage(window.parent, 'DELETE_USER', 123).then(() => console.log('delete succeed!'));

addListener

监听当前窗口接受到的消息(只支持通过postMessage发送的消息),并且可以回复该消息

/**
 * 添加消息监听
 * @param {string|Array} msgTypes 要监听的消息类型,*表示任何消息
 * @param {Function} listener 监听方法
 * @param {Function} filter 可选,消息过滤,可以通过该方法过滤不符合要求的消息
 *
 * @return {function} 返回移除监听的方法
 */
export declare function addListener(msgTypes: ListenerTypes, listener: LisenterCall, id?: number): RemoveListener;

// 监听 DELETE_USER 消息
addListener('DELETE_USER', payload => {
    console.log('message:', payload);
});

// 通过return一个值,可以回复该消息
addListener('DELETE_USER', payload => {
    return 'delete succeed!';
});

// 你也可以返回一个promise对象(这里使用async/await语法):
// postMessage(window, 'DELETE_USER', 123)
//      .then(() => console.log('删除成功'), () => console.log('删除失败'))
addListener('DELETE_USER', async userId => {
    await fetch('/delete/user/' + userId);
});

// addListener调用后会返回一个清理函数,可以通过该函数随时移除当前的消息监听
const removeListener = addListener('DELETE_USER', () => {});
removeListener();

// 可以通过第三个filter参数过滤一些不符合的消息,例如只接收来自指定域的消息
addListener(
    'DELETE_USER',
    payload => {
        console.log(payload);
    },
    event => event.origin === 'https://valid.domain.com'
);
// 上面等同于,但是区别是当使用addListanerOnce时,通过第三个参数可以避免收到错误的消息后监听器被移除
addListener('DELETE_USER', (payload, event) => {
    if (event.origin === 'https://valid.domain.com') {
        console.og(payload);
    }
});

addListenerOnce

用法完全同addListener,唯一区别是当调用过一次后,会自动移除监听

/**
 * 添加单次消息监听
 * @param {string|Array} msgTypes 要监听的消息类型,*表示任何消息
 * @param {Function} listener 监听方法
 * @param {Function} filter 可选,消息过滤,可以通过该方法过滤不符合要求的消息
 *
 * @return {function} 返回移除监听的方法
 */
export declare function addListenerOnce(msgTypes: ListenerTypes, listener: LisenterCall, id?: number): RemoveListener;
You can’t perform that action at this time.