CKTIS / JavaScript
iframe: a propriedade contentWindow e o evento load
`contentWindow` dá acesso a uma referência à janela do iframe. `load` indica o fim de uma tentativa de carregamento, mas não confirma o êxito nem dá acesso ao DOM.
Versão: ECMAScript 2024 and the current web platform; runtime support varies
Sintaxe
const frameWindow = iframe.contentWindow;
iframe.addEventListener("load", handler);
iframe.addEventListener("load", handler, { once: true });iframe.contentWindow é uma propriedade só de leitura. Devolve o WindowProxy do contexto de navegação do iframe ou null se esse contexto ainda não existir, como num iframe acabado de criar, antes de ser inserido. Nas navegações dentro do mesmo contexto, o proxy mantém a sua identidade mesmo quando mudam os objetos Window e Document subjacentes. Ter o proxy não significa que o documento pretendido esteja pronto.
Regista o ouvinte de load no elemento iframe, não na sua janela, antes de o inserir ou de iniciar a navegação que queres observar. Uma navegação posterior pode voltar a desencadear o evento; com { once: true }, o ouvinte é removido imediatamente antes de ser chamado pela primeira vez. load pode ocorrer mesmo quando o carregamento falha, e o elemento não sinaliza essa falha com error. Nenhum dos eventos concede acesso ou confirma que a aplicação incorporada está pronta.
Podes ler iframe.contentWindow.document quando o documento do iframe e a página que o contém têm a mesma origem. Se as origens forem diferentes, a leitura lança SecurityError, mas iframe.contentDocument devolve null. Um sandbox sem allow-same-origin pode atribuir uma origem opaca ao documento. Para comunicar com um iframe cooperante de outra origem conhecida, usa postMessage() com um targetOrigin exato; quem recebe a mensagem deve verificar event.origin, event.source e a estrutura dos dados.
Estas são API da plataforma Web, não funcionalidades do ECMAScript 2024. O exemplo requer um navegador com DOM; o suporte e as políticas de segurança dependem do ambiente.
Exemplos
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>iframe contentWindow and load</title>
</head>
<body>
<script>
(() => {
const iframe = document.createElement("iframe");
console.log(iframe.contentWindow === null);
iframe.srcdoc = "<!doctype html><title>Frame ready</title>";
iframe.addEventListener("load", () => {
console.log(iframe.contentWindow.document.title);
iframe.remove();
}, { once: true });
document.body.append(iframe);
})();
</script>
</body>
</html>Resultado
true Frame ready
Guarda o exemplo num ficheiro HTML, serve-o por HTTP(S) e abre-o num navegador. A página tem de permitir o script incorporado, o iframe e a atribuição a `srcdoc`. Na consola do navegador, é apresentado `true` antes da inserção e `Frame ready` no tratamento de `load`. O código usa uma cadeia `srcdoc` fixa e de confiança, não carrega qualquer documento externo e remove o iframe depois de ler o respetivo título.
Lições relacionadas
- JavaScript · Lição 5 · Avançado · Versão: 4