jQuery ajax - ajax() metodi

jQuery Ajax 参考手册

Esimerkki

Lataa tekstikappale AJAX:n avulla:

jQuery-koodi:

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

HTML-koodi:

<div id="myDiv"><h2>Anna AJAX muuttaa tätä tekstiä</h2></div>
<button id="b01" type="button">Muuta sisältöä</button>

Kokeile itse

Määritelmä ja käyttö

ajax()-metodi ladataan HTTP-pyynnöllä etäistä tietoa.

Tämä on jQuery:n pohjainen AJAX-toteutus. Yksinkertainen ja helppokäyttöinen korkeampi toteutus on $.get, $.post jne. $.ajax() palauttaa luomansa XMLHttpRequest-objektin. Useimmissa tapauksissa sinun ei tarvitse suoraan käyttää tätä funktiota, ellei tarvitse käyttää harvinaisia asetuksia saadaksesi enemmän joustavuutta.

Yksinkertaisimmassa tapauksessa $.ajax() voidaan käyttää ilman minkäänlaisia parametreja.

Huomioitavaa:Kaikki asetukset voidaan asettaa globaalisti $.ajaxSetup() -funktiolla.

Syntaksi

jQuery.ajax([settings]
Parametrit Kuvaus
settings

Valinnainen. Asetetaan Ajax-pyynnön konfiguraation avain-arvo-kerros.

Voit asettaa kaikki asetukset oletusarvoiksi $.ajaxSetup() -funktion avulla.

Parametrit

options

Tyyppi: Object

Valinnainen. AJAX-pyynnön asetukset. Kaikki asetukset ovat valinnaisia.

async

Tyyppi: Boolean

Oletusarvo: true. Oletusasetuksissa kaikki pyynnöt ovat asynkronisia. Jos haluat lähettää synkronisen pyynnön, aseta tämä asetus false.

Huomaa, että synkroniset pyynnöt lukitsevat selaimen, ja käyttäjän muut toiminnat on odotettava pyynnön valmistumista.

beforeSend(XHR)

Tyyppi: Function

Voit muokata XMLHttpRequest-objektia ennen pyynnön lähettämistä, esimerkiksi lisäämällä mukautetut HTTP-otsikot.

XMLHttpRequest-objekti on ainoa parametri.

Tämä on Ajax-tapahtuma. Jos palautat false, voit peruuttaa tämän ajastuksen.

välimuisto

Tyyppi: Boolean

Oletusarvo: true, dataType script ja jsonp arvojen oletus on false. Asettaessa false, sivu ei tallenneta välimuistiin.

jQuery 1.2 uudet toiminnot.

complete(XHR, TS)

Tyyppi: Function

Paluutoiminto, joka kutsutaan pyynnön suoritettua (kutsun menestyksen tai epäonnistumisen jälkeen).

Parametrit: XMLHttpRequest-objekti ja kuvaileva merkkijono, joka kuvaa pyyntötyyppiä.

Tämä on Ajax-tapahtuma.

contentType

Tyyppi: String

Oletusarvo: "application/x-www-form-urlencoded". Tietojen lähettäminen palvelimelle sisältökoodauksen tyyppi.

Oletusarvo sopii useimpiin tilanteisiin. Jos oletetaan, että olet nimenomaisesti määrittänyt content-type arvon $.ajax():lle, niin se lähetetään varmasti palvelimelle (vaikka mitään tietoja ei lähetetä).

context

Tyyppi: Object

Tämä objekti käytetään asettamaan Ajaxin liittyvät paluutoiminnot kontekstiin. Tämä tarkoittaa, että asetetaan, että paluutoiminnot sisällävät this-kohdistuksen tähän objektiin (jos tätä parametria ei aseteta, then this viittaa kutsun aikana tarjoamiin options-parametreihin). Esimerkiksi, jos määrität DOM-elementin kontekstiparametrina, niin tämä asettaa success-paluutoiminnon kontekstin tähän DOM-elementtiin.

Tässä tapauksessa:

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

Tyyppi: String

Lähetettävä tieto palvelimelle. Tämä muunnetaan automaattisesti pyyntömerkkijonoksi. GET-pyynnöissä tämä lisätään URL:n perään. Tarkista processData-asetuksen selitykset estääksesi tämän automaattisen muuntamisen. Tiedot on annettava Key/Value- muodossa. Jos tiedot ovat taulukko, jQuery muuntaa ne automaattisesti saman nimisiksi eri arvoille. Esimerkiksi {foo:["bar1", "bar2"]} muunnetaan '&foo=bar1&foo=bar2'.

dataFilter

Tyyppi: Function

Funktiota, joka käsittelee Ajax-vastauksen alkuperäistä dataa. Tarjoaa data ja type kaksi parametria: data on Ajax-vastauksen alkuperäinen data, ja type on tarjoama dataType parametri jQuery.ajax-kutsussa. Funktiosta palautettu arvo käsitellään edelleen jQuery:n toimesta.

dataType

Tyyppi: String

Odotetaan palvelimen palauttaman datan tyyppiä. Jos sitä ei määritellä, jQuery arvioi automaattisesti HTTP-paketin MIME-tiedot älykkäästi, esimerkiksi XML MIME-tyyppiä tunnistetaan XML:ksi. Versiossa 1.4 JSON luo JavaScript-objektin, ja script suorittaa tämän skriptin. Sitten palvelimen palauttama tieto käsitellään tämän arvon perusteella ja välitetään takaisin kutsuun. Mahdolliset arvot:

  • "xml": palauta XML-dokumentti, jota jQuery voi käsitellä.
  • "html": palauta puhtaa HTML-tietoa; sisältävät script-tikkit suoritetaan, kun ne lisätään DOMiin.
  • "script": palauta puhtaa JavaScript-koodia. Ei varastoida tulosta automaattisesti. Ellei aseteta "cache"-parametria. Huomautus: etäpyynnöissä (ei samassa域), kaikki POST-pyynnöt muunnetaan GET-pyynnöiksi (koska käytetään DOM:n script-tikittä).
  • "json": palauta JSON-data.
  • "jsonp": JSONP-muoto. Kun kutsutaan funktiota JSONP-muodossa, kuten "myurl?callback=?", jQuery korvaa ? oikealla funkti nimellä suorittaakseen paluutoiminnon.
  • "text": palauta puhtaa tekstijonoa
error

Tyyppi: Function

Oletusarvo: automaattinen arviointi (xml tai html). Kutsu tätä funktiota, jos pyyntö epäonnistuu.

On olemassa kolme parametria: XMLHttpRequest-objekti, virheilmoitus, (valinnainen) otettu vastaan poikkeusobjekti.

Jos tapahtuu virhe, virheilmoitus (toinen parametri) voi olla paitsi null myös "timeout", "error", "notmodified" ja "parsererror".

Tämä on Ajax-tapahtuma.

global

Tyyppi: Boolean

Onko globaali AJAX-tapahtuma käynnistetty. Oletusarvo: true. Aseta false estääksesi globaalin AJAX-tapahtuman käynnistämisen, kuten ajaxStart tai ajaxStop voidaan käyttää eri AJAX-tapahtumien hallintaan.

ifModified

Tyyppi: Boolean

Hanki uudet tiedot vain, jos palvelimen data muuttuu. Oletusarvo: false. Käytä HTTP-pakettia Last-Modified-otsikkoa arvioidaksesi. jQuery 1.4:ssä se tarkistaa myös palvelimen määrittämän 'etag'-arvon varmistaakseen, ettei dataa ole muutettu.

jsonp

Tyyppi: String

Muokkaa paluutoiminnon nimeä jsonp-pyynnössä. Tämä arvo korvaa "callback"-osion URL-parametrissa "callback=?"-muodossa, kuten {jsonp:'onJsonPLoad'} johtaa "onJsonPLoad=?"-pyynnön lähettämiseen palvelimelle.

jsonpCallback

Tyyppi: String

Määritä jsonp-pyynnölle paluutoiminnon nimi. Tämä arvo korvaa jQuery:n automaattisesti luomion satunnaisen funktion nimen. Tämä auttaa jQuery:ää luomaan ainutlaatuisia funktionimeitä, mikä helpottaa pyyntöjen hallintaa ja mahdollistaa paluutoimintojen ja virheenkäsittelyn tarjoamisen. Voit myös määrittää paluutoiminnon nimen, jos haluat, että selain tallentaa GET-pyynnön.

password

Tyyppi: String

Salasana, joka vastaa HTTP-sähköpostin todennuspyyntöä.

processData

Tyyppi: Boolean

Oletusarvo: true. Oletusarvoisesti data-valitsimen kautta toimitetut tiedot, jos ne ovat objekteja (teknisesti sanottuna, ei merkkijonoja), käsitellään ja muunnetaan kyselymerkkijonoksi, jotta ne sopivat oletusarvoiseen sisällön tyyppiin "application/x-www-form-urlencoded". Jos haluat lähettää DOM-puun tietoja tai muita tietoja, joita ei haluta muuntaa, aseta arvo false.

scriptCharset

Tyyppi: String

Käytetään vain, kun dataType on "jsonp" tai "script" ja type on "GET", ja pakotetaan charset-muutoksen suorittaminen. Käytetään yleensä vain, kun paikallinen ja etäisyydellä oleva sisällön koodaus eroaa toisistaan.

success

Tyyppi: Function

Paluutoiminto pyynnön onnistuttua.

Parametrit: palvelimen palauttamat ja dataType-parametrin mukaan käsitellyt tiedot; tilan kuvaava merkkijono.

Tämä on Ajax-tapahtuma.

traditional

Tyyppi: Boolean

Jos haluat käyttää perinteistä tietojen sarjautumistapaa, aseta arvo true. Katso jQuery.param-metodi työkaluissa.

timeout

Tyyppi: Number

Aseta pyynnön aikakatkaisu (millisekunnit). Tämä asetus korvaa globaalin asetuksen.

type

Tyyppi: String

Oletusarvo: "GET" (hakutapa). Määritä pyyntömenetelmä ("POST" tai "GET"), oletusarvo on "GET". Huomaa: muut HTTP-pyyntömenetelmät, kuten PUT ja DELETE, voidaan käyttää, mutta ne tukevat vain osaa selaimista.

url

Tyyppi: String

Oletusarvo: nykyinen sivun osoite. Lähetettävän pyynnön osoite.

username

Tyyppi: String

Käyttäjätunnus, joka vastaa HTTP-sähköpostin todennuspyyntöä.

xhr

Tyyppi: Function

Palautettava XMLHttpRequest-objekti. Oletusarvoisesti IE:ssä se on ActiveXObject, muissa tapauksissa XMLHttpRequest. Käytetään XMLHttpRequest-objektin uudelleenkirjoittamiseen tai laajentamiseen.

Paluutoiminnot

Jos haluat käsitellä $.ajax() -funktioon saadut tiedot, sinun täytyy käyttää paluutoimintoja: beforeSend, error, dataFilter, success, complete.

beforeSend

Kutsu tämä ennen pyynnön lähettämistä ja lisää XMLHttpRequest.

error

Kutsu tämä, kun pyyntö epäonnistuu. Lisää XMLHttpRequest-objekti, merkkijono, joka kuvaa virheen tyyppiä, sekä poikkeusobjekti (jos on olemassa).

dataFilter

Kutsu tämä, kun pyyntö on onnistunut. Lisää palautetut tiedot sekä "dataType"-parametrin arvo. Palauta uudet tiedot (mahdollisesti käsitellyt) success-kutsun takaisin.

success

Kutsu tämä, kun pyyntö on suoritettu. Lisää palautetut tiedot sekä merkkijono, joka sisältää onnistumiskoodin.

complete

Kutsu tämä funktio, kun pyyntö on valmis, riippumatta siitä onnistui se vai ei. Lisää XMLHttpRequest-objekti sekä merkkijono, joka sisältää onnistumiskoodin tai virheen.

Datan tyyppi

jQuery:n $.ajax()-funktio riippuu palvelimen tarjoamista tiedoista palautetun datan käsittelyssä. Jos palvelin ilmoittaa, että palautetut tiedot ovat XML:ää, tulokset voidaan käyttää tavallisten XML-metodien tai jQueryn valitsimien avulla. Jos näkyy muita tyyppjä, kuten HTML, tiedot käsitellään tekstimuodossa.

dataType-valinnolla voidaan määrittää muita erilaisia datankäsittelytapoja. Paitsi puhdasta XML:ää, voidaan määrittää myös html, json, jsonp, script tai text.

Teksti- ja xml-tyypit palauttavat tiedot eivät käsitellä dataa. Tiedot siirretään yksinkertaisesti XMLHttpRequest:n responseText- tai responseHTML-ominaisuuden avulla success-kutsun takaisin.

Huomioitavaa:Meidän täytyy varmistaa, että verkkosivustoverkoston raportoima MIME-tyyppi vastaa valitsemaamme dataType:ta. Esimerkiksi, jos XML, palvelimen täytyy ilmoittaa text/xml tai application/xml saadakseen yhtenevät tulokset.

Jos määritetty html-tyypiksi, kaikki sisäänrakennettu JavaScript suoritetaan ennen kuin HTML palautetaan merkkijonona. Samoin, jos määritetty script-tyypiksi, palvelin generoima JavaScript suoritetaan ensin, ja sitten skripti palautetaan tekstidataana.

Jos määritetään json-tyyppiksi, niin saadut tiedot käsitellään JavaScript-objektina, ja rakennettu objekti palautetaan tuloksena. Tämä tavoite saavutetaan ensin yritettämällä JSON.parse(). Jos selain ei tue sitä, käytetään funktiota rakentamaan.

JSON-tiedot ovat strukturoituja tietoja, joita voidaan helposti解析oida JavaScriptillä. Jos saadut tietojen tiedostot sijaitsevat etäpalvelimella (erillinen verkkotunnus, eli tietojen saaminen eri verkkotunnuksesta), tarvitaan jsonp-tyyppiä. Tässä tapauksessa luodaan haetun merkkijonon parametri callback=?, joka lisätään pyynnön URL:n perään. Palvelimen tulisi lisätä paluufunktion nimi JSON-tietojen eteen, jotta voidaan suorittaa kelvollinen JSONP-pyyntö. Jos halutaan määrittää paluufunktion parametrin nimi korvaamaan oletusarvoinen callback, voidaan asettaa $.ajax() -parametrin jsonp.

Huomioitavaa:JSONP on JSON-muodon laajennus. Se vaatii joitakin palvelimella olevia koodia, jotka tarkistavat ja käsittelevät haetun merkkijonon parametreja.

Jos on määritetty script tai jsonp-tyyppi, niin kun vastaanotetaan tietoja palvelimelta, käytetään todellisuudessa <script>-elementtiä eikä XMLHttpRequest-objektia. Tässä tapauksessa $.ajax() ei enää palauta XMLHttpRequest-objektia, eikä se edes välitä tapahtumankäsittelijöitä, kuten beforeSend.

Lähetä tietoja palvelimelle

Oletusarvoisesti Ajax-pyynnöt käyttävät GET-metodia. Jos haluamme käyttää POST-metodia, voimme asettaa type-parametrin arvon. Tämä vaihtoehto vaikuttaa myös siihen, miten data-vaihtoehtoon sisältyvät tiedot lähetetään palvelimelle.

data-vaihtoehto voi sisältää sekä haetun merkkijonon, kuten key1=value1&key2=value2, että mappauksen, kuten {key1: 'value1', key2: 'value2'}. Jos käytetään jälkimmäistä muotoa, tietoja muunnetaan haetun merkkijonoksi lähettäessä. Tämä käsittelyprosessi voidaan välttää asettamalla processData- vaihtoehto arvoon false. Jos haluamme lähettää XML-objektin palvelimelle, tämä käsittely voi olla sopimatonta, ja tässä tapauksessa meidän tulisi myös muuttaa contentType-vaihtoehdon arvoa, korvaamalla oletusarvoinen MIME-tyyppi muulla sopivalla MIME-tyypillä, kuten application/x-www-form-urlencoded.

Advanced options

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