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

CKTIS / JavaScript

Pesquisa por ID, elemento raiz e corpo do documento

Usa `getElementById()` para procurar um elemento por ID, `documentElement` para obter o elemento raiz e `body` para aceder ao corpo HTML do documento. As três operações podem devolver `null` por motivos diferentes.

Versão: ECMAScript 2024 and the current web platform; runtime support varies

Sintaxe

doc.getElementById(id) // id: string; returns Element or null
 doc.documentElement // read-only; returns Element or null
 doc.body // returns HTMLBodyElement, HTMLFrameSetElement, or null
 doc.body = newBody // assigns an HTML body or frameset element

doc.getElementById(id) pesquisa na árvore do documento doc. Passa o valor exato de id sem acrescentar o prefixo #: não é um seletor CSS e a pesquisa distingue maiúsculas de minúsculas. O método devolve um Element correspondente ou null. Os IDs devem ser únicos; se houver duplicados, prevalece o primeiro elemento na ordem da árvore. A pesquisa exclui nós desligados da árvore do documento e não entra nas árvores do Shadow DOM.

doc.documentElement é só de leitura: devolve o elemento raiz (<html> num documento HTML; em XML pode ser outro elemento) ou null se não existir. doc.body devolve o primeiro filho direto de <html> que seja um <body> ou um <frameset> obsoleto, ou null se não houver nenhum. Lê ambas as propriedades sem parênteses.

Ao contrário de documentElement, body permite atribuir um valor para substituir o elemento existente. Os seus filhos não são transferidos para o novo elemento. Atribuir null ou um HTMLElement que não seja <body> nem <frameset> lança HierarchyRequestError. Se o elemento não implementar HTMLElement, como acontece com um elemento SVG, a conversão Web IDL lança um TypeError antes de o setter ser executado. Atribuir um <body> ou um <frameset> válido também lança HierarchyRequestError se o documento não tiver um elemento raiz.

Durante a análise do HTML, o corpo ou o elemento procurado pode ainda não existir. Se o código depender da marcação da página, aguarda por DOMContentLoaded quando document.readyState === "loading"; caso contrário, executa-o de imediato. Confirma que o resultado não é null antes de o usares: ler diretamente uma propriedade de null lança um TypeError. Estas API são definidas pelas normas DOM e HTML, não pelo ECMAScript. A referência ao ECMAScript 2024 não indica se estão disponíveis; nem todos os ambientes JavaScript disponibilizam document.

Exemplos

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Document lookup demo</title>
</head>
<body>
  <script>
    const doc = document.implementation.createHTMLDocument("Demo");
    const panel = doc.createElement("section");
    panel.id = "Panel";

    console.log(doc.documentElement.localName);
    console.log(doc.body.localName);
    console.log(doc.getElementById("Panel"));

    doc.body.appendChild(panel);
    console.log(doc.getElementById("Panel") === panel);
    console.log(doc.getElementById("panel"));
  </script>
</body>
</html>

Resultado

html
body
null
true
null

Guarda o exemplo como ficheiro HTML, abre-o num navegador e consulta a consola de desenvolvimento. O documento HTML separado já contém `html` e `body` e não altera a página que executa o script. `Panel` só é encontrado depois da inserção; `panel` não corresponde devido à diferença entre maiúsculas e minúsculas.

Lições relacionadas

  • JavaScript · Lição 37 · Avançado · Versão: 4

Fontes