# jQuery()

所属分类：核心 API 英文文档：jQuery()
返回匹配的元素集合，无论是通过在DOM的基础上传递的参数还是创建一个HTML字符串。

## jQuery( selector [, context ] )返回: jQuery

描述: 接受一个包含一个CSS选择器的字符串，用于匹配的一组元素。

- #### 添加的版本: 1.0jQuery( selector [, context ] )

  - selector
    类型: selector
    一个包含CSS选择器的字符串
  - context
    类型: Element, jQuery
    一个DOM 元素、文档或 作为上下文（context）的jQuery 对象。

- #### 添加的版本: 1.0jQuery( element )

  - element
    类型: Element
    一个用于封装成jQuery对象的DOM元素。

- #### 添加的版本: 1.0jQuery( elementArray )

  - elementArray
    类型: Array
    一个用于封装成jQuery对象的DOM元素数组。

- #### 添加的版本: 1.0jQuery( object )

  - object
    类型: PlainObject
    一个普通的对象包装在一个jQuery对象。

- #### 添加的版本: 1.0jQuery( jQuery object )

  - jQuery object
    类型: PlainObject
    一个用于克隆的jQuery对象。

- #### 添加的版本: 1.4jQuery()

  - 这个方法不接受任何参数。

在上文列出的第一个公式中，`jQuery()` — 这个也可以写成 `$()` — 通过提供的选择器检索任何DOM元素并且通过这些元素创建一个新的jQuery对象：

1 |
    $( "div.foo" );

如果提供的选择器没有相匹配的，新的jQuery对象是“空”;即，它不包含任何元素，`.length`属性为0。

#### Selector Context(上下文选择器)

默认情况下,选择器是从文档根节点开始执行搜索。然而,可以给`$()`函数传递一个用于上下文检索的第二个可选参数(注：第二个上下文参数用于来指定选择器查找的范围)。 举个例子，如果在一个回调函数中我们希望为一个元素做一个检索， 我们可以限制搜索的范围:

1 2 3 |
    $( "div.foo" ).click(function() {  $(  "span", this ).addClass( "bar" );});

由于我们限制这个span选择器的上下文为 `this`, 只有在点击元素里的span将会被附加样式。

在jQuery内部，选择器上下文是使用`.find()`方法的，所以 `$('span', this)` 等价于`$(this).find('span')`。

#### Using DOM elements(使用DOM节点)

这个函数的第二个和第三个的方式使用一个或多个DOM元素或者我们用其他一些方式已找到的元素,创建一个jQuery对象.

注意：这些方式意思仅消耗DOM元素;输送混合数据给 elementArray（元素数组） 的形式是特别鼓励。

这个设备普遍使用jQuery方法通过一个回调函数传递`this`关键字 ：

1 2 3 |
    $( "div.foo" ).click(function() {  $(this).slideUp();});

这个例子，当点击使得这些元素隐藏的时候使用了滑动动画。因为事件处理通过 `this` 关键字，接收到了被点击的元素，但是该元素是原生的 DOM 元素，所以需要通过 $() 函数，将它转换成 jQuery 对象，然后就可以在该 jQuery 对象上调用 jQuery 方法了。

当一个Ajax请求返回XML数据时，我们可以使用 `$()` 方法去把他包含在jQuery对象中，我们可以很容易的工作。一旦这样做了之后，我们可以使用`.find()`和其他DOM遍历方法在XML结构中检索特定元素。

1 2 3 |
    $.post( "url.xml", function(data) {  var $child = $(data).find("child");})

#### Cloning jQuery Objects(克隆jQuery对象)

当一个jQuery对象作为一个参数传递给`$()`方法时，这个对象的一个克隆对象将被创建。这个新的jQuery对象引用同一DOM元素。

#### Returning an Empty Set(返回一个空集合)

在jQuery 1.4中，如果你传递给`jQuery()`方法一个空参数，一个空的jQuery设置将被返回（`.length`属性为0）。 在以前的jQuery版本中，一个包含整个文档节点的集合将被返回。

#### Working With Plain Objects（使用普通的对象）

目前，只支持包裹在jQuery中的普通的JavaScript对象是：`.data()`,`.prop()`,`.bind()`, `.unbind()`, `.trigger()` 和 `.triggerHandler()`。使用`.data()`（或者任何返回`.data()`的方法），在一个普通的对象会产生一个新的属性的名为jQuery{randomNumber}（如jQuery123456789）。

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 |
    // define a plain objectvar foo = {foo: "bar", hello: "world"}; // Pass it to the jQuery functionvar $foo = $( foo ); // test accessing property valuesvar test1 = $foo.prop( "foo" ); // bar // test setting property values$foo.prop( "foo", "foobar" );var test2 = $foo.prop( "foo" ); // foobar // test using .data() as summarized above$foo.data( "keyName", "someValue");console.log( $foo ); // will now contain a jQuery{randomNumber} property // test binding an event name and triggering$foo.bind( "eventName", function () {  console.log("eventName was called");}); $foo.trigger( "eventName" ); // logs "eventName was called"

如果`.trigger( "eventName" )`被使用，它会在这个对象上搜寻一个“eventName的”属性，并且尝试任何附加在jQuery上的处理器执行完成后执行。它不检查该属性是否是一个函数。为了避免这种情况，`.triggerHandler( "eventName" )`应代替使用。

1 |
    $foo.triggerHandler( "eventName" ); // also logs "eventName was called"

## 例子:

#### Example: 查找所有 div 下的 p 元素，并为它们加上边框。

1 2 3 4 5 6 7 8 9 10 11 12 13 |
    <!DOCTYPE html><html><head>  <script src="https://code.jquery.com/jquery-latest.js"></script></head><body>  <p>one</p> <div><p>two</p></div> <p>three</p><script>$( "div > p").css("border", "1px solid gray");    </script> </body></html>

#### Demo:

#### Example: 查找文档中第一个表单中的所有单选按钮。

1 |
    $("input:radio", document.forms[0]);

#### Example: 查找 Ajax 返回的 XML 文档中的所有 div 元素。

1 |
    $("div", xml.responseXML);

#### Example: 将页面的背景色设置成黑色。

1 |
    $(document.body).css( "background", "black" );

#### Example: 隐藏 myForm 表单中的所有 input 元素。

1 |
    $(myForm.elements).hide()

## jQuery( html [, ownerDocument ] )返回: jQuery

描述: 根据提供的原始 HTML 标记字符串，动态创建由 jQuery 对象包装的 DOM 元素。

- #### 添加的版本: 1.0jQuery( html [, ownerDocument ] )

  - html
    类型: String
    用于动态创建DOM元素的HTML标记字符串，不是XML。
  - ownerDocument
    类型: document
    一个文档的新元素将被创建。

- #### 添加的版本: 1.4jQuery( html, attributes )

  - html
    类型: String
    一个单标记的HTML 元素字符串(例如 <div/> or <div></div>).
  - attributes
    类型: PlainObject
    访问新创建元素的属性，事件和方法。

#### Creating New Elements（创建新元素）

如果一个字符串做为一个参数传递个`$()`, jQuery 检查这个属性是否看上去像HTML (也就是， `<tag ... >` 之类的元素在这个字符串中)。如果没有, 这个字符串将被解释为选择器， 作为解析上下文。 但是如果该字符串是一个 HTML 代码片断，那么jQuery 就会根据它尝试创建一个新的 DOM 元素。然后jQuery对象创建并返回引用的这些元素。我们可以在这个对象上执行一些常用的jQuery方法：

1 |
    $( "<p id='test'>My <em>new</em> text</p>" ).appendTo( "body" );

一个字符串显式解析成HTML，请使用$.parseHTML() 方法.

在上面的例子中，当一个HTML比一个没有属性的简单标签复杂的时候，实际上，创建元素的处理是利用了浏览器的 `innerHTML` 机制。特别说明，jQuery创建一个新的<div>元素，并且设置innerHTML属性为传入的HTML代码片段。当参数是一个单标签，就像 `$('<img />')` or `$('<a></a>')`，jQuery将使用javasrcipt原生的 `createElement()`函数创建这个元素。

当传入一个复杂的html，一些浏览器可能不会产生一个完全复制HTML源代码所提供的DOM。正如前面提到的，jQuery使用的浏览器`.innerHTML`属性来解析传递的HTML并将其插入到当前文档中。在此过程中，一些浏览器过滤掉某些元素，如`<html>`, `<title>`, 或 `<head>`的元素。其结果是，被插入元素可能不是传入的原始的字符串。

不过，这些被过滤掉的标签有限的。有些浏览器可能不完全复制所提供的HTML源代码生成DOM。例如，Internet Explorer的版本8之前转换所有链接的`href`属性为绝对URL路径，和Internet Explorer第9版之前，不增加一个单独的兼容层的情况下，将无法正确处理HTML5元素。

为了确保跨平台的兼容性，代码片段必须是良好的。标签可以包含其他元素，但需要搭配的结束标记：

1 |
    $( "<a href='http://jquery.com'></a>" );

标签不能包含元素可能很快封闭，当然也可以不这样做：

1 2 |
    $( "<img />" );$( "<input>" );

当传递HTML给`jQuery()`时，文本节点并不必当作 DOM 元素来看待。除了一些方法（如内容`.content()`），它们一般都被忽略或删除。例如：

1 2 |
    var el = $( "1<br/>2<br/>3" ); // returns [<br>, "2", <br>]el  = $( "1<br/>2<br/>3 >" ); // returns [<br>, "2", <br>, "3 &gt;"]

这是预期的结果。

从jQuery 1.4开始，给`jQuery()` 的第二个参数可以接受一个简单的对象组成的一个属性集合，可以传递.attr()方法。

重要提示： 如果第二个参数被传递，第一个参数中的HTML字符串 必须代表一个没有任何属性简单的元素。 从 jQuery 1.4开始，我们可以传递一个对象作为第二个参数。 这个参数接受一个属性的集合，这些可以传递给.attr() 方法。此外，一些event type（事件类型）能通过， 而且后面的jQuery方法能够调用： val, css, html, text, data, width, height, or offset。

从 jQuery 1.8开始, 任何jQuery实例方法（一个`jQuery.fn`的方法），可以被用来作为一个该对象的属性传递给第二个参数：

1 2 3 4 5 6 7 8 |
    $( "<div></div>", {  "class": "my-div",  on: {    touchstart: function( event ) {      // do something    }  }}).appendTo( "body" );

在这个对象中，`"class"`（类）的名称必须使用引号括起来，因为它是一个JavaScript保留字，还有不能使用`"className"`，因为它是指的DOM属性（property），不是属性（attribute）。

虽然第二个参数是方便，它的灵活性可能会导致意想不到的后果（例如`$("<input>", {size: "4"})`调用`.size()`方法，代替设置size属性）。上面的代码块可以被写入，代替为：

1 2 3 4 5 6 7 |
    $( "<div></div>" ).addClass( "my-div" ).on({  touchstart: function( event ) {    // do something  }}).appendTo( "body" );

## 例子:

#### Example: 动态创建一个 div 元素(以及它的内容)，并将它追加到 body 元素后。在 jQuery 内部是通过所指定元素的 innerHTML 属性对新生成的元素进行赋值的。

1 |
    $( "<div><p>Hello</p></div>" ).appendTo( "body" )

#### Example: 创建一些 DOM 元素。

1 2 3 4 5 6 7 |
    $( "<div/>", {  "class": "test",  text: "Click me!",  click: function() {    $( this ).toggleClass( "test" );  }}).appendTo( "body" );

## jQuery( callback )返回: jQuery

描述: 当DOM完成加载的时候绑定一个要执行的函数。

- #### 添加的版本: 1.0jQuery( callback )

  - callback
    类型: Function()
    当DOM ready的时候执行的函数。

这个函数的作用如同`$(document).ready()`一样，只不过用这个函数时，需要把页面中所有需要在 DOM ready时执行的 `$()`操作符都包装到其中来。从技术上来说，这个函数是可链式调用的－－但真正以这种方式链接的情况并不多。

## 例子:

#### Example: 当 DOM 加载完成时执行函数。

1 2 3 |
    $(function(){  // Document is ready});

#### Example: 为了更加安全的使用 jQuery 的 $ 别名，而不依赖全局的 $ 别名，我们可以同时使用 $(document).ready() 的快捷方式和参数来达到此目的。

1 2 3 |
    jQuery(function($) {  // Your code using failsafe $ alias here...});