Array : méthode includes()

Exemple interactif

const array1 = [1, 2, 3];

console.log(array1.includes(2));
// Résultat attendu : true

const pets = ['chat', 'chien', 'chauve-souris'];

console.log(pets.includes('chat'));
// Résultat attendu : true

console.log(pets.includes('at'));
// Résultat attendu : false

Syntaxe

includes(searchElement)
includes(searchElement, fromIndex)

Paramètres

searchElement

La valeur à rechercher.

fromIndex Facultatif

La position (en partant de 0) dans le tableau à partir de laquelle commencer la recherche. Cette valeur est convertie en entier.

• Un indice négatif compte à rebours depuis la fin du tableau — si -array.length <= fromIndex < 0, fromIndex + array.length est utilisé. Cependant, le tableau est tout de même parcouru de l'avant vers l'arrière dans ce cas.
• Si fromIndex < -array.length ou si fromIndex est omis, 0 est utilisé, ce qui fait que tout le tableau est parcouru.
• Si fromIndex >= array.length, le tableau n'est pas parcouru et false est retourné.

Valeur de retour

Une valeur booléenne qui vaut true si la valeur searchElement est trouvée dans le tableau (ou dans la partie du tableau indiquée par l'indice fromIndex, si précisé).

Description

La méthode includes() compare un searchElement aux éléments du tableau en utilisant l'algorithme SameValueZero. Les valeurs nulles sont toutes considérées comme égales, quel que soit leur signe : ainsi, -0 est égal à 0, mais false n'est pas considéré comme équivalent à 0. NaN peut être recherché correctement.

Lorsqu'elle est utilisée sur un tableau creux, la méthode includes() parcourt les emplacements vides comme s'ils avaient la valeur undefined.

La méthode includes() est générique : elle attend uniquement que la valeur de this possède une propriété length et des propriétés à clés entières.

Exemples

Utilisation d'includes()

[1, 2, 3].includes(2); // true
[1, 2, 3].includes(4); // false
[1, 2, 3].includes(3, 3); // false
[1, 2, 3].includes(3, -1); // true
[1, 2, NaN].includes(NaN); // true
["1", "2", "3"].includes(3); // false

fromIndex supérieur ou égal à la longueur du tableau

Si fromIndex est supérieur ou égal à la longueur du tableau, false est retourné. Le tableau ne sera pas parcouru.

const arr = ["a", "b", "c"];

arr.includes("c", 3); // false
arr.includes("c", 100); // false

L'indice calculé est inférieur à 0

Si fromIndex est négatif, l'indice calculé est utilisé comme position dans le tableau à partir de laquelle commencer la recherche de searchElement. Si l'indice calculé est inférieur ou égal à 0, tout le tableau sera parcouru.

// la longueur du tableau est 3
// fromIndex vaut -100
// l'indice calculé vaut 3 + (-100) = -97

const arr = ["a", "b", "c"];

arr.includes("a", -100); // true
arr.includes("b", -100); // true
arr.includes("c", -100); // true
arr.includes("a", -2); // false

Utilisation de includes() sur un tableau creux

Vous pouvez rechercher undefined dans un tableau creux et obtenir true.

console.log([1, , 3].includes(undefined)); // true

Appel de includes() sur des objets qui ne sont pas des tableaux

La méthode includes() lit la propriété length de this puis accède à chaque propriété dont la clé est un entier non négatif inférieur à length.

const arrayLike = {
  length: 3,
  0: 2,
  1: 3,
  2: 4,
  3: 1, // ignoré par includes() car length vaut 3
};
console.log(Array.prototype.includes.call(arrayLike, 2));
// true
console.log(Array.prototype.includes.call(arrayLike, 1));
// false

Spécifications

Compatibilité des navigateurs

Voir aussi

• Guide des collections indexées
• L'objet global Array
• La méthode Array.prototype.indexOf()
• La méthode Array.prototype.find()
• La méthode Array.prototype.findIndex()
• La méthode TypedArray.prototype.includes()
• La méthode String.prototype.includes()
• Prothèse d'émulation de Array.prototype.includes dans core-js ^(angl.)
• Prothèse d'émulation es-shims de Array.prototype.includes ^(angl.)