nodejs之cheerio中文API 說明
我們將用到的標記示例
<ul id="fruits"> <li class="apple">Apple</li> <li class="orange">Orange</li> <li class="pear">Pear</li></ul>
這是我們將會在所有的API例子中用到的HTML標記
Loading
首先你需要載入HTML。這一步對jQuery來說是必須的，since jQuery operates on the one, baked-in DOM。通過Cheerio,我們需要把HTML document 傳進去。
這是首選:
var cheerio =require('cheerio'), $ = cheerio.load('<ul id="fruits">...</ul>');
或者通過傳遞字串作為內容來載入HTML:
$ =require('cheerio');
$('ul','<ul id="fruits">...</ul>');
Or as the root:
$ =require('cheerio');
$('li','ul','<ul id="fruits">...</ul>');你也可以傳遞一個額外的物件給.load()如果你需要更改任何的預設解析選項的話:
$ = cheerio.load('<ul id="fruits">...</ul>',{
ignoreWhitespace:true,
xmlMode:true});
這些解析選項都是直接來自htmlparser ，因此任何在htmlparser裡有效的選項在Chreeio裡也是行得通的。預設的選項如下:
{ ignoreWhitespace:false, xmlMode:false, lowerCaseTags:false}
Selectors
Cheerio的選擇器用起來幾乎和jQuery一樣，所以API也很相似。
$(selectior,[context],[root])
選擇器在 Context 範圍內搜尋，Context又在Root範圍內搜尋。selector 和context可是是一個字串表示式，DOM元素，和DOM元素的陣列，或者chreeio物件。root 是通常是HTML 文件字串。
$('.apple','#fruits').text()//=> Apple$('ul .pear').attr('class')//=> pear$('li[class=orange]').html()//=> <li class="orange">Orange</li>
Attributes
獲得和修改屬性
.attr(name,value)
獲得和修改屬性。在匹配的元素中只能獲得第一元素的屬性。如果設定一個屬性的值為null，則移除這個屬性。你也可以傳遞一對鍵值，或者一個函式。
$('ul').attr('id')//=> fruits$('.apple').attr('id','favorite').html()//=> <li class="apple" id="favorite">Apple</li>
.val([value])
獲得和修改input,select,textarea的value.注意: 對於傳遞鍵值和函式的支援還沒有被加進去。
$('input[type="text"]').val()//=> input_text$('input[type="text"]').val('test').html()//=><input type="text" value="test"/>
.removeAttr(name)
通過name刪除屬性
$('.pear').removeAttr('class').html()//=> <li>Pear</li>
.hasClass( className )
檢查匹配的元素是否有給出的類名
$('.pear').hasClass('pear')//=> true$('apple').hasClass('fruit')//=> false$('li').hasClass('pear')//=> true
.addClass(className)
增加class(es)給所有匹配的elements.也可以傳函式。
$('.pear').addClass('fruit').html()//=> <li class="pear fruit">Pear</li>$('.apple').addClass('fruit red').html()//=> <li class="apple fruit red">Apple</li>
.removeClass([className])
從選擇的elements裡去除一個或多個有空格分開的class。如果className 沒有定義，所有的classes將會被去除，也可以傳函式。
$('.pear').removeClass('pear').html()//=> <li class="">Pear</li>$('.apple').addClass('red').removeClass().html()//=> <li class="">Apple</li>
.toggleClass( className, [switch] )
新增或刪除class，依賴於當前是否有該class.
$('.apple.green').toggleClass('fruit green red').html()//=> <li class="apple fruit red">Apple</li>$('.apple.green').toggleClass('fruit green red', true).html()//=> <li class="apple green fruit red">Apple</li>
.is( selector )
.is( element )
.is( selection )
.is( function(index) )
有任何元素匹配selector就返回true。如果使用判定函式，判定函式在選中的元素中執行，所以this指向當前的元素。
Traversing
.find(selector)
獲得一個在匹配的元素中由選擇器濾過的後代。
$('#fruits').find('li').length//=> 3
.parent([selector])
獲得每個匹配元素的parent,可選擇性的通過selector篩選。
$('.pear').parent().attr('id')
//=> fruits
.parents([selector])
獲得通過選擇器篩選匹配的元素的parent集合。
$('.orange').parents().length// => 2$('.orange').parents('#fruits').length// => 1
.closest([selector])
對於每個集合內的元素，通過測試這個元素和DOM層級關係上的祖先元素，獲得第一個匹配的元素
$('.orange').closest()// => []$('.orange').closest('.apple')// => []$('.orange').closest('li')// => [<li class="orange">Orange</li>]$('.orange').closest('#fruits')// => [<ul id="fruits"> ... </ul>]
.next()
獲得第一個本元素之後的同級元素
$('.apple').next().hasClass('orange')
//=> true
.nextAll()
獲得本元素之後的所有同級元素
$('.apple').nextAll()//=> [<li class="orange">Orange</li>, <li class="pear">Pear</li>]
.prev()
獲得本元素之前的第一個同級元素
$('.orange').prev().hasClass('apple')//=> true
.preAll()
$('.pear').prevAll()//=> [<li class="orange">Orange</li>, <li class="apple">Apple</li>]
獲得本元素前的所有同級元素
.slice(start,[end])
獲得選定範圍內的元素
$('li').slice(1).eq(0).text()//=> 'Orange'$('li').slice(1,2).length//=> 1
.siblings(selector)
獲得被選擇的同級元素，不包括本身
$('.pear').siblings().length//=> 2$('.pear').siblings('.orange').length//=> 1
.children(selector)
獲被選擇元素的子元素
$('#fruits').children().length//=> 3$('#fruits').children('.pear').text()//=> Pear
.each(function(index,element))
迭代一個cheerio物件，為每個匹配元素執行一個函式。When the callback is fired, the function is fired in the context of the DOM element, so this refers to the current element, which is equivalent to the function parameter element.要提早跳出迴圈，返回false.
var fruits =[]; $('li').each(function(i, elem){ fruits[i]= $(this).text();}); fruits.join(', ');//=> Apple, Orange, Pear
.map(function(index,element))
迭代一個cheerio物件，為每個匹配元素執行一個函式。Map會返回一個迭代結果的陣列。the function is fired in the context of the DOM element, so this refers to the current element, which is equivalent to the function parameter element
$('li').map(function(i, el){// this === elreturn $(this).attr('class');
}).join(', ');//=> apple, orange, pear
.filter(selector)
.filter(function(index))
迭代一個cheerio物件，濾出匹配選擇器或者是傳進去的函式的元素。如果使用函式方法，這個函式在被選擇的元素中執行，所以this指向的手勢當前元素。
Selector:
$('li').filter('.orange').attr('class');//=> orange
Function:
$('li').filter(function(i, el){// this === elreturn $(this).attr('class')==='orange';
}).attr('class')//=> orange
.first()
會選擇chreeio物件的第一個元素
$('#fruits').children().first().text()//=> Apple
.last()
$('#fruits').children().last().text()//=> Pear
會選擇chreeio物件的最後一個元素
.eq(i)
通過索引篩選匹配的元素。使用.eq(-i)就從最後一個元素向前數。
$('li').eq(0).text()//=> Apple$('li').eq(-1).text()//=> Pear
Manipulation
改變DOM結構的方法
.append(content,[content...])
在每個元素最後插入一個子元素
$('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,...])
在每個元素最前插入一個子元素
$('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,...])
在每個匹配元素之後插入一個元素
$('.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,...])
在每個匹配的元素之前插入一個元素
$('.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中去除匹配的元素和它們的子元素。選擇器用來篩選要刪除的元素。
$('.pear').remove()
$.html()//=> <ul id="fruits">// <li class="apple">Apple</li>// <li class="orange">Orange</li>// </ul>
.replaceWith( content )
替換匹配的的元素
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()
清空一個元素，移除所有的子元素
$('ul').empty()
$.html()//=> <ul id="fruits"></ul>
.html( [htmlString] )
獲得元素的HTML字串。如果htmlString有內容的話，將會替代原來的HTML
$('.orange').html()//=> Orange$('#fruits').html('<li class="mango">Mango</li>').html()//=> <li class="mango">Mango</li>
.text( [textString] )
獲得元素的text內容，包括子元素。如果textString被指定的話，每個元素的text內容都會被替換。
$('.orange').text()//=> Orange$('ul').text()//=> Apple// Orange// Pear
Rendering
如果你想呈送document，你能使用html多效用函式。
$.html()//=> <ul id="fruits">// <li class="apple">Apple</li>// <li class="orange">Orange</li>// <li class="pear">Pear</li>// </ul>
如果你想呈送outerHTML,你可以使用 $.html(selector)
$.html('.pear')//=> <li class="pear">Pear</li>
By default, html will leave some tags open. Sometimes you may instead want to render a valid XML document. For example, you might parse the following XML snippet:
$ = cheerio.load('<media:thumbnail url="http://www.foo.com/keyframe.jpg" width="75" height="50" time="12:05:01.123"/>');
... and later want to render to XML. To do this, you can use the 'xml' utility function:
$.xml()//=> <media:thumbnail url="http://www.foo.com/keyframe.jpg" width="75" height="50" time="12:05:01.123"/>
Miscellaneous
不屬於其它地方的DOM 元素方法
.toArray()
取得所有的在DOM元素，轉化為陣列、
$('li').toArray()//=> [ {...}, {...}, {...} ]
.clone()
克隆cheerio物件
var moreFruit = $('#fruits').clone()
Utilities
$.root
Sometimes you need to work with the top-level root element. To query it, you can use $.root().
$.root().append('<ul id="vegetables"></ul>').html();//=> <ul id="fruits">...</ul><ul id="vegetables"></ul>
$.contains( container, contained )
檢視cotained元素是否是container元素的子元素
$.parseHTML( data [, context ] [, keepScripts ] )
將字串解析為DOM節點陣列。context引數對chreeio沒有意義，但是用來維護APi的相容性。