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

CKTIS / JavaScript

Deslocamento e substituição dos filhos de um elemento: scrollTop, scrollHeight e replaceChildren()

Lê e define a posição de deslocamento, distingue a altura total da área de deslocamento da altura interior visível e substitui nós filhos sem interpretar as cadeias como HTML.

Versão: Current web platform; runtime support varies

Sintaxe

const offset = el.scrollTop;
el.scrollTop = y;
const contentHeight = el.scrollHeight;
const visibleHeight = el.clientHeight;
el.replaceChildren();
el.replaceChildren(node, "text");
el.replaceChildren(...items);

scrollTop é o desvio vertical a partir da origem do deslocamento, em píxeis CSS. A propriedade é de leitura e escrita e pode ter um valor fracionário. Uma atribuição pede uma posição absoluta, não um movimento relativo, com o comportamento auto. Com flex-direction: column-reverse, são possíveis valores negativos; o efeito de ressalto no Safari pode levar temporariamente o valor para fora do intervalo habitual.

scrollHeight é a altura inteira, só de leitura, de toda a área de deslocamento, incluindo a parte fora da vista. Inclui o espaçamento interior (padding) e pode incluir pseudoelementos, mas exclui o contorno (border), a margem e a barra de deslocamento horizontal. clientHeight mede a altura interior visível. Se o conteúdo não transbordar na vertical, as alturas são iguais.

Num contentor normal que se desloca para baixo, el.scrollHeight - el.clientHeight aproxima o valor de scrollTop no limite inferior. Verifica esse limite com Math.abs(el.scrollHeight - el.clientHeight - el.scrollTop) <= 1 em vez de ===: as alturas são arredondadas, mas a posição pode ser fracionária. Não uses o teste sem alterações numa disposição invertida nem durante o ressalto.

replaceChildren() substitui todos os nós filhos diretos, não o elemento em si. Aceita qualquer número de objetos Node ou cadeias de caracteres, move os nós existentes em vez de os clonar e transforma as cadeias em nós Text sem interpretar HTML. Sem argumentos, esvazia o elemento. Devolve undefined; uma inserção que viole a hierarquia da árvore pode lançar HierarchyRequestError (uma DOMException).

Substitui primeiro o conteúdo, depois mede a nova disposição e ajusta a posição, pois o intervalo de deslocamento pode mudar. ECMAScript 2024 é a versão de referência da linguagem JavaScript, não uma versão destas API da plataforma Web. A norma DOM define replaceChildren() e CSSOM View define scrollTop, scrollHeight e clientHeight. O suporte depende da versão do navegador; as medições exigem um motor de formatação visual.

Exemplos

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Element scrolling and child replacement</title>
</head>
<body>
<script>
(() => {
  const box = document.createElement('div');
  box.style.cssText = 'width:200px;height:100px;padding:0;border:0;overflow-x:hidden;overflow-y:auto;scroll-behavior:auto';
  box.textContent = 'Old content';
  document.body.append(box);

  try {
    const row = document.createElement('div');
    row.style.height = '160px';
    box.replaceChildren(row);

    const end = box.scrollHeight - box.clientHeight;
    box.scrollTop = end;
    const atBottom = Math.abs(end - box.scrollTop) <= 1;
    console.log(`${box.scrollHeight} ${box.clientHeight} ${atBottom}`);

    box.replaceChildren('<b>Done</b>');
    console.log(`${box.textContent} | ${box.children.length}`);

    box.replaceChildren();
    console.log(box.childNodes.length);
  } finally {
    box.remove();
  }
})();
</script>
</body>
</html>

Resultado

160 100 true
<b>Done</b> | 0
0

Guarda o exemplo num ficheiro HTML, abre-o num navegador e consulta a consola de programador. As alturas 160 e 100 dão um percurso de 60 píxeis CSS. `true` indica que a posição está dentro da tolerância para o limite inferior. As etiquetas aparecem como texto literal e o último `0` indica que não restam nós filhos.

Lições relacionadas

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

Fontes