Cheerio JavaScript (Node.js) : méthodes, exemples…

Qu'est-ce que Cheerio et pourquoi l'utiliser ?

Cheerio est une bibliothèque rapide, flexible et légère pour analyser (parser) du HTML et du XML côté serveur avec Node.js. Elle offre aux développeurs une syntaxe puissante, similaire à jQuery, pour naviguer, rechercher et manipuler l'arbre DOM. Si vous avez déjà utilisé jQuery dans un navigateur, Cheerio vous semblera intuitif — Cheerio implémente un sous-ensemble de jQuery, adapté à une utilisation serveur.

Les principaux cas d'utilisation de Cheerio :

Web Scraping : Extraire des données de pages web (prix, titres d'actualités, contenu d'articles).
Tests : Vérifier la structure de templates HTML dans des tests unitaires sans navigateur réel.
Prétraitement HTML : Nettoyer, transformer et extraire des parties de documents HTML avant de les envoyer au client.
Analyse de flux RSS/XML : Traiter des documents XML, bien qu'il existe des outils plus spécialisés pour le XML.

Contrairement à un moteur de navigateur complet (comme Puppeteer ou Playwright), Cheerio ne rend pas le JavaScript, ne charge pas le CSS, les images ou les ressources externes. Cela le rend extrêmement rapide et économe en mémoire. Cheerio travaille sur une chaîne HTML déjà prête, que vous obtenez par exemple via une requête HTTP (avec axios, node-fetch ou le module http/https intégré).

Installation de Cheerio

L'installation de Cheerio dans un projet Node.js se fait via le gestionnaire de paquets npm (ou yarn). Ouvrez un terminal à la racine de votre projet et exécutez :

npm install cheerio

Si vous utilisez yarn :

yarn add cheerio

Après l'installation, vous pouvez importer la bibliothèque dans votre code :

const cheerio = require('cheerio');
// ou pour les modules ES :
// import * as cheerio from 'cheerio';

Notez bien : Cheerio est une bibliothèque pour Node.js et n'est pas conçue pour fonctionner dans un navigateur. Si vous devez parser du HTML côté client, utilisez plutôt le DOMParser natif.

Premiers pas : premier exemple

Écrivons un script simple qui charge une chaîne HTML, trouve tous les liens et affiche leur texte et leur attribut href.

const cheerio = require('cheerio');

// Exemple de code HTML (vous l'obtenez généralement via une requête HTTP)
const html = `
<html>
<head><title>Page d'exemple</title></head>
<body>
    <h1>Bienvenue !</h1>
    <ul>
        <li><a href="https://example.com">Lien 1</a></li>
        <li><a href="https://google.com">Lien 2</a></li>
        <li class="special"><a href="https://github.com">Lien 3</a></li>
    </ul>
</body>
</html>
`;

// Charger le HTML dans Cheerio
const $ = cheerio.load(html);

// Trouver toutes les balises <a> et les parcourir
$('a').each((index, element) => {
    const text = $(element).text();       // Texte à l'intérieur de la balise
    const href = $(element).attr('href'); // Valeur de l'attribut href
    console.log(`${index + 1}. ${text} - ${href}`);
});

// Résultat :
// 1. Lien 1 - https://example.com
// 2. Lien 2 - https://google.com
// 3. Lien 3 - https://github.com

Comme vous le voyez, la syntaxe est très proche de jQuery : nous utilisons la fonction $() pour sélectionner des éléments, puis les méthodes .text(), .attr(), .each() pour les manipuler.

Méthodes et fonctions essentielles de Cheerio

Voici une analyse détaillée de 10 méthodes clés de Cheerio avec descriptions, paramètres et exemples.

1. `cheerio.load(html, options?)`

Fonction : Charge une chaîne HTML et retourne la fonction principale $, via laquelle vous interagissez avec le DOM. C'est le point d'entrée de la bibliothèque.

Paramètres :

html (string) : Le code HTML ou XML à analyser.
options (objet, optionnel) : Options de configuration, comme decodeEntities (décoder les entités HTML) ou xmlMode (activer le mode XML).

Exemple :

const $ = cheerio.load('<h1>Bonjour le monde</h1>');
console.log($('h1').text()); // Affiche : Bonjour le monde

2. `$(selector, [context])`

Fonction : Sélectionne des éléments dans le DOM en fonction d'un sélecteur CSS. Retourne un objet Cheerio (similaire à un objet jQuery).

Paramètres :

selector (string) : Sélecteur CSS (ex: 'div', '.classe', '#id', 'ul > li').
context (élément Cheerio, optionnel) : Élément racine pour limiter la recherche.

Exemple :

const $ = cheerio.load('<ul><li>Item 1</li><li>Item 2</li></ul>');
const items = $('li'); // Sélectionne tous les <li>
console.log(items.length); // 2

3. `.text([value])`

Fonction : Obtient ou définit le contenu textuel combiné des éléments sélectionnés (y compris celui des éléments enfants).

Paramètres :

value (string, optionnel) : Si fourni, remplace le texte de tous les éléments sélectionnés.

Exemple :

const $ = cheerio.load('<p>Texte <strong>important</strong></p>');
console.log($('p').text()); // "Texte important"
$('p').text('Nouveau texte');
console.log($('p').text()); // "Nouveau texte"

4. `.html([value])`

Fonction : Obtient ou définit le contenu HTML (balises incluses) du premier élément sélectionné.

Paramètres :

value (string, optionnel) : Si fourni, remplace le contenu HTML.

Exemple :

const $ = cheerio.load('<div><p>Bonjour</p></div>');
console.log($('div').html()); // "<p>Bonjour</p>"
$('div').html('<span>Nouveau</span>');
console.log($('div').html()); // "<span>Nouveau</span>"

5. `.attr(name, [value])`

Fonction : Obtient ou définit la valeur d'un attribut pour le premier élément sélectionné.

Paramètres :

name (string) : Nom de l'attribut (ex: 'href', 'class', 'src').
value (string, optionnel) : Si fourni, définit la valeur de l'attribut.

Exemple :

const $ = cheerio.load('<a href="https://exemple.com">Lien</a>');
console.log($('a').attr('href')); // "https://exemple.com"
$('a').attr('href', 'https://nouveau-site.com');
console.log($('a').attr('href')); // "https://nouveau-site.com"

6. `.each(function(index, element))`

Fonction : Parcourt chaque élément de la sélection et exécute une fonction pour chacun.

Paramètres :

function(index, element) : Fonction de rappel. index est la position (0, 1, 2...), element est l'élément DOM brut.

Exemple :

const $ = cheerio.load('<ul><li>A</li><li>B</li><li>C</li></ul>');
$('li').each((i, el) => {
    console.log(`${i}: ${$(el).text()}`);
});
// 0: A
// 1: B
// 2: C

7. `.find(selector)`

Fonction : Recherche les éléments descendants correspondant au sélecteur, à partir des éléments sélectionnés.

Paramètres :

selector (string) : Sélecteur CSS.

Exemple :

const $ = cheerio.load('<div><p>Texte</p></div>');
const p = $('div').find('p');
console.log(p.text()); // "Texte"

8. `.children([selector])`

Fonction : Obtient les enfants directs des éléments sélectionnés. Si un sélecteur est fourni, filtre les enfants.

Paramètres :

selector (string, optionnel) : Sélecteur CSS pour filtrer les enfants.

Exemple :

const $ = cheerio.load('<ul><li>1</li><li>2</li></ul>');
const enfants = $('ul').children();
console.log(enfants.length); // 2

9. `.parent()`

Fonction : Obtient le parent direct de chaque élément sélectionné.

Exemple :

const $ = cheerio.load('<div><p>Texte</p></div>');
const parent = $('p').parent();
console.log(parent[0].tagName); // "div"

10. `.remove()`

Fonction : Supprime les éléments sélectionnés du DOM.

Exemple :

const $ = cheerio.load('<div><p>Gardé</p><span>Supprimé</span></div>');
$('span').remove();
console.log($.html()); // "<div><p>Gardé</p></div>"

Conclusion

Cheerio est un outil indispensable pour tout développeur Node.js travaillant avec du HTML côté serveur. Sa simplicité, sa rapidité et sa syntaxe familière (inspirée de jQuery) en font le choix idéal pour le web scraping, les tests et le prétraitement de templates. Essayez-le dans votre prochain projet et découvrez sa puissance !