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

CKTIS / JavaScript

`length`: a propriedade modificável de um array

Lê `arr.length` para obter o comprimento do array ou atribui-lhe um valor para encurtar o mesmo array ou aumentá-lo sem criar elementos.

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

Sintaxe

arr.length
arr.length = newLength

arr.length é uma propriedade de dados própria de uma instância de Array, não a propriedade length do construtor Array. Inicialmente permite escrita, mas não é enumerável nem configurável. O seu valor é superior a qualquer índice próprio do array e pode exceder o número de elementos presentes.

Reduzir length elimina os elementos próprios cujo índice seja igual ou superior ao novo comprimento. arr.length = 0 esvazia um array normal sem o substituir: a alteração é visível através de todas as referências ao mesmo array. Aumentar o comprimento deixa posições vazias, não elementos com o valor undefined, e não recupera os elementos eliminados. Criar um elemento num índice válido i igual ou superior ao comprimento atual aumenta-o para i + 1.

O comprimento é um inteiro do tipo Number entre 0 e 2 ** 32 - 1, inclusive. Quando length permite escrita, o valor atribuído é convertido: por exemplo, "3" é aceite como 3, mas 2.5, -1 e 2 ** 32 provocam um RangeError. Converter um Symbol ou um BigInt provoca antes um TypeError.

Se, ao encurtar o array, for encontrado um elemento não configurável, a operação para nesse índice. O comprimento passa a ser esse índice mais um, e os elementos de índice superior já eliminados não são repostos. Também é possível impedir permanentemente a escrita em length com writable: false. Isto bloqueia atribuições a length e a adição de elementos que aumentariam o comprimento, mas não impede todas as alterações aos elementos. Em ambos os casos, uma atribuição falhada provoca um TypeError em modo estrito; fora desse modo, não lança uma exceção.

Exemplos

(() => {
  "use strict";
  const arr = ["a", "b", "c"];
  const alias = arr;

  arr.length = 1;
  console.log(`${alias.length}: ${alias.join(",")}`);

  arr.length = 3;
  arr[2] = undefined;
  console.log(`${arr.length}: ${Object.hasOwn(arr, 1)}, ${Object.hasOwn(arr, 2)}`);

  arr[4] = "e";
  console.log(`${arr.length}: ${arr[4]}`);

  try {
    arr.length = 2.5;
  } catch (error) {
    console.log(`${error.name}: ${arr.length}`);
  }
})();

Resultado

1: a
3: false, true
5: e
RangeError: 5

`alias` permite observar o encurtamento do mesmo array. Depois de aumentar o comprimento, `Object.hasOwn` distingue a posição vazia no índice `1` do valor `undefined` atribuído explicitamente ao índice `2`. Escrever no índice `4` aumenta o comprimento para `5`; a rejeição de `2.5` não o altera.

Lições relacionadas

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

Fontes