jQuery ajax - ajax() metoden

jQuery Ajax 参考手册

Exempel

Ladda ett stycke text med AJAX:

jQuery-kod:

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

HTML-kod:

<div id="myDiv"><h2>Låt AJAX ändra detta text</h2></div>
<button id="b01" type="button">Ändra innehåll</button>

Prova själv

Definition och användning

ajax() -metoden laddar fjärrdata genom HTTP-förfrågningar.

Detta är jQuery:s grundläggande AJAX-implementering. En enkel högre implementering finns i $.get, $.post och andra. $.ajax() returnerar det skapade XMLHttpRequest-objektet. I de flesta fall behöver du inte direkt manipulera denna funktion, om du inte behöver manipulera ovanliga alternativ för att få mer flexibilitet.

I det enklaste fallet kan $.ajax() användas utan några parametrar.

Observera:Alla alternativ kan globalt ställas in med hjälp av $.ajaxSetup() -funktionen.

Syntaks

jQuery.ajax([settings]
Parameter Beskrivning
settings

Valfritt. En samling nyckel-värdepar för att konfigurera Ajax-förfrågningar.

Du kan ställa in standardvärden för alla alternativ med hjälp av $.ajaxSetup().

Parameter

options

Typ: Object

Valfritt. AJAX-förfrågans inställningar. Alla alternativ är valfria.

async

Typ: Boolesk

Standardvärde: true. Under standardinställningar är alla förfrågningar asynkrona. Om du behöver skicka en synkron förfrågan, ställ in detta alternativ till false.

Observera att synkrona förfrågningar låser webbläsaren, användarens andra operationer måste vänta på att förfrågan är klar innan de kan utföras.

beforeSend(XHR)

Typ: Funktion

Funktioner för att ändra XMLHttpRequest-objektet innan anropet skickas, som att lägga till anpassade HTTP-huvuden.

XMLHttpRequest-objektet är den unika parametern.

Detta är ett Ajax-händelse. Om false returneras kan detta ajax-forespår avbrytas.

cache

Typ: Boolesk

Standardvärde: true, när dataType är script och jsonp är standardvärdet false. När false är inställt kommer denna sida inte att cachas.

jQuery 1.2 nya funktioner.

complete(XHR, TS)

Typ: Funktion

Callback-funktion som anropas efter att förfrågan är slutförd (anropas efter att förfrågan har lyckats eller misslyckats).

Parametrar: XMLHttpRequest-objektet och en sträng som beskriver förfrågningsTypen.

Detta är ett Ajax-händelse.

contentType

Typ: Sträng

Standardvärde: "application/x-www-form-urlencoded". Innehållskodningstyp som används när information skickas till servern.

Standardvärdet är lämpligt för de flesta fall. Om du tydligt anger en content-type till $.ajax() kommer den att skickas till servern (även om det inte finns några data att skicka).

context

Typ: Object

Detta objekt används för att ställa in kontexten för Ajax-relaterade callback-funktioner. Det innebär att låta this peka på detta objekt (om denna parameter inte sätts, kommer this att peka på options-argumentet som överfördes vid anrop av detta AJAX-forespår). Till exempel, om en DOM-element specificeras som context-argument, sätts således kontexten för success-callback-funktionen till detta DOM-element.

Liksom detta:

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

Typ: Sträng

Data som skickas till servern. Konverteras automatiskt till en förfrågningssträngformat. Läggas till efter URL:en i GET-förfrågningar. Se till processData-alternativet för att förhindra denna automatiska konvertering. Måste vara i Key/Value-format. Om det är en array, kommer jQuery att automatiskt tilldela samma namn till olika värden. Till exempel {foo: ["bar1", "bar2"]} konverteras till '&foo=bar1&foo=bar2'.

dataFilter

Typ: Funktion

Funktion för att förbehandla det ursprungliga data som returneras av Ajax. Tillhandahåller data och type två parametrar: data är det ursprungliga data som returneras av Ajax, och type är dataType-argumentet som tillhandahålls vid anrop av jQuery.ajax. Värdet som returneras av funktionen kommer att bearbetas vidare av jQuery.

dataType

Typ: Sträng

Förväntad datatyp som servern returnerar. Om det inte specificeras, kommer jQuery att automatiskt bedöma den intelligenta sättet baserat på HTTP-paketets MIME-information, till exempel kommer XML MIME-typen att kännetecknas som XML. I version 1.4 genereras JSON en JavaScript-objekt, medan script kommer att köra detta skript. Därefter kommer serverns returnerade data att analyseras baserat på detta värde och överföras till callback-funktionen. Tillgängliga värden:

  • "xml": Returnera XML-dokument, som kan hanteras av jQuery.
  • "html": Returnera ren text HTML-information; innehållande script-taggar kommer att köras när de läggas till i DOM.
  • "script": Returnera ren text JavaScript-kod. Resultatet lagras inte automatiskt. Om inte sattes "cache"-parametern.Observera: vid fjärrförfrågningar (inte på samma domän), kommer alla POST-förfrågningar att omvandlas till GET-förfrågningar. (Eftersom DOM:s script-tag kommer att användas för att ladda.)
  • "json": Returnera JSON-data.
  • "jsonp": JSONP-format. När en funktion anropas med JSONP-format, till exempel "myurl?callback=?", kommer jQuery automatiskt att ersätta ? med det korrekta funktionsnamnet för att köra callback-funktionen.
  • "text": Returnera ren textsträng
error

Typ: Funktion

Standardvärde: automatisk bedömning (xml eller html). Anropa denna funktion vid misslyckade förfrågningar.

Det finns tre parametrar: XMLHttpRequest-objektet, felmeddelandet, (valfritt) den fångade undantagsobjektet.

Om ett fel inträffar kan felmeddelandet (den andra parametern) utöver null vara "timeout", "error", "notmodified" och "parsererror".

Detta är ett Ajax-händelse.

global

Typ: Boolesk

Om den globala AJAX-händelsen ska utlösas eller inte. Standardvärde: true. Om det sätts till false kommer inte den globala AJAX-händelsen att utlösas, till exempel kan ajaxStart eller ajaxStop användas för att kontrollera olika AJAX-händelser.

ifModified

Typ: Boolesk

Hämta nya data endast när serverdata ändras. Standardvärde: false. Använd HTTP-paketets Last-Modified-huvudinformation för att bedöma. I jQuery 1.4 kommer det också att kontrollera serverangivna 'etag' för att avgöra att data inte har ändrats.

jsonp

Typ: Sträng

Återställ namnet på callback-funktionen i en jsonp-förfrågan. Detta värde används för att ersätta delen "callback" i URL-parametrarna för GET- eller POST-förfrågningar av typen "callback=?", till exempel {jsonp:'onJsonPLoad'} kommer att resultera i att "onJsonPLoad=?" skickas till servern.

jsonpCallback

Typ: Sträng

Ange ett callback-funktionsnamn för jsonp-förfrågningar. Detta värde kommer att användas för att ersätta jQuery:s automatiskt genererade slumpmässiga funktion namn. Detta används huvudsakligen för att låta jQuery generera unika funktion namn, vilket gör det enklare att hantera förfrågningar, och det är också bekvämt att tillhandahålla callback-funktioner och felhantering. Du kan också använda detta för att specificera callback-funktionsnamnet när du vill att webbläsaren ska cacha GET-förfrågningar.

password

Typ: Sträng

Används för att svara på lösenord för HTTP-autentiseringsförfrågningar

processData

Typ: Boolesk

Standardvärde: true. Som standard omvandlas data som skickas in via data-alternativet, om det är ett objekt (tekniskt sett om det inte är en sträng), till en frågesträng för att matcha den standardinnehållstypen "application/x-www-form-urlencoded". Om du vill skicka DOM-trädinformation eller annan information som du inte vill omvandla, sätt den till false.

scriptCharset

Typ: Sträng

Används endast när dataType är "jsonp" eller "script" och type är "GET" för att tvinga ändring av charset. Används vanligtvis när innehudkodingen är annorlunda lokalt och på avstånd.

success

Typ: Funktion

Återkallningsfunktion efter framgångsrik förfrågan.

Parametrar: Data som returneras av servern och bearbetas enligt dataType-parametern; en sträng som beskriver tillståndet.

Detta är ett Ajax-händelse.

traditional

Typ: Boolesk

Om du vill använda ett traditionellt sätt att serialisera data, sätt den till true. Se till verktygskategorin för jQuery.param-metoden.

timeout

Typ: Nummer

Ställ in förfrågnings Timeout-tid (millisekunder). Denna inställning kommer att överskriva den globala inställningen.

type

Typ: Sträng

Standardvärde: "GET")). Förfrågningsmetod ("POST" eller "GET"), standard är "GET". Observera: Andra HTTP-förfrågningsmetoder, såsom PUT och DELETE, kan också användas, men endast av delvis stödja webbläsare.

url

Typ: Sträng

Standardvärde: Nuvarande sidadress. Adressen för att skicka förfrågan.

username

Typ: Sträng

Används för att svara på användarnamn för HTTP-autentiseringsförfrågningar.

xhr

Typ: Funktion

Kräver att returnera ett XMLHttpRequest-objekt. Standard i IE är ActiveXObject och i andra fall XMLHttpRequest. Används för att skriva över eller tillhandahålla ett förbättrat XMLHttpRequest-objekt. Denna parameter var inte tillgänglig innan jQuery 1.3.

Kallbackefunktioner

Om du vill bearbeta data som $.ajax() returnerar, måste du använda kallbackefunktioner: beforeSend, error, dataFilter, success, complete.

beforeSend

Anropa denna funktion innan förfrågan skickas och skicka XMLHttpRequest som parameter.

error

Anropa denna funktion vid fel. Skicka XMLHttpRequest-objektet, en sträng som beskriver feltypen och ett undantagsobjekt (om det finns).

dataFilter

Anropa denna funktion efter att förfrågan har lyckats. Skicka tillbaka data och värdet för "dataType"-parametern. Och måste returnera nya data (kan vara bearbetade) till success-kallbackefunktionen.

success

Anropa denna funktion efter förfrågan. Skicka tillbaka data och en sträng som innehåller framgångscode.

complete

Anropa denna funktion efter att förfrågan är klar, oavsett om den är framgångsrik eller misslyckad. Skicka XMLHttpRequest-objektet och en sträng som innehåller framgångs- eller felkoder.

Datatyp

Funktionen $.ajax() är beroende av informationen från servern för att hantera returnerade data. Om servern rapporterar att returnerade data är XML, kan resultatet användas med vanliga XML-metoder eller jQuery:s selektorer. Om andra typer som HTML ses, behandlas data som text.

Genom dataType-valet kan du också specificera andra olika datahanteringsmetoder. Förutom ren XML kan du specificera html, json, jsonp, script eller text.

För text och xml-typ returnerades data utan bearbetning. Data överförs enkelt till success-kallbackefunktionen genom XMLHttpRequest:s responseText eller responseHTML-attribut.

Observera:Vi måste säkerställa att den MIME-typ som webbservern rapporterar matchar den dataType vi väljer. Till exempel, om XML, måste servern deklarera text/xml eller application/xml för att få konsistenta resultat.

Om specifikeras som html-typ, kommer alla inbäddade JavaScript att köras innan HTML returneras som en sträng. På samma sätt, om specifikeras script-typ, kommer serverns genererade JavaScript att köras först innan skriptet returneras som textdata.

Om json-typen anges, kommer det att tolka det insamlade data som ett JavaScript-objekt och returnera det byggda objektet som resultat. För att uppnå detta försöker det först använda JSON.parse(). Om webbläsaren inte stöder det, används en funktion för att bygga.

JSON-data är ett strukturerat dataformat som är mycket enkelt att解析a genom JavaScript. Om den datafil som innehåller data är placerad på en fjärrserver (dvs. olika domäner, dvs. korsdomänshämtning av data) måste jsonp-typen användas. Genom att använda denna typ skapas en frågesträngparametrar callback=?. Denna parameter läggs till i slutet av URL:en. Servern bör lägga till namnet på callback-funktionen innan JSON-data för att slutföra en giltig JSONP-fostran. Om du vill specificera namnet på callback-funktionen för att ersätta det standarda callback kan du sätta jsonp-parametern i $.ajax().

Observera:JSONP är en utökning av JSON-formatet. Det kräver vissa serverkod för att upptäcka och hantera frågesträngparametrar.

Om script eller jsonp-typen anges, används faktiskt <script>-taggen istället för XMLHttpRequest-objektet när data tas emot från servern. I detta fall returnerar inte $.ajax() ett XMLHttpRequest-objekt och överför inte heller händelsbehandlingsfunktioner, som beforeSend.

Skicka data till servern

Som standard använder Ajax-fostran GET-metoden. Om du vill använda POST-metoden kan du sätta type-parametervärdet. Detta alternativ påverkar också hur innehållet i data-alternativet skickas till servern.

data-alternativet kan innehålla en frågesträng, till exempel key1=value1&key2=value2, eller en mappning, till exempel {key1: 'value1', key2: 'value2'}. Om den senare formen används, kommer data att konverteras till en frågesträng vid sändning. Denna behandlingsprocess kan också undvikas genom att sätta processData-alternativet till false. Om vi vill skicka ett XML-objekt till servern kan detta inte vara lämpligt. Och i detta fall bör vi också ändra contentType-alternativets värde, använda andra lämpliga MIME-typer för att ersätta standarden application/x-www-form-urlencoded.

Avancerade alternativ

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 参考手册