jQuery()| jqueryAPI 2.2 中文手册- AspRain.cn 致力于Web开发技术翻译整理

jQuery API 2.2.0

jQuery()

分类:核心

返回匹配元素的一个集合,要么是在DOM中根据传入的参数找到的,要么是用传入的HTMLstring创建的。

返回: jQuery

jQuery( selector [, context ] )

描述:接受一个包含了CSS选择器的字符串,它用来匹配一个元素集合。

加入于: 1.0
jQuery( selector [, context ] )
  • selector
    类型:Selector
    一个字符串,它包含了一个选择器表达式。
  • context
    类型:Element or jQuery
    一个DOM元素、Document,或者jQuery,用作上下文。
加入于: 1.0
jQuery( element )
  • element
    类型:Element
    一个DOM元素,它被包裹在一个jQuery对象中。
加入于: 1.0
jQuery( elementArray )
  • elementArray
    类型:Array
    一个数组,它包含了一个DOM元素的集合,被包裹在一个jQuery对象中。
加入于: 1.0
jQuery( object )
  • object
    类型:PlainObject
    一个纯对象,它被包含在一个jQuery对象中。
加入于: 1.0
jQuery( selection )
  • selection
    类型:jQuery
    一个用来克隆的已有jQuery对象。
加入于: 1.4
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

jQuery( selector [, context ] )

描述:用提供的HTML字符串快速创建DOM对象。

加入于: 1.0
jQuery( html [, ownerDocument ] )
  • html
    类型:htmlString
    一个快速创建元素的HTML字符串。注意这是解析HTML,不是解析XML
  • ownerDocument
    类型:document
    创建新元素的document。
加入于: 1.4
jQuery( html, attributes )
  • 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 &gt;"]

这个行为是可预期的。自从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

jQuery( selector [, context ] )

描述:绑定一个函数,当DOM完成加载时执行它。

加入于: 1.0
jQuery( callback )
  • callback
    类型:Function()
    当DOM就绪时执行的函数。

该函数的行为就像$( document ).ready(),在这里它必须用来在网页上包裹别的$()运算符,取决于DOM是否已经就绪。与此同时,从技术上来说,该函数是可连缀的,虽然对它作连缀真的没什么用处。

示例

当DOM已经准备好可用时执行这个函数。

$(function() {
  // Document已就绪
});

为了更加安全的使用jQuery的$别名,而不依赖全局的$别名,我们可以使用$(document).ready()的简写和参数来达到此目的。

jQuery(function( $ ) {
  // 你在这里使用更加安全的$别名的代码
});

如果网页上不能运行示例,请点击http://www.asprain.cn/jQueryAPI/jquery.htm查看示例。

如果你觉得本文档对你有用,欢迎给翻译作者支付宝打赏,支持翻译作者源源不断翻译更多有用的技术文档。