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 または負の場合、要素は除去されません。この場合、少なくとも 1 つの新しい要素を指定する必要があります（下記参照）。

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"];// インデックス 1 の要素の挿入const months2 = months.toSpliced(1, 0, "Feb");console.log(months2); // ["Jan", "Feb", "Mar", "Apr", "May"]// インデックス 2 から始まる 2 つの要素を削除const months3 = months2.toSpliced(2, 2);console.log(months3); // ["Jan", "Feb", "May"]// インデックス 1 の要素を 2 つの新しい要素で置き換えconst months4 = months3.toSpliced(1, 1, "Feb", "Mar");console.log(months4); // ["Jan", "Feb", "Mar", "May"]// 元配列は変更しない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() メソッドはthis のlength プロパティを読み取ります。そして、必要な整数キーのプロパティを読み込み、新しい配列に書き込みます。

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]

仕様書

ブラウザーの互換性

関連情報

• Array.prototype.toSpliced のポリフィル (core-js)
• es-shims によるArray.prototype.toSpliced のポリフィル
• Array.prototype.splice()
• Array.prototype.toReversed()
• Array.prototype.toSorted()
• Array.prototype.with()