您现在的位置：程式碼之家 >> 編程語言 > >> Java 程式設計 >> Java 相關知識

jQuery AJAX 方法參數詳解與最佳實踐指南

編輯：Java 相關知識

jQuery $.ajax() 是前端異步請求的核心 API，參數豐富且靈活。本文系統整理所有配置選項、簡寫方法、常見陷阱與現代替代方案，作為開發查閱手冊。

一、`$.ajax(options)` 完整參數表

參數	類型	默認值	說明
url	String	當前頁面	請求地址
type / method	String	"GET"	HTTP 方法：GET、POST、PUT、DELETE 等
async	Boolean	true	true=異步，false=同步（阻塞瀏覽器，慎用）
timeout	Number	0(無限制)	請求超時毫秒數，覆蓋全局設置
data	Object/String	無	發送數據。Object 會用 $.param() 編碼為 key=val&...；String 直接發送
processData	Boolean	true	false 時不將 data 編碼，適合發送 DOM、File、ArrayBuffer 等
contentType	String	"application/x-www-form-urlencoded; charset=UTF-8"	請求體編碼類型。發送 JSON 時需設為 "application/json"
dataType	String	智能判斷	預期響應類型：xml、html、script、json、jsonp、text。決定回調參數類型
headers	Object	{}	額外請求頭，如 {"X-CSRF-Token": "xxx"}
beforeSend	Function(xhr)	無	發送前修改 XHR，返回 false 可取消請求
success	Function(data, textStatus, jqXHR)	無	請求成功回調
error	Function(jqXHR, textStatus, errorThrown)	無	請求失敗回調
complete	Function(jqXHR, textStatus)	無	完成回調（成功/失敗均觸發）
cache	Boolean	true(GET 為 false)	false 時在 URL 追加 "_={timestamp}" 防緩存
ifModified	Boolean	false	僅響應 Last-Modified/ETag 變化時獲取
global	Boolean	true	false 禁用全局 Ajax 事件（ajaxStart/Stop 等）
xhrFields	Object	{}	設置 XHR 屬性，如 withCredentials: true 攜帶跨域 Cookie
crossDomain	Boolean	自動檢測	強制標記為跨域請求
username/password	String	無	HTTP 基本認證憑據

二、常用簡寫方法

// GET 請求
$.get(url, data?, success?, dataType?)

// POST 請求
$.post(url, data?, success?, dataType?)

// 載入腳本
$.getScript(url, success?)

// JSONP 跨域
$.getJSON(url, data?, success?)

三、關鍵場景最佳實踐

1. 發送 JSON 數據

$.ajax({
    url: '/api/user',
    type: 'POST',
    contentType: 'application/json',
    data: JSON.stringify({name: 'Tom', age: 20}),
    dataType: 'json',
    success: function(res) { console.log(res); }
});

2. 文件上傳

var formData = new FormData();
formData.append('file', $('#fileInput')[0].files[0]);
formData.append('token', 'xxx');

$.ajax({
    url: '/upload',
    type: 'POST',
    data: formData,
    processData: false,  // 必須 false
    contentType: false,  // 必須 false，瀏覽器自動設置 boundary
    success: function(res) { ... }
});

3. 全局 Loading 提示

$(document).ajaxStart(function() { $('#loading').show(); });
$(document).ajaxStop(function() { $('#loading').hide(); });

4. 統一錯誤處理

$.ajaxSetup({
    error: function(jqXHR, status, err) {
        if (jqXHR.status === 401) location.href = '/login';
        else console.error(status, err);
    }
});

四、常見陷阱避坑指南

dataType: 'json' 但響應非合法 JSON → 進入 error 回調，jqXHR.responseText 可見原始文本
跨域請求缺少 CORS 頭 → 瀏覽器攔截，控制台報 CORS 錯誤，需後端配置 Access-Control-Allow-Origin
同步請求 (async: false) 導致頁面卡死 → 極少數場景使用，現代瀏覽器主線程已棄用
傳統表單序列化：$('#form').serialize() → "a=1&b=2" 字符串，適配 application/x-www-form-urlencoded
data 為 Object 但 contentType 為 json → 必須手動 JSON.stringify()，否則發送 "[object Object]"

五、現代替代方案

Fetch API：原生 Promise 風格，fetch(url, {method, headers, body}).then(r => r.json())
Axios：自動 JSON 轉換、攔截器、取消令牌、XSRF 保護，axios.post(url, data)
jQuery 3.5+：$.ajax 返回 Promise，可 await $.ajax(...)

掌握 $.ajax 全參數細節，能快速定位網絡請求疑難雜症；新項目建議遷移至 Fetch 或 Axios，獲得更優雅的異步體驗。