Array.prototype.toSpliced()

Метод toSpliced() экземпляров Array является копирующей версией метода splice(). Он возвращает новый массив с удаленными и/или замененными элементами по указанному индексу.

Синтаксис

toSpliced(start)
toSpliced(start, skipCount)
toSpliced(start, skipCount, item1)
toSpliced(start, skipCount, item1, item2)
toSpliced(start, skipCount, item1, item2, /* …, */ itemN)

Параметры

start

Нулевой индекс, начиная с которого будут вноситься изменения в массив, преобразованный в целое число.

• Отрицательный индекс отсчитывается с конца массива — если -array.length <= start < 0, используется start + array.length.
• Если start < -array.length или start опущены, используется 0.
• Если start >= array.length, элементы не будут удаляться, но метод будет работать как функция добавления, добавляя столько элементов, сколько указано.

skipCount Необязательный

Целое число, указывающее количество элементов в массиве для удаления (или пропуска) начиная с start.

Если skipCount опущен или его значение больше или равно количеству элементов после позиции, указанной start, то все элементы от start до конца массива будут удалены. Однако, если вы хотите передать любой параметр itemN, вам следует передать Infinity как skipCount, чтобы удалить все элементы после start, поскольку явное undefined преобразуется в 0.

Если skipCount является 0 или отрицательным, элементы не удаляются. В этом случае следует указать хотя бы один новый элемент (см. ниже).

item1, …, itemN Необязательный

Элементы для добавления в массив, начиная с start.

Если вы не укажете никаких элементов, toSpliced() будет только удалять элементы из массива.

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

Новый массив, состоящий из всех элементов до start, item1, item2, …, itemN, и всех элементов после start + skipCount.

Описание

Метод toSpliced(), как и splice(), выполняет несколько действий одновременно: он удаляет указанное количество элементов из массива, начиная с указанного индекса, а затем вставляет указанные элементы в тот же индекс. Однако он возвращает новый массив вместо изменения исходного. Удаленные элементы, таким образом, не возвращаются этим методом, но остаются доступными в исходном массиве.

Метод toSpliced() никогда не создает разреженный массив. Если исходный массив разрежен, пустые слоты будут заменены на undefined в новом массиве.

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

Примеры

Удаление, добавление и замена элементов

Вы можете использовать toSpliced() для удаления, добавления и замены элементов в массиве и создания нового массива более эффективно, чем при использовании slice() и concat().

const months = ["Jan", "Mar", "Apr", "May"];

// Inserting an element at index 1
const months2 = months.toSpliced(1, 0, "Feb");
console.log(months2); // ["Jan", "Feb", "Mar", "Apr", "May"]

// Deleting two elements starting from index 2
const months3 = months2.toSpliced(2, 2);
console.log(months3); // ["Jan", "Feb", "May"]

// Replacing one element at index 1 with two new elements
const months4 = months3.toSpliced(1, 1, "Feb", "Mar");
console.log(months4); // ["Jan", "Feb", "Mar", "May"]

// Original array is not modified
console.log(months); // ["Jan", "Mar", "Apr", "May"]

Использование toSpliced() на разреженных массивах

Метод toSpliced() всегда создает плотный массив.

const arr = [1, , 3, 4, , 6];
console.log(arr.toSpliced(1, 2)); // [1, 4, undefined, 6]

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

Метод toSpliced() считывает свойство length объекта this. Затем он считывает необходимые целочисленные свойства и записывает их в новый массив.

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

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

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

См. также

• Polyfill для Array.prototype.toSpliced в core-js
• Polyfill для Array.prototype.toSpliced от es-shims
• Array.prototype.splice()
• Array.prototype.toReversed()
• Array.prototype.toSorted()
• Array.prototype.with()