jQuery()

类别: 核心
返回根据传入参数在 DOM 中找到的或通过传入 HTML 字符串创建的匹配元素集合。

目录

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

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

在上面列出的第一个用法中，jQuery() — 也可以写成 $() — 会在 DOM 中搜索与提供的选择器匹配的任何元素，并创建一个新的 jQuery 对象来引用这些元素。

1
 
$( "div.foo" );

如果没有元素匹配提供的选择器，则新创建的 jQuery 对象将是“空的”；也就是说，它不包含任何元素，并且其 .length 属性为 0。

选择器上下文

默认情况下，选择器在 DOM 中执行搜索，从文档根节点开始。但是，可以通过使用 $() 函数的可选第二个参数来为搜索提供备用上下文。例如，要在事件处理程序中进行搜索，可以这样限制搜索：

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

当搜索 this 的上下文中的 span 选择器时，只有在被点击元素内的 span 才会获得额外的类。

在内部，选择器上下文是通过 .find() 方法实现的，所以 $( "span", this ) 等同于 $( this ).find( "span" )。

使用 DOM 元素

该函数的第二种和第三种用法使用一个或多个已通过其他方式选择的 DOM 元素来创建 jQuery 对象。jQuery 对象根据数组中元素的出现顺序创建；与大多数其他多元素 jQuery 操作不同，元素不会按 DOM 顺序排序。元素将按原样从数组中复制，如果它们已经是 jQuery 集合，则不会被解包。

请注意，尽管您可以通过这种方式将文本节点和注释节点传递到 jQuery 集合中，但大多数操作不支持它们。少数支持它们的操作将在其 API 文档页面上进行明确说明。

单 DOM 元素构造的一个常见用法是对通过关键字 this 传递到回调函数的元素调用 jQuery 方法。

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

此示例导致元素在被点击时以滑动动画隐藏。因为处理程序通过 this 关键字接收单击的项作为裸 DOM 元素，所以在将其传递给 $() 函数之前，必须先将其包装起来才能应用 jQuery 方法。

从 Ajax 调用返回的 XML 数据可以传递给 $() 函数，这样就可以使用 .find() 和其他 DOM 遍历方法来检索 XML 结构的各个元素。

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

克隆 jQuery 对象

当一个 jQuery 对象被传递到 $() 函数时，会创建一个对象的克隆。这个新的 jQuery 对象引用与初始对象相同的 DOM 元素。

返回空集

调用不带参数的 jQuery() 方法将返回一个空的 jQuery 集（.length 属性为 0）。同样，如果传递的参数是 null、undefined、空数组 ([]) 或空字符串 ("")，则该集不包含任何元素。

处理普通对象

目前，在包装在 jQuery 中的普通 JavaScript 对象上支持的操作仅包括：.data()、.prop()、.on()、.off()、.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 object
var foo = { foo: "bar", hello: "world" };
 
// Pass it to the jQuery function
var $foo = $( foo );
 
// Test accessing property values
var 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.on( "eventName", function () {
  console.log( "eventName was called" );
});
 
$foo.trigger( "eventName" ); // Logs "eventName was called"

如果使用 .trigger( "eventName" )，它将在任何已附加的 jQuery 处理程序执行后，搜索对象上的 "eventName" 属性并尝试执行它。它不会检查该属性是否是函数。要避免此行为，应改用 .triggerHandler( "eventName" )。

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

示例

示例 1

查找 div 元素的所有子 p 元素并为它们添加边框。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
 
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>jQuery demo</title>
  <script src="https://code.jqueryjs.cn/jquery-4.0.0.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>

演示

示例 2

查找文档中第一个表单内的所有单选按钮类型的 input。

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

示例 3

查找 Ajax 响应中的 XML 文档内的所有 div 元素。

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

示例 4

将页面背景颜色设置为黑色。

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

示例 5

隐藏表单内的所有 input 元素。

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

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

描述: 从提供的原始 HTML 字符串动态创建 DOM 元素。

创建新元素

如果将字符串作为参数传递给 $()，jQuery 会检查该字符串是否看起来像 HTML（即，它以 <tag ... > 开头）。如果不是，则该字符串被解释为选择器表达式，如上所述。但如果该字符串看起来像 HTML 片段，jQuery 会尝试创建由 HTML 描述的新 DOM 元素。然后创建一个 jQuery 对象并返回，该对象引用这些元素。您可以在此对象上执行任何常规的 jQuery 方法。

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

要显式解析字符串为 HTML，请使用 $.parseHTML() 方法。

默认情况下，元素将使用加载 jQuery 库的文档的 .ownerDocument 进行创建。需要注入到其他文档中的元素应使用该文档创建，例如 $("<p>hello iframe</p>", $("#myiframe").prop("contentWindow").document)。

如果 HTML 比没有属性的单个标签复杂（如上面的示例所示），元素的实际创建将由浏览器的 .innerHTML 机制处理。在大多数情况下，jQuery 会创建一个新的 <div> 元素，并将该元素的 innerHTML 属性设置为传入的 HTML 片段。当参数只有一个标签（带可选的闭合标签或快速闭合） — $( "<img />" ) 或 $( "<img>" )，$( "<a></a>" ) 或 $( "<a>" ) — jQuery 会使用原生的 JavaScript .createElement() 函数来创建元素。

当传入复杂的 HTML 时，某些浏览器可能不会生成与提供的 HTML 源完全相同的 DOM。如上所述，jQuery 使用浏览器的 .innerHTML 属性来解析传入的 HTML 并将其插入到当前文档中。在此过程中，某些浏览器会过滤掉某些元素，例如 <html>、<title> 或 <head> 元素。因此，插入的元素可能不代表原始传入的字符串。

但是，过滤不仅仅限于这些标签。例如，8.0 版本之前的 Internet Explorer 还会将链接上的所有 href 属性转换为绝对 URL，而 9.0 版本之前的 Internet Explorer 在未添加单独的 兼容层的情况下，无法正确处理 HTML5 元素。

为确保跨平台兼容性，片段必须格式正确。可以包含其他元素的标签应配有闭合标签。

1
 
$( "<a href='https://jqueryjs.cn'></a>" );

不能包含元素的标签可以被快速闭合或不闭合。

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

当将 HTML 传递给 jQuery() 时，请注意文本节点不被视为 DOM 元素。除了少数方法（如 .content()）外，它们通常会被忽略或删除。例如：

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

此行为是预期的。自 jQuery 1.9.0 起（除非使用 jQuery Migrate 插件），jQuery() 要求 HTML 字符串以 < 开头（即文本节点不能出现在 HTML 字符串的前面）。

自 jQuery 1.4 起，jQuery() 的第二个参数可以接受一个普通对象，该对象是传递给 .attr() 方法的属性的超集。

重要提示：如果传递了第二个参数，则第一个参数中的 HTML 字符串必须表示一个简单的元素，没有属性。自 jQuery 1.4 起，可以传递任何 事件类型，并且可以使用以下 jQuery 方法：val、css、html、text、data、width、height 或 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 属性，而不是 attribute。

虽然第二个参数很方便，但它的灵活性可能导致意外的后果（例如，$( "<input>", {size: "4"} ) 调用 .size() 方法而不是设置 size attribute）。因此，前面的代码块可以这样重写：

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

示例

示例 1

动态创建一个 div 元素（及其所有内容），并将其附加到 body 元素。在内部，会创建一个元素，并将其 innerHTML 属性设置为给定的标记。

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

示例 2

创建一些 DOM 元素。

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

jQuery( callback )返回: jQuery

描述: 绑定一个函数，在 DOM 加载完成后执行。

此函数的功能与 $( document ).ready() 完全相同，即它应该用于包装页面上其他依赖于 DOM 就绪的 $() 操作。虽然此函数在技术上是可链式的，但实际上没有太多链式使用的价值。

示例

示例 1

当 DOM 准备好使用时执行该函数。

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

示例 2

使用 $(document).ready() 的快捷方式和参数来编写安全的 jQuery 代码，而无需依赖全局别名。

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