核心 AJAX 方法對照
| 方法 | 用途 | 簡述 |
$.ajax() | 最底層、功能最完整 | 所有選項可控,適合複雜場景 |
$.get() | GET 請求 | 簡潔語法,快速查詢 |
$.post() | POST 請求 | 表單提交、資料異動 |
$.getJSON() | GET 並自動解析 JSON | REST API 獲取資料 |
$.getScript() | 載入並執行 JS 檔案 | 動態載入腳本 |
.load() | 載入 HTML 片段插入元素 | 局部頁面更新 |
一、基礎範例:使用者名稱即時檢查
HTML 頁面
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>jQuery AJAX 使用者名稱檢查</title>
<style>
.valid { color: green; }
.invalid { color: red; }
.checking { color: orange; }
#username { padding: 8px; width: 250px; }
#result { margin-top: 10px; min-height: 24px; }
</style>
</head>
<body>
<h3>使用者名稱即時檢查</h3>
<label>使用者名稱: </label>
<input type="text" id="username" placeholder="輸入用戶名" autocomplete="off" />
<div id="result"></div>
<script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>
<script src="verify.js"></script>
</body>
</html>
JavaScript (verify.js)
$(function() {
var $username = $("#username");
var $result = $("#result");
var requestTimer = null;
$username.on("input", function() {
var val = $.trim($(this).val());
// 清除上一次延遲請求
clearTimeout(requestTimer);
if (!val) {
$result.removeClass().text("");
return;
}
// 顯示檢查中狀態
$result.removeClass().addClass("checking").text("檢查中...");
// 防抖:300ms 後發送請求
requestTimer = setTimeout(function() {
checkUsername(val);
}, 300);
});
function checkUsername(username) {
$.ajax({
url: "/api/check-username", // 後端 API
type: "POST",
dataType: "json",
data: { username: username },
success: function(response) {
if (response.available) {
$result.removeClass().addClass("valid").text("✓ 可使用");
} else {
$result.removeClass().addClass("invalid").text("✗ " + (response.message || "已被使用"));
}
},
error: function(xhr, status, error) {
$result.removeClass().addClass("invalid").text("⚠ 檢查失敗:" + error);
}
});
}
});
後端範例 - ASP.NET (WebForms/MVC)
// WebForms Generic Handler (.ashx)
public class CheckUsername : IHttpHandler {
public void ProcessRequest(HttpContext context) {
context.Response.ContentType = "application/json";
var username = context.Request["username"];
bool exists = UserRepository.Exists(username); // 查資料庫
var result = new {
available = !exists,
message = exists ? "該使用者名稱已被註冊" : ""
};
context.Response.Write(Newtonsoft.Json.JsonConvert.SerializeObject(result));
}
public bool IsReusable { get { return false; } }
}
// MVC Controller
[HttpPost]
public JsonResult CheckUsername(string username) {
bool exists = _userService.Exists(username);
return Json(new {
available = !exists,
message = exists ? "該使用者名稱已被註冊" : ""
});
}
二、$.ajax() 完整選項詳解
$.ajax({
// 必要
url: "/api/users", // 請求地址
type: "POST", // HTTP 方法: GET, POST, PUT, DELETE, PATCH
// 資料
data: { id: 1, name: "test" }, // 物件/字串/陣列,GET 會轉 query string
dataType: "json", // 預期回應類型: json, xml, html, text, script, jsonp
contentType: "application/x-www-form-urlencoded; charset=UTF-8", // 發送類型
// 快取控制
cache: false, // GET 時加時間戳防快取
// 非同步 (預設 true,勿改 false)
async: true,
// 超時 (毫秒)
timeout: 30000,
// 標頭
headers: {
"Authorization": "Bearer " + token,
"X-CSRF-Token": csrfToken
},
// 跨域
xhrFields: { withCredentials: true }, // 攜帶 Cookie
crossDomain: true,
// 回呼函式
beforeSend: function(xhr) {
// 請求前:顯示 loading、設定額外 header
showLoading();
},
success: function(data, textStatus, jqXHR) {
// 成功:處理資料
handleData(data);
},
error: function(jqXHR, textStatus, errorThrown) {
// 失敗:網路錯誤、HTTP 錯誤碼、解析失敗
handleError(jqXHR, textStatus, errorThrown);
},
complete: function(jqXHR, textStatus) {
// 完成 (無論成敗):隱藏 loading
hideLoading();
}
});
三、Promise 介面 (jQuery 1.5+)
// 返回 Promise-like 物件 (jqXHR),支援 .done/.fail/.always/.then
var request = $.ajax({ url: "/api/data", dataType: "json" });
request.done(function(data) {
console.log("成功", data);
}).fail(function(jqXHR, status, error) {
console.error("失敗", status, error);
}).always(function() {
console.log("完成 (無論成敗)");
});
// 串聯
$.ajax({ url: "/api/step1" })
.then(function(data1) {
return $.ajax({ url: "/api/step2", data: { id: data1.id } });
})
.then(function(data2) {
return $.ajax({ url: "/api/step3", data: { id: data2.id } });
})
.done(function(finalData) {
console.log("流程完成", finalData);
})
.fail(function(jqXHR, status, error) {
console.error("任一步驟失敗", error);
});
// 並行
$.when(
$.ajax({ url: "/api/users" }),
$.ajax({ url: "/api/roles" }),
$.ajax({ url: "/api/perms" })
).done(function(usersRes, rolesRes, permsRes) {
// 參數為 [data, status, jqXHR]
initPage(usersRes[0], rolesRes[0], permsRes[0]);
});
四、現代化:Fetch API + async/await (推薦新專案)
// 封裝通用 fetch
async function apiRequest(url, options = {}) {
const defaultOptions = {
headers: {
"Content-Type": "application/json",
"X-Requested-With": "XMLHttpRequest"
},
credentials: "same-origin" // 攜帶 Cookie
};
const config = { ...defaultOptions, ...options };
if (config.data && !(config.data instanceof FormData)) {
config.body = JSON.stringify(config.data);
delete config.data;
}
const response = await fetch(url, config);
if (!response.ok) {
const error = new Error(`HTTP ${response.status}`);
error.response = response;
throw error;
}
const contentType = response.headers.get("content-type");
if (contentType && contentType.includes("application/json")) {
return response.json();
}
return response.text();
}
// 使用
async function checkUsername(username) {
try {
const result = await apiRequest("/api/check-username", {
method: "POST",
data: { username }
});
return result.available;
} catch (error) {
console.error("檢查失敗", error);
throw error;
}
}
五、常見問題與解決
| 問題 | 原因 | 解決方案 |
| 跨域 (CORS) 錯誤 | 瀏覽器同源策略 | 後端設定 Access-Control-Allow-Origin、Credentials、Headers |
| CSRF 攻擊 | 偽造跨站請求 | 雙重 Cookie 驗證、CSRF Token、SameSite Cookie |
| 重複提交 | 使用者連點按鈕 | 按鈕 loading 狀態禁用、Token 一致性、冪等性設計 |
| 中文亂碼 | 編碼不一致 | 統一 UTF-8,Content-Type 指定 charset,URL 參數 encodeURIComponent |
| 大檔案上傳 | 預設限制、超時 | FormData + 分片上傳、WebUploader、調整伺服器限制 |
| 快取問題 | GET 請求被快取 | cache: false、URL 加時間戳、後端 Cache-Control: no-cache |
六、檔案上傳 (FormData + AJAX)
$("#uploadForm").on("submit", function(e) {
e.preventDefault();
var formData = new FormData(this); // 自動收集 form 所有欄位含檔案
// 或手動構建
// var formData = new FormData();
// formData.append("file", $("#fileInput")[0].files[0]);
// formData.append("folder", "images");
$.ajax({
url: "/api/upload",
type: "POST",
data: formData,
processData: false, // 關鍵:不要處理資料
contentType: false, // 關鍵:不要設 Content-Type (瀏覽器自動設 multipart/form-data)
xhr: function() {
var xhr = $.ajaxSettings.xhr();
// 上傳進度
xhr.upload.addEventListener("progress", function(e) {
if (e.lengthComputable) {
var percent = Math.round((e.loaded / e.total) * 100);
$("#progressBar").css("width", percent + "%").text(percent + "%");
}
}, false);
return xhr;
},
success: function(res) {
if (res.success) LG.showSuccess("上傳成功");
else LG.showError(res.message);
}
});
});
七、總結
jQuery AJAX 提供簡潔 API 處理非同步請求。基礎專案用 $.get/post,複雜場景用 $.ajax 完整控制。現代專案建議遷移至 **Fetch API + async/await**,獲得原生 Promise 支援、更好的錯誤堆疊、Request/Response 物件操作、Service Worker 相容性。核心概念不變:非同步請求、回呼/處理、錯誤處理、載入狀態管理、安全防護 (CORS/CSRF)。