jQuery()
分类:核心
返回匹配元素的一个集合,要么是在DOM中根据传入的参数找到的,要么是用传入的HTMLstring创建的。
jQuery( selector [, context ] )
描述:接受一个包含了CSS选择器的字符串,它用来匹配一个元素集合。
- selector类型:Selector一个字符串,它包含了一个选择器表达式。
- context一个DOM元素、Document,或者jQuery,用作上下文。
- element类型:Element一个DOM元素,它被包裹在一个jQuery对象中。
- elementArray类型:Array一个数组,它包含了一个DOM元素的集合,被包裹在一个jQuery对象中。
- object类型:PlainObject一个纯对象,它被包含在一个jQuery对象中。
- selection类型:jQuery一个用来克隆的已有jQuery对象。
该签名不接受任何参数。
在上面列出的第一个公式中,jQuery()
——也可以把它写成$()
——搜索遍了DOM以找到任何匹配提供的选择器的元素,并创建了一个新的jQuery对象,引用这些元素:
$( "div.foo" );
如果没有元素匹配提供的选择器,这些新的jQuery对象是“空的”;那是说,它不包含元素,而且.length
属性是0。
选择器上下文
默认情况下,选择器从document根节点开始,在DOM中进行搜索。然而,可以给$()
函数传递一个用于上下文搜索的可选的第二个参数。举个例子,在一个事件处理函数内部作搜索,可以这样限制搜索范围:
$( "div.foo" ).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方法:
$( "div.foo" ).click(function() { $( this ).slideUp(); });
这个示例导致点击元素时,元素以一个滑动动画隐藏起来。因为这个处理函数在this
关键词中接收被点击的项目,作为一个光裸的元素,该元素在对它应用jQuery方法之前,必须被传递给$()
函数。
从一个Ajax调用返回的XML数据,可以传递给$()
函数,因此XML结构的单个元素可以使用.find()
和别的DOM遍历方法来检索。
$.post( "url.xml", function( data ) { var $child = $( data ).find( "child" ); });
克隆jQuery对象
当一个jQuery对象被传递给$()
函数,就创建了这个对象的克隆体。这是一个新的jQuery对象,引用相同的DOM元素,作为初值。
返回一个空集合
自从jQuery 1.4,调用不带参数的jQuery
方法,会返回一个空的jQuery集合(它的.length
属性是0)。在以前的jQuery版本中,这将返回包含document节点的集合。
对纯对象起作用
现在,为数不多的几个支持jQuery包裹纯JavaScript对象的操作符是:.data()
、.prop()
、.on()
、.off()
、.trigger()
和.triggerHandler()
。.data()
(或别的需要.data()
的方法)在一个纯对象上的使用,将导致对象上出现一个新属性,称为jQuery{randomNumber}
(例如,jQuery123456789
)。
// 定义一个纯对象 var foo = { foo: "bar", hello: "world" }; // 把它传递到jQuery函数中 var $foo = $( foo ); // 测试访问的属性值 var test1 = $foo.prop( "foo" ); // bar // 测试设置属性值 $foo.prop( "foo", "foobar" ); var test2 = $foo.prop( "foo" ); // foobar // 测试使用.data()作为上面的总结 $foo.data( "keyName", "someValue" ); console.log( $foo ); // will now contain a jQuery{randomNumber} property // 测试绑定一个事件名,并触发它 $foo.on( "eventName", function () { console.log( "eventName was called" ); }); $foo.trigger( "eventName" ); // Logs "eventName was called"
必须使用.trigger( "eventName" )
,它将在对象上搜索一个“eventName”属性,并试图在件附加一个要执行的jQuery处理函数之后执行它。它不会检查该属性是不是一个函数。要想避免这种行为,必须用.triggerHandler( "eventName" )
来代替它。
$foo.triggerHandler( "eventName" ); // 还记录了"eventName was called"
示例
找到属于一个<div>元素的子元素的所有<p>元素,并给它应用一个边框。
<!doctype html> <html lang="en"> <head> <meta charset="utf-8"> <title>jQuery demo</title> <script src="https://code.jquery.com/jquery-1.10.2.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>
演示结果
在document的第一个表单中找到所有的type="radio"的<input>。
$( "input:radio", document.forms[ 0 ] );
找到来自一个Ajax请求的XML document中的所有的div元素。
$( "div", xml.responseXML );
把网页的背景色设置成黑色。
$( document.body ).css( "background", "black" );
隐藏一个表单内的所有输入元素。
$( myForm.elements ).hide();
jQuery( selector [, context ] )
描述:用提供的HTML字符串快速创建DOM对象。
- html类型:htmlString一个快速创建元素的HTML字符串。注意这是解析HTML,不是解析XML
- ownerDocument类型:document创建新元素的document。
- html类型:htmlString一个字符串,它定义了一个独立的HTML元素(例如:<div/>或<div></div>)。
- attributes类型:PlainObject一个元素属性、事件和方法的对象,将在新创建的元素上调用它。
创建新元素
如果一个字符串作为参数传递给$()
,jQuery会检查该字符串,以看看它是否像是html(亦即,它是否以<tag ... >
开头)。如果不是,该字符串会被翻译成一个选择器表达式,如上面所解释的。但是如果字符串看起来像是一个HTML片段,jQuery会尝试作这段HTML创建一个新DOM元素。然后就创建了一个jQuery对象,并返回对这些元素的引用。你可以在这个对象上实施任何别的常用的jQuery方法:
$( "<p id='test'>My <em>new</em> text</p>" ).appendTo( "body" );
要把字符串显式地解析成HTML,请使用$.parseHTML()
方法。
默认情况下,用一个.ownerDocument
创建的元素,会把document匹配到jQuery库所载入的地方。被注入到一个不同的document的元素,必须使用那个document来创建,例如:$("<p>hello iframe</p>", $("#myiframe").prop("contentWindow").document)
。
如果HTML比较复杂,不仅仅是一个不带元素属性的标签,如上面这个例子中的,元素的实际创建是用浏览器的.innerHTML
机制来处理的。在大多数情况下,jQuery创建了一个新的<div>
元素,并把元素的innerHTML
属性设置成所传入的HTML片段。当参数具有简单的标签(带有可选的关闭标签或者快速关闭符)——$( "<img />" )
或者$( "<img>" )
、$( "<a></a>" )
或者$( "<a>" )
——jQuery会使用原生的JavaScript函数.createElement()
来创建元素。
如果传入了一个复杂的HTML,有些浏览器可能不能生成一个DOM,严格复制所提供的HTML源。如前所述,jQuery使用浏览器的.innerHTML
属性来解析传入的HTML,并把它插入到当前的document中。在这个过程中,一些浏览器筛掉了某些元素,比如说<html>
、<title>
或<head>
元素。结果是,插入的元素可能不代表原来传入的字符串。
然而,筛选并不只限于这些元素。举个例子,Internet Explorer 8及以前的版本会把所有的链接上的href
属性转换成绝对的URL,而且Internet Explorer 9及以前的版本如果不附加独立的兼容性层,就不能正确地处理HTML 5元素。
为了确保跨平台兼容性,这个片段必须是格式良好的。可以包含别的元素的标签,必须是成对的,用一个闭标签:
$( "<a href='http://jquery.com'></a>" );
标签不能包含可以被快速关闭或者不关闭的元素:
$( "<img>" ); $( "<input>" );
在把HTML传递给jQuery()
时,要注意文本节点不会被视为一个DOM元素。除了一些例外方法(比如说.content()
),它们一般会被忽略,或者删除。例如:
var el = $( "<br>2<br>3" ); // returns [<br>, "2", <br>] el = $( "<br>2<br>3 >" ); // returns [<br>, "2", <br>, "3 >"]
这个行为是可预期的。自从jQuery 1.9.0(以前的版本除非使用jQuery移值插件),jQuery()
要求HTML字符串以<
开头(亦即,文本节点不能出现在HTML字符串的前面)。
自从jQuery 1.4,一个可以传递给.attr()
方法的属性的超集构成的纯对象,可以传递给jQuery()
作为第二个参数。
重要:如果传递了第二个参数,第一个参数中的HTML字符串必须代表一个简单的元素,没有元素属性。自从jQuery 1.4,可以传入任何事件类型,而且可以调用下面的jQuery方法:.val()
、.css()
、.html()
、.text()
、.data()
、.width()
、.height()
以及.offset()
。
自从jQuery 1.8,任何jQuery实例方法(jQuery.fn
的方法)可以用作一个对象的属性,传递给第二个参数:
$( "<div></div>", { "class": "my-div", on: { touchstart: function( event ) { // Do something } } }).appendTo( "body" );
在对象中,名称"class"
必须用引号引起来,因为它是一个jQuery保留词,而且不能用"className"
,因为它引用了DOM属性,不是元素属性。
虽然第二个参数变方便了,但是它的灵活性也导致了没意识到的后果(例如,$( "<input>", {size:"4"} )
调用了.size()
方法,而不是设置元素属性size。)因此前面的代码块可以改成这样子:
$( "<div></div>" ) .addClass( "my-div" ) .on({ touchstart: function( event ) { // Do something } }) .appendTo( "body" );
示例
动态地创建一个div元素(以及它的所有的内容),并把它追加到body元素末尾。会内在地创建一个元素,它的innerHTML属性被设置为给定的元素标签。
$( "<div><p>Hello</p></div>" ).appendTo( "body" )
创建一些DOM元素。
$( "<div/>", { "class": "test", text: "Click me!", click: function() { $( this ).toggleClass( "test" ); } }) .appendTo( "body" );
jQuery( selector [, context ] )
描述:绑定一个函数,当DOM完成加载时执行它。
该函数的行为就像$( document ).ready()
,在这里它必须用来在网页上包裹别的$()
运算符,取决于DOM是否已经就绪。与此同时,从技术上来说,该函数是可连缀的,虽然对它作连缀真的没什么用处。
示例
当DOM已经准备好可用时执行这个函数。
$(function() { // Document已就绪 });
为了更加安全的使用jQuery的$别名,而不依赖全局的$别名,我们可以使用$(document).ready()
的简写和参数来达到此目的。
jQuery(function( $ ) { // 你在这里使用更加安全的$别名的代码 });