Documentation Cheerio v1.2.0

Cheerio est une bibliothèque rapide, flexible et élégante pour analyser et manipuler HTML et XML côté serveur. Elle implémente un sous-ensemble des fonctionnalités principales de jQuery, fournissant une API familière aux développeurs tout en étant optimisée pour les environnements serveur.

Fonctionnalités de la version actuelle (1.2.0)

Méthodes principales de chargement

La version actuelle fournit plusieurs façons puissantes de charger et analyser les documents HTML/XML :

import * as cheerio from 'cheerio';

// Basic loading from string
const $ = cheerio.load('<h2 class="title">Hello world</h2>');

// Loading from buffer with encoding detection
const buffer = fs.readFileSync('index.html');
const $ = cheerio.loadBuffer(buffer);

// Loading from URL with automatic encoding detection
const $ = await cheerio.fromURL('https://example.com');

// Stream-based loading for large documents
const stream = cheerio.stringStream({}, (err, $) => {
  if (!err) {
    console.log($('h1').text());
  }
});

Prise en charge TypeScript améliorée

La version 1.2.0 inclut des définitions TypeScript complètes avec une sécurité de type améliorée :

import { CheerioAPI, Cheerio, Element } from 'cheerio';

// Strongly typed element selection
const $: CheerioAPI = cheerio.load(html);
const elements: Cheerio<Element> = $('.my-class');

Nouvelle API Extract

Une nouvelle fonctionnalité puissante pour l'extraction de données depuis les documents HTML :

const data = $root.extract({
  title: 'h1',
  links: [{ selector: 'a', value: 'href' }],
  metadata: {
    selector: '.meta',
    value: {
      author: '.author',
      date: '.date'
    }
  }
});

Gestion avancée des URL

Prise en charge améliorée de la résolution d'URL avec baseURI :

const $ = cheerio.load(html, { 
  baseURI: 'https://example.com/page/' 
});

// Automatically resolves relative URLs
$('a').prop('href'); // Returns absolute URL
$('img').prop('src'); // Returns absolute URL

Fonctionnalités principales par catégorie

Manipulation du DOM

• Sélection d'éléments de style jQuery avec des sélecteurs CSS
• Manipulation complète des attributs et propriétés
• Prise en charge complète des méthodes de parcours du DOM
• Insertion, suppression et modification d'éléments

Gestion des formulaires

// Serialize forms to URL-encoded strings
$('form').serialize(); // 'name=value&email=test@example.com'

// Get form data as structured arrays
$('form').serializeArray();
// [{ name: 'username', value: 'john' }, ...]

CSS et stylisation

// Get/set CSS properties
$('.element').css('color', 'red');
$('.element').css(['margin', 'padding']); // Get multiple properties

// Class manipulation
$('.item').addClass('active selected');
$('.item').removeClass('old-class');
$('.item').toggleClass('visible');

Attributs de données

// HTML5 data-* attribute support with automatic type coercion
$('.widget').data('config'); // Parses JSON automatically
$('.widget').data('count', 42); // Set data programmatically

Migration depuis les anciennes versions

De 0.x vers 1.x

• Breaking : Node.js 12+ requis (suppression du support des versions antérieures)
• Breaking : Certaines API internes ont changé
• Amélioré : Meilleur support TypeScript dans l'ensemble
• Nouveau : Analyse basée sur les flux pour une meilleure efficacité mémoire

Changements principaux à surveiller

// Old way (0.x) - still works but discouraged
const cheerio = require('cheerio');
const $ = cheerio.load(html);

// New way (1.x) - recommended
import * as cheerio from 'cheerio';
const $ = cheerio.load(html);

Améliorations de performance

La version 1.2.0 inclut des améliorations de performance significatives :

• Analyse plus rapide : Analyseur HTML amélioré avec une meilleure gestion d'erreurs
• Efficacité mémoire : Empreinte mémoire réduite pour les documents volumineux
• Support de streaming : Traitement des documents volumineux sans chargement complet en mémoire

// Stream processing for large files
const stream = cheerio.decodeStream({
  encoding: { defaultEncoding: 'utf8' }
}, (err, $) => {
  // Process document as it streams
});

Fonctionnalités avancées

Options d'analyseur personnalisées

const $ = cheerio.load(html, {
  xmlMode: true,        // Parse as XML
  decodeEntities: false, // Don't decode HTML entities
  scriptingEnabled: false // Disable script tag processing
});

Chargement réseau avec options

const $ = await cheerio.fromURL('https://api.example.com/data', {
  requestOptions: {
    headers: { 'User-Agent': 'MyBot/1.0' }
  },
  encoding: { defaultEncoding: 'utf8' }
});

Bonnes pratiques

1. Utilisez TypeScript : Profitez des définitions de type complètes
2. Streamez les documents volumineux : Utilisez les API de streaming pour une meilleure gestion de la mémoire
3. Tirez parti de l'API extract : Utilisez la nouvelle méthode extract pour l'extraction de données structurées
4. Définissez baseURI : Lors du scraping de sites web, définissez baseURI pour une résolution d'URL appropriée

Différences entre navigateur et serveur

Cheerio est conçu pour un usage côté serveur et supprime les fonctionnalités jQuery spécifiques au navigateur tout en ajoutant des fonctionnalités optimisées pour le serveur comme :

• Aucune incohérence DOM du navigateur
• Meilleure gestion d'erreurs pour HTML mal formé
• Analyse efficace en mémoire
• Capacités de traitement en flux
• Détection automatique d'encodage

Cela rend Cheerio idéal pour le web scraping, le rendu côté serveur, et toutes les tâches de traitement HTML/XML dans les environnements Node.js.