Array.prototype.unshift()

Метод unshift() (відсунути) примірників Array додає передані елементи на початок масиву та повертає нову довжину масиву.

Спробуйте його в дії

Синтаксис

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

Параметри

element1, …, elementN

Елементи, які потрібно додати на початок масиву.

Повернене значення

Нова властивість 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]; // скидання масиву

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); // результатом виклику є 3, що є новою довжиною масиву
// arr is [0, 1, 2]

arr.unshift(-2, -1); // довжина нового масиву дорівнює 5
// arr is [-2, -1, 0, 1, 2]

arr.unshift([-4, -3]); // довжина нового масиву дорівнює 6
// arr is [[-4, -3], -2, -1, 0, 1, 2]

arr.unshift([-7, -6], [-5]); // довжина нового масиву дорівнює 8
// arr is [ [-7, -6], [-5], [-4, -3], -2, -1, 0, 1, 2 ]

Виклик unshift() на об'єктах-немасивах

Метод unshift() зчитує з this властивість length. Він зсуває всі індекси в діапазоні від 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 = {};
// Немає властивості length, тому довжина дорівнює 0
Array.prototype.unshift.call(plainObj, 1, 2);
console.log(plainObj);
// { '0': 1, '1': 2, length: 2 }

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

Сумісність із браузерами

desktop mobile server
Chrome Edge Firefox Internet Explorer Opera Safari WebView Android Chrome Android Firefox for Android Opera Android Safari on iOS Samsung Internet Deno Node.js
unshift
Chrome Full support 1
Edge Full support 12
Firefox Full support 1
Internet Explorer Full support 5.5
Opera Full support 4
Safari Full support 1
WebView Android Full support 1
Chrome Android Full support 18
Firefox for Android Full support 4
Opera Android Full support 10.1
Safari on iOS Full support 1
Samsung Internet Full support 1.0
Deno Full support 1.0
Node.js Full support 0.10.0

Дивіться також