jQuery 的 ajaxPrefilter 與 ajaxTransport 提供了兩個擴充點,讓你能在標準 AJAX 流程中插入自訂的請求型別。本文以「用 Image 物件模擬一個 image 型別的請求」為例,說明這兩個掛勾怎麼用。
//////////////////////////////////////////////////////////////////
// options 請求的選項
// originalOptions 傳給 Ajax 方法、未經修改的原始選項,
// 因此不含 ajaxSettings 中的預設值
// jqXHR 請求的 jqXHR 物件
//////////////////////////////////////////////////////////////////
$.ajaxPrefilter("image", function(options, originalOptions, jqXHR) {
// 透過預處理器轉換型別
if (options.test) {
options.type = 'GET';
}
// 加上網域前綴
options.url = "https://img.mukewang.com/" + options.url;
});
///////////////////////
// 請求分發器 transports
///////////////////////
$.ajaxTransport("image", function(s) {
if (s.type === "GET" && s.async) {
var image;
return {
send: function(_, callback) {
image = new Image();
function done(status) {
if (image) {
var statusText = (status == 200) ? "success" : "error",
tmp = image;
image = image.onreadystatechange = image.onerror = image.onload = null;
callback(status, statusText, { image: tmp });
}
}
image.onreadystatechange = image.onload = function() { done(200); };
image.onerror = function() { done(404); };
image.src = s.url;
},
abort: function() {
if (image) {
image = image.onreadystatechange = image.onerror = image.onload = null;
}
}
};
}
});
這裡的關鍵是 send 回傳的物件必須提供 send 與 abort 兩個方法。完成或失敗時呼叫 callback(狀態碼, 狀態文字, 回應物件),jQuery 就會把它當成一般的 XHR 回應往下處理。另外注意完成後把 onload/onerror 等處理器設為 null,避免圖片物件與回呼之間形成無法釋放的引用。
$("#test").click(function(){
var ajax = $.ajax({
test : true, // 自訂的旗標,供 prefilter 判斷
url : '547d5a45000156f406000338-590-330.jpg',
dataType : 'image',
type : 'POST',
data: { foo: ["bar1", "bar2"] },
context: document.body, // 回呼中的 this
beforeSend: function(xhr) {
xhr.overrideMimeType("text/plain; charset=x-user-defined");
show('局部事件 beforeSend');
},
complete: function() { show('局部事件 complete'); },
error: function() { show('局部事件 error,請求失敗時呼叫'); },
success: function() { show('局部事件 success'); }
});
ajax.done(function() { show('done'); })
.fail(function() { show('fail'); })
.always(function() { show('always'); });
});
prefilter 適合用來做「請求前的統一加工」:加上共同的網域前綴、補上全域的權杖、依條件改寫 method,這些原本要在每個 $.ajax() 呼叫處重複書寫的邏輯,都能收攏到一處。
transport 則更底層,適合用來「換掉整個傳輸實作」:除了本例的圖片載入,常見用途還包括以 fetch 或 WebSocket 取代 XHR、實作離線佇列、或加入自訂的重試與簽章邏輯。
兩個掛勾搭配起來,就能在幾乎不改動呼叫端程式碼的前提下,替整個應用換上一套自訂的請求行為——這是 jQuery 內部架構設計得相當漂亮的一處。要注意的是 transport 的契約(回傳物件需有 send/abort)屬於內部介面,不同 jQuery 版本間可能有差異,升級時值得回頭驗證。