Documentação do Cheerio v1.2.0

Cheerio é uma biblioteca rápida, flexível e elegante para analisar e manipular HTML e XML no lado do servidor. Ela implementa um subconjunto da funcionalidade principal do jQuery, fornecendo uma API familiar para desenvolvedores enquanto é otimizada para ambientes do lado do servidor.

Recursos da Versão Atual (1.2.0)

Métodos de Carregamento Principais

A versão atual oferece várias maneiras poderosas de carregar e analisar documentos 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());
  }
});

Suporte Aprimorado ao TypeScript

A versão 1.2.0 inclui definições abrangentes de TypeScript com segurança de tipos melhorada:

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

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

Nova API Extract

Um novo recurso poderoso para extração de dados de documentos HTML:

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

Manipulação Avançada de URL

Suporte aprimorado para resolução de URL com 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

Recursos Principais por Categoria

Manipulação do DOM

• Seleção de elementos no estilo jQuery com seletores CSS
• Manipulação abrangente de atributos e propriedades
• Suporte completo para métodos de navegação do DOM
• Inserção, remoção e modificação de elementos

Manipulação de Formulários

// 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 e Estilos

// 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');

Atributos de Dados

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

Migração de Versões Anteriores

Da 0.x para 1.x

• Breaking: Node.js 12+ obrigatório (removido suporte para versões anteriores)
• Breaking: Algumas APIs internas foram alteradas
• Melhorado: Melhor suporte ao TypeScript em geral
• Novo: Análise baseada em stream para melhor eficiência de memória

Principais Mudanças a Observar

// 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);

Melhorias de Performance

A versão 1.2.0 inclui melhorias significativas de performance:

• Análise mais rápida: Parser HTML melhorado com melhor tratamento de erros
• Eficiência de memória: Redução do uso de memória para documentos grandes
• Suporte a streaming: Processa documentos grandes sem carregar inteiramente na memória

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

Recursos Avançados

Opções de Parser Personalizadas

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

Carregamento via Rede com Opções

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

Melhores Práticas

1. Use TypeScript: Aproveite as definições de tipos abrangentes
2. Faça stream de documentos grandes: Use APIs de streaming para melhor gerenciamento de memória
3. Aproveite a API extract: Use o novo método extract para extração estruturada de dados
4. Defina baseURI: Ao fazer scraping de sites, defina baseURI para resolução adequada de URL

Diferenças entre Navegador e Servidor

Cheerio é projetado para uso no lado do servidor e remove recursos específicos do navegador do jQuery enquanto adiciona funcionalidades otimizadas para servidor como:

• Sem inconsistências do DOM do navegador
• Melhor tratamento de erros para HTML malformado
• Análise eficiente em memória
• Capacidades de processamento em stream
• Detecção automática de codificação

Isso torna o Cheerio ideal para web scraping, renderização do lado do servidor e quaisquer tarefas de processamento HTML/XML em ambientes Node.js.