jQuery.ajax()

描述：实施一个异步HTTP（Ajax）请求。

• 增补版本：1.5jQuery.ajax( url [, settings ] )

  • url
    类型：String
    一个字符串，包含了请求被发送到的URL。
  • settings
    类型：PlainObject
    一个键值对集合，配置了Ajax请求。所有的设置都是可选的。可以利用$.ajaxSetup()来设置默认值。请参阅下面的jQuery.ajax( settings )以了解设置的完整列表。

• 增补版本：1.0jQuery.ajax( [settings ] )

  • settings
    类型：PlainObject
    配置Ajax请求的键值对集合。所有的设置都是可选的。可以利用$.ajaxSetup()来设置默认值。
    • accepts (默认值： depends on DataType)
      类型：PlainObject
      一个键值对的集合，把给定的dataType映射到MIME类型，会在Accept请求头中发送它。此请求头告诉服务器，它将接受哪种返回的响应。例如，下面定义了自定义的类型mycustomtype，与请求一起发送：

      1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16

      $.ajax({ accepts: { mycustomtype: 'application/x-some-custom-type' }, // Instructions for how to deserialize a `mycustomtype` converters: { 'text mycustomtype': function(result) { // Do Stuff return newresult; } }, // Expect a `mycustomtype` back from server dataType: 'mycustomtype' });

      注意：你需要在converters中为此类型指定一个互补的项，以使它正确地工作。
    • async (默认值： true)
      类型：Boolean
      默认情况下，所有的请求都会被异步发送（亦即，此属性默认被设置为true）。如果你需要同步请求，请把此选择设置为false。跨域请求以及dataType: "jsonp"请求，并不支持同步操作。请注意，同步请求可能临时锁住浏览器，在请求被激活的同时，禁用任何操作。自从jQuery 1.8以来，async: false配合jQXHR的用法（$.Deferred）被淘汰了；你必须使用success、error、complete回调函数选项来代替jqXHR对象的对应的方法，譬如jqXHR.done()。
    • beforeSend
      类型：Function( jqXHR jqXHR, PlainObject settings )
      一个请求前回调函数，可以用来在发送请求之前修改jqXHR（在jQuery 1.4.x中，是XMLHTTPRequest）对象。使用此回调函数来设置自定义头，等等。传入jqXHR和setting对象作为参数。它是一个Ajax事件。在beforeSend函数中返回false将撤销请求。自从jQuery 1.5以来，无论请求类型如何，都会调用beforeSend选项。
    • cache (默认值：对于dataType为“script”或“jsonp”的情况，是false，其它都是true)
      类型：Boolean
      如果设置为false，它将强制浏览器不缓存请求的页面。注意：把cache设置为false只能在HEAD请求和GET请求中正常工作。它的作用方式是对GET参数追加一个_={timestamp}。别的请求类型不需要此参数，除了在IE8中，当一个POST请求一个已经用GET请求过的URL。
    • complete
      类型：Function( jqXHR jqXHR, String textStatus )
      当请求完成时要调用的函数（在success和error回调函数执行了之后）。此函数获得两个传入的参数：jqXHR（在jQuery 1.4.x中，是XMLHTTPRequest）对象，以及一个字符 ，分类了请求的状态（"success"、"notmodified"、"nocontent"、"error"、"timeout"、"abort"或"parsererror"）。自从jQuery 1.5以后，complete设置可以接受一个函数的数组。将依次调用每个函数。这是一个Ajax事件。
    • contents
      类型：PlainObject
      一个字符串、正则表达对对象，确定了jQuery将如何解析响应，给定它的内容类型。 (增补版本：1.5)
    • contentType (默认值： 'application/x-www-form-urlencoded; charset=UTF-8')
      类型：Boolean or String
      如果要把数据发送到服务器，请使用此内容类型。默认是“application/x-www-form-urlencoded; charset=UTF-8”，它在大多数情况下都很好。如果你对$.ajax()显式传入内容类型，则它始终会发送到服务器（哪怕没有设置数据）。自从jQuery，你可以传入false以告诉jQuery不要发送任何数据类型头。注意：W3C XMLHttpRequest规范文档指示字符集始终是UTF-8；指定其它字符集将不会强迫浏览器改变此编码。注意：对于跨域请求，将此内容类型设置为除了application/x-www-form-urlencoded、multipart/form-data和text/plain之外的任何东西，都会触发浏览器对服务器发送一个起飞前OPTIONS请求。
    • context
      类型：PlainObject
      此对象将成为所有Ajax相关回调函数的上下文。默认情况下，上下文是一个对象，代表了在调用中使用的Ajax设置（$.ajaxSettings合并了传递给$.ajax的设置）。例如，指定DOM元素为上下文，将制作出针对请求的complete回调函数的上下文，如下：

      1 2 3 4 5 6

      $.ajax({ url: "test.html", context: document.body }).done(function() { $( this ).addClass( "done" ); });

    • converters (默认值： {"* text": window.String, "text html": true, "text json": jQuery.parseJSON, "text xml": jQuery.parseXML})
      类型：PlainObject
      一个对象，包含了内容类型到内容类型的转换器。每种转换器的值是一个函数，返回响应的转换值。 (增补版本：1.5)
    • crossDomain (默认值： 对于同源请求是false，对于跨域请求是true)
      类型：Boolean
      如果你想要在同一个域上强迫跨域请求（譬如JSONP），请把crossDomain的值设置为true。这允许，例如，允许服务器端重定向到另一个域名。 (增补版本：1.5)
    • data
      类型：PlainObject or String or Array
      发送到服务器的数据。如果还没有字符串的话，它会转换到一个请求字符串。针对GET请求，它是追加到URL后面。请参阅processData选项以防止此自动处理。对象必须是键值对。如果值是一个数组，jQuery会基于traditional设置（在下面有所描述），用相同的键序列化多个值。
    • dataFilter
      类型：Function( String data, String type ) => Anything
      一个函数，用来处理XMLHttpRequest的原始响应数据。这是用来对响应除害化的预处理函数。你应该返回已除害化的数据。此函数接受两个参数：返回自服务器的原始数据，以及“dataType”参数。
    • dataType (默认值： Intelligent Guess (xml, json, script, or html))
      类型：String
      期待从服务器返回的数据类型。如果没有指定，jQuery将根据响应的MIME类型判断（XML MIME类型将被识别为XML，在jQuery 1.4中，如果是JSON将生成一个JavaScript对象，而如果是Script则会执行这些脚本，其它则返回为一个字符串。）可用的类型（以及向success回调函数传递为第一个参数的结果）是：

      • "xml": 返回可以通过jQuery被处理的XML文档。
      • "html": 将HTML返回为纯文本；包含的脚本标签会在插入到DOM时被执行。
      • "script": 将响应当作JavaScript来执行，并将它作为纯文本返回。通过对URL追加一个查询字符串参数_=[TIMESTAMP]来禁用缓存，除非cache选项被设置为true。注意：对远程序域请求，所有的POST请求都转换成GET请求。
      • "json": 把响应的结果当作JSON执行，并返回一个JavaScript对象。跨域“json”请求会被转换为“jsonp”，除非在请求选中中，请求包含了jsonp: false。会按严格方式解析JSON数据，任何有错误的JSON都会被拒绝，并抛出一个解析错误。自从jQuery 1.9以来，任何空响应都会被拒绝；服务器应该返回一个null或{}来代替。（请参阅json.org以进一步了解正确的JSON格式。）
      • "jsonp": 使用JSONP载入一个JSON块。会把额外的"?callback=?"添加到URL的末尾以指定回调函数。通过向URL末尾追加请求字符串参数"_=[TIMESTAMP]"来禁用缓存，除非cache选项被设置为true。
      • "text": 纯文本字符串。
      • 多个空格分隔的值: 自从jQuery 1.5以来，jQuery可以把从内容类型头（Content-Type）收到的dataType转换成你想要的。例如，如果你想要一个文本响应为XML处理，使用“text xml”数据类型。你还可以将一个JSONP请求，以文本形式接受，并用jQuery解析为XML："jsonp text xml"。类似的，一个简写字符串，譬如"jsonp xml"将先尝试从jsonp转换到xml，然后，如果失败的话，再把jsonp转换为text，然后再从text转换为xml。
    • error
      类型：Function( jqXHR jqXHR, String textStatus, String errorThrown )
      当请求失败时要调用的函数。此函数接受三个参数：jqXHR（在jQuery 1.4中，是XMLHttpRequest）对象，一个字符串描述发生的错误的类型，以及一个可选的异常对象，如果发生了的话。针对第二个参数可能的值（除了null之外）是“timeout”、“error”、“abort”和“parsererror”。如果发生了一次HTTP错误，errorThrown会接收到HTTP状态的文本部分，譬如“Not Found”或者“Internet Server Error”。自从jQuery 1.5以来，error设置可以接受一个函数的数组。每个函数将被依次调用。注意：对于跨域脚本和跨域JSPNP请求，不会调用此处理函数。它是一个Ajax事件。
    • global (默认值： true)
      类型：Boolean
      是否为此请求触发全局Ajax事件处理函数。默认值是true。把它设置为false可以防止触发全局处理函数，譬如ajaxStart和ajaxStop。这可以用来控制各种各样的Ajax事件。
    • headers (默认值： {})
      类型：PlainObject
      一个附加的头键值对对象，利用XMLHttpRequest传输，随请求一起发送。始终会添加头X-Requested-With: XMLHttpRequest，但是它的默认XMLHttpRequest值在这里会被修改。headers中设置的值会在beforeSend函数内部被覆盖。 (增补版本：1.5)
    • ifModified (默认值： false)
      类型：Boolean
      只有当请求在上一次请求之后有所改变，才允许请求成功。这是通过检查Last-Modified头来实现的。默认值是false忽略此头。在jQuery 1.4中，此技术也会检查由服务器指定的“etag”来捕获未修改的数据。
    • isLocal (默认值： 取决于当前本地协议)
      类型：Boolean
      允许当前环境被识别为“local”（例如，文件系统），哪怕jQuery并不能默认识别它。下面的协议是目前能识别为本地的协议：file、*-extension和widget。如果需要修改isLocal设置，建议在$.ajaxSetup()方法中做一次这样的修改。 (增补版本：1.5.1)
    • jsonp
      类型：String or Boolean
      在一个JSONP请求中覆盖回调函数名称。在url的查询字符串的“callback=?”部分中，此值将被用来代替“callback”。所以{jsonp:'onJSONPLoad'}将导致'onJSONPLoad=?'传到服务器。自从jQuery 1.5以来，将jsonp选项设置为false会防止jQuery在传输中对url添加“?callback”字符串，并防止试图使用“=?”。在这种情况下，你必须明确设置jsonpCallback设置。例如：{ jsonp: false, jsonpCallback: "callbackName" }。如果你并不信任你的Ajax请求的目标，为了安全起见，请考虑将jsonp属性设置为false。
    • jsonpCallback
      类型：String or Function()
      为一个JSONP请求指定回调函数名称。该值将被用来代替jQuery自动生成的随机名称。最好让jQuery生成唯一名称，因为这将使它易于管理请求，提供回调函数和error处理函数。当你想要启用更好的GET请求的浏览器缓存时，你可能想要指定回调函数。自从jQuery 1.5以来，针对此设置还可以使用一个函数，那样的话，jsonpCallback的值会被设置为那个函数的返回值。
    • method (默认值： 'GET')
      类型：String
      用于请求的HTTP方法（例如："POST"、"GET"、"PUT"） (增补版本：1.9.0)
    • mimeType
      类型：String
      覆盖XHR mime类型的mime类型。 (增补版本：1.5.1)
    • password
      类型：String
      在响应HTTP身份验证请求中，与XMLHttpRequest配合使用的密码。
    • processData (默认值： true)
      类型：Boolean
      默认情况下，以对象（严格地说，是除了字符串以外的任何东西）的形式向data传递数据，对象都将被处理，并转换为一个查询字符 ，固定到默认的content-type“application/x-www-form-urlencoded”。如果你想发送一个DOMDocument，或者其它未处理的数据，请把此选项设置为false。
    • scriptCharset
      类型：String
      只有使用“script”传输（例如，利用“jsonp”的跨域请求，或者利用“script”数据类型和“GET”请求类型）的时候才应用它。在请求中用到的脚本标记上设置charset特性。当在本地页面上设置字符集与远程脚本所用的字符集不一致时使用它。
    • statusCode (默认值： {})
      类型：PlainObject

      一个数字HTTP代码和要调用的函数的对象，当响应具有对应的代码时调用该函数。例如，下面的代码将对404响应状态弹出警告框：

      1 2 3 4 5 6 7

      $.ajax({ statusCode: { 404: function() { alert( "page not found" ); } } });

      如果请求成功了，代码代码取用与success回调函数相同的参数；如果它产生了一个错误（包括3xx重定向），它将取用与error回调函数相同的参数。

      (增补版本：1.5)
    • success
      类型：Function( Anything data, String textStatus, jqXHR jqXHR )
      当请求成功时要调用的函数。此函数取得三个传入的参数：由服务器返回的data，根据dataType参数或dataFilter回调函数格式化，如果指定了它们的话；一个字符串，描述响应状态；以及jqXHR（在jQuery 1.4.x中，是XMLHttpREquest）对象。自从jQuery 1.5以来，success设置可以接受一个函数的数组。将依次调用每个函数。它是一个Ajax事件。
    • timeout
      类型：Number
      为请求设置一个超时（以毫秒计）。如果值为0表示没有超时。它将覆盖利用$.ajaxSetup()所作的任何全局设置。超时阶段从制作$.ajax调用的时点开始计时；如果若干个其它请求正在处理中，浏览器没有可用的连接，一个请求可能在它被发送之前就超时了。在jQuery 1.4.x以及以前版本中，如果请求超时的话，XMLHttpRequest对象将处于无效状态；访问任何对象可能都可能抛出异常。只在在Firefox 3.0+中，可以用timeout来撤销script请求和JSONP请求；脚本将继续运行，哪怕它已经超过了超时阶段。
    • traditional
      类型：Boolean
      如果你想要使用传统的参数序列化样式，就把它设置为true。
    • type (默认值： 'GET')
      类型：String
      针对method的别名。如果使用jQuery 1.9.0以前的版本，你必须使用type。
    • url (默认值： The current page)
      类型：String
      一个字符串，包含了请求被发送到的URL。
    • username
      类型：String
      在响应HTTP身份验证请求中，与XMLHttpRequest配合使用的用户名。
    • xhr (默认值： 如果可以的话（IE中）是ActiveXObject，否则是XMLHttpRequest)
      类型：Function()
      针对创建XMLHttpRequest对象的回调函数。默认情况下，当可用时（IE中）是ActiveXObject，否则是XMLHttpRequest。覆盖它以提供你自己的XMLHttpRequest实现器，或增强XMLHttpRequest工厂函数。
    • xhrFields
      类型：PlainObject

      在原生的XHR对象上设置的字段名-字段值对对象。例如，如果需要的话，针对跨域请求，你可以用它来把withCredentials设置为true。

      1 2 3 4 5 6

      $.ajax({ url: a_cross_domain_url, xhrFields: { withCredentials: true } });

      在jQuery 1.5中，withCredentials属性不会传播给原生XHR，因此需要它的CORS请求会忽略此标记。出于此原因，如果你需要使用到它，我们建议使用jQuery 1.5.1+。

      (增补版本：1.5.1)

$.ajax();

$.ajax({
  url: "http://fiddle.jshell.net/favicon.png",
  beforeSend: function( xhr ) {
    xhr.overrideMimeType( "text/plain; charset=x-user-defined" );
  }
})
  .done(function( data ) {
    if ( console && console.log ) {
      console.log( "Sample of data:", data.slice( 0, 100 ) );
    }
  });

// Assign handlers immediately after making the request,
// and remember the jqXHR object for this request
var jqxhr = $.ajax( "example.php" )
  .done(function() {
    alert( "success" );
  })
  .fail(function() {
    alert( "error" );
  })
  .always(function() {
    alert( "complete" );
  });
 
// Perform other work here ...
 
// Set another completion function for the request above
jqxhr.always(function() {
  alert( "second complete" );
});

$.ajaxSetup({
  contents: {
    mycustomtype: /mycustomtype/
  },
  converters: {
    "mycustomtype json": function( result ) {
      // Do stuff
      return newresult;
    }
  }
});

$.ajaxSetup({
  contents: {
    mycustomtype: /mycustomtype/
  },
  converters: {
    "text mycustomtype": true,
    "mycustomtype json": function( result ) {
      // Do stuff
      return newresult;
    }
  }
});

补充说明：

$.ajax({
  method: "POST",
  url: "some.php",
  data: { name: "John", location: "Boston" }
})
  .done(function( msg ) {
    alert( "Data Saved: " + msg );
  });

$.ajax({
  url: "test.html",
  cache: false
})
  .done(function( html ) {
    $( "#results" ).append( html );
  });

var xmlDocument = [create xml document];
var xmlRequest = $.ajax({
  url: "page.php",
  processData: false,
  data: xmlDocument
});
 
xmlRequest.done( handleResponse );

var menuId = $( "ul.nav" ).first().attr( "id" );
var request = $.ajax({
  url: "script.php",
  method: "POST",
  data: { id : menuId },
  dataType: "html"
});
 
request.done(function( msg ) {
  $( "#log" ).html( msg );
});
 
request.fail(function( jqXHR, textStatus ) {
  alert( "Request failed: " + textStatus );
});

$.ajax({
  method: "GET",
  url: "test.js",
  dataType: "script"
});