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

CKTIS / JavaScript

Comprimento do array: Array.length

A propriedade length indica o comprimento de um array, mas não necessariamente o número de elementos existentes. Atribuir-lhe um valor pode eliminar elementos ou aumentar o comprimento sem preencher as novas posições.

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

array.length
array.length = newLength

Array.length designa aqui a propriedade length de uma instância de array, lida como array.length, e não a propriedade do construtor Array. É uma propriedade, não um método. O seu valor é um número inteiro entre 0 e 2 ** 32 - 1, inclusive.

O comprimento não conta os elementos existentes: um array pode conter posições vazias. Se uma atribuição criar um elemento num índice do array igual ou superior ao comprimento atual, length aumenta para esse índice mais um. Se length tiver sido definida como não gravável, essa atribuição não adiciona o elemento nem aumenta o comprimento do array: em modo estrito, lança um TypeError; fora desse modo, falha silenciosamente. delete array[i] remove o elemento se este for uma propriedade própria e configurável do array, mas não reduz o comprimento. Se a propriedade própria nesse índice não for configurável, não é removida: delete devolve false fora do modo estrito e lança um TypeError em modo estrito.

Atribuir um comprimento menor elimina os elementos próprios cujos índices sejam superiores ou iguais ao novo comprimento. Aumentar o comprimento não cria elementos com o valor undefined; deixa posições vazias. No exemplo, escrever no índice 4 define o comprimento como 5, e reduzi-lo depois para 2 elimina esse elemento.

Se uma atribuição a array.length chegar à validação do novo comprimento, um número negativo, uma fração não inteira, NaN, Infinity ou 2 ** 32 provoca um RangeError. Se length não for gravável, a atribuição é rejeitada sem validar o novo comprimento: em modo estrito, lança um TypeError; fora desse modo, falha silenciosamente. Inicialmente, length é gravável, não enumerável e não configurável. Um elemento não configurável pode impedir o truncamento: o comprimento fica no índice desse elemento mais um. Em modo estrito, essa atribuição lança um TypeError, e os elementos com índices superiores podem já ter sido eliminados.

Exemplos

const items = [10, 20];
items[4] = 50;
console.log(items.length);
console.log(Object.hasOwn(items, 2));
items.length = 2;
console.log(JSON.stringify(items));
items.length = 4;
console.log(items.length);
console.log(Object.hasOwn(items, 2));

Resultado

5
false
[10,20]
4
false

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