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.
Le code source de cet exemple interactif est disponible dans un dépôt GitHub. Si vous souhaitez contribuez à ces exemples, n'hésitez pas à cloner https://github.com/mdn/interactive-examples et à envoyer une pull request !
Voir aussi la méthode findIndex()
qui renvoie l'index de l'élément trouvé et non sa valeur. Si on souhaite repérer la position d'un élément donné dans le tableau, on pourra utiliser Array.prototype.indexOf()
. Si on souhaite déterminer si un tableau contient un élément donné, on pourra utiliser la méthode Array.prototype.includes()
.
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.
index
Facultatif- L'index de l'élément actuellement traité dans le tableau
array
Facultatif- 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 fonctioncallback
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
Ordinateur | Mobile | Serveur | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Support simple | Chrome Support complet 45 | Edge Support complet Oui | Firefox Support complet 25 | IE Aucun support Non | Opera Support complet 32 | Safari Support complet 8 | WebView Android Support complet Oui | Chrome Android Support complet Oui | Edge Mobile Support complet Oui | Firefox Android Support complet 4 | Opera Android Support complet Oui | Safari iOS Support complet 8 | Samsung Internet Android Support complet Oui | nodejs
Support complet
4.0.0
|
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
Array.prototype.findIndex()
– trouver et renvoyer un indexArray.prototype.includes()
– tester si une valeur existe dans le tableauArray.prototype.filter()
– trouver tous les éléments correspondantsArray.prototype.every()
– tester l'ensemble des éléments d'un tableauArray.prototype.some()
– tester si au moins un élément du tableau respecte un critère