ajax 方法全参数与全局事件

6.2 ajax 方法全参数与全局事件

上一节立住了通道原理，本节上手主力器械。$.ajax 只有一个参数——配置对象，但这个对象里装得下请求的全部性格：方法、地址、数据、超时、缓存策略、回调风格。它还是全章唯一"什么都能配"的入口，其余简化方法都只是它的预包装版本。本节把高频参数分组讲透，再补上两件容易忽视的装备：监听全站请求动态的全局事件，以及 jQuery 3 起正式拿到手的 Promise 外形。

本节摘要：$.ajax(配置对象) 的高频参数分五组——目标（url、type、data）、数据（dataType、contentType、traditional）、时限与缓存（timeout、cache、ifModified）、回调（success、error、complete、beforeSend）、杂项（headers、async、context）。全局事件（ajaxStart、ajaxStop 等）做统一加载指示；返回对象自带 Promise 接口，then 与 await 皆可用。

参数分组速查

三个易漏的细节先划出来。timeout 不设就永远等——弱网环境里这是体验事故的种子，生产请求都该有期限。cache 只对 GET 生效，置为 false 时 jQuery 自动在地址后追加时间戳参数绕过缓存，接口数据本该实时时记得开。traditional 是历史包袱：默认把数组序列化成 ids[]=1&ids[]=2 的风格，某些老服务端只认 ids=1&ids=2，置 true 切换。

三类回调与 beforeSend 的出场顺序

$.ajax({
  url: 'api/queue',
  type: 'POST',
  data: { guest: '孙七', bed: 'b' },
  dataType: 'json',
  timeout: 5000,
  beforeSend: function (xhr) {
    xhr.setRequestHeader('X-Client', 'triage');   // 发出前最后一次修改机会
    $('#loading').show();
  },
  success: function (data, status, xhr) { renderQueue(data); },
  error: function (xhr, status, thrown) {
    console.error('状态', xhr.status, '原因', status);
  },
  complete: function () {
    $('#loading').hide();                          // 无论成败都会执行
  }
});
​

回调的分工要读成一条时间线：beforeSend 在请求离手前执行（塞自定义头的唯一正规位置），成功入 success，失败入 error，两者之后 complete 收尾——加载指示的开与关正好对称地放在第一个与最后一个。error 回调的三参值得记住：响应对象、错误性质字符串（timeout、error、parsererror 等）、可选的异常对象；区分"超时"与"服务端 500"全靠第二个参数。

全局事件：全站请求的总控台

每上一个请求，页面上所有监听者都能收到广播——这就是全局事件族。最常用的一对是开闭加载指示：

$('#loading')
  .on('ajaxStart', function () { $(this).show(); })
  .on('ajaxStop',  function () { $(this).hide(); });
​

ajaxStart 在本页第一个请求启动时触发，ajaxStop 在最后一个请求结束时触发——中间无论并发多少请求，指示条只闪一次，这正是"总控台"的价值。同族还有 ajaxSuccess、ajaxError、ajaxComplete，分别在每笔请求的成功、失败、收尾时广播，可做统一日志与统一错误提示。它们的参数与局部回调不同：第一个参数是事件对象，第二个才是响应对象。全局错误兜底是它们的看家用法——页面上几十处请求不必每处都写错误分支，一处 ajaxError 统一弹提示，局部回调只管差异化处理。

一个开关要认识：配置项 global: false 能让某笔请求不广播全局事件。后台静默轮询这类"不想让用户看见转圈"的请求，就靠它退出总控台。

Promise 外形：then 与 await

jQuery 3 起，$.ajax 返回的对象实现了标准 Promise 接口，回调风格的另一种写法是：

$.ajax({ url: 'api/queue', dataType: 'json' })
  .then(renderQueue)
  .catch(function (err) { console.error('加载失败', err); });

// 配合 async 函数顺序取数
async function loadWard() {
  var list = await $.ajax({ url: 'api/queue', dataType: 'json' });
  var detail = await $.ajax({ url: 'api/bed/' + list[0].bed, dataType: 'json' });
  renderAll(detail);
}
​

Promise 风格的真正优势在组织依赖：后一个请求要用前一个的结果时，await 的写法把嵌套拍平成顺序；互不依赖的请求则用原生 Promise.all 并发等待。老代码里层层嵌套的 success 回调（俗称回调隧道）迁移时都可改成这个形状。

原生对照：fetch 的等价配置

对照表里最扎眼的是超时一行：fetch 原生没有 timeout 参数，要用中止控制器配合定时器自己实现——这是"简不下来"的现代接口里少见的倒退感，也说明 jQuery 那套配置并非历史包袱，而是真实需求的清单。

要点复盘

• $.ajax 一参定乾坤：目标、数据、时限缓存、回调、杂项五组参数覆盖全部需求。
• 回调时间线：beforeSend 出门前、success 或 error、complete 收尾；加载指示的开关对称放两端。
• 全局事件族是全站总控：ajaxStart 与 ajaxStop 做唯一加载指示，ajaxError 做统一兜底；静默请求用 global: false 退出广播。
• jQuery 3 的返回对象是标准 Promise，依赖请求用 await 拍平，独立请求用 Promise.all 并发。
• 迁 fetch 时自查清单：失败判定靠 res.ok，超时要自己接中止控制器。

主力器械用熟了，下一节盘点四件快捷工具——多数日常请求其实用不着全套配置。