Array.prototype.splice()

試してみましょう

const months = ["Jan", "March", "April", "June"];
months.splice(1, 0, "Feb");
// インデックス 1 に挿入
console.log(months);
// 予想される結果: Array ["Jan", "Feb", "March", "April", "June"]

months.splice(4, 1, "May");
// インデックス 4 の要素 1 つを置換
console.log(months);
// 予想される結果: Array ["Jan", "Feb", "March", "April", "May"]

構文

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

引数

start

配列の変更を始める位置のゼロから始まるインデックスで、整数に変換されます。

• インデックスが負の場合、配列の末尾からさかのぼって数えます。 start < 0 の場合、 start + array.length が使用されます。
• start < -array.length の場合は 0 が使用されます。
• start >= array.length の場合、要素は削除されませんが、メソッドは追加関数として動作し、指定された数だけ要素を追加します。
• start が省略された場合（そして splice() が引数なしで呼び出された場合）、何も削除されません。これは undefined を渡すと 0 に変換されるのとは異なります。

deleteCount 省略可

配列の start の位置から取り除く古い要素の個数を示す整数です。

deleteCount が省略された場合、または deleteCount の値が start で指定した位置より後の要素数以上の場合、 start から配列の末尾までのすべての要素が削除されます。ただし、任意の itemN 引数を渡したい場合は、 start より後の要素をすべて削除するために deleteCount として Infinity を渡す必要があります。明示的に undefined を渡すと、変換されて 0 になるからです。

deleteCount が 0 または負の数の場合、どの要素も取り除かれません。この場合、少なくとも 1 つの新しい要素を指定する必要があります（以下参照）。

item1, …, itemN 省略可

配列に追加する要素で、start から始まります。

要素を指定しなかった場合、splice() は単に配列から要素を取り除きます。

返値

取り除かれた要素を含む配列です。

要素が 1 つだけ取り除かれた場合は、要素数 1 の配列が返されます。

要素が取り除かれなかった場合、空の配列が返されます。

解説

splice() メソッドは変更メソッドです。 this の内容を変更します。指定した挿入する要素数と除去される要素数が異なる場合、配列の length も変更されます。同時に、 [Symbol.species] を使用して、返す新しい配列インスタンスを作成します。

削除された部分が疎配列の場合、 splice() が返す配列も疎配列になり、対応するインデックスは空のスロットになります。

splice() メソッドは汎用的です。このメソッドは this 値に length プロパティと整数キーのプロパティがあることだけを期待します。文字列も配列風ですが、文字列は不変なので、このメソッドを適用するのには適していません。

例

2 の位置の手前から 0 個の要素を削除して "drum" を挿入

const myFish = ["angel", "clown", "mandarin", "sturgeon"];
const removed = myFish.splice(2, 0, "drum");

// myFish は ["angel", "clown", "drum", "mandarin", "sturgeon"]
// removed は [] であり、どの要素も取り除かれていない

2 の位置の手前から 0 個の要素を削除して、"drum" と "guitar" を挿入

const myFish = ["angel", "clown", "mandarin", "sturgeon"];
const removed = myFish.splice(2, 0, "drum", "guitar");

// myFish は ["angel", "clown", "drum", "guitar", "mandarin", "sturgeon"]
// removed は [] であり、どの要素も取り除かれていない

0（ゼロ）個の要素を 0 の位置から削除して、"angel" を挿入

splice(0, 0, ...elements) は、unshift() のように配列の先頭に要素を挿入します。

const myFish = ["clown", "mandarin", "sturgeon"];
const removed = myFish.splice(0, 0, "angel");

// myFish は ["angel", "clown", "mandarin", "sturgeon"]
// アイテムは削除されない

0（ゼロ）個の要素を末尾の位置から削除して、"sturgeon" を挿入

splice(array.length, 0, ...elements) は、push() のように配列の末尾に要素を挿入します。

const myFish = ["angel", "clown", "mandarin"];
const removed = myFish.splice(myFish.length, 0, "sturgeon");

// myFish は ["angel", "clown", "mandarin", "sturgeon"]
// アイテムは削除されない

3 の位置から 1 つ取り除く

const myFish = ["angel", "clown", "drum", "mandarin", "sturgeon"];
const removed = myFish.splice(3, 1);

// myFish は ["angel", "clown", "drum", "sturgeon"]
// removed は ["mandarin"]

2 の位置から 1 つ取り除いて "trumpet" を挿入

const myFish = ["angel", "clown", "drum", "sturgeon"];
const removed = myFish.splice(2, 1, "trumpet");

// myFish は ["angel", "clown", "trumpet", "sturgeon"]
// removed は ["drum"]

0 の位置から 2 つ取り除き、そこへ "parrot" と "anemone" と "blue" を挿入

const myFish = ["angel", "clown", "trumpet", "sturgeon"];
const removed = myFish.splice(0, 2, "parrot", "anemone", "blue");

// myFish は ["parrot", "anemone", "blue", "trumpet", "sturgeon"]
// removed は ["angel", "clown"]

2 の位置から 2 つ取り除く

const myFish = ["parrot", "anemone", "blue", "trumpet", "sturgeon"];
const removed = myFish.splice(2, 2);

// myFish は ["parrot", "anemone", "sturgeon"]
// removed は ["blue", "trumpet"]

-2 の位置から 1 つ取り除く

const myFish = ["angel", "clown", "mandarin", "sturgeon"];
const removed = myFish.splice(-2, 1);

// myFish は ["angel", "clown", "sturgeon"]
// removed は ["mandarin"]</pre>

2 の位置からすべての要素を取り除く

const myFish = ["angel", "clown", "mandarin", "sturgeon"];
const removed = myFish.splice(2);

// myFish は ["angel", "clown"]
// removed は ["mandarin", "sturgeon"]

疎配列に対する splice() の使用

splice() メソッドは疎配列であることを維持します。

const arr = [1, , 3, 4, , 6];
console.log(arr.splice(1, 2)); // [empty, 3]
console.log(arr); // [1, 4, empty, 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()