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

CKTIS / JavaScript

Document.readyState — estado de carregamento do documento

Document.readyState descreve a fase de carregamento do documento: loading, interactive ou complete. Verificar esta propriedade ajuda a inicializar código relacionado com o DOM mesmo quando um script é carregado demasiado tarde para receber DOMContentLoaded.

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

document.readyState

Document.readyState, lido como document.readyState, descreve o estado de carregamento atual do documento. É uma API Web do navegador, não uma funcionalidade da linguagem ECMAScript. A MDN classifica-a como amplamente disponível nos navegadores desde julho de 2015; a versão do Node.js, por si só, não comprova que esta API é suportada.

O valor "loading" significa que o analisador HTML ainda está a trabalhar. Em "interactive", o documento já foi analisado, mas os recursos dependentes podem ainda estar a carregar. O documento chega ao estado "complete" quando termina de carregar e nenhum recurso continua a atrasar o evento load. O evento load é disparado após esta transição. As imagens com loading="lazy" podem ainda não estar carregadas, pois não atrasam esse evento. Uma alteração de estado dispara readystatechange no documento.

O estado "interactive" não significa que DOMContentLoaded já tenha sido disparado: os scripts clássicos com defer e os scripts de módulo que devem ser executados após a análise do documento podem ainda estar à espera de execução. Antes de disparar o evento, o navegador executa esses scripts clássicos e inicia a avaliação desses módulos. Não espera que termine a avaliação de um módulo suspenso por um await de nível superior, nem espera pelos scripts de módulo com async ou pelas imagens. Por isso, o DOM estar pronto não significa que a página esteja totalmente carregada.

O exemplo espera por DOMContentLoaded apenas quando o estado é "loading"; caso contrário, chama init() de imediato. Assim, um script executado tardiamente não fica à espera de um evento que já ocorreu. Este padrão permite aceder ao DOM analisado, mas não garante que outros scripts defer ou de módulo tenham terminado. { once: true } remove o listener após a primeira chamada.

Exemplos

(() => {
  function init() {
    console.log("DOM parsed");
  }

  if (document.readyState === "loading") {
    document.addEventListener("DOMContentLoaded", init, { once: true });
  } else {
    init();
  }
})();

Resultado

DOM parsed

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