🎯 核心概念

1. 加载 HTML

const cheerio = require('cheerio');
const $ = cheerio.load(html, {
  decodeEntities: false,  // 是否解码实体，默认为 true
  xmlMode: false,        // XML 模式，默认为 false
});

2. 选择器类型

// CSS 选择器
$('div.class')           // 类选择器
$('div#id')              // ID 选择器
$('div[data-value]')     // 属性选择器
$('parent > child')      // 子选择器
$('div:first-child')     // 伪类选择器

// 自定义筛选
$('div').filter((i, el) => $(el).text().includes('文本'))
$('div').find('span')    // 后代查找
$('div').children()      // 直接子元素

🔍 精准查找技巧

1. 避免文本匹配污染

// ❌ 错误：可能匹配到父元素
$("div").filter((_, el) => $(el).text().trim() === "目标文本")

// ✅ 正确：确保是直接文本
$("div").filter((_, el) => {
  const $el = $(el);
  // 检查元素是否直接包含文本（没有子元素）
  return $el.children().length === 0 && $el.text().trim() === "目标文本";
})

// ✅ 使用 :contains 配合检查
$("div:contains('目标文本')").filter((_, el) => {
  return $(el).children().length === 0;
})

2. DOM 遍历方法

const $element = $('.target');

// 向上查找
$element.parent()                    // 直接父元素
$element.parents('.container')       // 所有祖先元素中匹配选择器的
$element.closest('.wrapper')         // 最近的匹配祖先

// 向下查找
$element.children('.child')          // 直接子元素
$element.find('.descendant')         // 所有后代元素

// 同级查找
$element.next()                      // 下一个兄弟
$element.nextAll('.sibling')         // 后面所有兄弟
$element.prev()                      // 上一个兄弟
$element.prevAll('.sibling')         // 前面所有兄弟
$element.siblings()                  // 所有兄弟元素

🛠 数据提取技巧

1. 属性提取

// 获取属性
const href = $('a').attr('href');
const data = $('div').data('value');  // data-value 属性

// 获取所有属性
const attrs = $('div').attr();
Object.keys(attrs).forEach(key => {
  if (key.startsWith('data-')) {
    console.log(`数据属性 ${key}: ${attrs[key]}`);
  }
});

// 获取多个元素的属性
const links = $('a').map((i, el) => $(el).attr('href')).get();

2. 文本提取

// 获取元素文本
const text = $('div').text();                     // 包含子元素文本
const ownText = $('div').contents()               // 只获取直接文本
  .filter((_, node) => node.type === 'text')
  .text();

// 获取多个元素文本
const texts = $('li').map((i, el) => $(el).text().trim()).get();

// 获取 HTML
const html = $('div').html();                     // 内部 HTML
const outerHtml = $.html($('div'));               // 外层 HTML

🎨 操作 DOM

1. 修改内容

// 设置内容
$('div').text('新文本');              // 设置文本
$('div').html('<span>新HTML</span>'); // 设置HTML

// 添加内容
$('div').append('<span>追加</span>');  // 内部末尾
$('div').prepend('<span>前插</span>'); // 内部开头
$('div').after('<div>之后</div>');     // 元素之后
$('div').before('<div>之前</div>');    // 元素之前

// 替换元素
$('div').replaceWith('<p>替换</p>');

2. 操作类和属性

// 类操作
$('div').addClass('new-class');
$('div').removeClass('old-class');
$('div').toggleClass('active');
$('div').hasClass('target');          // 返回布尔值

// 属性操作
$('div').attr('title', '新标题');      // 设置
$('div').removeAttr('data-old');       // 删除