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

CKTIS / JavaScript

Array.prototype.unshift: adicionar no início

unshift desloca índices existentes para a direita, insere os argumentos no início e devolve o novo comprimento do recetor.

Versão: ECMAScript 1 onward; example target: Node.js 24.22.2

Sintaxe

array.unshift(...items)

array.unshift(...items) altera array: desloca propriedades indexadas para índices superiores pelo número de argumentos, escreve items desde o índice zero e atualiza length. Devolve o novo comprimento; os argumentos mantêm a ordem, portanto unshift("a", "b") coloca a antes de b. Sem argumentos, o comprimento mantém-se.

Os espaços vazios são preservados durante o deslocamento: uma propriedade de origem ausente faz eliminar a propriedade de destino correspondente. O método é genérico para objetos array-like mutáveis e não cria um array de resultado.

Se o novo comprimento excedesse 2^53 - 1, lança TypeError; os Arrays normais têm outro limite de comprimento. Índices ou length não graváveis, propriedades não elimináveis e erros de getters, setters ou traps de proxy podem interromper a operação depois de alterações parciais. A API existe desde o ECMAScript 1.

Exemplos

const queue = ["test", "deploy"];
const length = queue.unshift("lint", "build");
console.log(length, queue.join(","));

const sparse = [, "b"];
const sparseLength = sparse.unshift("a");
console.log(sparseLength, 0 in sparse, 1 in sparse, 2 in sparse, sparse[0], sparse[2]);

const arrayLike = { 1: "second", length: 2 };
const result = Array.prototype.unshift.call(arrayLike, "first");
console.log(result, arrayLike.length, arrayLike[0], 1 in arrayLike, arrayLike[2]);

Resultado

4 lint,build,test,deploy
3 true false true a b
3 3 first false second

Fontes