Array.prototype.unshift()

Метод unshift() экземпляров Array добавляет указанные элементы в начало массива и возвращает новую длину массива.

Попробуйте

const array = [1, 2, 3];

console.log(array.unshift(4, 5));
// Expected output: 5

console.log(array);
// Expected output: Array [4, 5, 1, 2, 3]

Синтаксис

unshift()
unshift(element1)
unshift(element1, element2)
unshift(element1, element2, /* …, */ elementN)

Параметры

element1, …, elementN

Элементы, которые нужно добавить в начало arr.

Возвращаемое значение

Новое свойство length объекта, к которому был применен метод.

Описание

Метод unshift() вставляет заданные значения в начало объекта, похожего на массив.

Array.prototype.push() имеет схожее поведение с unshift(), но применяется к концу массива.

Обратите внимание, что если в качестве параметров передается несколько элементов, они вставляются пакетом в начало объекта, в том же порядке, в котором они были переданы в качестве параметров. Следовательно, вызов unshift() с n аргументами один раз или вызов его n раз с 1 аргументом (например, в цикле) не дает одинаковых результатов.

См. пример:

let arr = [4, 5, 6];

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

arr = [4, 5, 6]; // resetting the array

arr.unshift(1);
arr.unshift(2);
arr.unshift(3);

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

Метод unshift() является универсальным. Он ожидает, что значение this будет иметь свойство length и свойства с целочисленными ключами. Хотя строки также похожи на массивы, этот метод не подходит для их применения, поскольку строки неизменяемы.

Примеры

Использование unshift()

const arr = [1, 2];

arr.unshift(0); // result of the call is 3, which is the new array length
// arr is [0, 1, 2]

arr.unshift(-2, -1); // the new array length is 5
// arr is [-2, -1, 0, 1, 2]

arr.unshift([-4, -3]); // the new array length is 6
// arr is [[-4, -3], -2, -1, 0, 1, 2]

arr.unshift([-7, -6], [-5]); // the new array length is 8
// arr is [ [-7, -6], [-5], [-4, -3], -2, -1, 0, 1, 2 ]

Вызов unshift() для объектов, не являющихся массивами

Метод unshift() считывает свойство length объекта this. Он сдвигает все индексы в диапазоне 0 на length - 1 вправо на количество аргументов (увеличивая их значения на это число). Затем он устанавливает каждый индекс, начиная с 0, значениями аргументов, переданных в unshift(). Наконец, он устанавливает length равным предыдущей длине плюс количество добавленных элементов.

const arrayLike = {
  length: 3,
  unrelated: "foo",
  2: 4,
};
Array.prototype.unshift.call(arrayLike, 1, 2);
console.log(arrayLike);
// { '0': 1, '1': 2, '4': 4, length: 5, unrelated: 'foo' }

const plainObj = {};
// There's no length property, so the length is 0
Array.prototype.unshift.call(plainObj, 1, 2);
console.log(plainObj);
// { '0': 1, '1': 2, length: 2 }

Спецификации

Совместимость с браузерами

См. также

• Polyfill для Array.prototype.unshift в core-js с исправлениями этого метода
• Polyfill Array.prototype.unshift из es-shims
• Руководство по индексированным коллекциям
• Array
• Array.prototype.push()
• Array.prototype.pop()
• Array.prototype.shift()
• Array.prototype.concat()
• Array.prototype.splice()