Node.js npm cheerio

傷城~ 2022-07-12 06:18 260阅读 0赞

译自 [https://www.npmjs.com/package/cheerio][https_www.npmjs.com_package_cheerio]

# cheerio #

> Tiny, fast, and elegant implementation of core jQuery designed specifically for the server

极小的，快速的并且使用 jQuery 设计的简洁的内核，专为服务器定制。

let cheerio = require('cheerio')
    let $ = cheerio.load('<h2 class="title">Hello world</h2>')
    
    $('h2.title').text('Hello there!')
    $('h2').addClass('welcome')
    
    $.html()
    //=> <h2 class="title welcome">Hello there!</h2>

## Installation（安装） ##

> npm install cheerio

## Features（特性） ##

> ❤ **Familiar syntax:** Cheerio implements a subset of core jQuery. Cheerio removes all the DOM inconsistencies and browser cruft from the jQuery library, revealing its truly gorgeous API.

相似的语法：Cheerio 实现了 jQuery 内核的一个子集。Cheerio 从 jQuery 库移除了所有的 DOM 不一致的和浏览器支持参差不齐的东西，从而展示出它真正优雅的 API。

> ϟ **Blazingly fast:** Cheerio works with a very simple, consistent DOM model. As a result parsing, manipulating, and rendering are incredibly efficient. Preliminary end-to-end benchmarks suggest that cheerio is about 8x faster than JSDOM.

纯净快速：Cheerio 工作在一个非常简单，一致的 DOM 模型下。解析结果，操作，和呈现都难以置信的极为高效。初级的端到端的基准显示 cheerio 比 JSDOM 大约快了 8 倍。

> ❁ **Incredibly flexible:** Cheerio wraps around @FB55’s forgiving htmlparser2. Cheerio can parse nearly any HTML or XML document.

极其灵活：Cheerio 包裹了 @FB55 的宽容的 htmlparser2。 Cheerio 可以解析接近任何 HTML 或 XML 文档。

## Sponsors（赞助者） ##

> Does your company use Cheerio in production? Please consider sponsoring this project. Your help will allow maintainers to dedicate more time and resources to its development and support.

你的公司的产品中是否使用 Cheerio？请考虑下赞助这个项目。你的帮助将会让维护人员投入更多的时间和资源来进行开发和支持。

[Become a Sponsor][]

## Backers（支持者） ##

> Become a backer to show your support for Cheerio and help us maintain and improve this open source project.

成为一个支持者来表达你对 Cheerio 的支持，并且帮助我们来维护和提升这个开源项目。

[Become a Backers][]

## API（Application Programming Interface,应用程序编程接口） ##

### Markup example we’ll be using: ###

我们将使用的标记范例：

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

> This is the HTML markup we will be using in all of the API examples.

在所有的 API 范例中，我们都将使用这个 HTML 标记。

### Loading ###

> First you need to load in the HTML. This step in jQuery is implicit, since jQuery operates on the one, baked-in DOM. With Cheerio, we need to pass in the HTML document.

首先，你需要载入 HTML。这一步在 jQuery 中是隐式的，因为在其上的 jQuery 操作已经嵌入到 DOM中了。使用 Cheerio，我们需要传入一个 HTML 文档。

> This is the preferred method:

首选的方法是：

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

> Optionally, you can also load in the HTML by passing the string as the context:

作为另一个可选项，你也可以通过传递字符串作为其上下文来加载 HTML。

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

> Or as the root:

或者把它当作根元素：

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

> You can also pass an extra object to .load() if you need to modify any of the default parsing options:

如果你需要修改任何默认的解析选项的话，你也可以传递一个额外的对象到 .load() 。

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

> These parsing options are taken directly from htmlparser2, therefore any options that can be used in htmlparser2 are valid in cheerio as well. The default options are:

这些传递的选项都会直接被 htmlparser2 拿走，因此任何可以被用在 htmlparser2 的选项，在 cheerio 中也都是合法的。默认的选项是：

{
        withDomLvl1: true,
        normalizeWhitespace: false,
        xmlMode: false,
        decodeEntities: true
    }

> For a full list of options and their effects, see [this][] and [htmlparser2’s options][htmlparser2_s options].

获取完整的选项列表和它们的影响，请参看 这个 和 htmlparser2 的选项。

### Selectors ###

> Cheerio’s selector implementation is nearly identical to jQuery’s, so the API is very similar.

Cheerio 的选择器的实现与 jQuery 几乎相同，因此 API 是非常相似的。

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

> selector searches within the context scope which searches within the root scope. selector and context can be a string expression, DOM Element, array of DOM elements, or cheerio object. root is typically the HTML document string.

selector 在 context 范围内进行搜索，context 在 root 范围内进行搜素。selector 和 context 可以是一个字符串表达式，DOM 元素，DOM元素数组，或者 cheerio 对象。root 是典型的 HTML 文档字符串。

> This selector method is the starting point for traversing and manipulating the document. Like jQuery, it’s the primary method for selecting elements in the document, but unlike jQuery it’s built on top of the CSSSelect library, which implements most of the Sizzle selectors.

这个选择方法遍历和操作文档的起点。就像 jQuery，在文档中，它是主要的选取元素的方法，但是和 jQuery 不一样的是它是建立在 CSS 选择库之上的，它实现了大部分的 Sizzle 选择。

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

### Attributes ###

> Methods for getting and modifying attributes.

获取和改变属性的方法。

#### .attr( name, value ) ####

> Method for getting and setting attributes. Gets the attribute value for only the first element in the matched set. If you set an attribute’s value to null, you remove that attribute. You may also pass a map and function like jQuery.

获取和设置 attributes 的方法。只能获取匹配集合中的第一个元素的属性值。如果你设置了一个属性值为 null，就是删除该属性。你也可以像 jQuery 一样传递映射表和函数。

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

> See [http://api.jquery.com/attr/][http_api.jquery.com_attr] for more information

查看 [http://api.jquery.com/attr/][http_api.jquery.com_attr] 来获取更多信息

#### .prop( name, value ) ####

> Method for getting and setting properties. Gets the property value for only the first element in the matched set.

获取和设置 properties 的方法。只能获取匹配集合中的第一个元素的特征值。

$('input[type="checkbox"]').prop('checked')
    //=> false 
    
    $('input[type="checkbox"]').prop('checked', true).val()
    //=> ok

> See [http://api.jquery.com/prop/][http_api.jquery.com_prop] for more information

查看 [http://api.jquery.com/prop/][http_api.jquery.com_prop] 来获取更多信息

#### .data( name, value ) ####

> Method for getting and setting data attributes. Gets or sets the data attribute value for only the first element in the matched set.

获取和设置 data 属性的方法。只能获取或者设置匹配集合中的第一个元素的 data 属性。

$('<div data-apple-color="red"></div>').data()
    //=> { appleColor: 'red' } 
    
    $('<div data-apple-color="red"></div>').data('apple-color')
    //=> 'red' 
    
    var apple = $('.apple').data('kind', 'mac')
    apple.data('kind')
    //=> 'mac'

> See [http://api.jquery.com/data/][http_api.jquery.com_data] for more information

查看 [http://api.jquery.com/data/][http_api.jquery.com_data] 来获取更多信息

#### .val( \[value\] ) ####

> Method for getting and setting the value of input, select, and textarea. Note: Support for map, and function has not been added yet.

获取和设置 input，select，textarea 值的方法。注意：对 map，function 的支持还未被加进来。

$('input[type="text"]').val()
    //=> input_text 
    
    $('input[type="text"]').val('test').html()
    //=> <input type="text" value="test"/>

#### .removeAttr( name ) ####

> Method for removing attributes by name.

通过名称来移除属性的方法。

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

#### .hasClass( className ) ####

> Check to see if any of the matched elements have the given className.

查看是否存在符合给定类名的元素。

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

#### .addClass( className ) ####

> Adds class(es) to all of the matched elements. Also accepts a function like jQuery.

将类添加到所有满足的元素中。也可以接收一个像 jQuery 的函数。

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

> See [http://api.jquery.com/addClass/][http_api.jquery.com_addClass] for more information.

查看 [http://api.jquery.com/addClass/][http_api.jquery.com_addClass] 来获取更多信息。

#### .removeClass( \[className\] ) ####

> Removes one or more space-separated classes from the selected elements. If no className is defined, all classes will be removed. Also accepts a function like jQuery.

从选中的元素中移除一个或多个空格分隔的类。如果（参数中）没定义类名，那么所有类都将被移除。也可以接收一个像 jQuery 的函数。

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

> See [http://api.jquery.com/removeClass/][http_api.jquery.com_removeClass] for more information.

查看 [http://api.jquery.com/removeClass/][http_api.jquery.com_removeClass] 来获取更多信息。

#### .toggleClass( className, \[switch\] ) ####

> Add or remove class(es) from the matched elements, depending on either the class’s presence or the value of the switch argument. Also accepts a function like jQuery.

根据出现的类或 switch 参数的值，在匹配的元素中添加或移除类。也可以接收一个像 jQuery 的函数。

$('.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>

> See [http://api.jquery.com/toggleClass/][http_api.jquery.com_toggleClass] for more information.

查看 [http://api.jquery.com/toggleClass/][http_api.jquery.com_toggleClass] 来获取更多信息。

#### .is( selector ) ####

#### .is( element ) ####

#### .is( selection ) ####

#### .is( function(index) ) ####

> Checks the current list of elements and returns true if any of the elements match the selector. If using an element or Cheerio selection, returns true if any of the elements match. If using a predicate function, the function is executed in the context of the selected element, so this refers to the current element.

校验当前的元素列表，并且如果任何元素都满足该选择器则返回真。如果使用的是一个元素或者 Cheerio 选择中的，如果任何元素都满足，那么返回真。如果使用一个断言函数，该函数会在选中元素的上下文中被执行，因此它会引用当前元素。

### Forms（构成） ###

#### .serializeArray() ####

> Encode a set of form elements as an array of names and values.

将一系列的表单元素编码为名称和值的数组。

$('<form><input name="foo" value="bar" /></form>').serializeArray()
    //=> [ { name: 'foo', value: 'bar' } ]

### Traversing ###

#### .find(selector) ####

#### .find(selection) ####

#### .find(node) ####

Get the descendants of each element in the current set of matched elements, filtered by a selector, jQuery object, or element.

[https_www.npmjs.com_package_cheerio]: https://www.npmjs.com/package/cheerio
[Become a Sponsor]: https://opencollective.com/cheerio/sponsor/0/website
[Become a Backers]: https://opencollective.com/cheerio/backer/0/website
[this]: https://github.com/fb55/DomHandler
[htmlparser2_s options]: https://github.com/fb55/htmlparser2/wiki/Parser-options
[http_api.jquery.com_attr]: http://api.jquery.com/attr/
[http_api.jquery.com_prop]: http://api.jquery.com/prop/
[http_api.jquery.com_data]: http://api.jquery.com/data/
[http_api.jquery.com_addClass]: http://api.jquery.com/addClass/
[http_api.jquery.com_removeClass]: http://api.jquery.com/removeClass/
[http_api.jquery.com_toggleClass]: http://api.jquery.com/toggleClass/