toSpliced() - метод для изменения массива без мутации исходного массива в JavaScript

toSpliced() позволяет удалить, добавить или заменить элементы массива и при этом вернуть новый массив.

Это современная альтернатива splice(), когда нужно изменить структуру массива, но не трогать исходные данные.

Синтаксис

array.toSpliced(start)
array.toSpliced(start, deleteCount)
array.toSpliced(start, deleteCount, item1, item2, ...)

start - позиция, с которой начинается изменение массива.

deleteCount - сколько элементов нужно удалить.

После этого можно передать новые элементы, которые нужно вставить на это место.

Что делает toSpliced()

toSpliced() не меняет исходный массив.

Он создаёт новую версию массива с нужными изменениями.

const numbers = [1, 2, 3, 4];
const result = numbers.toSpliced(1, 2);

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

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

Если передать start и deleteCount, метод удалит нужное количество элементов в новом массиве.

const fruits = ["apple", "banana", "orange", "kiwi"];
const result = fruits.toSpliced(1, 2);

console.log(result); // ["apple", "kiwi"]

Добавление элементов

Если deleteCount равен 0, ничего не удаляется, а новые элементы вставляются в нужную позицию.

const numbers = [1, 4];
const result = numbers.toSpliced(1, 0, 2, 3);

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

Это удобный способ вставить элементы в середину массива без мутации исходного.

Замена элементов

toSpliced() умеет одновременно удалять старые элементы и вставлять новые.

const colors = ["red", "green", "blue"];
const result = colors.toSpliced(1, 1, "yellow");

console.log(result); // ["red", "yellow", "blue"]
console.log(colors); // ["red", "green", "blue"]

Здесь "green" был заменён на "yellow".

Что возвращает toSpliced()

toSpliced() всегда возвращает новый массив.

const numbers = [10, 20, 30];
const result = numbers.toSpliced(1, 1);

console.log(result);             // [10, 30]
console.log(result === numbers); // false

Это не тот же самый массив, а новая копия.

Исходный массив не меняется

Это главное отличие от splice().

const items = ["a", "b", "c"];
const result = items.toSpliced(1, 1);

console.log(items);  // ["a", "b", "c"]
console.log(result); // ["a", "c"]

Если нужно изменение “на месте”, используют splice().

Если deleteCount не указать

Если передать только start, метод удалит элементы от этой позиции до конца массива, но в новом результате.

const numbers = [1, 2, 3, 4];
const result = numbers.toSpliced(2);

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

Отрицательный индекс

start может быть отрицательным.

В этом случае отсчёт идёт с конца массива.

const numbers = [1, 2, 3, 4];
const result = numbers.toSpliced(-2, 1);

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

Здесь -2 указывает на элемент 3.

toSpliced() и splice()

Эти методы делают похожие вещи, но работают по-разному.

const numbers = [1, 2, 3, 4];
const result = numbers.toSpliced(1, 2);

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

toSpliced() возвращает новый массив.

splice() меняет исходный массив прямо на месте.

toSpliced() и slice()

slice() только копирует часть массива.

toSpliced() умеет удалять, вставлять и заменять элементы.

const numbers = [1, 2, 3, 4];

console.log(numbers.slice(1, 3));        // [2, 3]
console.log(numbers.toSpliced(1, 2, 9)); // [1, 9, 4]

Это разные задачи, хотя названия похожи.

Поверхностная копия

toSpliced() создаёт поверхностную копию массива.

Это значит, что вложенные объекты внутри не копируются глубоко.

const users = [{ name: "Anna" }, { name: "Ivan" }];
const result = users.toSpliced(1, 0, { name: "Oleg" });

console.log(result);
// [{ name: "Anna" }, { name: "Oleg" }, { name: "Ivan" }]

Сами объекты внутри массива остаются обычными ссылками.

Когда это полезно

toSpliced() удобно использовать, когда:

нужно удалить элементы без изменения исходного массива
нужно вставить значения в середину массива
нужно заменить часть массива
важен неизменяемый стиль работы с данными

Пример:

const tasks = ["task-1", "task-3"];
const nextTasks = tasks.toSpliced(1, 0, "task-2");

console.log(tasks);     // ["task-1", "task-3"]
console.log(nextTasks); // ["task-1", "task-2", "task-3"]

Частые ошибки

Думать, что toSpliced() меняет исходный массив

const numbers = [1, 2, 3];

numbers.toSpliced(1, 1);

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

Если результат не сохранить, исходный массив останется прежним.

Путать toSpliced() и splice()

const numbers = [1, 2, 3];
const result = numbers.toSpliced(1, 1);

console.log(result); // [1, 3]

splice() в похожей ситуации вернул бы удалённые элементы и изменил исходный массив.

Путать toSpliced() и slice()

const numbers = [1, 2, 3, 4];

console.log(numbers.toSpliced(1, 2)); // [1, 4]

Этот метод не просто берёт часть массива, а именно строит новый массив с изменениями.

Быстрая памятка

toSpliced() удаляет, добавляет или заменяет элементы массива
метод возвращает новый массив
исходный массив не меняется
start может быть отрицательным
это “неизменяемая” альтернатива splice()

Коротко

toSpliced() - это удобный способ изменить структуру массива без мутации исходных данных. Главное, что стоит запомнить: по смыслу он похож на splice(), но результатом всегда будет новый массив.