Methods
offPostMessage(target, originopt, nullable, messageTypeopt, nullable, handleropt, nullable, tryNativeRemovalopt, nullable)
Unregister (an) event handler(s) for (a) post message(s) on a valid target, like a window or an iframe.
Similar to off, this function can handle rather unspecific cases as well as very specific definitions.
Just setting the target, removes all registrations for that target. Setting an origin and/or a messageType
additionally, only removes handlers, that were registered explicitly for these values. Adding a handler only
removes that specific handler (without origin and/or messageType, the handler is removed everywhere).
Putting the origin parameter at the second place, is deliberate by design, to force everyone to really think about,
what to use here. Usually, most people, just throw in the "*" wildcard, paying no attention to the security
implications, when setting a post message handler. Since we force this on onPostMessage, we keep the signature
here as well, just making everything except target optional.
If you try to remove event handlers not previously created with onPostMessage (and therefore there are no fitting
target entries in the POST_MESSAGE_MAP), the function will fall back to native removeEventListener
(if tryNativeRemoval is true), but in that case, a handler has to be defined and the return value will not
increment, since we do not know if the removal really worked.
Parameters:
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
target |
Window | HTMLIFrameElement | window/iframe to remove handler(s) from (iframes are automatically resolved to the contentWindow) |
||
origin |
String |
<optional> <nullable> |
null | the origin the received post message has to have, for the handler to get executed (defaults to "*", if receiving a nullish value) |
messageType |
String |
<optional> <nullable> |
null | the type/name the post message has to have, for the handler to get executed (will be checked using the key "type" in the message's payload) |
handler |
function |
<optional> <nullable> |
null | the handler to execute, if a post message, matching all conditions, is received |
tryNativeRemoval |
Boolean |
<optional> <nullable> |
true | if a target is not part of the POST_MESSAGE_MAP native removeEventListener is used as a fallback if this is true (handler needs to be set in that case) |
- Source:
- See:
Throws:
error if target is not usable
Returns:
Example
const offCount = offPostMessage(window, 'https://foobar.com:80/', 'foobar-message');
offPostMessage(window, null, null, specialHandlerFunction);