Array : méthode includes()

Baseline Widely available

Cette fonctionnalité est bien établie et fonctionne sur de nombreux appareils et versions de navigateurs. Elle est disponible sur tous les navigateurs depuis ⁨août 2016⁩.

La méthodeincludes() des instances deArray détermine si un tableau contient une certaine valeur parmi ses éléments, et retournetrue oufalse selon le cas.

Exemple interactif

const array1 = [1, 2, 3];console.log(array1.includes(2));// Résultat attendu : trueconst pets = ['chat', 'chien', 'chauve-souris'];console.log(pets.includes('chat'));// Résultat attendu : trueconsole.log(pets.includes('at'));// Résultat attendu : false

Syntaxe

includes(searchElement)includes(searchElement, fromIndex)

Paramètres

searchElement

La valeur à rechercher.

fromIndexFacultatif

La position (en partant de 0) dans le tableau à partir de laquelle commencer la recherche. Cette valeur estconvertie 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.
SifromIndex < -array.length ou sifromIndex est omis,0 est utilisé, ce qui fait que tout le tableau est parcouru.
SifromIndex >= array.length, le tableau n'est pas parcouru etfalse est retourné.

Valeur de retour

Une valeur booléenne qui vauttrue si la valeursearchElement est trouvée dans le tableau (ou dans la partie du tableau indiquée par l'indicefromIndex, si précisé).

La méthodeincludes() compare unsearchElement aux éléments du tableau en utilisant l'algorithmeSameValueZero. Les valeurs nulles sont toutes considérées comme égales, quel que soit leur signe : ainsi,-0 est égal à0, maisfalse n'estpas considéré comme équivalent à0.NaN peut être recherché correctement.

Lorsqu'elle est utilisée sur untableau creux, la méthodeincludes() parcourt les emplacements vides comme s'ils avaient la valeurundefined.

La méthodeincludes() estgénérique : elle attend uniquement que la valeur dethis 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

SifromIndex 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); // falsearr.includes("c", 100); // false

L'indice calculé est inférieur à 0

SifromIndex est négatif, l'indice calculé est utilisé comme position dans le tableau à partir de laquelle commencer la recherche desearchElement. 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) = -97const arr = ["a", "b", "c"];arr.includes("a", -100); // truearr.includes("b", -100); // truearr.includes("c", -100); // truearr.includes("a", -2); // false

Utilisation de`includes()` sur un tableau creux

Vous pouvez rechercherundefined dans un tableau creux et obtenirtrue.

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

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

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

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