Array.prototype.splice()

Сводка

Метод splice() изменяет содержимое массива, добавляя новые и удаляя старые элементы.

Синтаксис

array.splice(index, howMany[, element1[, ...[, elementN]]])
array.splice(index) // расширение SpiderMonkey/Firefox

Параметры

index

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

howMany

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

elementN

Необязательные параметры. Добавляемые к массиву элементы. Если вы не укажете никакого элемента, splice просто удалит элементы из массива.

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

Массив, содержащий удалённые элементы. Если будет удалён только один элемент, вернётс я массив из одного элемента. Если никакие элементы не будут удалены, вернётся пустой массив.

Описание

Если количество указанных вставляемых элементов будет отличным от количества удаляемых элементов, массив изменит длину после вызова.

Примеры

Пример: использование splice

Следующий пример иллюстрирует использование splice:

var myFish = ['ангел', 'клоун', 'мандарин', 'хирург'];

// удаляет 0 элементов с индекса 2 и вставляет элемент 'барабанщик'
var removed = myFish.splice(2, 0, 'барабанщик');
// myFish равен ['ангел', 'клоун', 'барабанщик', 'мандарин', 'хирург']
// removed равен [], никакие элементы не были удалены

// удаляет 1 элемент с индекса 3
removed = myFish.splice(3, 1);
// myFish равен ['ангел', 'клоун', 'барабанщик', 'хирург']
// removed равен ['мандарин']

// удаляет 1 элемент с индекса 2 и вставляет элемент 'телескоп'
removed = myFish.splice(2, 1, 'телескоп');
// myFish равен ['ангел', 'клоун', 'телескоп', 'хирург']
// removed равен ['барабанщик']

// удаляет 2 элемента с индекса 0 и вставляет элементы 'попугай', 'анемон' и 'голубая'
removed = myFish.splice(0, 2, 'попугай', 'анемон', 'голубая');
// myFish равен ['попугай', 'анемон', 'голубая', 'телескоп', 'хирург']
// removed равен ['ангел', 'клоун']

// удаляет 2 элемента с индекса 3
removed = myFish.splice(3, Number.MAX_VALUE);
// myFish равен ['попугай', 'анемон', 'голубая']
// removed равен ['телескоп', 'хирург']

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

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

Обратная совместимость

В JavaScript 1.2 метод splice возвращал удалённый элемент только если был удалён один элемент (параметр howMany равен 1); в противном случае метод возвращал массив с удалёнными элементами. Обратите внимание, что последним браузером, использующим JavaScript 1.2, был Netscape Navigator 4, так что вы можете считать, что splice всегда возвращает массив.

Смотрите также

• push / pop — добавление / удаление элементов с конца массива
• unshift / shift — добавление / удаление элементов с начала массива
• concat — возвращает новый массив, состоящий из данного массива, соединённого с другими массивами и/или значениями