CKTIS / JavaScript
HTMLIFrameElement: contentWindow e o evento load
HTMLIFrameElement representa uma frame incorporada. A propriedade contentWindow expõe a janela da frame, enquanto load permite reagir quando o carregamento termina. O acesso ao documento depende da política de mesma origem, e load, por si só, não confirma que a obtenção foi bem-sucedida.
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
iframe.contentWindow
iframe.addEventListener("load", handler);
iframe.srcdoc = trustedMarkup;HTMLIFrameElement é a interface DOM de um elemento iframe, não uma funcionalidade da linguagem ECMAScript. «Iframe contentWindow and load» combina o acesso à janela de uma frame com o tratamento do seu carregamento. Esta é uma API do browser; a presença de Node 24 não comprova a sua disponibilidade. A interface principal e contentWindow são amplamente suportadas, mas a compatibilidade das propriedades adicionais deve ser verificada separadamente.
A propriedade só de leitura contentWindow expõe a janela do contexto incorporado através de um WindowProxy. A política de mesma origem restringe o acesso: a leitura de contentWindow.document é permitida numa frame da mesma origem, mas gera uma exceção numa frame de outra origem. Para comunicar entre origens diferentes, utiliza postMessage e verifica, no recetor, os valores esperados de event.origin e event.source.
Regista load na própria frame antes de iniciar o carregamento ou de a anexar ao documento. O evento não propaga para cima e não pode ser cancelado. Não o consideres prova de uma obtenção bem-sucedida: as frames disparam load mesmo quando o carregamento falha e não disparam um error correspondente. A opção { once: true } trata apenas o primeiro evento, não as navegações seguintes.
O exemplo atribui um documento fixo através de srcdoc, lê o respetivo texto depois de load e remove a frame. Sem restrições sandbox, esse documento tem a mesma origem que o elemento pai. srcdoc interpreta HTML: não lhe passes dados não fiáveis. A CSP ou um requisito TrustedHTML podem bloquear o exemplo.
Exemplos
const iframe = document.createElement("iframe");
iframe.title = "Demo";
iframe.addEventListener("load", () => {
const childWindow = iframe.contentWindow;
console.log(childWindow.document.querySelector("p").textContent);
iframe.remove();
}, { once: true });
iframe.srcdoc = '<!doctype html><html lang="en"><title>Demo</title><body><p>Ready</p></body></html>';
document.body.append(iframe);Resultado
Ready
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.