中文文档
frame-subscriber
Communication between different iframes based on postMessage
Basic usage
There is only one instance of the client bus under an iframe, so initializeClient
always returns the same object
// iframe one
import initializeClient, { subscriber } from "frame-subscriber";
let client = initializeClient();
client.on("say", function (payload) {
console.log("say ", payload.data, payload.from);
});
// iframe two
import initializeClient from "frame-subscriber";
let client = initializeClient();
client.emit("say", "hello");
// iframe one log 'say hello'
Subscribe to events
import initializeClient from "frame-subscriber";
let client = initializeClient();
client.on("some-event", function (payload) {
console.log("some event fired", payload.data);
});
// can only be called once
client.once("some-event", function (payload) {
console.log("only run once", payload.data);
});
/**
* emit all subscribed 'foo' listener
*/
client.emit("foo", "hello");
// chain invoke
client
.once("some-event", handler)
.on("other-event", handler)
.emit("my-emit", "hello");
Specify subscribe
import initializeClient, { subscriber } from "frame-subscriber";
let client = initializeClient();
// Now the subscriber with the namespace cool will only be fired when emit with the same namespace
let sub = subscriber({
namespace: "cool",
// In addition to namespace, there are `origin` and `unique` parameters that can be specified
unique: "very cool",
});
sub.on("test", handler);
// on method can also specify subscription, it's same as above
client.on("test", handler, { namespace: "cool", unique: "very cool" });
// in other frame
// the sub will receive message
otherClient.emit("test", "realy cool", {
namespace: "cool",
unique: "very cool",
});
//the sub nothing will happen
otherClient.emit("foo", "hello", { namespace: "awesome" });
//the sub nothing will happen too
otherClient.emit("test", "realy cool", { namespace: "cool", unique: "cool" });
Advanced usage
Custom handling of client events
import { Events } from "frame-subscriber";
client.on(Events.ORIGIN_RECEIVE, function customHandlerEvent(payload) {
if (["foo", "bar"].include(payload.from.namespace)) {
console.log(payload.data);
}
});
// Events constants and other internal events properties
client
.on(Events.CREATED, handler)
.on(Events.EXPECT_RECEIVE, handler)
.on(Events.DECLINE, handler);
API
Client
initializeClient(options?: ClientOptions): Client
event bus
Type
ClientOptions
ClientOptions {
/**
* Unique ID, you can specify it, otherwise it will be automatically generated
*/
unique?: string
/**
* namespace
*/
namespace?: string
origin?: string
/**
* The default option used by the emit method
*/
emit?: BaseOptions
/**
* Controls whether the client triggers the event when messages received
*/
shouldReceive?: (payload: Payload) => boolean
}
let client = initializeClient({
unique: 'foo',
namespace: 'bar'
})
Method
on<T = any>(type: string, listener: EventHandler<T>, options?: SubscriberOptions): Client
add event listenerTo monitor events, if valid options
is provided, the corresponding Subscriber
will be created internally. It is more recommended to manually create a Subscriber
to monitor the corresponding events, which is more convenient for management
once<T = any>(type: string, listener: EventHandler<T>, options?: SubscriberOptions): Client
Similar to on
, but only listens once
off(type: string, listener?: EventHandler, options?: BaseOptions): Client
remove event listener
emit(type: string, data: any, options?: BaseOptions): Client
trigger event
whenReady(callback: EventHandler): Client
Invoke callback when clients under other frames are created (or already created)
whenReady(unique: string | string[], callback: EventHandler): Client
Invoke when the Client under the specified frame is created (or already created)
send(message: any, targetOrigin?: string)
it's same as postMessage
Subscriber
Client-based subscriber, the subscriber only receives events that provide the specified options on the client, and Subscriber
can only subscribe to some messages forwarded by Client
subscriber(options?: SubscriberOptions): Subscriber
SubscriberOptions {
unique?: string
namespace?: string
origin?: string
}
import { subscriber } from 'frame-subscriber'
let mySubscriber = subscriber({
origin: 'http://example.com'
})
These three parameters are consistent with the role of the client. It should be noted that if the client has specified a certain one, which restricts the subscription of the message, the subscriber will become invalid.
Method
Subscriber
also has on
, once
, off
, offAll
methods, the only difference from Client
is that there is no options
parameter, because Subscriber
already provides
remove
Remove this subscriber from the client and remove all its event listeners