通讀Cheerio文檔

前言

cheerio是一款非常實(shí)用的nodejs第三方包，適用于服務(wù)端（nodejs端）處理html。它有著與jquery及其相似（幾乎是一致）的api，速度飛快，使用靈活，而且不僅能夠處理html，同樣也能處理xml。

本文主要的參考文檔就是cheerio的官方文檔，基本上就是它的翻譯。

APIs

cheerio文檔的api我將其分為以下幾個(gè)方面，包括

• 加載（loading）
• 選擇器（selectors）
• 屬性操作（attributes）
• 結(jié)構(gòu)推導(dǎo)（traversing）
• 結(jié)構(gòu)操作（manipulation）
• 實(shí)用方法（Miscellaneous & Utilities）

在具體講述各個(gè)api之前，我們給出一份html代碼，這份html代碼將會(huì)是我們下面所有api操作的示例代碼。

<ul id="fruits">
    <li class="apple">Apple</li>
    <li class="orange">Orange</li>
    <li class="pear">Pear</li>
</ul>

加載（loading）

在使用cheerio進(jìn)行各種操作之前，我們需要首先加載一份html得到一個(gè)cherrio對(duì)象。比如

var cheerio = require('cheerio');
var $ = cheerio.load('<ul>...</ul>');

因?yàn)閏heerio與jquery有著極其相似的語(yǔ)法，所以我們一般將得到的cheerio對(duì)象命名為$，裝作它就是jquery對(duì)象，反正基本上用法都一樣。

除了.load()方法之外，我們還可以使用$( selector, [context], [root] )這個(gè)api來(lái)獲得部分html節(jié)點(diǎn)作為cheerio對(duì)象。比如

var $ = require('cheerio');
var t1 = $('ul', '<ul id = "fruits">...</ul>');
var t2 = $('li', 'ul', '<ul id = "fruits">...</ul>');

其中第一個(gè)參數(shù)就是我們獲取的目標(biāo)參數(shù)。所以t1得到是ul標(biāo)簽封裝的cheerio對(duì)象，t2得到是3個(gè)li標(biāo)簽封裝的cheerio對(duì)象的集合。

此外，我們?cè)诩虞dhtml時(shí)還可以設(shè)置一些配置參數(shù)，比如

$ = cheerio.load('<ul id = "fruits">...</ul>', {
    ignoreWhitespace: true,
    xmlMode: true
});

關(guān)于cheerio的配置，一般我們用的較少，它默認(rèn)的配置如下，

{
    ignoreWhitespace: false, // 是否忽略空白符
    xmlMode: false, // 是否是解析xml文檔
    lowerCaseTags: false // 是否采用xml模式處理。這將會(huì)影響部分tag的處理。
}

關(guān)于cheerio配置的更多內(nèi)容，請(qǐng)參考這里和這里。

選擇器（selectors）

cheerio的選擇器基本上跟jquery擁有一致的用法。如果你熟悉jquery，那你將會(huì)倍感親切。

$(selector, [context], [root])

其中selector是目標(biāo)選擇器，context是目標(biāo)選擇器的上下文，root是上下文context的上下文。selector和context可以是字符串表達(dá)式、dom元素、dom元素集合、cheerio對(duì)象，而root一般都是html文檔字符串。

一般地，我們通過(guò)cheerio操作html，都是以上面的這個(gè)api得到目標(biāo)元素的cheerio對(duì)象開(kāi)始，然后再進(jìn)行各種操作。比如

$('.apple', '#fruits').text()； //=> Apple
$('ul .pear').attr('class')； //=> pear
$('li[class=orange]').html()； //=> <li class="orange">Orange</li>

屬性操作（attributes）

cheerio提供了操作元素屬性的一系列方法。

.attr(name[, value])

這個(gè)方法很簡(jiǎn)單，第二個(gè)參數(shù)是可選的。當(dāng)只有第一個(gè)參數(shù)時(shí)表示獲取屬性的值，當(dāng)有帶有第二個(gè)參數(shù)時(shí)，表示設(shè)置屬性的值。

$('ul').attr('id'); //=> fruits
$('.apple').attr('id', 'favorite').html();
//=> <li class="apple" id="favorite">Apple</li>

.removeAttr(name)

通過(guò)name移除某一個(gè)屬性，同時(shí)返回被移除的這個(gè)元素。

$('.pear').removeAttr('class').html();
//=> <li>Pear</li>

.hasClass(className)

判斷某元素的class中是否包含className。

$('.pear').hasClass('pear'); //=> true
$('apple').hasClass('fruit'); //=> false
$('li').hasClass('pear'); //=> true

.addClass(className)

給某元素添加一個(gè)名為className的樣式名。

$('.pear').addClass('fruit').html();
//=> <li class = "pear fruit">Pear</li>
$('.apple').addClass('fruit red').html();
//=> <li class = "apple fruit red">Apple</li>

.removeClass(className)

將某元素上名為className的樣式名移除。如果不存在className，則移除所有的樣式名。

$('.pear').removeClass('pear').html();
//=> <li class="">Pear</li>
$('.apple').addClass('red').removeClass().html();
//=> <li class="">Apple</li>

結(jié)構(gòu)推導(dǎo)（traversing）

可以像使用jquery那樣使用cheerio，通過(guò)某一個(gè)元素來(lái)獲取它的父元素、子元素、兄弟元素等等。

.find(selector)

在某元素下查詢滿足選擇條件的元素。

$('#fruits').find('li').length; //=> 3

.parent()

獲取某元素的父元素。

$('.pear').parent().attr('id'); //=> fruits

.next()

獲取某元素的下一個(gè)兄弟元素。

$('.apple').next().hasClass('orange'); //=> true

.perv()

獲取某元素的上一個(gè)兄弟元素。

$('.orange').prev().hasClass('apple'); //=> true

.siblings()

獲取某元素的所有同級(jí)元素。（當(dāng)然除了它自己）

$('.pear').siblings().length; //=> 2

.children([selector])

獲取某元素的孩子節(jié)點(diǎn)?？梢詡魅?yún)?shù)在所有的孩子節(jié)點(diǎn)中進(jìn)行篩選。

$('#fruits').children().length; //=> 3
$('#fruits').children('.pear').text(); //=> Pear

.each(function(index, element){...})

和jquery類(lèi)似的each迭代器，對(duì)每一個(gè)元素進(jìn)行處理。

var fruits = [];
$('li').each(function(i, elem) {
    fruits[i] = $(this).text();
});
fruits.join(', '); //=> Apple, Orange, Pear

.map(function(index, element){...})

和jquery類(lèi)似的each迭代器，對(duì)每一個(gè)元素進(jìn)行處理并返回一個(gè)值。

$('li').map(function(i, el) {
    // this === el
    return $(this).attr('class');
}).get().join(', '); //=> apple, orange, pear

.filter(selector) & .filter(function(index))

在cheerio對(duì)象集合中進(jìn)行條件篩選。

$('li').filter('.orange').attr('class'); //=> orange
$('li').filter(function(i, el) {
  // this === el
  return $(this).attr('class') === 'orange';
}).attr('class') //=> orange

.first()

獲取cheerio集合中的第一個(gè)cheerio對(duì)象。

$('#fruits').children().first().text(); //=> Apple

.last()

獲取cheerio集合中的最后一個(gè)cheerio對(duì)象。

$('#fruits').children().last().text(); //=> Pear

.eq(i)

根據(jù)索引獲取cheerio集合中的某一個(gè)對(duì)象。參數(shù)可以使負(fù)數(shù)，表示從尾部開(kāi)始索引。

$('li').eq(0).text(); //=> Apple
$('li').eq(-1).text(); //=> Pear

結(jié)構(gòu)操作（manipulation）

cheerio提供一系列修改dom結(jié)構(gòu)的方法。

.append(content, [content, ...])

將content插入到某元素中作為該元素的最后一個(gè)子元素。

$('ul').append('<li class = "plum">Plum</li>');
$.html();
// <ul id = "fruits">
//     <li class = "apple">Apple</li>
//     <li class = "orange">Orange</li>
//     <li class = "pear">Pear</li>
//     <li class = "plum">Plum</li>
// </ul>

.prepend(content, [content, ...])

將content插入到某元素中作為該元素的第一個(gè)子元素。

$('ul').prepend('<li class = "plum">Plum</li>');
$.html();
// <ul id = "fruits">
//     <li class = "plum">Plum</li>
//     <li class = "apple">Apple</li>
//     <li class = "orange">Orange</li>
//     <li class = "pear">Pear</li>
// </ul>

.after(content, [content, ...])

將content插入到某元素的后面，并作為其后面第一個(gè)兄弟節(jié)點(diǎn)。

$('.apple').after('<li class = "plum">Plum</li>');
$.html();
// <ul id = "fruits">
//     <li class = "apple">Apple</li>
//     <li class = "plum">Plum</li>
//     <li class = "orange">Orange</li>
//     <li class = "pear">Pear</li>
// </ul>

.before(content, [content, ...])

將content插入到某元素的前面，并作為其前面的第一個(gè)兄弟節(jié)點(diǎn)。

$('.apple').before('<li class = "plum">Plum</li>');
$.html();
// <ul id = "fruits">
//     <li class = "plum">Plum</li>
//     <li class = "apple">Apple</li>
//     <li class = "orange">Orange</li>
//     <li class = "pear">Pear</li>
// </ul>

.remove([selector])

移除某一個(gè)節(jié)點(diǎn)以及他們的孩子節(jié)點(diǎn)。

$('.pear').remove();
$.html();
// <ul id = "fruits">
//     <li class = "apple">Apple</li>
//     <li class = "orange">Orange</li>
// </ul>

.replaceWith(content)

替換匹配的節(jié)點(diǎn)。

var plum = $('<li class = "plum">Plum</li>');
$('.pear').replaceWith(plum);
$.html();
// <ul id = "fruits">
//    <li class = "apple">Apple</li>
//    <li class = "orange">Orange</li>
//    <li class = "plum">Plum</li>
// </ul>

.empty()

清空一個(gè)節(jié)點(diǎn)，移除其所有的孩子節(jié)點(diǎn)。

$('ul').empty();
$.html();
// <ul id = "fruits"></ul>

.html([htmlString])

獲取某節(jié)點(diǎn)的html字符串。如果傳入?yún)?shù)，則設(shè)置該元素的html結(jié)構(gòu)。

$('.orange').html(); //=> Orange
$('#fruits').html('<li class = "mango">Mango</li>').html();
//=> <li class="mango">Mango</li>

.text([textString])

獲取某節(jié)點(diǎn)的純文本。

$('.orange').text();
//=> Orange
$('ul').text();
//=>  Apple
//    Orange
//    Pear

實(shí)用方法（Miscellaneous & Utilities）

.toArray()

將cheerio對(duì)象集合轉(zhuǎn)換成真正的數(shù)據(jù)結(jié)構(gòu)。

$('li').toArray();
//=> [ {...}, {...}, {...} ]

.clone()

克隆一個(gè)節(jié)點(diǎn)。

var moreFruit = $('#fruits').clone();

$.root

對(duì)某一cheerio對(duì)象的根節(jié)點(diǎn)進(jìn)行相關(guān)操作。

$.root().append('<ul id="vegetables"></ul>').html();
//=> <ul id="fruits">...</ul><ul id="vegetables"></ul>

$.contains(container, contained)

檢查container中是否是否包含contained元素。

$.contains('#fruits', '.pear'); // => true