数组length

¥Value

小于 2³² 的非负整数。

¥A nonnegative integer less than 2³².

¥Description

length 属性的值是一个小于 2³² 的非负整数。

¥The value of the length property is a nonnegative integer with a value less than 2³².

const listA = [1, 2, 3];
const listB = new Array(6);

console.log(listA.length);
// 3

console.log(listB.length);
// 6

listB.length = 2 ** 32; // 4294967296
// RangeError: Invalid array length

const listC = new Array(-100); // Negative numbers are not allowed
// RangeError: Invalid array length

数组对象观察 length 属性，并自动将 length 值与数组内容同步。这意味着：

¥The array object observes the length property, and automatically syncs the length value with the array's content. This means:

• 将 length 设置为小于当前长度的值会截断数组 — 超出新 length 的元素将被删除。
• 将任何数组索引（小于 2³² 的非负整数）设置为超出当前 length 会扩展数组 - 增加 length 属性以反映新的最高索引。
• 将 length 设置为无效值（例如负数或非整数）会引发 RangeError 异常。

当 length 设置为大于当前长度的值时，数组将通过添加 空槽 而不是实际的 undefined 值来扩展。空槽与数组方法有一些特殊的交互；见 数组方法和空槽。

¥When length is set to a bigger value than the current length, the array is extended by adding empty slots, not actual undefined values. Empty slots have some special interactions with array methods; see array methods and empty slots.

const arr = [1, 2];
console.log(arr);
// [ 1, 2 ]

arr.length = 5; // set array length to 5 while currently 2.
console.log(arr);
// [ 1, 2, <3 empty items> ]

arr.forEach((element) => console.log(element));
// 1
// 2

另见 length 与数值性质的关系。

¥See also Relationship between length and numerical properties.

¥Examples

¥Iterating over an array

在以下示例中，通过查看 length 属性来迭代数组 numbers。然后每个元素中的值加倍。

¥In the following example, the array numbers is iterated through by looking at the length property. The value in each element is then doubled.

const numbers = [1, 2, 3, 4, 5];
const length = numbers.length;
for (let i = 0; i < length; i++) {
  numbers[i] *= 2;
}
// numbers is now [2, 4, 6, 8, 10]

¥Shortening an array

如果当前长度大于 3，以下示例将数组 numbers 缩短为长度 3。

¥The following example shortens the array numbers to a length of 3 if the current length is greater than 3.

const numbers = [1, 2, 3, 4, 5];

if (numbers.length > 3) {
  numbers.length = 3;
}

console.log(numbers); // [1, 2, 3]
console.log(numbers.length); // 3
console.log(numbers[3]); // undefined; the extra elements are deleted

¥Create empty array of fixed length

将 length 设置为大于当前长度的值会创建 稀疏数组。

¥Setting length to a value greater than the current length creates a sparse array.

const numbers = [];
numbers.length = 3;
console.log(numbers); // [empty x 3]

¥Array with non-writable length

当添加的元素超出当前长度时，数组会自动更新 length 属性。如果 length 属性设置为不可写，则数组将无法更新它。这会导致 严格模式 中出现错误。

¥The length property is automatically updated by the array when elements are added beyond the current length. If the length property is made non-writable, the array will not be able to update it. This causes an error in strict mode.

"use strict";

const numbers = [1, 2, 3, 4, 5];
Object.defineProperty(numbers, "length", { writable: false });
numbers[5] = 6; // TypeError: Cannot assign to read only property 'length' of object '[object Array]'
numbers.push(5); // // TypeError: Cannot assign to read only property 'length' of object '[object Array]'

¥See also

• 索引集合 指南
• Array
• TypedArray.prototype.length
• String：length
• 范围错误：数组长度无效