String.prototype.includes()

La méthode includes() détermine si une chaîne de caractères est contenue dans une autre et renvoie true ou false selon le cas de figure.

Syntaxe

str.includes(chaîneRecherchée);
str.includes(chaîneRecherchée, position);

Paramètres

chaîneRecherchée
Une chaîne à rechercher dans la chaîne courante.
position Facultatif
La position dans la chaîne à partir de laquelle commencera la recherche. La valeur par défaut de position est 0.

Valeur de retour

true si la chaîne de caractères contient la sous-chaîne recherchée, false sinon.

Description

Cette méthode détermine si une chaîne de caractères est contenue dans une autre.

Sensibilité à la case

includes() est sensible à la casse. Par exemple, l'expression suivante nous retournera false :

'Baleine bleue'.includes('baleine'); // false

Exemples

Utiliser includes()

const str = "Être ou ne pas être, telle est la question.";

console.log(str.includes("Être"));       // true
console.log(str.includes("question"));   // true
console.log(str.includes("pléonasme"));  // false
console.log(str.includes("Être", 1));    // false
console.log(str.includes("ÊTRE"));       // false
console.log(str.includes(""));       // true

Prothèse d'émulation (polyfill)

Cette méthode a été ajoutée à la spécification ECMAScript 2015 et n'est peut-être pas encore disponible dans toutes les implémentations JavaScript.

Cependant, vous pouvez facilement polyfill cette méthode pour de vieux navigateurs :

if (!String.prototype.includes) {
  String.prototype.includes = function(search, start) {
    'use strict';

    if (search instanceof RegExp) {
      throw TypeError('first argument must not be a RegExp');
    } 
    if (start === undefined) { start = 0; }
    return this.indexOf(search, start) !== -1;
  };
}

Spécifications

Spécification État Commentaires
ECMAScript (ECMA-262)
La définition de 'String.prototype.includes' dans cette spécification.
Standard évolutif
ECMAScript 2015 (6th Edition, ECMA-262)
La définition de 'String.prototype.includes' dans cette spécification.
Standard Définition initiale.

Compatibilité du navigateur

Update compatibility data on GitHub
OrdinateurMobileServeur
ChromeEdgeFirefoxInternet ExplorerOperaSafariWebview AndroidChrome pour AndroidFirefox pour AndroidOpera pour AndroidSafari sur iOSSamsung InternetNode.js
includesChrome Support complet 41Edge Support complet 12Firefox Support complet 40
Support complet 40
Aucun support 18 — 48
Autre nom
Autre nom Cette fonctionnalité utilise le nom non-standard : contains
IE Aucun support NonOpera Support complet 28Safari Support complet 9WebView Android Support complet 41Chrome Android Support complet 41Firefox Android Support complet 40
Support complet 40
Aucun support 18 — 48
Autre nom
Autre nom Cette fonctionnalité utilise le nom non-standard : contains
Opera Android Support complet 28Safari iOS Support complet 9Samsung Internet Android Support complet 4.0nodejs Support complet 4.0.0

Légende

Support complet  
Support complet
Aucun support  
Aucun support
Cette fonctionnalité utilise un nom non-standard.
Cette fonctionnalité utilise un nom non-standard.

String.prototype.contains

Les versions de Firefox allant de Firefox 18 à Firefox 39 utilisent cette méthode avec le nom contains(). Cette méthode a été renommée en includes() via bug 1102219 pour la raison suivante :

Il a été rapporté que certains sites web utilisant MooTools 1.2 plantaient sur Firefox 17. Cette version de MooTools vérifie que String.prototype.contains() existe bien, et si ce n'est pas le cas, ajoute sa propre fonction similaire. Avec l'introduction de cette fonction dans Firefox 17, le comportement de ce contrôle a changé de telle manière qu'il cause un plantage du code de MooTools implémenté pour String.prototype.contains(). En conséquence, cette implémentation a été désactivée de Firefox 17. String.prototype.contains() est ainsi disponible sur une version ultérieure : Firefox 18 lorsque MooTools a déclenché la sortie de la version 1.2.6.

MooTools 1.3 force sa propre version de String.prototype.includes(), les sites Web l'implémentant ne sont donc pas perturbés. Néanmoins, il faut noter que les signatures des méthodes diffèrent entre MooTools 1.3 et ECMAScript 2015 (pour le second paramètre). MooTools 1.5+ a modifié sa signature afin de prendre en compte le standard de ES2015.

Dans Firefox 48, la méthode String.prototype.contains() a été retirée. String.prototype.includes() doit être utilisée à la place.

Voir aussi