La méthode includes() permet de déterminer si un tableau contient un élément et renvoie true si c'est le cas, false sinon.

Note : Cette méthode utilise l'algorithme de comparaison SameValueZero qui fonctionne comme l'égalité stricte, à la différence que NaN est ici égal à lui même.

Syntaxe

array.includes(élémentRecherché)
array.includes(élémentRecherché[, indiceDépart])

Paramètres

élémentRecherché
L'élément qu'on souhaite trouver dans le tableau.
indiceDépart Facultatif
La position du tableau à partir de laquelle commencer à chercher élémentRecherché. Si on utilise une valeur négative, la recherche commencera à partir de la fin du tableau (autrement dit à l'indice array.length - indiceDépart). La valeur par défaut est 0.

Valeur de retour

Un booléen qui vaut true si élémentRecherché est trouvé dans le tableau (à partir de l'indiceDépart si celui-ci est indiqué). Les valeurs -0, +0 et 0 sont considérées comme équivalentes mais false n'est pas considéré comme équivalent à 0.

Note : Pour être tout à fait précis, includes() utilise l'algorithme sameValueZero afin de déterminer si un élément donné est trouvé.

Exemples

[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

['a', 'b', 'c'].includes('c', 5);    // false
['a', 'b', 'c'].includes('c', -100); // true

indiceDépart est supérieur ou égal à la longueur du tableau

SI indiceDépart est supérieur ou égal à la longueur du tableau, la méthode retourne false. Le tableau n'est pas parcouru.

var arr = ['a', 'b', 'c'];

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

indiceDépart est strictement négatif

Si indiceDépart est strictement négatif, l'indice de départ effectif est la somme entre la taille du tableau et indiceDépart. Si cette somme est toujours négative, le tableau est intégralement parcouru.

// Le tableau a une taille de 3
// indiceDépart vaut -2
// L'indice de départ effectif vaut is 3 + (-2) = 1

var arr = ['a', 'b', 'c'];

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

Prothèse d'émulation (polyfill)

// https://tc39.github.io/ecma262/#sec-array.prototype.includes
if (!Array.prototype.includes) {
  Object.defineProperty(Array.prototype, 'includes', {
    value: function(searchElement, fromIndex) {

      if (this == null) {
        throw new TypeError('"this" est nul ou non défini');
      }

      // 1. Soit o égal à ? Object(cette valeur).
      var o = Object(this);

      // 2. Soit len égal à ? Length(? Get(o, "length")).
      var len = o.length >>> 0;

      // 3. Si len = 0, renvoyer "false".
      if (len === 0) {
        return false;
      }

      // 4. Soit n = ? ToInteger(fromIndex).
      // Pour la cohérence du code, on gardera le nom anglais "fromIndex" pour la variable auparavant appelée "indiceDépart"
      //    (Si fromIndex n'est pas défini, cette étape produit la valeur 0.)
      var n = fromIndex | 0;

      // 5. Si n ≥ 0,
      //  a. Alors k = n.
      // 6. Sinon, si n < 0,
      //  a. Alors k = len + n.
      //  b. Si k < 0, alors k = 0.
      var k = Math.max(n >= 0 ? n : len - Math.abs(n), 0);

      function sameValueZero(x, y) {
        return x === y || (typeof x === 'number' && typeof y === 'number' && isNaN(x) && isNaN(y));
      }

      // 7. Répéter tant que k < len
      while (k < len) {
        // a. Soit elementK le résultat de ? Get(O, ! ToString(k)).
        // b. Si SameValueZero(searchElement, elementK) est vrai, renvoyer "true".
        if (sameValueZero(o[k], searchElement)) {
          return true;
        }
        // c. Augmenter la valeur de k de 1. 
        k++;
      }

      // 8. Renvoyer "false"
      return false;
    }
  });
}

Spécifications

Spécification État Commentaires
ECMAScript 2016 (ECMA-262)
La définition de 'Array.prototype.includes' dans cette spécification.
Standard Définition initiale.
ECMAScript Latest Draft (ECMA-262)
La définition de 'Array.prototype.includes' dans cette spécification.
Projet  

Compatibilité des navigateurs

Update compatibility data on GitHub
OrdinateurMobileServeur
ChromeEdgeFirefoxInternet ExplorerOperaSafariWebview AndroidChrome pour AndroidEdge MobileFirefox pour AndroidOpera pour AndroidSafari pour iOSSamsung InternetNode.js
Support simpleChrome Support complet 47Edge Support complet 14Firefox Support complet 43IE Aucun support NonOpera Support complet 34Safari Support complet 9WebView Android Support complet OuiChrome Android Support complet OuiEdge Mobile Support complet 14Firefox Android Support complet 43Opera Android Support complet 34Safari iOS Support complet 9Samsung Internet Android Support complet Ouinodejs Support complet 6.0.0
Support complet 6.0.0
Support complet 5.0.0
Désactivée
Désactivée From version 5.0.0: this feature is behind the --harmony runtime flag.

Légende

Support complet  
Support complet
Aucun support  
Aucun support
Une action explicite de l'utilisateur est nécessaire pour activer cette fonctionnalité.
Une action explicite de l'utilisateur est nécessaire pour activer cette fonctionnalité.

Voir aussi

Étiquettes et contributeurs liés au document

Contributeurs à cette page : SphinxKnight, MetaAnr, EtiennePY, rougepied, ghusse, vision-4, fscholz
Dernière mise à jour par : SphinxKnight,