$.ajax()
是 jQuery 中最核心的 AJAX 方法,它提供了丰富的 回调钩子(Callback Options),让你可以在请求的不同阶段插入自定义逻辑。
下面是对 beforeSend
、success
等常用参数的全面、详细、带示例的介绍。
✅ $.ajax()
常用回调参数详解
参数名 | 触发时机 | 是否异步 | 典型用途 |
---|---|---|---|
beforeSend |
请求发送前 | 同步 | 设置请求头、取消请求 |
success |
请求成功(HTTP 2xx) | 异步 | 处理返回数据、更新页面 |
error |
请求失败(网络错误、4xx/5xx) | 异步 | 错误提示、重试机制 |
complete |
请求完成(无论成功或失败) | 异步 | 隐藏加载动画、清理资源 |
statusCode |
按 HTTP 状态码定制处理 | 异步 | 特定状态码处理(如 401 跳登录) |
1️⃣ beforeSend(xhr, settings)
🔹 触发时机
- 在请求发送之前立即调用
- 是最后一个可以修改请求的机会
- 执行是同步的(会阻塞请求发送)
🔹 参数
参数 | 类型 | 说明 |
---|---|---|
xhr |
XMLHttpRequest |
原生请求对象,可用于设置请求头 |
settings |
Object |
当前请求的配置项(包含 url , type , data 等) |
🔹 典型用途
- 设置认证头(如
Authorization
) - 添加 CSRF Token
- 条件性取消请求
- 显示加载动画(开始)
✅ 示例代码
$.ajax({
url: '/api/data',
type: 'POST',
data: { name: '张三' },
beforeSend: function(xhr, settings) {
// 1. 添加 CSRF Token(Django 项目常见)
var token = getCookie('csrftoken');
if (token) {
xhr.setRequestHeader('X-CSRFToken', token);
}
// 2. 添加 JWT 认证头
var jwt = localStorage.getItem('token');
if (jwt) {
xhr.setRequestHeader('Authorization', 'Bearer ' + jwt);
}
// 3. 条件性取消请求
if (settings.type === 'DELETE' && !confirm('确定要删除吗?')) {
return false; // 返回 false 可取消请求
}
// 4. 显示加载动画
$('#loading').show();
},
success: function(data) {
console.log('成功:', data);
}
});
⚠️ 注意:
beforeSend
中return false
会取消请求。
2️⃣ success(data, textStatus, xhr)
🔹 触发时机
- 请求成功且服务器返回有效响应时调用
- HTTP 状态码为
2xx
(如 200, 201) - 执行是异步的
🔹 参数
参数 | 类型 | 说明 |
---|---|---|
data |
Object/String |
解析后的响应数据(自动根据 dataType 解析) |
textStatus |
String |
状态描述,通常是 "success" |
xhr |
XMLHttpRequest |
原生请求对象,可读取响应头等 |
🔹 典型用途
- 更新页面内容(DOM 操作)
- 处理 JSON 数据
- 跳转页面
- 隐藏加载动画
✅ 示例代码
$.ajax({
url: '/api/user',
type: 'GET',
dataType: 'json', // 告诉 jQuery 期望返回 JSON
success: function(data, textStatus, xhr) {
// data 已自动解析为 JavaScript 对象
console.log('用户数据:', data);
console.log('状态:', textStatus); // "success"
console.log('响应头 ETag:', xhr.getResponseHeader('ETag'));
// 更新页面
$('#username').text(data.name);
$('#email').text(data.email);
// 跳转
if (data.isAdmin) {
window.location.href = '/admin';
}
}
});
💡 如果
dataType
是'json'
,jQuery 会自动JSON.parse()
,你拿到的就是 JS 对象。
3️⃣ error(xhr, textStatus, errorThrown)
🔹 触发时机
- 请求失败时调用
- 包括:
- 网络错误(无法连接)
- HTTP 错误(404, 500, 403 等)
- 超时
- JSON 解析失败
🔹 参数
参数 | 类型 | 说明 |
---|---|---|
xhr |
XMLHttpRequest |
可读取 status 、statusText 、响应体 |
textStatus |
String |
错误类型:"timeout" 、"error" 、"abort" 、"parsererror" |
errorThrown |
String |
HTTP 状态文本(如 "Not Found" ),仅当有 HTTP 错误时 |
🔹 典型用途
- 显示错误提示
- 日志记录
- 重试机制
- 处理特定错误(如 401 跳登录)
✅ 示例代码
$.ajax({
url: '/api/data',
type: 'GET',
error: function(xhr, textStatus, errorThrown) {
console.error('AJAX 错误:', textStatus, errorThrown);
let message = '';
if (textStatus === 'timeout') {
message = '请求超时,请检查网络';
} else if (xhr.status === 404) {
message = '请求的资源不存在';
} else if (xhr.status === 401) {
message = '未登录,即将跳转...';
setTimeout(() => {
window.location.href = '/login';
}, 1000);
} else if (xhr.status === 500) {
message = '服务器内部错误';
} else {
message = '请求失败:' + errorThrown;
}
alert(message);
}
});
📌 常见
textStatus
:
"timeout"
:超时"error"
:一般网络或服务器错误"abort"
:请求被取消(如页面跳转)"parsererror"
:JSON/XML 解析失败
4️⃣ complete(xhr, textStatus)
🔹 触发时机
- 请求完成后调用,无论成功或失败
- 是"收尾工作"的理想位置
- 总是执行一次
🔹 参数
参数 | 类型 | 说明 |
---|---|---|
xhr |
XMLHttpRequest |
请求对象 |
textStatus |
String |
最终状态:"success" 、"notmodified" 、"error" 、"timeout" 、"abort" |
🔹 典型用途
- 隐藏加载动画
- 清理资源
- 统一日志记录
✅ 示例代码
$.ajax({
url: '/api/upload',
type: 'POST',
beforeSend: function() {
$('#loading').show(); // 显示加载
},
success: function(data) {
alert('上传成功!');
},
error: function() {
alert('上传失败!');
},
complete: function(xhr, textStatus) {
// 无论成功失败都隐藏加载动画
$('#loading').hide();
// 统一日志
console.log('请求结束,状态:', textStatus);
console.log('最终状态码:', xhr.status);
}
});
✅ 这是最佳实践 :
beforeSend
显示加载,complete
隐藏加载。
5️⃣ statusCode
(高级用法)
🔹 作用
- 按 HTTP 状态码 定制处理函数
- 可以与
error
并存,更精细控制
✅ 示例代码
$.ajax({
url: '/api/data',
type: 'GET',
statusCode: {
404: function() {
alert('页面找不到了');
},
403: function() {
alert('权限不足');
},
401: function() {
alert('请先登录');
window.location.href = '/login';
},
500: function() {
alert('服务器开小差了,请稍后再试');
},
200: function(data) {
// 也可以为 200 写处理(但通常用 success 更好)
console.log('正常返回:', data);
}
},
error: function(xhr, status) {
// 如果 statusCode 中没有匹配的状态码,才会走 error
alert('未知错误:', status);
}
});
🔁 优先级:
statusCode
>error
🧩 完整示例:综合使用所有回调
$.ajax({
url: '/api/profile',
type: 'PUT',
data: { name: '李四', age: 25 },
beforeSend: function(xhr) {
// 设置认证
xhr.setRequestHeader('Authorization', 'Bearer ' + getToken());
// 显示加载
$('#spinner').show();
},
success: function(data) {
alert('保存成功!');
$('#profile-form').addClass('saved');
},
error: function(xhr, status, err) {
if (status !== 'abort') { // 排除手动取消
alert('保存失败: ' + err);
}
},
complete: function() {
// 隐藏加载
$('#spinner').hide();
},
statusCode: {
401: function() {
window.location.href = '/login';
}
}
});
🎯 总结表格
回调 | 触发条件 | 是否可取消请求 | 常见用途 |
---|---|---|---|
beforeSend |
发送前 | ✅ 可通过 return false 取消 |
设置头、验证、显示加载 |
success |
成功(2xx) | ❌ 不可取消 | 更新 UI、处理数据 |
error |
失败(网络/4xx/5xx) | ❌ 不可取消 | 错误提示、日志 |
complete |
结束(成功或失败) | ❌ 不可取消 | 隐藏加载、清理 |
statusCode |
按状态码 | ❌ 不可取消 | 精细化错误处理 |
🚀 一句话终极解释
$.ajax
的回调就像一场舞台剧的流程控制:
beforeSend
→ 开幕前准备道具(设置头)success
→ 演出成功,观众鼓掌(更新页面)error
→ 演出失败,主持人救场(报错提示)complete
→ 谢幕,收拾舞台(隐藏加载)statusCode
→ 按剧本分支处理不同结局