这篇参考手册是对cheerio 官方文档 的中文翻译
cheerio是jquery核心功能的一个快速灵活而又简洁的实现，主要是为了用在服务器端需要对DOM进行操作的地方
简介
让你在服务器端和html愉快的玩耍
|
0 1 2 3 4 5 6 7 |
var cheerio = require('cheerio'), $ = cheerio.load('<h2 class = "title">Hello world</h2>'); $('h2.title').text('Hello there!'); $('h2').addClass('welcome'); $.html(); //=> <h2 class = "title welcome">Hello there!</h2> |
安装
|
0 |
npm install cheerio |
特点
- 熟悉的语法：cheerio实现了jQuery的一个子集，去掉了jQuery中所有与DOM不一致或者是用来填浏览器的坑的东西，重现了jQuery最美妙的API
- 快到没朋友：cheerio使用了及其简洁而又标准的DOM模型， 因此对文档的转换，操作，渲染都极其的高效。基本的端到端测试显示它的速度至少是JSDOM的8倍
- 极其灵活：cheerio使用了@FB55编写的非常兼容的htmlparser2，因此它可以解析几乎所有的HTML和XML
关于JSDOM
cheerio产生的原因是出于对JSDOM的失望，主要体现在以下三点：
- JSDOM的解析规则太过于严格：JSDOM的解析器无法处理现在许多的流行网站的内容
- JSDOM太慢了：解析大的网站甚至可以产生可察觉的延迟
- JSDOM太过于重量级：JSDOM的目标是提供与浏览器一样的DOM环境，但是我们往往不需要这样。我们需要的只是一种简单，熟悉的方式来操作我们的HTML
什么时候你应该用JSDOM
cheerio并非万能，当你需要一个浏览器一样的环境时，你最好还是用JSDOM，尤其是你需要进行自动化的功能测试时
API
后面的例子中用到的HTML模板如下：
|
0 1 2 3 4 |
<ul id="fruits"> <li class="apple">Apple</li> <li class="orange">Orange</li> <li class="pear">Pear</li> </ul> |
1. 解析html（load）
首先你需要先加载你的HTML。jQuery会自动完成这一步，因为jQuery操作的DOM是固定的。但是在使用cheerio时我们要手动加载我们的HTML文档
首选的方式如下：
|
0 1 |
var cheerio = require('cheerio'), $ = cheerio.load('<ul id = "fruits">...</ul>'); |
其次，直接把HTML字符串作为上下文也是可以的：
|
0 1 |
$ = require('cheerio'); $('ul', '<ul id = "fruits">...</ul>'); |
或者把HTML字符串作为root
|
0 1 |
$ = require('cheerio'); $('li', 'ul', '<ul id = "fruits">...</ul>'); |
如果你需要自定义一些解析选项，你可以多传递一个对象给load方法：
|
0 1 2 3 |
$ = cheerio.load('<ul id = "fruits">...</ul>', { ignoreWhitespace: true, xmlMode: true }); |
更多的解析选项可以参考domhandler和parser-options
2. 选择器（selectors）
cheerio的选择器几乎和jQuery一模一样，所以语法上十分相像
|
0 |
$( selector, [context], [root] ) |
selector在context的范围内搜索，context的范围又包含在root的范围内。selector和context可以是一个字符串，DOM元素，DOM数组或者cheerio实例。root一般是一个HTML文档字符串
选择器是文档遍历和操作的起点。如同在jQuery中一样，它是选择元素节点最重要的方法，但是在jQuery中选择器建立在CSS选择器标准库上。cheerio的选择器实现了大部分的方法
|
0 1 2 3 4 5 6 7 |
$('.apple', '#fruits').text() //=> Apple $('ul .pear').attr('class') //=> pear $('li[class=orange]').html() //=> <li class = "orange">Orange</li> |
3. 属性操作（atrributes）
用来获取和更改属性的方法：
.attr(name, value)
这个方法用来获取和设置属性。获取第一个符合匹配的元素的属性值。如果某个属性值被设置成null，那么该属性会被移除。你也可以把map和function作为参数传递进去，就像在jQuery中一样
|
0 1 2 3 4 |
$('ul').attr('id') //=> fruits $('.apple').attr('id', 'favorite').html() //=> <li class = "apple" id = "favorite">Apple</li> |
更多信息请查看 http://api.jquery.com/attr/
.removeAtrr(name)
移除名为name的属性
|
0 1 |
$('.pear').removeAttr('class').html() //=> <li>Pear</li> |
.hasClass(className)
检查元素是否含有此类名
|
0 1 2 3 4 5 6 7 |
$('.pear').hasClass('pear') //=> true $('apple').hasClass('fruit') //=> false $('li').hasClass('pear') //=> true |
.addClass(className)
添加类名到所有的匹配元素，可以用函数作为参数
|
0 1 2 3 4 |
$('.pear').addClass('fruit').html() //=> <li class = "pear fruit">Pear</li> $('.apple').addClass('fruit red').html() //=> <li class = "apple fruit red">Apple</li> |
.remoteClass([className])
移除一个或者多个（空格分隔）的类名，如果className为空，则所有的类名都会被移除，可以传递函数作为参数
|
0 1 2 3 4 |
$('.pear').removeClass('pear').html() //=> <li class = "">Pear</li> $('.apple').addClass('red').removeClass().html() //=> <li class = "">Apple</li> |
遍历
.find(selector)
在当前元素集合中选择符合选择器规则的元素集合
|
0 1 |
$('#fruits').find('li').length //=> 3 |
.parent()
获取元素集合第一个元素的父元素
|
0 1 |
$('.pear').parent().attr('id') //=> fruits |
.next()
选择当前元素的下一个兄弟元素
|
0 1 |
$('.apple').next().hasClass('orange') //=> true |
.prev()
同.next()相反
.siblings()
获取元素集合中第一个元素的所有兄弟元素，不包含它自己
|
0 1 |
$('.pear').siblings().length //=> 2 |
.children( selector )
获被选择元素的子元素
.each( function(index, element) )
遍历函数返回false即可终止遍历
|
0 1 2 3 4 5 6 7 |
var fruits = []; $('li').each(function(i, elem) { fruits[i] = $(this).text(); }); fruits.join(', '); //=> Apple, Orange, Pear |
.map( function(index, element) )
迭代一个cheerio对象，为每个匹配元素执行一个函数。Map会返回一个迭代结果的数组。这个函数是在DOM元素的上下文中触发的，所以它引用当前元素，它相当于函数参数元素
|
0 1 2 3 4 |
$('li').map(function(i, el) { // this === el return $(this).attr('class'); }).get().join(', '); //=> apple, orange, pear |
.filter( selector )
|
0 1 |
$('li').filter('.orange').attr('class'); //=> orange |
.filter( function(index) )
迭代一个cheerio对象，滤出匹配选择器或者是传进去的函数的元素。如果使用函数方法，这个函数在被选择的元素中执行，所以this指向的手势当前元素。
|
0 1 2 3 4 |
$('li').filter(function(i, el) { // this === el return $(this).attr('class') === 'orange'; }).attr('class') //=> orange |
.first()
选择chreeio对象的第一个元素
|
0 1 |
$('#fruits').children().first().text() //=> Apple |
.last()
选择chreeio对象的最后一个元素
|
0 1 |
$('#fruits').children().last().text() //=> Pear |
.eq( i )
缩小元素集合，可以用负数表示倒数第 i 个元素被保留
|
0 1 2 3 4 |
$('li').eq(0).text() //=> Apple $('li').eq(-1).text() //=> Pear |
操作DOM
操作DOM结构的方法
.append( content, [content, ...] )
在每个元素最后插入一个子元素
.prepend( content, [content, ...] )
在每个元素最前插入一个子元素
.after( content, [content, ...] )
在每个匹配元素之后插入一个元素
|
0 1 2 3 4 5 6 7 |
$('.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, ...] )
在每个匹配的元素之前插入一个元素
|
0 1 2 3 4 5 6 7 |
$('.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] )
从DOM中去除匹配的元素和它们的子元素。选择器用来筛选要删除的元素。
|
0 1 2 3 4 5 |
$('.pear').remove() $.html() //=> <ul id = "fruits"> // <li class = "apple">Apple</li> // <li class = "orange">Orange</li> // </ul> |
.replaceWith( content )
替换匹配的的元素
|
0 1 2 3 4 5 6 7 |
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()
清空一个元素，移除所有的子元素
|
0 1 2 |
$('ul').empty() $.html() //=> <ul id = "fruits"></ul> |
.html( [htmlString] )
获得元素的HTML字符串。如果htmlString有内容的话，将会替代原来的HTML
|
0 1 2 3 4 |
$('.orange').html() //=> Orange $('#fruits').html('<li class = "mango">Mango</li>').html() //=> <li class="mango">Mango</li> |
.text( [textString] )
|
0 1 2 3 4 5 6 |
$('.orange').text() //=> Orange $('ul').text() //=> Apple // Orange // Pear |
解析和渲染
|
0 1 2 3 4 5 |
$.html() //=> <ul id = "fruits"> // <li class = "apple">Apple</li> // <li class = "orange">Orange</li> // <li class = "pear">Pear</li> // </ul> |
输出包含自己在内的HTML（outer HTML）
|
0 1 |
$.html('.pear') //=> <li class = "pear">Pear</li> |
杂项
.toArray()
取得所有的在DOM元素，转化为数组
|
0 1 |
$('li').toArray() //=> [ {...}, {...}, {...} ] |
.clone()
克隆cheerio对象
|
0 |
var moreFruit = $('#fruits').clone() |
常用工具
$.root()
有时候你想找到最上层的root元素,那么$.root()就能获得:
|
0 1 |
$.root().append('<ul id="vegetables"></ul>').html(); //=> <ul id="fruits">...</ul><ul id="vegetables"></ul> |
$.contains( container, contained )
查看cotained元素是否是container元素的子元素
cheerio 官方文档
.