La méthode find() renvoie la valeur du premier élément trouvé dans le tableau qui respecte la condition donnée par la fonction de test passée en argument. Sinon, la valeur undefined est renvoyée.

Voir aussi la méthode findIndex() qui renvoie l'index de l'élément trouvé et non sa valeur.

Syntaxe

arr.find(callback(element[, index[, tableau]])[, thisArg])

Paramètres

callback
Fonction à exécuter sur chaque valeur du tableau, elle prend 3 arguments :
element
L'élément actuellement traité dans le tableau.
indexFacultatif
L'index de l'élément actuellement traité dans le tableau
arrayFacultatif
Le tableau pour lequel la méthode find a été appelée.
thisArg Facultatif
Ce paramètre est optionnel. Objet à utiliser en tant que this lorsque la fonction callback est exécutée.

Valeur de retour

La valeur du premier élément du tableau qui réussit le test, sinon undefined.

Description

La méthode find exécute la fonction callback une fois pour chaque élément présent dans le tableau jusqu'à ce qu'elle retourne une valeur vraie (qui peut être convertie en true). Si un élément est trouvé, find retourne immédiatement la valeur de l'élément. Autrement, find retourne undefined. La méthode callback est seulement appelée pour les index du tableau pour lesquels on dispose d'une valeur. Elle n'est pas appelée pour les index supprimés ou pour ceux qui n'ont pas de valeur.

La méthode callback est appelée avec trois arguments : la valeur de l'élément, l'index de l'élément, et l'objet correspondant au tableau traversé.

Si le paramètre thisArg est fourni à find, il sera utilisé comme le this pour chaque exécution de la fonction callback. S'il n'est pas fourni, alors undefined sera utilisé.

find ne modifie pas le tableau à partir duquel elle est appelée.

L'intervalle des éléments inspectés par find est défini avant la première exécution de callback. Les éléments ajoutés au tableau après l'appel à find ne seront pas inspectés par la fonction callback. Si un élément existant est modifié avant le passage du callback, alors la valeur traitée par le callback sera celle présente lors du passage de find sur son index. Les éléments supprimés ne seront pas traités.

Exemples

Trouver un objet dans un tableau grâce à une de ses propriétés

var inventaire = [
  {nom: 'pommes', quantité: 2},
  {nom: 'bananes', quantité: 0},
  {nom: 'cerises', quantité: 5}
];

function estCerises(fruit) {
  return fruit.nom === 'cerises';
}

console.log(inventaire.find(estCerises));
// { nom: 'cerises', quantité: 5}

Utiliser les fonctions fléchées ES6/ES2015

const inventaire = [
                     {nom: 'pommes', quantité: 2},
                     {nom: 'bananes', quantité: 0},
                     {nom: 'cerises', quantité: 5}
                   ];

const resultat = inventaire.find( fruit => fruit.nom === 'cerises');
console.log(resultat);
// { nom: 'cerises', quantité: 5}

Trouver un nombre premier dans un tableau

Dans l'exemple suivant, on cherche un nombre premier parmi les éléments d'un tableau (ou retourne undefined s'il n'y en a pas ).

function estPremier(element, index, array) {
    var début = 2;
    while (début <= Math.sqrt(element)) {
        if (element % début ++ < 1) return false;
    }
    return (element > 1);
}

console.log( [4, 6, 8, 12].find(estPremier) ); // undefined, rien trouvé
console.log( [4, 5, 8, 12].find(estPremier) ); // 5

Prothèse d'émulation (polyfill)

Cette méthode a été ajoutée avec la spécification ECMAScript 2015 (appelée également ES6) et n'est peut-être pas disponible pour toutes les implémentations de JavaScript. Cependant, vous pouvez émuler le fonctionnement d'Array.prototype.find grâce au code suivant :

// https://tc39.github.io/ecma262/#sec-array.prototype.find
if (!Array.prototype.find) {
  Object.defineProperty(Array.prototype, 'find', {
    value: function(predicate) {
     // 1. Let O be ? ToObject(this value).
      if (this == null) {
        throw new TypeError('"this" is null or not defined');
      }

      var o = Object(this);

      // 2. Let len be ? ToLength(? Get(O, "length")).
      var len = o.length >>> 0;

      // 3. If IsCallable(predicate) is false, throw a TypeError exception.
      if (typeof predicate !== 'function') {
        throw new TypeError('predicate must be a function');
      }

      // 4. If thisArg was supplied, let T be thisArg; else let T be undefined.
      var thisArg = arguments[1];

      // 5. Let k be 0.
      var k = 0;

      // 6. Repeat, while k < len
      while (k < len) {
        // a. Let Pk be ! ToString(k).
        // b. Let kValue be ? Get(O, Pk).
        // c. Let testResult be ToBoolean(? Call(predicate, T, « kValue, k, O »)).
        // d. If testResult is true, return kValue.
        var kValue = o[k];
        if (predicate.call(thisArg, kValue, k, o)) {
          return kValue;
        }
        // e. Increase k by 1.
        k++;
      }

      // 7. Return undefined.
      return undefined;
    },
    configurable: true,
    writable: true
  });
}

Mieux vaut éviter d'utiliser cette prothèse si Object.defineProperty() n'est pas disponible car il n'y a pas d'autre moyen de rendre la méthode non énumérable.

Spécifications

Spécification État Commentaires
ECMAScript 2015 (6th Edition, ECMA-262)
La définition de 'Array.prototype.find' dans cette spécification.
Standard Définition initiale
ECMAScript Latest Draft (ECMA-262)
La définition de 'Array.prototype.find' dans cette spécification.
Projet  

Compatibilité des navigateurs

Update compatibility data on GitHub
OrdinateurMobileServeur
ChromeEdgeFirefoxInternet ExplorerOperaSafariWebview AndroidChrome pour AndroidEdge MobileFirefox pour AndroidOpera pour AndroidSafari sur iOSSamsung InternetNode.js
Support simpleChrome Support complet 45Edge Support complet OuiFirefox Support complet 25IE Aucun support NonOpera Support complet 32Safari Support complet 8WebView Android Support complet OuiChrome Android Support complet OuiEdge Mobile Support complet OuiFirefox Android Support complet 4Opera Android Support complet OuiSafari iOS Support complet 8Samsung Internet Android Support complet Ouinodejs Support complet 4.0.0
Support complet 4.0.0
Support complet 0.12
Désactivée
Désactivée From version 0.12: 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, warpdesign, kdex, goofy_bz, Fredchat, ferncoder
Dernière mise à jour par : SphinxKnight,