jQuery ajax - de methode ajax()

jQuery Ajax 参考手册

Voorbeeld

Door AJAX een stuk tekst laden:

jQuery 代码：

$(document).ready(function(){
  $("#b01").click(function(){
  htmlobj=$.ajax({url:"/jquery/test1.txt",async:false});
  $("#myDiv").html(htmlobj.responseText);
  });
});

HTML 代码：

<div id="myDiv"><h2>Let AJAX change this text</h2></div>
<button id="b01" type="button">Change Content</button>

亲自试一试

定义和用法

ajax() 方法通过 HTTP 请求加载远程数据。

该方法是 jQuery 底层 AJAX 实现。简单易用的高层实现见 $.get, $.post 等。$.ajax() 返回其创建的 XMLHttpRequest 对象。大多数情况下你无需直接操作该函数，除非你需要操作不常用的选项，以获得更多的灵活性。

最简单的情况下，$.ajax() 可以不带任何参数直接使用。

Opmerking:所有的选项都可以通过 $.ajaxSetup() 函数来全局设置。

语法

jQuery.ajax([settings])
参数 描述
settings

可选。用于配置 Ajax 请求的键值对集合。

可以通过 $.ajaxSetup() 设置任何选项的默认值。

参数

options

Type: Object

可选。AJAX 请求设置。所有选项都是可选的。

async

Type: Boolean

默认值: true。默认设置下，所有请求均为异步请求。如果需要发送同步请求，请将此选项设置为 false。

注意，同步请求将锁住浏览器，用户其它操作必须等待请求完成才可以执行。

beforeSend(XHR)

Type: Functie

发送请求前可修改 XMLHttpRequest 对象的函数，如添加自定义 HTTP 头。

XMLHttpRequest 对象是唯一的参数。

这是一个 Ajax 事件。如果返回 false 可以取消本次 ajax 请求。

cache

Type: Boolean

默认值: true，dataType 为 script 和 jsonp 时默认为 false。设置为 false 将不缓存此页面。

jQuery 1.2 新功能。

complete(XHR, TS)

Type: Functie

Callback-functie na voltooiing van het verzoek (wordt aangeroepen na het succesvol of mislukken van het verzoek).

Parameters: XMLHttpRequest-object en een string die het verzoekt type beschrijft.

Dit is een Ajax-gebeurtenis.

contentType

Type: String

Standaardwaarde: "application/x-www-form-urlencoded". Type van inhoudsencodering bij het verzenden van informatie naar de server.

Standaardwaarde is geschikt voor de meeste gevallen. Als je expliciet een content-type doorgeeft aan $.ajax(), zal het altijd naar de server worden verzonden (zelfs als er geen gegevens worden verzonden).

context

Type: Object

Dit object wordt gebruikt om de context van de Ajax-relateerde callback-functies in te stellen. Dit betekent dat de callback-functie binnen deze object this wijst (indien deze parameter niet wordt ingesteld, wijst this naar de options parameter die tijdens het oproepen van deze AJAX-verzoek wordt doorgegeven). Bijvoorbeeld, als een DOM-element als context parameter wordt gespecificeerd, wordt de context van de success callback-functie ingesteld op dit DOM-element.

zoals hieronder:

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

Type: String

Data die naar de server wordt gestuurd. Wordt automatisch geconverteerd naar een verzoekstring-formaat. Wordt in GET-verzoeken toegevoegd aan de URL. Raadpleeg de beschrijving van de processData-optie om deze automatische conversie te verbieden. Het moet in Key/Value-formaat zijn. Als het een array is, zal jQuery automatisch dezelfde naam toekennen aan verschillende waarden. Bijvoorbeeld {foo:["bar1", "bar2"]} wordt omgezet in '&foo=bar1&foo=bar2'.

dataFilter

Type: Functie

Functie die de oorspronkelijke data van de Ajax-terugkeer voorbereidt. Biedt de parameters data en type aan: data is de oorspronkelijke data van de Ajax-terugkeer, en type is de dataType-parameter die tijdens het oproepen van jQuery.ajax wordt verstrekt. De waarde die de functie retourneert, zal verder worden verwerkt door jQuery.

dataType

Type: String

Verwachte data-soort die de server teruggeeft. Als deze niet wordt gespecificeerd, zal jQuery automatisch een intelligente inschatting maken op basis van de MIME-informatie van het HTTP-pakket, bijvoorbeeld wordt de XML MIME-soort herkend als XML. In versie 1.4 wordt JSON omgezet in een JavaScript-object, terwijl script het script uitvoert. Vervolgens zal de serverkant van de teruggegeven gegevens worden ontleed op basis van deze waarde en doorgegeven aan de callback-functie. Beschikbare waarden:

  • "xml": Returns an XML document, which can be processed by jQuery.
  • "html": Returns plain text HTML information; the script tags included will be executed when inserted into the dom.
  • "script": Returns plain text JavaScript code. Will not automatically cache the results unless the "cache" parameter is set. Note: In remote requests (not on the same domain), all POST requests will be converted to GET requests. (Because the DOM's script tag will be used to load)
  • "json": Returns JSON data.
  • "jsonp": JSONP format. When calling a function in JSONP format, such as "myurl?callback=?", jQuery will automatically replace ? with the correct function name to execute the callback function.
  • "text": Returns a plain text string
error

Type: Functie

Default value: automatically judge (xml or html). Call this function when the request fails.

There are three parameters: XMLHttpRequest object, error information, (optional) caught exception object.

If an error occurs, the error information (the second parameter) in addition to getting null, can also be 'timeout', 'error', 'notmodified', and 'parsererror'.

Dit is een Ajax-gebeurtenis.

global

Type: Boolean

Whether to trigger global AJAX events. Default value: true. Setting it to false will not trigger global AJAX events, such as ajaxStart or ajaxStop can be used to control different Ajax events.

ifModified

Type: Boolean

Only retrieve new data when the server data changes. Default value: false. Use HTTP package Last-Modified header information to judge. In jQuery 1.4, it will also check the 'etag' specified by the server to determine that the data has not been modified.

jsonp

Type: String

Rewrite the name of the callback function in a jsonp request. This value is used to replace the 'callback' part in the URL parameters of GET or POST requests in the form 'callback=?', such as {jsonp:'onJsonPLoad'} will result in 'onJsonPLoad=?' being sent to the server.

jsonpCallback

Type: String

Stel een callback-functienaam in voor jsonp-verzoeken. Deze waarde wordt gebruikt om de door jQuery gegenereerde willekeurige functienaam te vervangen. Dit wordt voornamelijk gebruikt om unieke functienamen te genereren, zodat het beheer van verzoeken eenvoudiger wordt, en het gemakkelijker is om callback-functies en foutafhandeling te bieden. Je kunt deze callback-functienaam ook specificeren om GET-verzoeken te laten cachen door de browser.

password

Type: String

Gebruikt om het wachtwoord in te stellen voor de HTTP authenticatieverzoek.

processData

Type: Boolean

Standaardwaarde: true. Standaard worden gegevens die via de data-optie worden doorgegeven en die een object zijn (technisch gezien niet een string), omgezet in een querystring om te passen bij de standaard contenttype "application/x-www-form-urlencoded". Als je DOM-tree-informatie of andere gegevens wilt verzenden die niet moeten worden geconverteerd, stel deze in op false.

scriptCharset

Type: String

Alleen in gebruik als dataType "jsonp" of "script" is en type "GET" is, zal dit worden gebruikt om de charset te dwingen te wijzigen. Dit wordt meestal gebruikt wanneer de contentencoding van lokaal en verrem content verschillend is.

success

Type: Functie

Callback-functie die wordt aangeroepen na een succesvol verzoek.

Parameters: De gegevens die door de server worden geretourneerd en worden verwerkt op basis van de dataType parameter; een string die de status beschrijft.

Dit is een Ajax-gebeurtenis.

traditional

Type: Boolean

Als je de traditionele manier wilt gebruiken om gegevens te serialiseren, stel deze in op true. Raadpleeg de jQuery.param-methode onder de categorie Tools.

timeout

Type: Number

Stel de timeout-tijd van het verzoek in (miliseconden). Deze instelling overschrijft de globale instelling.

type

Type: String

Standaardwaarde: "GET"). Verzoekmethode ("POST" of "GET"), standaard "GET". Opmerking: Andere HTTP-verzoekmethoden, zoals PUT en DELETE, kunnen ook worden gebruikt, maar worden slechts door een deel van de browsers ondersteund.

url

Type: String

Standaardwaarde: huidige paginaadres. Het adres waarvan de verzoek wordt verzonden.

username

Type: String

Gebruikt om de gebruikersnaam in te stellen voor de gebruiker die de HTTP authenticatieverzoek moet beantwoorden.

xhr

Type: Functie

Een XMLHttpRequest-object moet worden geretourneerd. Standaard is dit in IE een ActiveXObject, terwijl het in andere gevallen een XMLHttpRequest is. Gebruikt om een aangepaste of verbeterde XMLHttpRequest-object te bieden. Deze parameter was in jQuery 1.3 en eerder niet beschikbaar.

Callbackfuncties

Als de gegevens die $.ajax() ophaalt moeten worden verwerkt, moet gebruik worden gemaakt van callbackfuncties: beforeSend, error, dataFilter, success, complete.

beforeSend

Wordt aangeroepen voordat de aanvraag wordt verzonden en een XMLHttpRequest als parameter wordt ingediend.

error

Wordt aangeroepen wanneer de aanvraag mislukt. Stuur het XMLHttpRequest-object, een string die de fouttype beschrijft en een uitzonderingsobject (indien aanwezig) in.

dataFilter

Roep deze functie aan nadat de aanvraag succesvol is verlopen. Stuur de retourgegevens en de waarde van het parameter 'dataType' in. En moet nieuwe gegevens (mogelijk verwerkte) retourneren die aan de success-callbackfunctie worden doorgegeven.

success

Wordt aangeroepen nadat de aanvraag is voltooid. Stuur de retourgegevens en een string met een succescode in.

complete

Roep deze functie aan nadat de aanvraag is voltooid, ongeacht succes of falen. Stuur het XMLHttpRequest-object en een string met een succes- of foutcode in.

Gegevenssoort

De functie $.ajax() is afhankelijk van de informatie die de server verstrekt om de retourgegevens te verwerken. Als de server meldt dat de retourgegevens XML zijn, kunnen de resultaten worden doorzocht met behulp van gewone XML-methoden of jQuery-selectors. Als andere typen worden gezien, zoals HTML, worden de gegevens behandeld als tekst.

Met behulp van de dataType-optie kan ook andere manieren van gegevensverwerking worden gespecificeerd. Naast puur XML kan ook html, json, jsonp, script of text worden gespecificeerd.

Voor text en xml-typen wordt de gegevens niet verwerkt. De gegevens worden eenvoudig doorgegeven aan de success-callbackfunctie via de responseText of responseHTML-eigenschappen van XMLHttpRequest.

Opmerking:We moeten ervoor zorgen dat het MIME-type dat de webserver rapporteert overeenkomt met het geselecteerde dataType. Bijvoorbeeld, voor XML moet de server text/xml of application/xml verklaren om een consistent resultaat te krijgen.

Als de html-type is gespecificeerd, wordt elke ingesloten JavaScript uitgevoerd voordat de HTML als een string wordt geretourneerd. Op dezelfde manier wordt de server-side gegenereerde JavaScript uitgevoerd voordat de script als tekstgegevens wordt geretourneerd als de script-type is gespecificeerd.

Als het type 'json' is opgegeven, wordt de verkregen gegevens als een JavaScript-object geïnterpreteerd en het opgebouwde object wordt als resultaat geretourneerd. Om dit te bereiken, probeert het eerst JSON.parse() te gebruiken. Als de browser dit niet ondersteunt, gebruikt het een functie om dit te bouwen.

JSON-gegevens zijn een gestructureerde datatype die gemakkelijk kan worden geïnterpreteerd door JavaScript. Als de gegevens die je ophaalt op een externe server worden opgeslagen (bijvoorbeeld met een andere domeinnaam, dus cross-domain data ophalen), moet je het type 'jsonp' gebruiken. Bij gebruik van dit type wordt een query string parameter 'callback=?' toegevoegd aan het einde van de URL. De server moet de JSON-gegevens voorafgaand aan de callback-functienaam plaatsen om een geldige JSONP-verzoek te voltooien. Als je de naam van de callback-functie wilt wijzigen in plaats van de standaard 'callback', kun je de optie 'jsonp' van $.ajax() instellen.

Opmerking:JSONP is een uitbreiding van het JSON-formaat. Het vereist enige server-side code om de query string parameters te detecteren en te verwerken.

Als het type 'script' of 'jsonp' is opgegeven, wordt bij het ontvangen van gegevens van de server in feite een <script>-tag gebruikt in plaats van een XMLHttpRequest-object. In dit geval retourneert $.ajax() geen XMLHttpRequest-object en worden geen event handlers zoals beforeSend doorgegeven.

Gegevens verzenden naar de server

Standaard gebruiken Ajax-verzoeken de GET-methode. Als je de POST-methode wilt gebruiken, kun je de waarde van het parameter 'type' instellen. Deze optie beïnvloedt ook hoe de inhoud van de optie 'data' wordt verzonden naar de server.

De optie 'data' kan zowel een query string bevatten, zoals 'key1=value1&key2=value2', als een mapping, zoals '{key1: 'value1', key2: 'value2'}'. Als de laatste vorm wordt gebruikt, wordt de data in de zender omgezet naar een query string. Dit proces kan ook worden vermeden door de optie 'processData' op false in te stellen. Als we een XML-object naar de server willen sturen, kan dit verwerking misschien niet geschikt zijn. In dit geval moeten we ook de waarde van de optie 'contentType' wijzigen, door een andere geschikte MIME-type te gebruiken in plaats van de standaard 'application/x-www-form-urlencoded'.

Geavanceerde opties

global 选项用于阻止响应注册的回调函数，比如 .ajaxSend，或者 ajaxError，以及类似的方法。这在有些时候很有用，比如发送的请求非常频繁且简短的时候，就可以在 ajaxSend 里禁用这个。

如果服务器需要 HTTP 认证，可以使用用户名和密码可以通过 username 和 password 选项来设置。

Ajax 请求是限时的，所以错误警告被捕获并处理后，可以用来提升用户体验。请求超时这个参数通常就保留其默认值，要不就通过 jQuery.ajaxSetup 来全局设定，很少为特定的请求重新设置 timeout 选项。

默认情况下，请求总会被发出去，但浏览器有可能从它的缓存中调取数据。要禁止使用缓存的结果，可以设置 cache 参数为 false。如果希望判断数据自从上次请求后没有更改过就报告出错的话，可以设置 ifModified 为 true。

scriptCharset 允许给 <script> 标签的请求设定一个特定的字符集，用于 script 或者 jsonp 类似的数据。当脚本和页面字符集不同时，这特别好用。

Ajax 的第一个字母是 asynchronous 的开头字母，这意味着所有的操作都是并行的，完成的顺序没有前后关系。$.ajax() 的 async 参数总是设置成true，这标志着在请求开始后，其他代码依然能够执行。强烈不建议把这个选项设置成 false，这意味着所有的请求都不再是异步的了，这也会导致浏览器被锁死。

$.ajax 函数返回它创建的 XMLHttpRequest 对象。通常 jQuery 只在内部处理并创建这个对象，但用户也可以通过 xhr 选项来传递一个自己创建的 xhr 对象。返回的对象通常已经被丢弃了，但依然提供一个底层接口来观察和操控请求。比如说，调用对象上的 .abort() 可以在请求完成前挂起请求。

jQuery Ajax 参考手册