La propriété de donnéeslength d'une instance deArray représente le nombre d'éléments dans ce tableau. Sa valeur est un entier non signé sur 32 bits qui est toujours numériquement supérieur au plus grand indice du tableau.

Exemple interactif

const clothing = ["chaussures", "chemises", "chaussettes", "pulls"];console.log(clothing.length);// Résultat attendu : 4

Valeur

Un entier positif inférieur à 2³².

Description

La valeur de la propriétélength est un entier positif dont la valeur est inférieure à 2³².

const listeA = [1, 2, 3];const listeB = new Array(6);console.log(listeA.length);// Résultat attendu : 3console.log(listeB.length);// Résultat attendu : 6listeB.length = 2 ** 32; // 4294967296// RangeError : Invalid array lengthconst listeC = new Array(-100); // Les nombres négatifs ne sont pas autorisés// RangeError : Invalid array length

L'objet tableau observe la propriétélength et synchronise automatiquement la valeur delength avec le contenu du tableau. Cela signifie :

• Définir la propriétélength à une valeur inférieure à la longueur actuelle tronque le tableau — les éléments au-delà de la nouvelle valeur delength sont supprimés.
• Définir un indice de tableau (un entier positif inférieur à 2³²) au-delà de la valeur actuelle delength étend le tableau — la propriétélength est augmentée pour refléter le nouvel indice le plus élevé.
• Définir la propriétélength à une valeur invalide (par exemple, un nombre négatif ou un nombre non entier) lève une exceptionRangeError.

Lorsque la propriétélength est définie à une valeur supérieure à la longueur actuelle, le tableau est étendu en ajoutant desemplacements vides, et non des valeursundefined réelles. Les emplacements vides ont des interactions particulières avec les méthodes de tableau : voirméthodes de tableau et emplacements vides.

const tableau = [1, 2];console.log(tableau);// [ 1, 2 ]tableau.length = 5; // On définit la longueur du tableau à 5 alors qu'elle vaut 2.console.log(tableau);// [ 1, 2, <3 éléments vides> ]tableau.forEach((élément) => console.log(élément));// 1// 2

Voir aussila relation entre longueur et propriétés numériques.

Exemples

Parcourir un tableau

Dans l'exemple suivant, on itère sur le tableaunombres en utilisant la propriétélength afin de connaître son nombre d'éléments. La valeur de chaque élément est ensuite multipliée par deux :

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

Tronquer un tableau

L'exemple suivant raccourcit le tableaunombres à une longueur de 3 si sa longueur actuelle est supérieure à 3.

const nombres = [1, 2, 3, 4, 5];if (nombres.length > 3) {  nombres.length = 3;}console.log(nombres); // [1, 2, 3]console.log(nombres.length); // 3console.log(nombres[3]); // undefined ; les éléments supplémentaires sont supprimés

Créer un tableau vide de longueur fixe

Définir la propriétélength à une valeur supérieure à la longueur actuelle crée untableau creux.

const nombres = [];nombres.length = 3;console.log(nombres); // [vide x 3]

Tableau avec une propriétélength non modifiable

La propriétélength est automatiquement mise à jour par le tableau lorsque des éléments sont ajoutés au-delà de la longueur actuelle. Si la propriétélength est rendue non modifiable, le tableau ne pourra pas la mettre à jour. Cela provoque une erreur enmode strict.

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

Spécifications

Compatibilité des navigateurs

Voir aussi

• Guide des collections indexées
• L'objet globalArray
• La propriétéTypedArray.prototype.length
• La propriétéString.length
• RangeError : longueur de tableau invalide