Array.prototype.splice()

Метод splice() (зростити) примірників Array змінює вміст масиву шляхом видалення чи заміни наявних елементів або додавання нових на місці.

Щоб створити новий масив, в якому частина видалена чи замінена, не змінюючи вихідний масив, слід скористатися toSpliced(). Щоб отримати доступ до частини масиву без його зміни, дивіться slice().

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

Синтаксис

splice(start)
splice(start, deleteCount)
splice(start, deleteCount, item1)
splice(start, deleteCount, item1, item2)
splice(start, deleteCount, item1, item2, /* …, */ itemN)

Параметри

start (початок)

Індекс, за яким почнуться зміни в масиві, перетворений на ціле число.

• Від'ємний індекс рахується від кінця масиву: якщо -array.length <= start < 0, використовується start + array.length.
• Якщо start < -array.length, використовується 0.
• Якщо start >= array.length, то жодний елемент не буде видалено, але метод спрацює як функція додавання, додаючи передані елементи.
• Якщо start пропущено (і splice() викликано без аргументів), то нічого не видаляється. Це відрізняється від передачі значення undefined, яке перетворюється на 0.

deleteCount (кількість до видалення) Необов'язкове

Ціле число, що вказує, яку кількість елементів видалити, починаючи від start.

Якщо deleteCount опущено, або ж якщо його значення більше або рівне числу елементів, що стоять після позиції, заданої start, то всі елементи від start до кінця масиву будуть видалені. Проте якщо є потреба передати параметр чи параметри itemN, то слід за deleteCount передати Infinity – для видалення всіх елементів після start, тому що явне значення undefined перетворюється на 0.

Якщо deleteCount — 0 або від'ємне число, жоден елемент не видалиться. В цьому випадку необхідно вказати принаймні один новий елемент (див. далі).

item1, …, itemN Необов'язкове

Елементи, які буде додано до масиву, починаючи з індексу start. Якщо не вказано жодного, splice() лише видалить елементи з масиву.

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

Масив, що містить всі видалені елементи.

Якщо видалено лише один елемент, буде повернено масив з одного елемента.

Якщо жодного елементу видалено не було, буде повернено порожній масив.

Опис

Метод splice() – це змінювальний метод. Він може змінити вміст this. Якщо кількість наданих для вставки елементів відрізняється від кількості елементів, які видаляються, властивість length масиву зміниться також. Крім того, він використовує Symbol.species для створення нового примірника масиву, що повертається.

Якщо видалена частка є розрідженою, то повернений splice() масив також буде розрідженим, і відповідні індекси будуть порожніми комірками.

Метод splice() є узагальненим. Він лишень очікує, що значення this матиме властивість length, а також властивості з цілочисловими ключами. Попри те, що рядки також є масивоподібними, цей метод не підходить для застосування до них, адже рядки є незмінними значеннями.

Приклади

Вилучити 0 (нуль) елементів перед індексом 2 та вставити "drum"

const myFish = ["янгол", "клоун", "мандаринка", "осетер"];
const removed = myFish.splice(2, 0, "горбань");

// myFish має ["янгол", "клоун", "горбань", "мандаринка", "осетер"]
// removed має [], жодного елементу видалено не було

Вилучити 0 (нуль) елементів перед індексом 2 та вставити "drum" і "guitar"

const myFish = ["янгол", "клоун", "мандаринка", "осетер"];
const removed = myFish.splice(2, 0, "горбань", "рохля");

// myFish має ["янгол", "клоун", "горбань", "рохля", "мандаринка", "осетер"]
// removed має [], жодного елементу видалено не було

Вилучити 0 (нуль) елементів за індексом 0, і вставити "янгол"

Виклик splice(0, 0, ...elements) вставляє елементи на початку масиву, як unshift().

const myFish = ["клоун", "мандаринка", "осетер"];
const removed = myFish.splice(0, 0, "янгол");

// myFish має ["янгол", "клоун", "мандаринка", "осетер"]
// жодні елементи не вилучені

Вилучити 0 (нуль) елементів за останнім індексом, і вставити "осетер"

Виклик splice(array.length, 0, ...elements) вставляє елементи в кінець масиву, як push().

const myFish = ["янгол", "клоун", "мандаринка"];
const removed = myFish.splice(myFish.length, 0, "осетер");

// myFish is ["янгол", "клоун", "мандаринка", "осетер"]
// жодні елементи не вилучені

Вилучити 1 елемент з індексом 3

const myFish = ["янгол", "клоун", "горбань", "мандаринка", "осетер"];
const removed = myFish.splice(3, 1);

// myFish має ["янгол", "клоун", "горбань", "осетер"]
// removed має ["мандаринка"]

Вилучити 1 елемент з індексом 2 та вставити "trumpet"

const myFish = ["янгол", "клоун", "горбань", "осетер"];
const removed = myFish.splice(2, 1, "флейта");

// myFish має ["янгол", "клоун", "флейта", "осетер"]
// removed має ["горбань"]

Вилучити 2 елементи, починаючи з індексу 0, та вставити "parrot", "anemone" і "blue"

const myFish = ["янгол", "клоун", "флейта", "осетер"];
const removed = myFish.splice(0, 2, "папуга", "анемонова", "луфар");

// myFish має ["папуга", "анемонова", "луфар", "флейта", "осетер"]
// removed має ["янгол", "клоун"]

Вилучити 2 елементи, починаючи з індексу 2

const myFish = ["папуга", "анемонова", "луфар", "флейта", "осетер"];
const removed = myFish.splice(2, 2);

// myFish має ["папуга", "анемонова", "осетер"]
// removed має ["луфар", "флейта"]

Вилучити 1 елемент з індексом -2

const myFish = ["янгол", "клоун", "мандаринка", "осетер"];
const removed = myFish.splice(-2, 1);

// myFish має ["янгол", "клоун", "осетер"]
// removed має ["мандаринка"]

Вилучити всі елементи, починаючи з індексу 2

const myFish = ["янгол", "клоун", "мандаринка", "осетер"];
const removed = myFish.splice(2);

// myFish має ["янгол", "клоун"]
// removed має ["мандаринка", "осетер"]

Використання splice() на розріджених масивах

Метод splice() зберігає розрідженість масиву.

const arr = [1, , 3, 4, , 6];
console.log(arr.splice(1, 2)); // [порожньо, 3]
console.log(arr); // [1, 4, порожньо, 6]

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

Метод splice() зчитує з this властивість length. Потім, за потреби, оновлює цілочислові властивості та властивість length.

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

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

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

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

• Посібник Колекції з індексами
• Array
• Array.prototype.concat()
• Array.prototype.push()
• Array.prototype.pop()
• Array.prototype.shift()
• Array.prototype.slice()
• Array.prototype.toSpliced()
• Array.prototype.unshift()