cheerio中文文档

这篇参考手册是对cheerio 官方文档 的中文翻译

cheerio是jquery核心功能的一个快速灵活而又简洁的实现,主要是为了用在服务器端需要对DOM进行操作的地方

简介

让你在服务器端和html愉快的玩耍

var cheerio = require('cheerio'),
    $ = cheerio.load('

Hello world

'); $('h2.title').text('Hello there!'); $('h2').addClass('welcome'); $.html(); //=>

Hello there!

安装

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模板如下:

  • Apple
  • Orange
  • Pear

1. 解析html(load)

首先你需要先加载你的HTML。jQuery会自动完成这一步,因为jQuery操作的DOM是固定的。但是在使用cheerio时我们要手动加载我们的HTML文档

首选的方式如下:

var cheerio = require('cheerio'),
$ = cheerio.load('
    ...
');

其次,直接把HTML字符串作为上下文也是可以的:

$ = require('cheerio');
$('ul', '
    ...
');

或者把HTML字符串作为root

$ = require('cheerio');
$('li', 'ul', '
    ...
');

如果你需要自定义一些解析选项,你可以多传递一个对象给load方法:

$ = cheerio.load('
    ...
', { ignoreWhitespace: true, xmlMode: true });

更多的解析选项可以参考domhandler和parser-options

2. 选择器(selectors)

cheerio的选择器几乎和jQuery一模一样,所以语法上十分相像

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

selectorcontext的范围内搜索,context的范围又包含在root的范围内。selectorcontext可以是一个字符串,DOM元素,DOM数组或者cheerio实例。root一般是一个HTML文档字符串

选择器是文档遍历和操作的起点。如同在jQuery中一样,它是选择元素节点最重要的方法,但是在jQuery中选择器建立在CSS选择器标准库上。cheerio的选择器实现了大部分的方法

$('.apple', '#fruits').text()
//=> Apple

$('ul .pear').attr('class')
//=> pear

$('li[class=orange]').html()
//=> 
  • Orange
  • 3. 属性操作(atrributes)

    用来获取和更改属性的方法:

    .attr(name, value)

    这个方法用来获取和设置属性。获取第一个符合匹配的元素的属性值。如果某个属性值被设置成null,那么该属性会被移除。你也可以把mapfunction作为参数传递进去,就像在jQuery中一样

    $('ul').attr('id')
    //=> fruits
    
    $('.apple').attr('id', 'favorite').html()
    //=> 
  • Apple
  • 更多信息请查看 http://api.jquery.com/attr/

    .removeAtrr(name)

    移除名为name的属性

    $('.pear').removeAttr('class').html()
    //=> 
  • Pear
  • .hasClass(className)

    检查元素是否含有此类名

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

    .addClass(className)

    添加类名到所有的匹配元素,可以用函数作为参数

    $('.pear').addClass('fruit').html()
    //=> 
  • Pear
  • $('.apple').addClass('fruit red').html() //=>
  • Apple
  • 参见 http://api.jquery.com/addClass/

    .remoteClass([className])

    移除一个或者多个(空格分隔)的类名,如果className为空,则所有的类名都会被移除,可以传递函数作为参数

    $('.pear').removeClass('pear').html()
    //=> 
  • Pear
  • $('.apple').addClass('red').removeClass().html() //=>
  • Apple
  • 参见 http://api.jquery.com/removeClass/

    遍历

    .find(selector)

    在当前元素集合中选择符合选择器规则的元素集合

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

    .parent()

    获取元素集合第一个元素的父元素

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

    .next()

    选择当前元素的下一个兄弟元素

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

    .prev()

    .next()相反

    .siblings()

    获取元素集合中第一个元素的所有兄弟元素,不包含它自己

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

    .children( selector )

    .each( function(index, element) )

    遍历函数返回false即可终止遍历

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

    .map( function(index, element) )

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

    .filter( selector )

    $('li').filter('.orange').attr('class');
    //=> orange
    

    .filter( function(index) )

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

    .first()

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

    .last()

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

    .eq( i )

    缩小元素集合,可以用负数表示倒数第 i 个元素被保留

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

    操作DOM

    操作DOM结构的方法

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

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

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

    $('.apple').after('
  • Plum
  • ') $.html() //=>
      //
    • Apple
    • //
    • Plum
    • //
    • Orange
    • //
    • Pear
    • //

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

    $('.apple').before('
  • Plum
  • ') $.html() //=>
      //
    • Plum
    • //
    • Apple
    • //
    • Orange
    • //
    • Pear
    • //

    .remove( [selector] )

    $('.pear').remove()
    $.html()
    //=>  
      //
    • Apple
    • //
    • Orange
    • //

    .replaceWith( content )

    var plum = $('
  • Plum
  • ') $('.pear').replaceWith(plum) $.html() //=>
      //
    • Apple
    • //
    • Orange
    • //
    • Plum
    • //

    .empty()

    $('ul').empty()
    $.html()
    //=>  

      .html( [htmlString] )

      $('.orange').html()
      //=> Orange
      
      $('#fruits').html('
    • Mango
    • ').html() //=>
    • Mango
    • .text( [textString] )

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

      解析和渲染

      $.html()
      //=>  
        //
      • Apple
      • //
      • Orange
      • //
      • Pear
      • //

      输出包含自己在内的HTML(outer HTML)

      $.html('.pear')
      //=> 
    • Pear
    • 杂项

      .toArray()

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

      .clone()

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

      常用工具

      $.root()

      $.root().append('
        ').html(); //=>
          ...

          $.contains( container, contained )

          你可能感兴趣的:(cheerio中文文档)