Array.prototype.unshift()

¥Syntax

unshift()
unshift(element1)
unshift(element1, element2)
unshift(element1, element2, /* …, */ elementN)

¥Parameters

element1, …, elementN

添加到 arr 前面的元素。

¥Return value

调用该方法的对象的新 length 属性。

¥The new length property of the object upon which the method was called.

¥Description

unshift() 方法将给定值插入到类似数组的对象的开头。

¥The unshift() method inserts the given values to the beginning of an array-like object.

Array.prototype.push() 与 unshift() 具有类似的行为，但应用于数组的末尾。

¥Array.prototype.push() has similar behavior to unshift(), but applied to the end of an array.

请注意，如果多个元素作为参数传递，它们将按照与作为参数传递的顺序完全相同的顺序插入到对象的开头。因此，使用 n 个参数调用 unshift() 一次，或使用 1 个参数（例如，使用循环）调用 n 次，不会产生相同的结果。

¥Please note that, if multiple elements are passed as parameters, they're inserted in chunk at the beginning of the object, in the exact same order they were passed as parameters. Hence, calling unshift() with n arguments once, or calling it n times with 1 argument (with a loop, for example), don't yield the same results.

参见示例：

¥See example:

let arr = [4, 5, 6];

arr.unshift(1, 2, 3);
console.log(arr);
// [1, 2, 3, 4, 5, 6]

arr = [4, 5, 6]; // resetting the array

arr.unshift(1);
arr.unshift(2);
arr.unshift(3);

console.log(arr);
// [3, 2, 1, 4, 5, 6]

unshift() 方法是 generic。它只期望 this 值具有 length 属性和整数键控属性。虽然字符串也是类似数组的，但此方法不适合应用于它们，因为字符串是不可变的。

¥The unshift() method is generic. It only expects the this value to have a length property and integer-keyed properties. Although strings are also array-like, this method is not suitable to be applied on them, as strings are immutable.

¥Examples

¥Using unshift()

const arr = [1, 2];

arr.unshift(0); // result of the call is 3, which is the new array length
// arr is [0, 1, 2]

arr.unshift(-2, -1); // the new array length is 5
// arr is [-2, -1, 0, 1, 2]

arr.unshift([-4, -3]); // the new array length is 6
// arr is [[-4, -3], -2, -1, 0, 1, 2]

arr.unshift([-7, -6], [-5]); // the new array length is 8
// arr is [ [-7, -6], [-5], [-4, -3], -2, -1, 0, 1, 2 ]

¥Calling unshift() on non-array objects

unshift() 方法读取 this 的 length 属性。它将 0 到 length - 1 范围内的所有索引右移参数数量（将它们的值增加该数字）。然后，它设置从 0 开始的每个索引，并将参数传递给 unshift()。最后，它将 length 设置为先前的长度加上前置元素的数量。

¥The unshift() method reads the length property of this. It shifts all indices in the range 0 to length - 1 right by the number of arguments (incrementing their values by this number). Then, it sets each index starting at 0 with the arguments passed to unshift(). Finally, it sets the length to the previous length plus the number of prepended elements.

const arrayLike = {
  length: 3,
  unrelated: "foo",
  2: 4,
};
Array.prototype.unshift.call(arrayLike, 1, 2);
console.log(arrayLike);
// { '0': 1, '1': 2, '4': 4, length: 5, unrelated: 'foo' }

const plainObj = {};
// There's no length property, so the length is 0
Array.prototype.unshift.call(plainObj, 1, 2);
console.log(plainObj);
// { '0': 1, '1': 2, length: 2 }

¥See also

• core-js 中的 Array.prototype.unshift 的 Polyfill 以及此方法的修复
• 索引集合 指南
• Array
• Array.prototype.push()
• Array.prototype.pop()
• Array.prototype.shift()
• Array.prototype.concat()
• Array.prototype.splice()