Документация Cheerio v1.2.0

Cheerio — это быстрая, гибкая и элегантная библиотека для парсинга и манипуляции HTML и XML на серверной стороне. Она реализует подмножество основной функциональности jQuery, предоставляя знакомый API для разработчиков и будучи оптимизированной для серверных сред.

Возможности текущей версии (1.2.0)

Основные методы загрузки

Текущая версия предоставляет несколько мощных способов загрузки и парсинга 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());
  }
});

Улучшенная поддержка TypeScript

Версия 1.2.0 включает всеобъемлющие определения TypeScript с улучшенной типобезопасностью:

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

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

Новый Extract API

Мощная новая функция для извлечения данных из HTML документов:

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

Продвинутая обработка URL

Улучшенная поддержка разрешения URL с 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

Ключевые возможности по категориям

Манипуляция DOM

Выбор элементов в стиле jQuery с CSS селекторами
Всеобъемлющая манипуляция атрибутами и свойствами
Полная поддержка методов обхода DOM
Вставка, удаление и изменение элементов

Работа с формами

// 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 и стилизация

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

Атрибуты данных

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

Миграция с более старых версий

С 0.x на 1.x

Критическое изменение: Требуется Node.js 12+ (прекращена поддержка более старых версий)
Критическое изменение: Некоторые внутренние API были изменены
Улучшение: Лучшая поддержка TypeScript во всем
Новое: Парсинг на основе потоков для лучшей эффективности памяти

Ключевые изменения, на которые стоит обратить внимание

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

Улучшения производительности

Версия 1.2.0 включает значительные улучшения производительности:

Более быстрый парсинг: Улучшенный HTML парсер с лучшей обработкой ошибок
Эффективность памяти: Уменьшенное потребление памяти для больших документов
Поддержка потоков: Обработка больших документов без полной загрузки в память

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

Продвинутые возможности

Пользовательские опции парсера

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

Сетевая загрузка с опциями

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

Лучшие практики

Используйте TypeScript: Воспользуйтесь преимуществами всеобъемлющих определений типов
Обрабатывайте большие документы потоками: Используйте streaming API для лучшего управления памятью
Используйте extract API: Применяйте новый метод extract для извлечения структурированных данных
Устанавливайте baseURI: При парсинге веб-сайтов устанавливайте baseURI для правильного разрешения URL

Различия между браузером и сервером

Cheerio предназначена для использования на серверной стороне и убирает браузерно-специфичные функции jQuery, добавляя серверно-оптимизированную функциональность, такую как:

Отсутствие браузерных несовместимостей DOM
Лучшая обработка ошибок для некорректного HTML
Эффективный парсинг памяти
Возможности потоковой обработки
Автоматическое определение кодировки

Это делает Cheerio идеальной для веб-скрапинга, серверного рендеринга и любых задач обработки HTML/XML в средах Node.js.

← FAQ