$.ajax() 是 jQuery 底層 Ajax 封裝,所有高層方法(.get()、.post()、.load())最終都調用它。本文系統梳理核心參數、現代寫法、錯誤處理、攔截器模式與 TypeScript 類型定義。
| 參數 | 類型 | 默認值 | 說明 |
|---|---|---|---|
| url | String | 當前頁 | 請求地址 |
| type / method | String | 'GET' | HTTP 方法:GET/POST/PUT/DELETE/PATCH |
| data | Object/String/Array | null | 發送數據,對象自動序列化為查詢字符串 |
| dataType | String | 智能猜測 | 預期返回類型:json/xml/html/script/text/jsonp |
| contentType | String/Boolean | 'application/x-www-form-urlencoded; charset=UTF-8' | 發送內容類型,false 時不設置(用於 FormData) |
| processData | Boolean | true | true 時將 data 轉為查詢字符串,File/FormData 必須 false |
| async | Boolean | true | 異步請求,**強烈建議保持 true**,同步會阻塞主線程 |
| cache | Boolean | true (GET 為 false) | GET 請求自動加 _ 參數防緩存 |
| timeout | Number | 0 (無超時) | 毫秒數,超時觸發 error(jqXHR, 'timeout') |
| headers | Object | {} | 額外請求頭,如 {'X-CSRF-Token': 'xxx'} |
| xhrFields | Object | {} | 設置底層 XHR 對象屬性,如 withCredentials: true 跨域攜帶 Cookie |
| beforeSend | Function(jqXHR, settings) | 無 | 發送前修改 jqXHR,返回 false 可取消請求 |
| success | Function(data, status, jqXHR) | 無 | 成功回調 |
| error | Function(jqXHR, status, error) | 無 | 失敗回調,status: timeout/error/abort/parsererror |
| complete | Function(jqXHR, status) | 無 | 無論成敗均執行 |
| statusCode | Object | {} | HTTP 狀態碼映射處理函數,如 {404: fn, 500: fn} |
// 封裝為 Promise
function ajax(options) {
return new Promise((resolve, reject) => {
$.ajax({
...options,
success: (data, status, xhr) => resolve({data, status, xhr}),
error: (xhr, status, err) => reject({xhr, status, err})
});
});
}
// 使用
async function fetchUser(id) {
try {
const {data} = await ajax({
url: `/api/users/${id}`,
method: 'GET',
dataType: 'json',
headers: {'Authorization': `Bearer ${getToken()}`}
});
return data;
} catch ({xhr, status, err}) {
if (status === 'timeout') return showToast('請求超時');
if (xhr.status === 401) return redirectLogin();
throw new Error(`請求失敗: ${xhr.status} ${err}`);
}
}
// 1. 統一添加 CSRF Token
$.ajaxPrefilter((options, original, jqXHR) => {
if (!options.crossDomain) {
jqXHR.setRequestHeader('X-CSRF-Token', $('meta[name=csrf-token]').attr('content'));
}
});
// 2. 統一錯誤處理
$(document).ajaxError((e, jqXHR, settings, thrownError) => {
if (jqXHR.status === 401) {
// 避免重複彈窗
if (!window._loginRedirectShown) {
window._loginRedirectShown = true;
alert('登錄已過期,請重新登錄');
location.href = '/login?redirect=' + encodeURIComponent(location.pathname);
}
}
});
// 3. 統一 Loading 狀態
$(document).ajaxStart(() => Loading.show());
$(document).ajaxStop(() => Loading.hide());
contentType = 請求頭 Content-Type(發送格式);dataType = 預期響應解析格式。發送 JSON 時:contentType: 'application/json', data: JSON.stringify(obj), dataType: 'json'。const formData = new FormData();
formData.append('file', fileInput.files[0]);
$.ajax({url: '/upload', method: 'POST', data: formData, processData: false, contentType: false});<script src="url?callback=jQuery12345">,要求後端返回 jQuery12345({...})。**僅支持 GET**,且有 XSS 風險,現代項目改用 CORS。$.param({arr: [1,2]}) 默認生成 arr[]=1&arr[]=2(PHP 風格)。若後端為 Java/Spring 需 arr=1&arr=2,設置 $.ajaxSettings.traditional = true 或單次 traditional: true。// types/jquery.ajax.d.ts
interface JQueryAjaxSettings {
/** 自定義業務碼處理 */
businessCodeHandler?: (code: number, msg: string, data: any) => boolean;
}
declare interface JQueryStatic {
ajax(settings: JQueryAjaxSettings): JQuery.jqXHR & PromiseLike<{data: T, status: string, xhr: JQuery.jqXHR}>;
}
$.ajax() 全參數,能應對 99% 複雜網絡場景。async/await 寫出同步風格異步代碼。ajaxPrefilter 實現橫切關注點(Token、簽名、Loading、錯誤統一處理)。