$.ajax( properties )
使用HTTP请求(XMLHttpRequest)载入一个远程页面。
这是jQuery的低级AJAX实现。要查看高级抽象,见$.get、$.post等。高级的内容经常被很简单地理解和使用,但是不提供更多的方法(例如错误回调)。
$.ajax()返回创建好的XMLHttpRequest对象。多数情况下并不需要直接操纵这个对象,但是如果需要手动中止请求,它也是可用的。
注意:要确保服务器返回正确的MIME类型(例如:XML是“text/xml”)。如果返回了错误的MIME类型就会导致jQuery无法处理的严重问题。
支持的数据类型包括(见dataType选项):
"xml": 返回一个可以由jQuery对象处理的XML文档。
"html": 返回纯文本格式的HTML,包括求值后的脚本标记。
"script": 将响应作为Javascript语句求值,并返回纯文本。
"json": 将响应作为JSON求值,并返回一个Javascript对象。
选项
$.ajax()带有一个参数--“名/值对”形式的一个对象,用于初始化和处理请求。以下就是可用的所有“名/值对”:
async(Boolean) - 在默认的情况下,所有请求都是以异步的方式发送的(值为true)。如果要使用同步方式,需要将此项设置为false。
beforeSend(Function) - 用于设置自定义头部等信息的预调用函数,接收一个唯一的参数--XMLHttpRequest对象。
complete(Function) - 当请求完成时调用的函数。这个函数会得到两个参数:XMLHttpRequest对象和一个描述请求成功的类型的字符串。
contentType(String) - 设置发送请求的content=type。默认值是 "application/x-www-form-urlencoded", 这个值能满足多数情况。
data(Object|String) - 要发送到服务器的数据。如果还不是一个字符串,就自动轮换为一个查询字符串。即附加到GET请求的url后面的字符串。要防止自动处理见processData选项。对象必须是Key/Value对。如果value是一个数组,jQuery对于同一个key会连续使用多个值,例如{foo:["bar1","bar2"]}将变成'&foo=var1&foo=bar2'。
dataType(String) - 期望从服务器端返回的数据类型。无默认值:如果服务器返回XML,就将responseXML传递到回调函数,否则将resposeText传递到回调函数。
支持的数据类型包括(见dataType选项):
"xml": 返回一个可以由jQuery对象处理的XML文档。
"html": 返回纯文本格式的HTML,包括求值后的脚本标记。
"script": 将响应作为Javascript语句求值,并返回纯文本。
"json": 将响应作为JSON求值,并返回一个Javascript对象。
error(Function) - 当请求失败时调用的函数。这个函数会得到三个参数:XMLHttpRequest对象、一个描述所发生的错误类型的字符串和一个可选异常对象(如果有)。
global(Boolean) - 是否为当前的请求触发全局AJAX事件处理函数,默认值为true。设置为false可以防止触发像ajaxStart或ajaxStop这样的全局事件处理函数。
ifModified(Boolean) - 只有响应自上次请求后被修改过才承认是成功的请求。是通过检查头部的Last-Modified值实现的。默认值为false,即忽略 对部分的检查
processData(Boolean) - 在默认的情况下,如果data选项传进的数据是一个对象而不是字符串,将会自动地被处理和转换成一个查询字符串,以适应默认的content-type--"application/x-www-form-urlencoded"。如果想发送DOMDocuments,就要把这个选项设置为false。
success(Function) - 当请求成功时调用的函数。这个函数会得到一个参数:从服务器返回的数据(根据“dataType”进行了格式化)。
timeout(Number) - 覆盖全局延迟的局部延迟,例如,在其他所有延迟经过1秒钟后,启动一个较长延迟的单独请求。有关全局延迟,见$.ajaxTimeout()。
type(String) - 请求的类型 ("POST" 或 "GET"), 默认是 "GET"。
url(String) - 要将请求发送到的URL地址。
返回值:XMLHttpRequest
参数:
propertites(Map)形成这个请求的Key/Value对
例子:加载并执行一个JavaScript文件
$.ajax({
type: "GET",
url: "test.js",
dataType: "script"
})
例子:向服务器上保存一些数据,并在完成的时候提醒用户
$.ajax({
type: "POST",
url: "some.php",
data: "name=John&location=Boston",
success: function(msg){
alert( "Data Saved: " + msg );
}
});
例子:同步载入数据。当请求可用时阻止浏览(Blocks the browser while the requests is active)。这个可以更好地在需要同步处理的时候使用另一种方式阻止用户交互。
var html = $.ajax({
url: "some.php",
async: false
}).responseText;
例子:将一个xml文件作为数据发送给服务器。通过将processData选项设置为false,数据到字符串的自动的变化就被避免了。
var xmlDocument = [create xml document];
$.ajax({
url: "page.php",
processData: false,
data: xmlDocument,
success: handleResponse
});
$.ajaxSetup( settings )
为AJAX请求进行全局设置
有关所有的可用选项的描述,见$.ajax。
返回值:undefined
参数:
settings(Map)所有的AJAX请求所使用的Key/Value对
例子:
为AJAX请求设置默认的url“/xmlhttp/”,将所有全局的处理函数设置为不可用,使用POST代替GET。下边的ajax请求将会不用设置任何东西就发送一些数据。
$.ajaxSetup( {
url: "/xmlhttp/",
global: false,
type: "POST"
} );
$.ajax({ data: myData });
$.ajaxTimeout( time )
对所有的AJAX请求设置一个固定的超时时间。这个将会使所有的AJAX请求在一个特定的事件后超时。
设置为null或0可以将超时设置为无效(默认)
你可以手动的使用XMLHttpRequest的abort()方法中断请求。
不赞成使用该方法最好使用$.ajaxSetup来代替。
返回值:undefined
参数:
time(Number)在一个AJAX请求超时前的毫秒数
例子:
让所有的AJAX请求在5秒后超时
$.ajaxTimeout( 5000 );
$.get( url, params, callback )
使用一个HTTP GET请求加载一个远程页。
这是一个不用使用复杂的$.AJAX方法就向服务器发送一个简单的GET请求的方式。它允许特定一个单独的回调方法在这个请求结束的时候被执行(只有当响应有一个成功的响应代码)。如果你既需要错误的回调又需要成功的回调,你可以使用$.ajax。
返回值:XMLHttpRequest
参数:
url(String)加载的页面的url
params(Map)(可选)将要传送给服务器的Key/Value对
callback(Function)(可选)当数据加载成功时被执行的方法
例子:
$.get("test.cgi");
例子:
$.get("test.cgi", { name: "John", time: "2pm" } );
例子:
$.get("test.cgi", function(data){
alert("Data Loaded: " + data);
});
例子:
$.get("test.cgi",
{ name: "John", time: "2pm" },
function(data){
alert("Data Loaded: " + data);
}
);
$.getIfModified( url, params, callback )
使用一个HTTP GET请求来加载一个远程页,只有从它最后一次被得到后当他没有被修改(Load a remote page using an HTTP GET request, only if it hasn't been modified since it was last retrieved)
返回值:XMLHttpRequest
参数:
url(String)加载的页面的url
params(Map)(可选)将要传送给服务器的Key/Value对
callback(Function)(可选)当数据加载成功时被执行的方法
例子:
$.getIfModified("test.html");
例子:
$.getIfModified("test.html", { name: "John", time: "2pm" } );
例子:
$.getIfModified("test.cgi", function(data){
alert("Data Loaded: " + data);
});
例子:
$.getIfModified("test.cgi",
{ name: "John", time: "2pm" },
function(data){
alert("Data Loaded: " + data);
}
);
$.getJSON( url, params, callback )
使用一个HTTP GET请求来加载一个JSON数据
返回值:XMLHttpRequest
参数:
url(String)加载的页面的url
params(Map)(可选)将要传送给服务器的Key/Value对
callback(Function)(可选)当数据加载成功时被执行的方法
例子:
$.getJSON("test.js", function(json){
alert("JSON Data: " + json.users[3].name);
});
例子:
$.getJSON("test.js",
{ name: "John", time: "2pm" },
function(json){
alert("JSON Data: " + json.users[3].name);
}
);
使用HTTP请求(XMLHttpRequest)载入一个远程页面。
这是jQuery的低级AJAX实现。要查看高级抽象,见$.get、$.post等。高级的内容经常被很简单地理解和使用,但是不提供更多的方法(例如错误回调)。
$.ajax()返回创建好的XMLHttpRequest对象。多数情况下并不需要直接操纵这个对象,但是如果需要手动中止请求,它也是可用的。
注意:要确保服务器返回正确的MIME类型(例如:XML是“text/xml”)。如果返回了错误的MIME类型就会导致jQuery无法处理的严重问题。
支持的数据类型包括(见dataType选项):
"xml": 返回一个可以由jQuery对象处理的XML文档。
"html": 返回纯文本格式的HTML,包括求值后的脚本标记。
"script": 将响应作为Javascript语句求值,并返回纯文本。
"json": 将响应作为JSON求值,并返回一个Javascript对象。
选项
$.ajax()带有一个参数--“名/值对”形式的一个对象,用于初始化和处理请求。以下就是可用的所有“名/值对”:
async(Boolean) - 在默认的情况下,所有请求都是以异步的方式发送的(值为true)。如果要使用同步方式,需要将此项设置为false。
beforeSend(Function) - 用于设置自定义头部等信息的预调用函数,接收一个唯一的参数--XMLHttpRequest对象。
complete(Function) - 当请求完成时调用的函数。这个函数会得到两个参数:XMLHttpRequest对象和一个描述请求成功的类型的字符串。
contentType(String) - 设置发送请求的content=type。默认值是 "application/x-www-form-urlencoded", 这个值能满足多数情况。
data(Object|String) - 要发送到服务器的数据。如果还不是一个字符串,就自动轮换为一个查询字符串。即附加到GET请求的url后面的字符串。要防止自动处理见processData选项。对象必须是Key/Value对。如果value是一个数组,jQuery对于同一个key会连续使用多个值,例如{foo:["bar1","bar2"]}将变成'&foo=var1&foo=bar2'。
dataType(String) - 期望从服务器端返回的数据类型。无默认值:如果服务器返回XML,就将responseXML传递到回调函数,否则将resposeText传递到回调函数。
支持的数据类型包括(见dataType选项):
"xml": 返回一个可以由jQuery对象处理的XML文档。
"html": 返回纯文本格式的HTML,包括求值后的脚本标记。
"script": 将响应作为Javascript语句求值,并返回纯文本。
"json": 将响应作为JSON求值,并返回一个Javascript对象。
error(Function) - 当请求失败时调用的函数。这个函数会得到三个参数:XMLHttpRequest对象、一个描述所发生的错误类型的字符串和一个可选异常对象(如果有)。
global(Boolean) - 是否为当前的请求触发全局AJAX事件处理函数,默认值为true。设置为false可以防止触发像ajaxStart或ajaxStop这样的全局事件处理函数。
ifModified(Boolean) - 只有响应自上次请求后被修改过才承认是成功的请求。是通过检查头部的Last-Modified值实现的。默认值为false,即忽略 对部分的检查
processData(Boolean) - 在默认的情况下,如果data选项传进的数据是一个对象而不是字符串,将会自动地被处理和转换成一个查询字符串,以适应默认的content-type--"application/x-www-form-urlencoded"。如果想发送DOMDocuments,就要把这个选项设置为false。
success(Function) - 当请求成功时调用的函数。这个函数会得到一个参数:从服务器返回的数据(根据“dataType”进行了格式化)。
timeout(Number) - 覆盖全局延迟的局部延迟,例如,在其他所有延迟经过1秒钟后,启动一个较长延迟的单独请求。有关全局延迟,见$.ajaxTimeout()。
type(String) - 请求的类型 ("POST" 或 "GET"), 默认是 "GET"。
url(String) - 要将请求发送到的URL地址。
返回值:XMLHttpRequest
参数:
propertites(Map)形成这个请求的Key/Value对
例子:加载并执行一个JavaScript文件
$.ajax({
type: "GET",
url: "test.js",
dataType: "script"
})
例子:向服务器上保存一些数据,并在完成的时候提醒用户
$.ajax({
type: "POST",
url: "some.php",
data: "name=John&location=Boston",
success: function(msg){
alert( "Data Saved: " + msg );
}
});
例子:同步载入数据。当请求可用时阻止浏览(Blocks the browser while the requests is active)。这个可以更好地在需要同步处理的时候使用另一种方式阻止用户交互。
var html = $.ajax({
url: "some.php",
async: false
}).responseText;
例子:将一个xml文件作为数据发送给服务器。通过将processData选项设置为false,数据到字符串的自动的变化就被避免了。
var xmlDocument = [create xml document];
$.ajax({
url: "page.php",
processData: false,
data: xmlDocument,
success: handleResponse
});
$.ajaxSetup( settings )
为AJAX请求进行全局设置
有关所有的可用选项的描述,见$.ajax。
返回值:undefined
参数:
settings(Map)所有的AJAX请求所使用的Key/Value对
例子:
为AJAX请求设置默认的url“/xmlhttp/”,将所有全局的处理函数设置为不可用,使用POST代替GET。下边的ajax请求将会不用设置任何东西就发送一些数据。
$.ajaxSetup( {
url: "/xmlhttp/",
global: false,
type: "POST"
} );
$.ajax({ data: myData });
$.ajaxTimeout( time )
对所有的AJAX请求设置一个固定的超时时间。这个将会使所有的AJAX请求在一个特定的事件后超时。
设置为null或0可以将超时设置为无效(默认)
你可以手动的使用XMLHttpRequest的abort()方法中断请求。
不赞成使用该方法最好使用$.ajaxSetup来代替。
返回值:undefined
参数:
time(Number)在一个AJAX请求超时前的毫秒数
例子:
让所有的AJAX请求在5秒后超时
$.ajaxTimeout( 5000 );
$.get( url, params, callback )
使用一个HTTP GET请求加载一个远程页。
这是一个不用使用复杂的$.AJAX方法就向服务器发送一个简单的GET请求的方式。它允许特定一个单独的回调方法在这个请求结束的时候被执行(只有当响应有一个成功的响应代码)。如果你既需要错误的回调又需要成功的回调,你可以使用$.ajax。
返回值:XMLHttpRequest
参数:
url(String)加载的页面的url
params(Map)(可选)将要传送给服务器的Key/Value对
callback(Function)(可选)当数据加载成功时被执行的方法
例子:
$.get("test.cgi");
例子:
$.get("test.cgi", { name: "John", time: "2pm" } );
例子:
$.get("test.cgi", function(data){
alert("Data Loaded: " + data);
});
例子:
$.get("test.cgi",
{ name: "John", time: "2pm" },
function(data){
alert("Data Loaded: " + data);
}
);
$.getIfModified( url, params, callback )
使用一个HTTP GET请求来加载一个远程页,只有从它最后一次被得到后当他没有被修改(Load a remote page using an HTTP GET request, only if it hasn't been modified since it was last retrieved)
返回值:XMLHttpRequest
参数:
url(String)加载的页面的url
params(Map)(可选)将要传送给服务器的Key/Value对
callback(Function)(可选)当数据加载成功时被执行的方法
例子:
$.getIfModified("test.html");
例子:
$.getIfModified("test.html", { name: "John", time: "2pm" } );
例子:
$.getIfModified("test.cgi", function(data){
alert("Data Loaded: " + data);
});
例子:
$.getIfModified("test.cgi",
{ name: "John", time: "2pm" },
function(data){
alert("Data Loaded: " + data);
}
);
$.getScript( url, callback )
使用一个HTTP GET请求来加载并执行一远程的JavaScript文件
返回值:XMLHttpRequest
参数:
url(String)加载的页面的url
callback(Function)(可选)当数据加载成功时被执行的方法
例子:
$.getScript("test.js");
例子:
$.getScript("test.js", function(){
alert("Script loaded and executed.");
});
$.post( url, params, callback )
使用一个HTTP POST请求加载一个远程页。
这是一个不用使用复杂的$.AJAX方法就向服务器发送一个简单的POST请求的方式。它允许特定一个单独的回调方法在这个请求结束的时候被执行(只有当响应有一个成功的响应代码)。如果你既需要错误的回调又需要成功的回调,你可以使用$.ajax。
返回值:XMLHttpRequest
参数:
url(String)加载的页面的url
params(Map)(可选)将要传送给服务器的Key/Value对
callback(Function)(可选)当数据加载成功时被执行的方法
例子:
$.post("test.cgi");
例子:
$.post("test.cgi", { name: "John", time: "2pm" } );
例子:
$.post("test.cgi",
{ name: "John", time: "2pm" },
function(data){
alert("Data Loaded: " + data);
}
);
ajaxComplete( callback )
当AJAX请求完成时添加一个被执行的方法
XMLHttpRequest和它所具有的设置都被作为一个参数传递给了回调函数
返回值:jQuery
参数:
callback(Function)要执行的方法
例子:当AJAX请求完成时显示一条信息
$("#msg").ajaxComplete(function(request, settings){
$(this).append("<li>Request Complete.</li>");
});
ajaxError( callback )
当AJAX请求失败时添加一个被执行的方法
XMLHttpRequest和它所具有的设置都被作为一个参数传递给了回调函数。第三个参数,一个异常对象,当执行这个请求的过程中出现异常的时候将会被传递。
返回值:jQuery
参数:
callback(Function)要执行的方法
例子:败时显示一条信息
$("#msg").ajaxError(function(request, settings){
$(this).append("<li>Error requesting page " + settings.url + "</li>");
});
ajaxSend( callback )
在AJAX请求提交前添加一个被执行的方法
XMLHttpRequest和它所具有的设置都被作为一个参数传递给了回调函数。
返回值:jQuery
参数:
callback(Function)要执行的方法
例子:在AJAX请求提交前显示一条信息
$("#msg").ajaxSend(function(request, settings){
$(this).append("<li>Starting request at " + settings.url + "</li>");
});
ajaxStart( callback )
当一个AJAX请求开始并且没有被激活的时候添加一个被执行的方法
返回值:jQuery
参数:
callback(Function)要执行的方法
例子:在AJAX请求开始(并且没有激活)的时候显示一条载入信息
$("#loading").ajaxStart(function(){
$(this).show();
});
ajaxStop( callback )
当一个AJAX请求结束的时候添加一个被执行的方法
返回值:jQuery
参数:
callback(Function)要执行的方法
例子:在AJAX请求停止的时候隐藏一条载入信息
$("#loading").ajaxStop(function(){
$(this).hide();
});
ajaxSuccess( callback )
当一个AJAX请求成功结束的时候添加一个被执行的方法。
XMLHttpRequest和它所具有的设置都被作为一个参数传递给了回调函数。
返回值:jQuery
参数:
callback(Function)要执行的方法
例子:在AJAX请求成功结束的时候显示一条信息
$("#msg").ajaxSuccess(function(request, settings){
$(this).append("<li>Successful Request!</li>");
});
load( url, params, callback )
从远程的一个文件中载入HTML并且将它注入到DOM中
提示:应避免使用这个方法载入脚本,使用$.getScript代替它。
返回值:jQuery
参数:
url(String)加载的页面的url
params(Map)(可选)将要传送给服务器的Key/Value对
callback(Function)(可选)当数据加载完后(参数:responseText,status和response本身)被执行的方法。
例子:
$("#feeds").load("feeds.html");
之前:
<div id="feeds"></div>
结果:
<div id="feeds"><b>45</b> feeds found.</div>
例子:同上边的例子一样,但是当数据载入后会带有一个额外的参数和一个被执行的回调
$("#feeds").load("feeds.html",
{limit: 25},
function() { alert("The last 25 entries in the feed have been loaded"); }
);
loadIfModified( url, params, callback )
只有当它被服务器修改的时候,从一个远程文件中加载HTML并且注入到DOM中
返回值:jQuery
参数:
url(String)加载的页面的url
params(Map)(可选)将要传送给服务器的Key/Value对
callback(Function)(可选)当数据加载完后(参数:responseText,status和response本身)被执行的方法。
例子:
$("#feeds").loadIfModified("feeds.html");
之前:
<div id="feeds"></div>
结果:
<div id="feeds"><b>45</b> feeds found.</div>
serialize()
向一个数据字符串中连载一系列的input元素。这将会连载所有的给定元素。
A serialization designed to emulate the actual form submission of a browser is provided by the Form Plugin. The plugin's formSerialize method correctly handles multiple-selects and identically-named checkboxes as arrays, whereas the serialize method recognizes only a single value for these elements.
返回值:String
例子:
Serialize a selection of input elements to a string
$("input[@type=text]").serialize();
之前:
<input type='text' name='name' value='John'/>
<input type='text' name='location' value='Boston'/>
结果:
name=John&location=Boston