Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / JavaScript

window.postMessage — comunicação entre janelas

window.postMessage envia dados de forma assíncrona para uma janela de destino, mesmo entre origens diferentes. Recomenda-se indicar um `targetOrigin` exato; se for omitido, a entrega fica limitada à mesma origem. O destinatário deve verificar a origem do remetente, a janela emissora e a estrutura dos dados.

Versão: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Sintaxe

targetWindow.postMessage(message, targetOrigin[, transfer])
targetWindow.postMessage(message[, { targetOrigin, transfer }])

window.postMessage é uma API do navegador definida pelo HTML Living Standard, não uma funcionalidade de uma edição específica do ECMAScript. Os motores de navegador atuais suportam-na; a presença de Node 24 num repositório não comprova a sua disponibilidade. Chame o método na janela destinatária, por exemplo, iframe.contentWindow ou uma referência a uma janela aberta. O envio de mensagens não dá acesso ao DOM de outra origem.

O destinatário recebe um evento message assíncrono: event.data contém os dados, event.origin contém a origem serializada do remetente no momento do envio e event.source referencia a janela emissora. Uma origem representada por um tuplo é identificada pelo esquema, pelo anfitrião e pela porta, não pelo caminho. Uma origem opaca não tem esse tuplo e é serializada como a cadeia de caracteres "null". Verificar apenas essa cadeia não permite distinguir uma origem opaca de outra. Registe o listener antes de enviar; no caso de uma frame nova, coordene a disponibilidade do destinatário.

Indique um targetOrigin exato. Se não corresponder à origem do destinatário, a mensagem é descartada. Na forma com um objeto de opções, omitir targetOrigin equivale a "/", limitando a entrega à mesma origem. "*" permite qualquer origem — não o utilize para dados confidenciais. Os destinatários devem validar event.origin, event.source e a estrutura dos dados; nunca devem tratar as mensagens como código.

Os dados são serializados através do algoritmo de structured clone, não como JSON. As funções não podem ser clonadas. A lista transfer transfere recursos em vez de os copiar: um ArrayBuffer transferido fica separado do lado do remetente. Dados que não possam ser clonados ou entradas duplicadas na lista de transferência podem causar um DataCloneError. No exemplo, uma iframe isolada numa sandbox envia uma mensagem à janela que a contém através de window.parent.postMessage. Essa janela verifica se event.origin tem o valor "null" e se event.source corresponde à janela da iframe. Em seguida, valida os dados e regista received: 42 na consola.

Exemplos

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Send a message from an iframe</title>
</head>
<body>
  <script>
    const frame = document.createElement('iframe');
    frame.title = 'Message sender';
    frame.hidden = true;
    frame.setAttribute('sandbox', 'allow-scripts');

    // Use the page's exact origin when it has an HTTP(S) origin.
    // The wildcard fallback carries only the fixed, non-sensitive fixture.
    const targetOrigin = /^https?:\/\//.test(window.origin) ? window.origin : '*';

    function receive(event) {
      // The sandboxed sender has an opaque origin, serialized as "null".
      if (event.origin !== 'null' || event.source !== frame.contentWindow) return;
      const data = event.data;
      if (data === null || typeof data !== 'object' || Array.isArray(data)) return;
      if (data.type !== 'cktis-demo' || data.value !== 42) return;

      window.removeEventListener('message', receive);
      console.log(`received: ${data.value}`);
    }

    window.addEventListener('message', receive);
    frame.srcdoc = `<!doctype html>
<html lang="en">
<head><meta charset="utf-8"><title>Message sender</title></head>
<body>
  <script>
    window.parent.postMessage({ type: 'cktis-demo', value: 42 }, ${JSON.stringify(targetOrigin)});
  <\/script>
</body>
</html>`;
    document.body.append(frame);
  </script>
</body>
</html>

Resultado

received: 42

O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.

Fontes