Ajax 請求 · Zepto.js API 中文文檔 1.1.6

# Ajax 請求 ## $.ajax ``` $.ajax(options) => XMLHttpRequest ``` 執行Ajax請求。它可以是本地資源，或者通過支持[HTTP access control](https://developer.mozilla.org/en/http_access_control)的瀏覽器或者通過 [JSONP](http://json-p.org)來實現跨域。選項: * `type`(默認： “GET”)：請求方法 (“GET”, “POST”, or other) * `url` (默認：當前地址)：發送請求的地址 * `data` (默認：none)：發送到服務器的數據；如果是GET請求，它會自動被作為參數拼接到url上。非String對象將通過 [$.param](#$.param) 得到序列化字符串。 * `processData` (默認： true)：對于非Get請求。是否自動將 `data` 轉換為字符串。 * `contentType` (默認： “application/x-www-form-urlencoded”)：發送信息至服務器時內容編碼類型。 (這也可以通過設置 `headers`)。通過設置 `false` 跳過設置默認值。 * `mimeType` (默認： none): 覆蓋響應的MIME類型。 v1.1+ * `dataType` (默認： none)：預期服務器返回的數據類型(“json”, “jsonp”, “xml”, “html”, or “text”) * `jsonp` (默認：“callback”): JSONP回調查詢參數的名稱 * `jsonpCallback` (默認： “jsonp{N}”): 全局JSONP回調函數的字符串（或返回的一個函數）名。設置該項能啟用瀏覽器的緩存。 v1.1+ * `timeout` (默認： `0`): 以毫秒為單位的請求超時時間, `0` 表示不超時。 * `headers`: Ajax請求中額外的HTTP信息頭對象 * `async` (默認：true): 默認設置下，所有請求均為異步。如果需發送同步請求，請將此設置為 `false`。 * `global` (默認：true): 請求將觸發全局Ajax事件處理程序，設置為 false 將不會觸發全局 Ajax 事件。 * `context` (默認：window): 這個對象用于設置Ajax相關回調函數的上下文(this指向)。 * `traditional` (默認： false): 激活傳統的方式通過[$.param](#$.param)來得到序列化的 `data`。 * `cache` (默認： true): 瀏覽器是否應該被允許緩存GET響應。從v1.1.4開始，當dataType選項為 `"script"` 或 `jsonp`時，默認為`false`。 * `xhrFields` (默認： none): 一個對象包含的屬性被逐字復制到XMLHttpRequest的實例。 v1.1+ * `username` & `password` (默認： none): HTTP基本身份驗證憑據。 v1.1+ 如果URL中含有 `=?`或者`dataType`是“jsonp”，這講求將會通過注入一個 `<script>`標簽來代替使用 XMLHttpRequest (查看 [JSONP](http://json-p.org))。此時 `contentType`, `dataType`, `headers`有限制，`async` 不被支持。 ### Ajax 回調函數你可以指定以下的回調函數，他們將按給定的順序執行： 1. `beforeSend(xhr, settings)`：請求發出前調用，它接收xhr對象和settings作為參數對象。如果它返回 `false` ，請求將被取消。 2. `success(data, status, xhr)`：請求成功之后調用。傳入返回后的數據，以及包含成功代碼的字符串。 3. `error(xhr, errorType, error)`：請求出錯時調用。 (超時，解析錯誤，或者狀態碼不在HTTP 2xx)。 4. `complete(xhr, status)`：請求完成時調用，無論請求失敗或成功。 ### Promise 回調接口 v1.1+ 如果可選的“callbacks” 和 “deferred” 模塊被加載，從`$.ajax()`返回的XHR對象實現了promise接口鏈式的回調： ``` xhr.done(function(data, status, xhr){ ... }) xhr.fail(function(xhr, errorType, error){ ... }) xhr.always(function(){ ... }) xhr.then(function(){ ... }) ``` 這些方法取代了 `success`, `error`, 和 `complete` 回調選項. ### Ajax 事件當`global: true`時。在Ajax請求生命周期內，以下這些事件將被觸發。 1. `ajaxStart` _(global)_：如果沒有其他Ajax請求當前活躍將會被觸發。 2. `ajaxBeforeSend` (data: xhr, options)：再發送請求前，可以被取消。 3. `ajaxSend` (data: xhr, options)：像 `ajaxBeforeSend`，但不能取消。 4. `ajaxSuccess` (data: xhr, options, data)：當返回成功時。 5. `ajaxError` (data: xhr, options, error)：當有錯誤時。 6. `ajaxComplete` (data: xhr, options)：請求已經完成后，無論請求是成功或者失敗。 7. `ajaxStop` _(global)_：如果這是最后一個活躍著的Ajax請求，將會被觸發。默認情況下，Ajax事件在document對象上觸發。然而，如果請求的 `context` 是一個DOM節點，該事件會在此節點上觸發然后再DOM中冒泡。唯一的例外是 `ajaxStart` & `ajaxStop`這兩個全局事件。 ``` $(document).on('ajaxBeforeSend', function(e, xhr, options){ // This gets fired for every Ajax request performed on the page. // The xhr object and $.ajax() options are available for editing. // Return false to cancel this request. }) $.ajax({ type: 'GET', url: '/projects', // data to be added to query string: data: { name: 'Zepto.js' }, // type of data we are expecting in return: dataType: 'json', timeout: 300, context: $('body'), success: function(data){ // Supposing this JSON payload was received: // {"project": {"id": 42, "html": "<div>..." }} // append the HTML to context object. this.append(data.project.html) }, error: function(xhr, type){ alert('Ajax error!') } }) // post a JSON payload: $.ajax({ type: 'POST', url: '/projects', // post payload: data: JSON.stringify({ name: 'Zepto.js' }), contentType: 'application/json' }) ``` ## $.ajaxJSONP 不推薦, 使用 [$.ajax](#$.ajax) 代替。 ``` $.ajaxJSONP(options) => mock XMLHttpRequest ``` 執行JSONP跨域獲取數據。此方法相對 [$.ajax](#$.ajax) 沒有優勢，建議不要使用。 ## $.ajaxSettings 一個包含Ajax請求的默認設置的對象。大部分的設置在 [$.ajax](#$.ajax)中已經描述。以下設置為全局非常有用： * `timeout` (默認： `0`)：對Ajax請求設置一個非零的值指定一個默認的超時時間，以毫秒為單位。 * `global` (默認： true)：設置為false。以防止觸發Ajax事件。 * `xhr` (默認：XMLHttpRequest factory)：設置為一個函數，它返回XMLHttpRequest實例(或一個兼容的對象) * `accepts`: 從服務器請求的MIME類型，指定`dataType`值： * script: “text/javascript, application/javascript” * json: “application/json” * xml: “application/xml, text/xml” * html: “text/html” * text: “text/plain” ## $.get ``` $.get(url, function(data, status, xhr){ ... }) => XMLHttpRequest $.get(url, [data], [function(data, status, xhr){ ... }], [dataType]) => XMLHttpRequest v1.0+ ``` 執行一個Ajax GET請求。這是一個 [$.ajax](#$.ajax)的簡寫方式。 ``` $.get('/whatevs.html', function(response){ $(document.body).append(response) }) ``` ## $.getJSON ``` $.getJSON(url, function(data, status, xhr){ ... }) => XMLHttpRequest $.getJSON(url, [data], function(data, status, xhr){ ... }) => XMLHttpRequest v1.0+ ``` 通過 Ajax GET請求獲取JSON數據。這是一個 [$.ajax](#$.ajax) 的簡寫方式。 ``` $.getJSON('/awesome.json', function(data){ console.log(data) }) // fetch data from another domain with JSONP $.getJSON('//example.com/awesome.json?callback=?', function(remoteData){ console.log(remoteData) }) ``` ## $.param ``` $.param(object, [shallow]) => string $.param(array) => string ``` 序列化一個對象，在Ajax請求中提交的數據使用URL編碼的查詢字符串表示形式。如果shallow設置為true。嵌套對象不會被序列化，嵌套數組的值不會使用放括號在他們的key上。如果任何對象的某個屬性值是一個函數，而不是一個字符串，該函數將被調用并且返回值后才會被序列化。此外，還接受 [serializeArray](#serializeArray)格式的數組，其中每個項都有 “name” 和 “value”屬性。 ``` $.param({ foo: { one: 1, two: 2 }}) //=> "foo[one]=1&foo[two]=2)" $.param({ ids: [1,2,3] }) //=> "ids[]=1&ids[]=2&ids[]=3" $.param({ ids: [1,2,3] }, true) //=> "ids=1&ids=2&ids=3" $.param({ foo: 'bar', nested: { will: 'not be ignored' }}) //=> "foo=bar&nested[will]=not+be+ignored" $.param({ foo: 'bar', nested: { will: 'be ignored' }}, true) //=> "foo=bar&nested=[object+Object]" $.param({ id: function(){ return 1 + 2 } }) //=> "id=3" ``` ## $.post ``` $.post(url, [data], function(data, status, xhr){ ... }, [dataType]) => XMLHttpRequest ``` 執行Ajax POST請求。這是一個 [$.ajax](#$.ajax) 的簡寫方式。 ``` $.post('/create', { sample: 'payload' }, function(response){ // process response }) ``` `data` 參數可以是一個字符串： ``` $.post('/create', $('#some_form').serialize(), function(response){ // ... }) ``` ## load ``` load(url, function(data, status, xhr){ ... }) => self ``` 通過GET Ajax載入遠程 HTML 內容代碼并插入至當前的集合中。另外，一個css選擇器可以在url中指定，像這樣，可以使用匹配selector選擇器的HTML內容來更新集合。 ``` $('#some_element').load('/foo.html #bar') ``` 如果沒有給定CSS選擇器，將使用完整的返回文本。請注意，在沒有選擇器的情況下，任何javascript塊都會執行。如果帶上選擇器，匹配選擇器內的script將會被刪除。