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

CKTIS / JavaScript

Element — estrutura DOM, geometria e deslocamento

Element representa um elemento DOM, não um nó qualquer. Disponibiliza navegação, atributos e substituição de conteúdo; nos browsers, também permite medir o layout e controlar o deslocamento. Distingue a estrutura da árvore, as dimensões da área do cliente e os retângulos relativos à janela de visualização.

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

element.clientWidth; element.clientHeight; element.clientLeft; element.clientTop; element.scrollHeight; element.scrollTop; element.scrollTop = y; element.getBoundingClientRect(); element.getClientRects(); element.scrollIntoView({ block: "nearest", behavior: "instant" }); element.replaceChildren(...nodesOrStrings); element.children; element.tagName; element.parentElement; element.previousElementSibling; element.nextElementSibling; element.hasAttribute(name); element.toggleAttribute(name, force);

Element representa um elemento DOM. Element.children é uma coleção dinâmica dos filhos diretos que são elementos; exclui texto e comentários. Element.parentElement, Element.previousElementSibling e Element.nextElementSibling devolvem um elemento ou null. Element.tagName fornece o nome qualificado; nos documentos HTML, os nomes dos elementos HTML são escritos em maiúsculas.

Element.hasAttribute(name) verifica se um atributo está presente. Element.toggleAttribute(name, force) força a presença com true e a ausência com false; sem force, alterna o estado. Devolve a presença final. Element.replaceChildren(...nodesOrStrings) substitui todos os filhos; as cadeias de caracteres tornam-se texto, não HTML. Sem argumentos, remove todos os filhos.

Num elemento de bloco típico, Element.clientWidth e Element.clientHeight indicam a largura e a altura interiores, incluindo o preenchimento, mas excluindo os bordos e o espaço ocupado pelas barras de deslocamento. Num span inline comum, ambas as propriedades devolvem 0, mesmo que o elemento tenha preenchimento e conteúdo visível. Em modo de conformidade com as normas, para o elemento raiz devolvem as dimensões da janela de visualização sem as barras de deslocamento, e não as da própria caixa de preenchimento do elemento. Element.clientLeft e Element.clientTop indicam o afastamento da área do cliente em relação à extremidade da moldura; podem incluir uma barra de deslocamento. Element.scrollHeight inclui o conteúdo que ultrapassa verticalmente a área visível. Estas medidas são números inteiros. Element.scrollTop, que pode ser alterado, indica o deslocamento vertical e pode ser fracionário ou negativo em layouts invertidos.

Element.getBoundingClientRect() devolve um retângulo envolvente; Element.getClientRects() devolve os retângulos dos fragmentos, como as várias linhas de um elemento inline. As coordenadas são relativas à janela de visualização e têm em conta as transformações CSS. Element.scrollIntoView({ block: "nearest", behavior: "instant" }) desloca os contentores para mostrar o elemento. Ler propriedades geométricas pode obrigar o browser a calcular o layout; agrupa essas leituras antes de alterar os estilos.

Esta é uma API do ambiente do browser, não de ECMAScript por si só; o Node 24 não comprova a sua disponibilidade. A fonte DOM define a estrutura e os atributos, não os algoritmos de geometria e deslocamento de CSSOM View. Não são indicadas versões mínimas de browsers; verifica os métodos necessários no ambiente de destino. O exemplo evita deliberadamente medir o layout.

Exemplos

(() => {
  const box = document.createElement("div");
  const first = document.createElement("span");
  const last = document.createElement("span");
  box.replaceChildren(first, "text", last);
  box.toggleAttribute("data-ready", true);

  console.log(box.children.length);
  console.log(first.parentElement === box);
  console.log(first.nextElementSibling === last);
  console.log(last.previousElementSibling === first);
  console.log(box.hasAttribute("data-ready"));
  console.log(box.toggleAttribute("data-ready", false));
  box.replaceChildren("done");
  console.log(box.children.length, box.textContent);
})();

Resultado

2
true
true
true
true
false
0 done

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