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

CKTIS / JavaScript

HTMLCollection.length — número de elementos numa coleção

HTMLCollection.length devolve o número atual de elementos numa coleção DOM. É uma propriedade só de leitura e o seu valor é atualizado automaticamente quando o conteúdo da coleção dinâmica muda.

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

collection.length

HTMLCollection.length é uma propriedade só de leitura que devolve um número inteiro não negativo: o número de elementos na coleção. Leia-a como collection.length, sem parênteses de chamada. Uma coleção vazia tem comprimento 0. Os índices começam em 0, pelo que o último índice de uma coleção não vazia é collection.length - 1.

Uma HTMLCollection é dinâmica: as alterações no DOM que afetam o seu conteúdo atualizam automaticamente a coleção e a sua propriedade length. No exemplo, container.children inclui apenas os filhos diretos que são elementos. Adicionar um nó de texto não aumenta a contagem, mas adicionar um elemento aumenta. A mesma referência items também reflete a remoção posterior do elemento.

Não trate uma HTMLCollection como um array: atribuir um valor a length não é uma forma de a encurtar. Altere antes os elementos DOM relevantes. A remoção de elementos durante uma iteração pode deslocar os índices e fazer com que algumas entradas sejam ignoradas. Se planear essas alterações, percorra uma cópia criada com Array.from(collection).

Esta é uma API do DOM dos navegadores, não uma funcionalidade de uma edição específica do ECMAScript. A MDN indica que esta propriedade está amplamente disponível nos navegadores desde julho de 2015. A presença de Node 24 num repositório não comprova a disponibilidade do DOM nem o suporte desta API nos navegadores.

Exemplos

(() => {
  const container = document.createElement("div");
  const items = container.children;

  console.log(items.length);
  container.appendChild(document.createTextNode("text"));
  console.log(items.length);
  const child = document.createElement("span");
  container.appendChild(child);
  console.log(items.length);
  container.removeChild(child);
  console.log(items.length);
})();

Resultado

0
0
1
0

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