jQuery.ajax()

jQuery.ajax()方法用於通過後臺HTTP請求載入遠端資料。

此方法是jQuery封裝的AJAX技術實現，通過該函式，無需重新整理當前頁面即可獲取遠端伺服器上的資料。它是jQuery的底層AJAX實現。jQuery.get()、 jQuery.post()、 load()、 jQuery.getJSON()、 jQuery.getScript()等函式都是該函式的簡化形式(都呼叫該函式，只是引數設定有所不同或有所省略)。

返回當前該請求的jqXHR物件(jQuery1.4及以前版本返回原生XMLHttpRequest物件)。

語法結構一:

[JavaScript] 純文字檢視 複製程式碼
jQuery.ajax( url [, settings ] )

引數解析:

（1）.url:一個用來包含傳送請求的URL字串。

（2）.settings：可選，一個以"{鍵:值}"組成的AJAX 請求設定。所有選項都是可選的。

jQuery1.5版本新增。

語法結構二:

[JavaScript] 純文字檢視 複製程式碼
jQuery.ajax([settings ])

引數解析:

settings：可選，一個以"{鍵:值}"組成的AJAX 請求設定。所有選項都是可選的。

語法結構一是一個變體，只是將引數物件settings中的可選屬性url單獨提取出來作為一個獨立的引數。

jQuery1.0版本新增。

settings配置物件屬性:

（1）.acceptsObject:

object物件。

傳送的內容型別請求頭，用於告訴伺服器，瀏覽器可以接收伺服器返回何種型別的響應。

預設值：取決於dataType屬性。

（2）.async：

布林型別。

指示是否是非同步請求。同步請求將鎖定瀏覽器，直到獲取到遠端資料後才能執行其他操作。

預設值:true。

（3）.beforeSend:

指定在請求傳送前需要執行的回撥函式。該函式還有兩個引數：第一個是jqXHR物件，第二個是當前settings物件。這是一個Ajax事件，如果該函式返回false，將取消本次ajax請求。

（4）.cache:

布林型別。

指示是否快取URL請求。如果設為false將強制瀏覽器不快取當前URL請求。該引數只對HEAD、GET請求有效(POST請求本身就不會快取)。

預設值：true(dataType為'script'或'jsonp'時，則預設為false)。

（5）.complete:

函式或者陣列型別。

指定請求完成(無論成功或失敗)後需要執行的回撥函式。該函式還有兩個引數：一個是jqXHR物件，一個是表示請求狀態的字串('success'、 'notmodified'、 'error'、 'timeout'、 'abort'或'parsererror')。這是一個Ajax事件。

從jQuery 1.5開始，該屬性值可以是陣列形式的多個函式，每個函式都將被回撥執行。

（6）.contents:

object型別。

一個以"{字串:正規表示式}"配對的物件，用來確定jQuery將如何解析響應，給定其內容型別。

（7）.contentType:

字串型別。

使用指定的內容編碼型別將資料傳送給伺服器。W3C的XMLHttpRequest規範規定charset始終是UTF-8，你如果將其改為其他字符集，也無法強制瀏覽器更改字元編碼。

預設值：'application/x-www-form-urlencoded; charset=UTF-8'。

（8）.context：

object型別。

用於設定Ajax相關回撥函式的上下文物件(也就是函式內的this指標)。

（9）.converters:

object型別。

一個資料型別轉換器。每個轉換器的值都是一個函式，用於返回響應轉化後的值。

預設值：{'* text': window.String, 'text html': true, 'text json': jQuery.parseJSON, 'text xml': jQuery.parseXML}。

（10）.crossDomain:

布林型別。

指示是否是跨域請求。如果你想在同一域中強制跨域請求(如JSONP形式)，請設定為true。例如，這允許伺服器端重定向到另一個域。

預設值：同域請求為false，跨域請求為true。

（11）.data:

任意型別；傳送到伺服器的資料，它將被自動轉為字串型別。如果是GET請求，它將被附加到URL後面。

（12）.dataFilter:

Function型別；指定處理響應的原始資料的回撥函式。該函式還有兩個引數：其一表示響應的原始資料的字串，其二是dataType屬性字串。

（13）.dataType:

字串型別。

指定返回的資料型別。

預設值：jQuery智慧猜測，猜測範圍(xml、 json、 script或html)

該屬性值可以為：

<1>.'xml' :返回XML文件，可使用jQuery進行處理。

<2>.'html': 返回HTML字串。

<3>.'script': 返回JavaScript程式碼。不會自動快取結果。除非設定了cache引數。注意：在遠端請求時(不在同一個域下)，所有POST請求都將轉為GET請求。(因為將使用DOM的script標籤來載入)。

<4>.'json': 返回JSON資料。JSON資料將使用嚴格的語法進行解析(屬性名必須加雙引號，所有字串也必須用雙引號)，如果解析失敗將丟擲一個錯誤。從jQuery 1.9開始，空內容的響應將返回null或{}。

<5>.'jsonp': JSONP格式。使用JSONP形式呼叫函式時，如"url?callback=?"，jQuery將自動替換第二個?為正確的函式名，以執行回撥函式。

<6>.'text': 返回純文字字串。

（14）.error:

Function或者Array型別。

指定請求失敗時執行的回撥函式。該函式有3個引數：jqXHR物件、 請求狀態字串(null、 'timeout'、 'error'、 'abort'和'parsererror')、 錯誤資訊字串(響應狀態的文字描述部分，例如'Not Found'或'Internal Server Error')。這是一個Ajax事件。跨域指令碼和跨域JSONP請求不會呼叫該函式。

從jQuery 1.5開始，該屬性值可以是陣列形式的多個函式，每個函式都將被回撥執行。

（15）.global:

布林型別。

指示是否觸發全域性Ajax事件。將該值設為false將阻止全域性事件處理函式被觸發，例如ajaxStart()和ajaxStop()。它可以用來控制各種Ajax事件。

預設值：true。

（16）.headers:

object型別。

以物件形式指定附加的請求頭資訊。請求頭X-Requested-With: XMLHttpRequest將始終被新增，當然你也可以在此處修改預設的XMLHttpRequest值。headers中的值可以覆蓋beforeSend回撥函式中設定的請求頭(意即beforeSend先被呼叫)。

[JavaScript] 純文字檢視 複製程式碼
$.ajax({
    url: "my.php" ,
    headers: {
        "Referer": "http://www.softwhy.com" // 有些瀏覽器不允許修改該請求頭
        ,"User-Agent": "newLine" // 有些瀏覽器不允許修改該請求頭
        ,"X-Power": "newLine"
        ,"Accept-Language": "en-US"
    }
});

預設值：{}。

（17）.ifModified:

布林型別。

允許當前請求僅在伺服器資料改變時獲取新資料(如未更改，瀏覽器從快取中獲取資料)。它使用HTTP頭資訊Last-Modified來判斷。從jQuery 1.4開始，他也會檢查伺服器指定的'etag'來確定資料是否已被修改。

預設值：false。

（18）.isLocal:

布林型別。

允許將當前環境視作"本地"，(例如檔案系統)，即使預設情況下jQuery不會如此識別它。目前，以下協議將被視作本地：file、*-extension和widget。

預設值：取決於當前的位置協議。

（19）.jsonp:

字串型別。

重寫JSONP請求的回撥函式名稱。該值用於替代"url?callback=?"中的"callback"部分。

（20）.jsonpCallback:

String/Function型別。

為JSONP請求指定一個回撥函式名。這個值將用來取代jQuery自動生成的隨機函式名。

從jQuery 1.5開始，你也可以指定一個函式來返回所需的函式名稱。

（21）.mimeType:

字串型別。

一個mime型別用來覆蓋XHR的mime型別。

（22）.password:

字串型別。

用於響應HTTP訪問認證請求的密碼。

（23）.processData:

布林型別。

預設情況下，通過data屬性傳遞進來的資料，如果是一個物件(技術上講，只要不是字串)，都會處理轉化成一個查詢字串，以配合預設內容型別 "application/x-www-form-urlencoded"。如果要傳送 DOM樹資訊或其它不希望轉換的資訊，請設定為false。

預設值：true。

（24）.scriptCharset:

字串型別。

設定該請求載入的指令碼檔案的字符集。只有當請求時dataType為"jsonp"或"script"，並且type是"GET"才會用於強制修改charset。這相當於設定<script>標籤的charset屬性。通常只在當前頁面和遠端資料的內容編碼不同時使用。

（25）.statusCode:

object型別。

一組數值的HTTP程式碼和函式構成的物件，當響應時呼叫了相應的程式碼。例如：

[JavaScript] 純文字檢視 複製程式碼
$.ajax({
    url: a_not_found_url ,
    // 當響應對應的狀態碼時，執行對應的回撥函式
    statusCode: {
        404: function() {
            alert( "找不到頁面" );
        },
        200: function(){
            alert("請求成功");
        }
    }
});

預設值: {}。

（26）.success:

Function/Array型別。

指定請求成功後執行的回撥函式。該函式有3個引數：請求返回的資料、響應狀態字串、jqXHR物件。

從jQuery 1.5開始，該屬性值可以是陣列形式的多個函式，每個函式都將被回撥執行。

（27）.timeout:

Number型別。

設定請求超時的毫秒值。

（28）.traditional:

布林型別。

如果你希望使用傳統方式來序列化引數，將該屬性設為true。

（29）.type:

字串型別。

請求型別，可以為'POST'或'GET'。注意：你也可以在此處使用諸如'PUT'、'DELETE'等其他請求型別，但它們不被所有瀏覽器支援。

預設值："GET"。

（30）.url:

字串型別。

請求的目標URL。

預設值：當前頁面URL。

（31）.username:

字串型別。

用於響應HTTP訪問認證請求的使用者名稱。

（32）.xhr:

Function型別。

用於建立並返回XMLHttpRequest物件的回撥函式。可以重寫該屬性以提供自己的XHR實現，或增強其功能。

預設值：在IE下是ActiveXObject(如果可用)，在其他瀏覽器中是XMLHttpRequest。

（33）.xhrFields:

Object型別。

一個具有多個"欄位名稱-欄位值"對的物件，用於對本地XHR物件進行設定。一對「檔名-檔案值」在本機設定XHR物件。例如，如果需要，你可以用它來為跨域請求設定XHR物件的withCredentials屬性為true。

[JavaScript] 純文字檢視 複製程式碼
$.ajax({
   url: a_cross_domain_url,
   // 將XHR物件的withCredentials設為true
   xhrFields: {
      withCredentials: true
   }
});

特別說明:如果沒有給jQuery.ajax()指定任何引數，則預設請求當前頁面，並且不對返回資料進行處理。

程式碼例項:

程式碼例項一:

[JavaScript] 純文字檢視 複製程式碼
$.ajax({
     url: "jquery_ajax.php"
    , type: "POST"
    , data: "name=codeplayer&age=18"
    , success: function( data, textStatus, jqXHR ){
        // data 是返回的資料
        // textStatus 可能為"success"、"notmodified"等
        // jqXHR 是經過jQuery封裝的XMLHttpRequest物件
        alert("返回的資料" + data);
    }
});

程式碼例項二:

[JavaScript] 純文字檢視 複製程式碼
$.ajax({
     url: "jquery_ajax.php?page=1&id=3"
    , type: "POST"
    // jQuery會自動將物件資料轉換為 "name=codeplayer&age=18&uid=1&uid=2&uid=3"
    , data: { name:"codeplayer", age:18, uid: [1, 2, 3] }
    // 請求成功時執行
    , success: function( data, textStatus, jqXHR ){
        alert("返回的資料" + data);
    }
    // 請求失敗時執行
    , error: function(jqXHR, textStatus, errorMsg){
        // jqXHR 是經過jQuery封裝的XMLHttpRequest物件
        // textStatus 可能為： null、"timeout"、"error"、"abort"或"parsererror"
        // errorMsg 可能為： "Not Found"、"Internal Server Error"等
        alert("請求失敗：" + errorMsg);
    }
});

程式碼例項三:

[JavaScript] 純文字檢視 複製程式碼
// 將url單獨提取出來作為第一個引數(jQuery 1.5+才支援)
$.ajax("jquery_ajax.php?action=type&id=3", {
     dataType: "json" // 返回JSON格式的資料
    , success: function( data, textStatus, jqXHR ){
        // 假設返回的字串資料為{ "name": "CodePlayer", age: 20 }
        // jQuery已幫我們將該JSON字串轉換為對應的JS物件，可以直接使用
        alert( data.name ); // CodePlayer
    }   
});

程式碼例項四:

[JavaScript] 純文字檢視 複製程式碼
$.ajax( {
    // 注意這裡有個引數callback=?
     url: "http://cross-domain/jquery_ajax.php?name=Jim&callback=?&age=21"
    , async: false // 同步請求，傳送請求後瀏覽器被鎖定，只有該請求完成後，使用者才能操作，程式碼才會繼續執行
    , dataType: "jsonp" // 返回JSON格式的資料
    , success: function( data, textStatus, jqXHR ){
        // 假設返回的字串資料為{ "site_name": "螞蟻部落", "site_desc": "前端教程 }
        // jQuery已幫我們將該JSON字串轉換為對應的JS物件，可以直接使用
        alert( data.site_desc ); // 專注於程式設計開發技術分享
    }   
});