Array.prototype.push()

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

Resumo

O método push() adiciona um ou mais elementos ao final de um array e retorna o novo comprimento desse array.

js
var numeros = [1, 2, 3];
numeros.push(4);

console.log(numeros); // [1, 2, 3, 4]

numeros.push(5, 6, 7);

console.log(numeros); // [1, 2, 3, 4, 5, 6, 7]

Sintaxe

js
arr.push(elemento1, ..., elementoN)

Parâmetros

elementoN

Os elementos a serem incluídos ao final do array.

Retorno

O novo valor da propriedade length do objeto no qual o método foi chamado.

Descrição

O método push adiciona valores a um array.

Esse método é intencionalmente genérico. Podendo ser utilizado por call() ou apply() em objetos que implementam arrays. O método push depende da propriedade length para determinar onde começar a inserir os valores. Caso a propriedade length não possa ser convertida em número, é utilizado 0 como índice. Isto inclui a possibilidade de length não existir, nesse caso, essa propriedade será criada.

Os únicos objetos que implementam nativamente array são as strings, porém elas não são adequadas para a aplicação desse método, pois são imutáveis.

Exemplos

Exemplo: Adicionando elementos a um array

O seguinte código cria um array esportes que contém dois elementos. Então adiciona dois elementos a ele. A variável total contém o novo comprimento do array.

js
var esportes = ["futebol", "beisebol"];
var total = esportes.push("handebol", "natacao");

console.log(esportes); // ['futebol, 'beisebol', 'handebol', 'natacao']
console.log(total); // 4

Exemplo: Fusão de dois arrays

Este exemplo utiliza apply() para adicionar todos os elementos de um segundo array.

js
var vegetais = ["cenoura", "batata"];
var maisVegetais = ["aipo", "beterraba"];

// Adiciona o segundo array no primeiro
// Equivalente a vegetais.push('aipo', 'beterraba');
Array.prototype.push.apply(vegetais, maisVegetais);

console.log(vegetais); // ['cenoura', 'batata', 'aipo', 'beterraba']

Exemplo: Utilizando um object como um array-like

Como mencionado acima, push é intencionalmente genérico, e podemos usar isso para nossa vantagem. Array.prototype.push pode trabalhar em um objeto muito bem, como mostra este exemplo. Observe que não criamos um array para armazenar uma coleção de objetos. Em vez disso, armazenamos a coleção no objeto em si e usamos a chamada em Array.prototype.push para enganar o método e pensar que estamos lidando com um array, e ele simplesmente funciona, graças à forma como o JavaScript nos permite estabelecer o contexto de execução quando queremos.

js
var obj = {
  length: 0,

  addElem: function addElem(elem) {
    // obj.length é automaticamente incrementado
    // toda vez que um elemento for adicionado.
    [].push.call(this, elem);
  },
};

// Vamos adicionar alguns objetos vazios apenas para ilustrar.
obj.addElem({});
obj.addElem({});
console.log(obj.length);
// → 2

Observe que, embora obj não seja um array, o método push aumentou com sucesso a propriedade de comprimento (length) do obj como se estivéssemos lidando com um array.

Especificações

Specification
ECMAScript Language Specification
# sec-array.prototype.push

Compatibilidade em navegadores

BCD tables only load in the browser

Veja também