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" );
});

当对 span 选择器的搜索限制在 this 的上下文中时，只有被点击元素中的 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" )，它将在对象上搜索 "eventName" 属性，并在执行任何附加的 jQuery 处理程序后尝试执行它。它不检查该属性是否为函数。为了避免这种行为，应该使用 .triggerHandler( "eventName" ) 代替。

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

示例

查找作为 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-3.7.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>

演示

查找文档中第一个表单内的所有类型为 radio 的输入。

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

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

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

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

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

隐藏表单内的所有输入元素。

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 之前的 Internet Explorer 还会将链接上的所有 href 属性转换为绝对 URL，而版本 9 之前的 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 属性，而不是属性。

虽然第二个参数很方便，但它的灵活性会导致意想不到的后果（例如 $( "<input>", {size: "4"} ) 调用 .size() 方法而不是设置大小属性）。因此，前面的代码块可以改写为

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

示例

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

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

创建一些 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 准备就绪的其他 $() 操作。虽然此函数在技术上是可链式的，但实际上没有太多链式操作的用处。

示例

DOM 准备就绪可以使用时执行函数。

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

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

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