Клавиша / esc

.toSpliced()

Возвращает новый массив, созданный из исходного, удаляя и/или добавляя новые элементы.

Время чтения: меньше 5 мин

Кратко

Скопировано

Метод toSpliced() возвращает новый массив, удаляя определённое количество элементов и/или добавляя новые элементы, начиная с указанного индекса в исходном массиве.

Пример

Скопировано

Создадим массив, удаляя из исходного массива 2 элемента, начиная с элемента с индексом 3:

        
          
          const months = [  'Май', 'Июнь', 'Июль', 'Август', 'Сентябрь', 'Октябрь']const newMonths = months.toSpliced(3, 2)console.log(newMonths)// ['Май', 'Июнь', 'Июль', 'Октябрь']
          const months = [
  'Май', 'Июнь', 'Июль', 'Август', 'Сентябрь', 'Октябрь'
]
const newMonths = months.toSpliced(3, 2)

console.log(newMonths)
// ['Май', 'Июнь', 'Июль', 'Октябрь']

        
        
          
        
      

Создадим массив, заменяя в исходном массиве 2 последних элемента:

        
          
          const versions = [  'ES2016', 'ES2017', 'ES2018', 'неизвестно', 'неизвестно']const newVersions = versions.toSpliced(-2, 2, 'ES2019', 'ES2020')console.log(newVersions)// ['ES2016', 'ES2017', 'ES2018', 'ES2019', 'ES2020']
          const versions = [
  'ES2016', 'ES2017', 'ES2018', 'неизвестно', 'неизвестно'
]
const newVersions = versions.toSpliced(-2, 2, 'ES2019', 'ES2020')

console.log(newVersions)
// ['ES2016', 'ES2017', 'ES2018', 'ES2019', 'ES2020']

        
        
          
        
      

Как пишется

Скопировано

Array.toSpliced принимает аргументы:

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

Если индекс отрицательный, то отсчёт позиции начала изменений ведётся от конца массива.

Если индекс не соответствует размеру массива, то позиция начала изменений определяется по знаку индекса:

  • отрицательный индекс — элементы удаляются и/или добавляются начиная с 0-ого элемента исходного массива;
  • положительный индекс — элементы добавляются после последнего элемента исходного массива;

Если количество удаляемых элементов меньше или равно 0, элементы не удаляются.

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

Как понять

Скопировано

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

Создадим массив, добавив в исходный массив 3 элемента, начиная с элемента с индексом 1:

        
          
          const days = ['ПН', 'ПТ']const workDays = days.toSpliced(1, 0, 'ВТ', 'СР', 'ЧТ')console.log(workDays)// ['ПН', 'ВТ', 'СР', 'ЧТ', 'ПТ']// Исходный массив не изменилсяconsole.log(days)// ['ПН', 'ПТ']
          const days = ['ПН', 'ПТ']
const workDays = days.toSpliced(1, 0, 'ВТ', 'СР', 'ЧТ')
console.log(workDays)
// ['ПН', 'ВТ', 'СР', 'ЧТ', 'ПТ']

// Исходный массив не изменился
console.log(days)
// ['ПН', 'ПТ']

        
        
          
        
      

В отличие от метода splice(), toSpliced() не меняет исходный массив и не возвращает удаляемые элементы:

        
          
          const numbers = [10, 20, 30, 40]const newNumbers = numbers.toSpliced(1, 2)console.log(newNumbers, numbers)// [10, 40] [10, 20, 30, 40]// А вот как работает splice()const deletedNumbers = numbers.splice(1, 2)console.log(deletedNumbers, numbers)// [20, 30] [10, 40]
          const numbers = [10, 20, 30, 40]
const newNumbers = numbers.toSpliced(1, 2)
console.log(newNumbers, numbers)
// [10, 40] [10, 20, 30, 40]

// А вот как работает splice()
const deletedNumbers = numbers.splice(1, 2)
console.log(deletedNumbers, numbers)
// [20, 30] [10, 40]

        
        
          
        
      

Подсказки

Скопировано

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

Заменим в массиве последний элемент:

        
          
          const colors = ['crimson', , , 'purple']console.log(colors.toSpliced(-1, 1, 'blueviolet' ))console.log(colors)// ['crimson', undefined, undefined, 'blueviolet']// ['crimson', <2 empty items>, 'purple']
          const colors = ['crimson', , , 'purple']
console.log(colors.toSpliced(-1, 1, 'blueviolet' ))
console.log(colors)
// ['crimson', undefined, undefined, 'blueviolet']
// ['crimson', <2 empty items>, 'purple']

        
        
          
        
      

💡 Если элементы исходного массива являются объектами, то возвращаемый в результате работы метода toSpliced() массив будет содержать ссылки, а не новые объекты. Таким образом, изменения объекта в исходном массиве будут видны в созданном массиве и наоборот:

        
          
          const skills = [  {name: 'HTML'}, {name: 'CSS'}, {name: 'PHP'}]// Добавим новый элементconst result = skills.toSpliced(2, 0, {name: 'JS'})console.log(result)// [//  {name: 'HTML'}, {name: 'CSS'}, {name: 'JS'}, {name: 'PHP'}// ]// Изменим элемент исходного массиваskills[0].year = 2005console.log(skills)// [{name: 'HTML', year: 2005}, {name: 'CSS'}, {name: 'PHP'}]// Изменения так же видны в созданном массивеconsole.log(result)// [//  { name: 'HTML', year: 2005 }, { name: 'CSS' },//  { name: 'JS' }, { name: 'PHP' }// ]
          const skills = [
  {name: 'HTML'}, {name: 'CSS'}, {name: 'PHP'}
]

// Добавим новый элемент
const result = skills.toSpliced(2, 0, {name: 'JS'})
console.log(result)
// [
//  {name: 'HTML'}, {name: 'CSS'}, {name: 'JS'}, {name: 'PHP'}
// ]

// Изменим элемент исходного массива
skills[0].year = 2005
console.log(skills)
// [{name: 'HTML', year: 2005}, {name: 'CSS'}, {name: 'PHP'}]

// Изменения так же видны в созданном массиве
console.log(result)
// [
//  { name: 'HTML', year: 2005 }, { name: 'CSS' },
//  { name: 'JS' }, { name: 'PHP' }
// ]

        
        
          
        
      

Подсказки

Скопировано

💡 Поддержка метода toSpliced() в основных браузерах и в Node.js появилась сравнительно недавно. Например, попытка использовать toSpliced() в Node.js v.18.19.0 приведёт к ошибке:

        
          
          try {  console.log([1, 2, 3].toSpliced(1, 0, 1.5))} catch (err) {  console.error('Поймали ошибку! Вот она: ', err.message)}// Поймали ошибку!// Вот она: [1,2,3].toSpliced is not a function
          try {
  console.log([1, 2, 3].toSpliced(1, 0, 1.5))
} catch (err) {
  console.error('Поймали ошибку! Вот она: ', err.message)
}
// Поймали ошибку!
// Вот она: [1,2,3].toSpliced is not a function