Array.prototype.toSpliced()

¥Syntax

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

¥Parameters

start

开始更改数组的从零开始的索引，转换为整数。

• 负索引从数组末尾开始倒数 — 如果使用 -array.length <= start < 0、start + array.length。
• 如果省略 start < -array.length 或 start，则使用 0。
• 如果是 start >= array.length，则不会删除任何元素，但该方法将充当添加函数，添加所提供的尽可能多的元素。

deleteCount Optional

一个整数，指示数组中要从 start 中删除的元素数。

如果省略 deleteCount，或者其值大于或等于 start 指定位置之后的元素个数，则从 start 到数组末尾的所有元素都将被删除。但是，如果你希望传递任何 itemN 参数，则应将 Infinity 作为 deleteCount 传递，以删除 start 之后的所有元素，因为显式 undefined 会获取 converted 到 0。

如果 deleteCount 为 0 或负数，则不会删除任何元素。在这种情况下，你应该至少指定一个新元素（见下文）。

item1, …, itemN Optional

要添加到数组的元素，从 start 开始。

如果不指定任何元素，toSpliced() 只会从数组中删除元素。

¥Return value

一个新数组，由 start、item1、item2、…、itemN 之前的所有元素以及 start + deleteCount 之后的所有元素组成。

¥A new array that consists of all elements before start, item1, item2, …, itemN, and all elements after start + deleteCount.

¥Description

toSpliced() 方法与 splice() 一样，可以同时执行多项操作：它从数组中从给定索引开始删除给定数量的元素，然后在同一索引处插入给定元素。但是，它返回一个新数组，而不是修改原始数组。因此，此方法不会返回已删除的元素。

¥The toSpliced() method, like splice(), does multiple things at once: it removes the given number of elements from the array, starting at a given index, and then inserts the given elements at the same index. However, it returns a new array instead of modifying the original array. The deleted elements therefore are not returned from this method.

toSpliced() 方法永远不会产生 稀疏数组。如果源数组稀疏，则空槽将替换为新数组中的 undefined。

¥The toSpliced() method never produces a sparse array. If the source array is sparse, the empty slots will be replaced with undefined in the new array.

toSpliced() 方法是 generic。它只期望 this 值具有 length 属性和整数键控属性。

¥The toSpliced() method is generic. It only expects the this value to have a length property and integer-keyed properties.

¥Examples

¥Deleting, adding, and replacing elements

与使用 slice() 和 concat() 相比，你可以使用 toSpliced() 删除、添加和替换数组中的元素并更有效地创建新数组。

¥You can use toSpliced() to delete, add, and replace elements in an array and create a new array more efficiently than using slice() and concat().

const months = ["Jan", "Mar", "Apr", "May"];

// Inserting an element at index 1
const months2 = months.toSpliced(1, 0, "Feb");
console.log(months2); // ["Jan", "Feb", "Mar", "Apr", "May"]

// Deleting two elements starting from index 2
const months3 = months2.toSpliced(2, 2);
console.log(months3); // ["Jan", "Feb", "May"]

// Replacing one element at index 1 with two new elements
const months4 = months3.toSpliced(1, 1, "Feb", "Mar");
console.log(months4); // ["Jan", "Feb", "Mar", "May"]

// Original array is not modified
console.log(months); // ["Jan", "Mar", "Apr", "May"]

¥Using toSpliced() on sparse arrays

toSpliced() 方法始终创建密集数组。

¥The toSpliced() method always creates a dense array.

const arr = [1, , 3, 4, , 6];
console.log(arr.toSpliced(1, 2)); // [1, 4, undefined, 6]

¥Calling toSpliced() on non-array objects

toSpliced() 方法读取 this 的 length 属性。然后，它读取所需的整数键属性并将它们写入新数组中。

¥The toSpliced() method reads the length property of this. It then reads the integer-keyed properties needed and writes them into the new array.

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]

¥See also

• core-js 中 Array.prototype.toSpliced 的 Polyfill
• Array.prototype.splice()
• Array.prototype.toReversed()
• Array.prototype.toSorted()
• Array.prototype.with()