Base di conoscenzaCentro esami
ITItaliano
Scegli la lingua13

CKTIS / JavaScript

window.postMessage — comunicazione tra finestre

window.postMessage invia dati in modo asincrono a una finestra di destinazione, anche tra origini diverse. È consigliabile specificare un `targetOrigin` esatto; se lo si omette, la consegna è limitata alla stessa origine. Il destinatario dovrebbe verificare l’origine del mittente, la finestra mittente e la struttura dei dati.

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

Sintassi

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

window.postMessage è un’API del browser definita da HTML Living Standard, non una funzionalità di una particolare edizione di ECMAScript. I motori dei browser attuali la supportano; la presenza di Node 24 in un repository non ne dimostra la disponibilità. Chiama il metodo sulla finestra destinataria, ad esempio iframe.contentWindow o un riferimento a una finestra aperta. L’invio di messaggi non dà accesso al DOM di un’altra origine.

Il destinatario riceve un evento message asincrono: event.data contiene i dati, event.origin contiene l’origine serializzata del mittente al momento dell’invio ed event.source fa riferimento alla finestra mittente. Un’origine rappresentata da una tupla è identificata da schema, host e porta, non dal percorso. Un’origine opaca non ha questa tupla e viene serializzata come stringa "null". Verificare solo questa stringa non permette di distinguere un’origine opaca da un’altra. Registra il listener prima dell’invio; per un nuovo frame, coordina la disponibilità del destinatario.

Specifica un targetOrigin esatto. Se non corrisponde all’origine del destinatario, il messaggio viene scartato. Nella forma con un oggetto di opzioni, omettere targetOrigin equivale a "/" e limita la consegna alla stessa origine. "*" consente qualsiasi origine: non usarlo per dati riservati. I destinatari devono verificare event.origin, event.source e la struttura dei dati; non trattare mai i messaggi come codice.

I dati vengono serializzati con l’algoritmo di structured clone, non come JSON. Le funzioni non possono essere clonate. L’elenco transfer sposta le risorse invece di copiarle: un ArrayBuffer trasferito viene scollegato sul lato mittente. Dati non clonabili o voci duplicate nell’elenco di trasferimento possono causare un DataCloneError. Nell’esempio, un iframe isolato in una sandbox invia un messaggio alla finestra genitore tramite window.parent.postMessage. La finestra genitore verifica che event.origin sia "null" e che event.source corrisponda alla finestra dell’iframe. Poi verifica i dati e scrive received: 42 nella console.

Esempi

<!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>

Risultato

received: 42

Il codice mostrato e il risultato dichiarato sono stati verificati in un ambiente isolato con il metodo registrato nella prova di verifica di questa versione esatta.

Fonti