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

CKTIS / JavaScript

Diferença entre `document.body` e `document.documentElement`

Usa `document.body` para aceder ao elemento que contém o conteúdo da página e `document.documentElement` para aceder ao elemento raiz do documento. Ambas as propriedades podem devolver `null`.

Versão: Current web platform; runtime support varies

Sintaxe

document.body
 document.documentElement
 document.body = newBody

document.documentElement devolve o elemento raiz do documento, ou null se não existir. Numa página HTML normal, é <html>; num documento XML, a raiz pode ter outro nome. A propriedade é só de leitura, mas podes alterar o elemento devolvido, por exemplo, definindo o seu atributo lang.

document.body devolve o primeiro filho direto da raiz <html> que seja um <body> ou um <frameset> obsoleto. Os três nomes referem-se a elementos do espaço de nomes HTML. Se não houver um filho correspondente ou se a raiz não for um elemento HTML <html>, devolve null. Numa página HTML normal, adiciona conteúdo a <body>, não diretamente a <html>.

Atribuir um novo elemento a document.body substitui o corpo existente e a respetiva subárvore em vez de lhe acrescentar conteúdo. Se não houver corpo, o setter acrescenta o elemento fornecido à raiz. Atribuir null ou um elemento que não seja um <body> ou <frameset> de HTML, ou tentar inserir um elemento sem que exista uma raiz, lança uma DOMException chamada HierarchyRequestError.

A norma HTML define document.body e a norma DOM define document.documentElement. Nenhuma destas propriedades faz parte do ECMAScript 2024. Um ambiente de execução sem um DOM de página pode não disponibilizar o objeto global document. Durante a análise do HTML, um script pode ver a raiz antes de <body> ser criado. Verifica se o resultado não é null antes de o utilizares; numa página normal, podes esperar pelo evento DOMContentLoaded se a análise ainda estiver a decorrer.

Exemplos

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Document body and root</title>
</head>
<body>
  <script>
    {
      const doc = document.implementation.createHTMLDocument();
      const root = doc.documentElement;
      const body = doc.body;

      console.log(`${root.localName} > ${body.localName}`);
      console.log(body.parentElement === root);

      body.remove();
      console.log(doc.body === null);
      console.log(doc.documentElement === root);
    }
  </script>
</body>
</html>

Resultado

html > body
true
true
true

Guarda o exemplo como ficheiro HTML, abre-o num navegador e consulta a consola. O código cria um documento HTML separado, mostra os nomes dos elementos e verifica a relação entre pai e filho. Depois de remover `<body>`, `doc.body` devolve `null` e a raiz continua a ser o mesmo objeto. A página aberta não é alterada.

Lições relacionadas

  • JavaScript · Lição 32 · Intermédio · Versão: 3

Fontes