英文原版:http://jquery.bassistance.de/jquery-getting-started.html ,感谢原文作者Jörn Zaefferer
这个指南是一个对jQuery库的说明,要求读者了解HTML(DOM)和CSS的一些常识。它包括了一个简单的Hello World的例子,选择器和事件基础,AJAX、FX的用法,以及如何制作jQuery的插件。 这个指南包括了很多代码,你可以copy它们,并试着修改它们,看看产生的效果。
内容提要
安装
一开始,我们需要一个jQuery的库,最新的下载可以到这里找到。这个指南提供一个基本包含实例的包供下载.
下载:jQuery Starterkit
(译者Keel注:一定要下载这个包,光看文章不实践肯定是不行的。)
下载后解压缩,然后用你最喜欢的文本编辑器打开starterkit.html和custom.js这两个文件。(译者Keel注:这两个就是例子文件,所有的例子都用这两个例子作出,custom.js写jQuery代码,starterkit.html观察效果.建议用editPlus打开)
现在,我们就已经做好了一切准备来进行这个著名的"Hello world"例子.
本章的相关链接:
Hello jQuery
在做所有事情之前,我们要让jQuery读取和处理文档的DOM,必须尽可能快地在DOM载入后开始执行事件,所以,我们用一个ready事件作为处理HTML文档的开始.看看我们打开的custom.js这个文件,里面已经准备好了:
$(document).ready(function() { // do stuff when DOM is ready});
放一个简单的alert事件在需要等DOM完成载入,所以我们把任务稍稍变复杂一点:在点击任何一个链接时显示一个alert.
$(document).ready(function() { $("a").click(function() {alert("Hello world!"); });});
这样在你点击页面的一个链接时都会触发这个"Hello world"的提示。
(译者Keel注:请照此代码修改custom.js并保存,然后用浏览器打开starterkit.html观察效果。)
让我们看一下这些修改是什么含义。$("a") 是一个jQuery选择器(selector),在这里,它选择所有的a标签(译者Keel注:即),$号是 jQuery “类”(jQuery "class")的一个别称,因此$()构造了一个新的jQuery 对象(jQuery object)。函数 click() 是这个jQuery对象的一个方法,它绑定了一个单击事件到所有选中的标签(这里是所有的a标签),并在事件触发时执行了它所提供的alert方法.
这里有一个拟行相似功能的代码:
不同之处很明显,用jQuery不需要在每个a标签上写onclick事件,所以我们拥有了一个整洁的结构文档(HTML)和一个行为文档(JS),达到了将结构与行为分开的目的,就像我们使用CSS追求的一样.
下面我们会更多地了解到选择器与事件.
本章的相关链接:
Find me:使用选择器和事件
jQuery提供两种方式来选择html的elements,第一种是用CSS和Xpath选择器联合起来形成一个字符串来传送到jQuery的构造器(如:$("div > ul a"));第二种是用jQuery对象的几个methods(方法)。这两种方式还可以联合起来混合使用。
为了测试一下这些选择器,我们来试着在我们starterkit.html中选择并修改第一个ordered list.
一开始,我们需要选择这个list本身,这个list有一个ID叫“orderedlist”,通常的javascript写法是document.getElementById("orderedlist").在jQuery中,我们这样做:
$(document).ready(function() { $("#orderedlist").addClass("red");});
这里将starterkit中的一个CSS样式red附加到了orderedlist上(译者Keel注:参考测试包中的css目录下的core.css,其中定义了red样式)。因此,在你刷新了starterkit.html后,你将会看到第一个有序列表(ordered list )背景色变成了红色,而第二个有序列表没有变化.
现在,让我们添加一些新的样式到list的子节点.
$(document).ready(function() { $("#orderedlist > li").addClass("blue");});
这样,所有orderedlist中的li都附加了样式"blue"。
现在我们再做个复杂一点的,当把鼠标放在li对象上面和移开时进行样式切换,但只在list的最后一个element上生效。
$(document).ready(function() { $("#orderedlist li:last").hover(function() {$(this).addClass("green"); }, function() { $(this).removeClass("green"); });});
还有大量的类似的CSS和XPath例子,更多的例子和列表可以在这里找到。(译者Keel注:入门看此文,修行在个人,要想在入门之后懂更多,所以这段话的几个链接迟早是要必看的!不会又要翻译吧...^_^!)
每一个onXXX事件都有效,如onclick,onchange,onsubmit等,都有jQuery等价表示方法(译者Keel注:jQuery不喜欢onXXX,所以都改成了XXX,去掉了on)。其他的一些事件,如ready和hover,也提供了相应的方法。
你可以在Visual jQuery找到全部的事件列表,在Events栏目下.
用这些选择器和事件你已经可以做很多的事情了,但这里有一个更强的好东东!
$(document).ready(function() {$("#orderedlist").find("li").each(function(i) {$(this).html( $(this).html() + " BAM! " + i ); });});
find() 让你在已经选择的element中作条件查找,因此 $("#orderedlist).find("li") 就像 $("#orderedlist li"). each()一样迭代了所有的li,并可以在此基础上作更多的处理。 大部分的方法,如addClass(), 都可以用它们自己的 each() 。在这个例子中, html()用来获取每个li的html文本, 追加一些文字,并将之设置为li的html文本。(译者Keel注:从这个例子可以看到.html()方法是获取对象的html代码,而.html('xxx')是设置'xxx'为对象的html代码)
另一个经常碰到的任务是在没有被jQuery覆盖的DOM元素上call一些方法,想像一个在你用AJAX方式成功提交后的reset:
$(document).ready(function() { // use this to reset a single form$("#reset").click(function() { $("#form")[0].reset(); });});
(译者Keel注:这里作者将form的id也写成了form,源文件有
$.ajaxSetup(settings)
Ajax请求全局设置,详细请$.ajax选项描述。
返回值:undefined
参数:settings (Map):用于Ajax请求的键/值对。
示例:
设置默认请求url为”/xmlhttp/”,无全局操作权限,用POST方法请求。下面用Ajax请求一些数据!
1. $.ajaxSetup( {
2. url: "/xmlhttp/",
3. global: false,
4. type: "POST"
5. } );
6. $.ajax({ data: myData });
参数名 |
类型 |
描述 |
url |
String |
(默认: 当前页地址) 发送请求的地址。 |
type |
String |
(默认: “GET”) 请求方式 (”POST” 或 “GET”), 默认为 “GET”。注意:其它 HTTP 请求方法,如 PUT 和 DELETE 也可以使用,但仅部分浏览器支持。 |
timeout |
Number |
设置请求超时时间(毫秒)。此设置将覆盖全局设置。 |
async |
Boolean |
(默认: true) 默认设置下,所有请求均为异步请求。如果需要发送同步请求,请将此选项设置为 false。注意,同步请求将锁住浏览器,用户其它操作必须等待请求完成才可以执行。 |
beforeSend |
Function |
发送请求前可修改 XMLHttpRequest 对象的函数,如添加自定义 HTTP 头。XMLHttpRequest 对象是唯一的参数。 function(XMLHttpRequest) {this;// the options for thisajax request} |
cache |
Boolean |
(默认: true) jQuery 1.2 新功能,设置为 false 将不会从浏览器缓存中加载请求信息。 |
complete |
Function |
请求完成后回调函数 (请求成功或失败时均调用)。参数: XMLHttpRequest 对象,成功信息字符串。 function(XMLHttpRequest, textStatus) {this;// the options for thisajax request} |
contentType |
String |
(默认: “application/x-www-form-urlencoded”) 发送信息至服务器时内容编码类型。默认值适合大多数应用场合。 |
data |
Object, |
发送到服务器的数据。将自动转换为请求字符串格式。GET 请求中将附加在 URL 后。查看 processData 选项说明以禁止此自动转换。必须为 Key/Value 格式。如果为数组,jQuery 将自动为不同值对应同一个名称。如 {foo:["bar1", "bar2"]} 转换为 ‘&foo=bar1&foo=bar2′。 |
dataType |
String |
预期服务器返回的数据类型。如果不指定,jQuery 将自动根据 HTTP 包 MIME 信息返回 responseXML 或 responseText,并作为回调函数参数传递,可用值: “xml”: 返回 XML 文档,可用 jQuery 处理。 “html”: 返回纯文本 HTML 信息;包含 script. 元素。 “script”: 返回纯文本 JavaScript. 代码。不会自动缓存结果。 “json”: 返回 JSON 数据 。 “jsonp”:JSONP格式。使用JSONP形式调用函数时,如 “myurl?callback=?” jQuery 将自动替换 ? 为正确的函数名,以执行回调函数。 |
error |
Function |
(默认: 自动判断 (xml 或 html)) 请求失败时将调用此方法。这个方法有三个参数:XMLHttpRequest 对象,错误信息,(可能)捕获的错误对象。 function(XMLHttpRequest, textStatus, errorThrown) {//通常情况下textStatus和errorThown只有其中一个有值this;// the options for thisajax request} |
global |
Boolean |
(默认: true) 是否触发全局 AJAX 事件。设置为 false 将不会触发全局 AJAX 事件,如 ajaxStart 或 ajaxStop 。可用于控制不同的Ajax事件 |
ifModified |
Boolean |
(默认: false) 仅在服务器数据改变时获取新数据。使用 HTTP 包 Last-Modified 头信息判断。 |
processData |
Boolean |
(默认: true) 默认情况下,发送的数据将被转换为对象(技术上讲并非字符串) 以配合默认内容类型 “application/x-www-form-urlencoded”。如果要发送 DOM 树信息或其它不希望转换的信息,请设置为 false。 |
success |
Function |
请求成功后回调函数。这个方法有两个参数:服务器返回数据,返回状态 function(data, textStatus) {// data could be xmlDoc, jsonObj, html, text, etc...this;// the options for thisajax request} |
Example: 加载并执行一个 JS 文件。
$.ajax({ type: "GET", url: "test.js", dataType: "script" });
Example: 保存数据到服务器,成功时显示信息。
$.ajax({ type: "POST", url: "some.php", data: "name=John&location=Boston", success: function(msg){ alert( "Data Saved: " + msg ); } });
Example: 装入一个 HTML 网页最新版本。
$.ajax({ url: "test.html", cache: false, success: function(html){ $("#results").append(html); }});
Example: 同步加载数据。发送请求时锁住浏览器。需要锁定用户交互操作时使用同步方式。
var html = $.ajax({ url: "some.php", async: false }).responseText;
Example: 发送 XML 数据至服务器。设置 processData 选项为 false,防止自动转换数据格式。
var xmlDocument = [create xml document]; $.ajax({ url: "page.php", processData: false, data: xmlDocument, success: handleResponse });
Example: 作为发送数据到服务器的ID,保存一些数据到服务器,并通知用户一旦它的完成。请注意,此用法 - 返回到一个变量的调用的结果 - 需要同步(阻塞)的要求! (异步:假)
bodyContent = $.ajax({ url: "script.php", global: false, type: "POST", data: ({id : this.getAttribute('id')}), dataType: "html", async:false, success: function(msg){ alert(msg); } }).responseText;
version added: 1.5jQuery.ajax( url, [ settings ] )
url一个用来包含发送请求的URL字符串。
settings一个以"{键:值}"组成的AJAX 请求设置。所有选项都是可选的。可以使用$.ajaxSetup()设置任何默认参数。看jQuery.ajax( settings )下所有设置的完整列表。
version added: 1.0jQuery.ajax( settings )
settings一个以"{键:值}"组成的AJAX 请求设置。所有选项都是可选的。可以使用$.ajaxSetup()设置任何默认参数。
acceptsMap
默认: 取决于数据类型
asyncBoolean
默认: true
beforeSend(jqXHR, settings)Function
cacheBoolean
默认: true, dataType为"script"和"jsonp"时默认为false
complete(jqXHR, textStatus)Function, Array
contents(added 1.5)Map
contentTypeString
默认: 'application/x-www-form-urlencoded'
contextObject
converters(1.5新增)Map
默认: {"* text": window.String, "text html": true, "text json": jQuery.parseJSON, "text xml": jQuery.parseXML}
crossDomain(1.5新增)
默认: 同域请求为false, 跨域请求为true
dataObject, String
dataFilter(data, type)Function
dataTypeString
默认: Intelligent Guess (xml, json, script, or html)
error(jqXHR, textStatus, errorThrown)Function
请求失败时调用此函数。有以下三个参数:jqXHR (在 jQuery 1.4.x中, XMLHttpRequest) 对象、描述发生的错误类型的一个字符串和捕获的异常对象。如果发生了错误,错误信息(第二个参数)除了得到null
之外,还可能是"timeout"
,"error"
,"abort"
和"parsererror"
。这是一个 Ajax Event。 在jQuery 1.5, 在error
设置可以接受函数组成的数组。每个函数将被依次调用。注意:此处理程序不被跨域脚本和JSONP形式的请求调用。
globalBoolean
默认: true
无论怎么样这个请求将触发全局AJAX事件处理程序。默认是true
。设置为 false 将不会触发全局 AJAX 事件,如 ajaxStart 或 ajaxStop 可用于控制不同的。这可以用来控制各种Ajax Events.
headers(1.5新增)Map
Default: {}
一个额外的"{键:值}"对映射到请求一起发送。此设置被设置之前beforeSend
函数被调用;因此,消息头中的值设置可以在覆盖beforeSend
函数范围内的任何设置。
ifModifiedBoolean
默认: false
仅在服务器数据改变时获取新数据。使用 HTTP 包 Last-Modified 头信息判断。在jQuery 1.4中,他也会检查服务器指定的'etag'来确定数据没有被修改过。
isLocal(added 1.5.1)Boolean
默认: 取决于当前的位置协议
允许当前环境被认定为“本地”,(如文件系统),即使jQuery默认情况下不会承认它。以下协议目前公认为本地:file
, *-extension
, and widget
。如果isLocal
设置需要修改,建议在$.ajaxSetup()
方法中这样做一次。
jsonpString
在一个jsonp请求中重写回调函数的名字。这个值用来替代在"callback=?"这种GET或POST请求中URL参数里的"callback"部分,比如{jsonp:'onJsonPLoad'}会导致将"onJsonPLoad=?"传给服务器。在jQuery 1.5,,设置jsonp
选项为false
阻止了jQuery从加入"?callback"字符串的URL或试图使用"=?"转换。在这种情况下,你也应该明确设置jsonpCallback
设置。例如,{ jsonp: false, jsonpCallback: "callbackName" }
jsonpCallbackString, Function
为jsonp请求指定一个回调函数名。这个值将用来取代jQuery自动生成的随机函数名。这主要用来让jQuery生成度独特的函数名,这样管理请求更容易,也能方便地提供回调函数和错误处理。你也可以在想让浏览器缓存GET请求的时候,指定这个回调函数名。在jQuery 1.5,你也可以使用一个函数值该设置,在这种情况下jsonpCallback
的值设置到该函数的返回值。
mimeType(added 1.5.1)String
一个mime类型用来覆盖XHR的 MIME类型。
passwordString
用于响应HTTP访问认证请求的密码
processDataBoolean
默认: true
默认情况下,通过data选项传递进来的数据,如果是一个对象(技术上讲只要不是字符串),都会处理转化成一个查询字符串,以配合默认内容类型 "application/x-www-form-urlencoded"。如果要发送 DOM 树信息或其它不希望转换的信息,请设置为false
。
scriptCharsetString
只有当请求时dataType为"jsonp"或"script",并且type是"GET"才会用于强制修改charset。通常只在本地和远程的内容编码不同时使用。
statusCode(1.5新增)Map
默认: {}
一组数值的HTTP代码和函数对象,当响应时调用了相应的代码。例如,如果响应状态是404,将触发以下警报:
$.ajax({ statusCode: {404: function() { alert('page not found'); }});
如果请求成功,状态代码函数作为回调的成功相同的参数;如果在一个错误的结果,他们采取了相同的参数error
回调。
success(data, textStatus, jqXHR)Function, Array
请求成功后的回调函数。这个函数传递3个参数:从服务器返回的数据,并根据dataType参数进行处理后的数据,一个描述状态的字符串;还有 jqXHR(在jQuery 1.4.x的中,XMLHttpRequest) 对象 。在jQuery 1.5,成功设置可以接受一个函数数组。每个函数将被依次调用。这是一个Ajax Event.
timeoutNumber
设置请求超时时间(毫秒)。如果一个设置有$.ajaxSetup(),此设置将覆盖全局设置。例如,你可以使用这个属性来提供一个单一的请求比所有你所设置时间在一秒钟内的其他要求更长的超时。见$.ajaxSetup()
全局超时。
traditionalBoolean
如果你想要用传统的方式来序列化数据,那么就设置为true。请参考工具分类下面的jQuery.param方法.
typeString
默认: 'GET'
请求方式 ("POST" 或 "GET"), 默认为 "GET"。注意:其它 HTTP 请求方法,如 PUT 和 DELETE 也可以使用,但仅部分浏览器支持。
urlString
默认: 当前地址
发送请求的地址。
usernameString
于响应HTTP访问认证请求的用户名
xhrFunction
默认 当可用的ActiveXObject(IE)中,否则为XMLHttpRequest
回调创建XMLHttpRequest对象。当可用时默认为ActiveXObject(IE)中,否则为XMLHttpRequest。提供覆盖你自己的执行的XMLHttpRequest或增强工厂。
xhrFields(added 1.5.1)Map
一对“文件名-文件值”在本机设置XHR
对象。例如,如果需要的话,你可以用它来设置withCredentials
为true
的跨域请求。
$.ajax()
函数所有的基础jQuery的Ajax请求发送。它往往不是必须的,直接调用这个函数,几个高层次的替代品如$.get()
和.load()
可用,更容易使用,如果不常见的选项是必需的,不过,$.ajax()
可以使用更灵活。
在简单地说, $.ajax()
函数可以不带参数调用:
$.ajax();
注意: 所有的选项都可以通过$.ajaxSetup()
函数来全局设置
这个例子中,不使用选项,加载当前页面的内容,但其结果没有。若要使用结果,我们可以实现的回调功能之一。
jqXHR 对象
该jQuery的XMLHttpRequest(jqXHR)对象返回$.ajax()
在jQuery 1.5是一个对象的超集浏览器的原生的XMLHttpRequest。例如,它包含responseText
和responseXML
性能,以及一个getResponseHeader()
方法。当传输机制是XMLHttpRequest以外的东西(例如,一个一个JSONP请求脚本标签)的jqXHR对象尽可能的模拟原生的XHR功能。
在jQuery 1.5.1, 在jqXHR
对象还包含了overrideMimeType
方法。
$.ajax()
返回的jqXHR对象 实现约定的接口,给他们的所有属性,方法,和约定的行为(见Deferred object获取更多信息)。为了方便和一致性$.ajax()
回调函数名称中使用。jqXHR也提供.error()
.success()
和.complete()
方法。这些方法当$.ajax()
请求终止时需要一个函数参数调用,这个函数接收$.ajax()
回调函数名相同的参数。在jQuery 1.5这允许你指定一个请求的多个回调,甚至可能分配请求后已完成回调。(如果请求已经完成,回调立即触发。)
// Assign handlers immediately after making the request, // and remember the jqxhr object for this request var jqxhr = $.ajax({ url: "example.php" }) .success(function() { alert("success"); }) .error(function() { alert("error"); }) .complete(function() { alert("complete"); }); // perform other work here ... // Set another completion function for the request above jqxhr.complete(function(){ alert("second complete"); });
为了向后兼容XMLHttpRequest
,一jqXHR
对象将公开下列属性和方法:
readyState
status
statusText
responseXML
and/or responseText
当底层的请求分别作出XML和/或文本响应setRequestHeader(name, value)
这背离了换上了新一旧的价值,而不是串联的新值与旧标准 getAllResponseHeaders()
getResponseHeader()
abort()
假如没有onreadystatechange
机制,不管怎样 由于success
, error
,complete
和statusCode
覆盖所有可能的要求。
回调函数
如果要处理$.ajax()得到的数据,则需要使用回调函数。beforeSend、error、dataFilter、success、complete。
在jQuery 1.5, error
, success
,和complete
回调钩子先入先出队列管理。这意味着你可以为每个挂钩分配多个回调。见Deferred object methods ,这是实现内部的$.ajax()
回调挂钩。
在this
回调是在所有参考对象在context
选项传递给$.ajax
在设置;如果context
没有指定,this
是他们自己的Ajax设置参考。
某些类型Ajax的请求,如JSONP形式和跨域的GET请求,请不要使用XHR;在这些情况下XMLHttpRequest
和textStatus
参数传递给回调是undefined
。
这里有$.ajax()
提供的钩子回调 :
jqXHR
对象和settings
作为参数对象。jqXHR
,字符串表示的错误类型,如果适用的异常对象。一些内置的错误,将提供作为例外对象的字符串: "abort", "timeout", "No Transport"。dataFilter
在请求成功之后调用。传入返回的数据以及dataType
参数的值。并且必须返回新的数据(可能是处理过的)传递给success
回调函数。success
当请求之后调用。传入返回后的数据,以及包含成功代码的字符串。他们收到返回的数据,一个包含成功的代码和jqXHR
对象。complete
它们的顺序依次登记回调,请求完成时,无论是在失败或成功。他们收到jqXHR
对象,以及一个包含成功或错误代码。For example, 通过使用返回的HTML,我们可以实现一个success
事件处理器:
$.ajax({ url: 'ajax/test.html', success: function(data) { $('.result').html(data); alert('Load was performed.'); }});
数据类型
$.ajax()函数依赖服务器提供的信息来处理返回的数据。如果服务器报告说返回的数据是XML,那么返回的结果就可以用普通的XML方法或者jQuery的选择器来遍历。如果见得到其他类型,比如HTML,则数据就以文本形式来对待。
通过dataType选项还可以指定其他不同数据处理方式。除了单纯的XML,还可以指定 html、json、jsonp、script或者text。
其中,text和xml类型返回的数据不会经过处理。这些数据仅仅是传递给处理程序的成功,无论是通过responseText
或responseXML
所有的jqXHR
对象。
注意:我们必须确保网页服务器报告的MIME类型与我们选择的dataType所匹配。比如说,XML的话,服务器端就必须声明 text/xml
或者 application/xml
来获得一致的结果。
如果指定为 html
类型,任何内嵌的JavaScript都会在HTML作为一个字符串返回之前执行。类似的,指定script
类型的话,也会先执行服务器端生成JavaScript,然后再把脚本作为一个文本数据返回。
如果指定为json
类型,则会把获取到的数据作为一个JavaScript对象来解析,并且把构建好的对象作为结果返回。为了实现这个目的,他首先尝试使用jQuery.parseJSON()
。如果浏览器不支持,则使用一个Function
来构建。JSON数据是一种能很方便通过JavaScript解析的结构化数据。如果获取的数据文件存放在远程服务器上(域名不同,也就是跨域获取数据),则需要使用jsonp类型。使用这种类型的话,会创建一个查询字符串参数callback=?
,这个参数会加在请求的URL后面。服务器端应当在JSON数据前加上回调函数名,以便完成一个有效的JSONP请求。如果要指定回调函数的参数名来取代默认的callback,可以通过设置$.ajax()
的jsonp参数。
注意:JSONP是JSON格式的扩展。他要求一些服务器端的代码来检测并处理查询字符串参数。更多信息可以参阅original post detailing its use.
如果指定了script
或者jsonp
类型,那么当从服务器接收到数据时,实际上是用了