jQuery ajax - ajax() metoden

jQuery Ajax 参考手册

Eksempel

Indlæs et stykke tekst med AJAX:

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() 可以不带任何参数直接使用。

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

语法

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

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

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

参数

options

Type: Object

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

async

Type: Boolesk

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

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

beforeSend(XHR)

Type: Funktion

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

XMLHttpRequest 对象是唯一的参数。

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

cache

Type: Boolesk

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

jQuery 1.2 新功能。

complete(XHR, TS)

Type: Funktion

Callback-funktion, der kaldes efter afslutningen af forespørgslen (kaldes efter succes eller fejl).

Parametre: XMLHttpRequest-objektet og en streng, der beskriver forespørgselstypen.

Dette er en Ajax-hændelse.

contentType

Type: Streng

Standardværdi: "application/x-www-form-urlencoded". Indholdscodningstypen, der bruges til at sende information til serveren.

Standardværdien er egnet til de fleste situationer. Hvis du specifikt leverer en content-type til $.ajax(), vil den sendes til serveren (selv hvis der ikke er data at sende).

context

Type: Object

Dette objekt bruges til at indstille konteksten for Ajax-relaterede callback-funktioner. Det vil sige, at det lader callback-funktionen pege på dette objekt (hvis parameteren ikke defineres, vil this pege på options-parametret, der blev overført ved denne AJAX-anmodning). For eksempel, hvis en DOM-element specificeres som kontekstparameter, sættes succes callback-funktionens kontekst til dette DOM-element.

Som dette:

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

Type: Streng

Data sendt til serveren. Konverteres automatisk til forespørgselssnitformat. Tilføjes i GET-forespørgsler til URL'en. Se beskrivelsen af processData-indstillingen for at forbyde denne automatiske konvertering. Skal være i Key/Value-format. Hvis det er en array, vil jQuery automatisk tildele samme navn til forskellige værdier. Som {foo:["bar1", "bar2"]} konverteres til '&foo=bar1&foo=bar2'.

dataFilter

Type: Funktion

Funktion til præbehandling af det rå data, der returneres af Ajax. Tilbyder data og type to parametre: data er det rå data, der returneres af Ajax, og type er dataType-parametret, der leveres ved jQuery.ajax. Værdien, der returneres af funktionen, vil blive yderligere behandlet af jQuery.

dataType

Type: Streng

Forventer den datatyp, som serveren returnerer. Hvis den ikke specificeres, vil jQuery automatisk vurdere det intelligente baseret på HTTP-pakken MIME-info, f.eks. XML MIME-typen identificeres som XML. I version 1.4 vil JSON generere en JavaScript-objekt, mens script vil udføre denne skript. Derefter vil serverens returnerede data efterfølgende parses og overføres til callback-funktionen. Tilgængelige værdier:

  • "xml": Returnerer XML-dokument, som jQuery kan håndtere.
  • "html": Returnerer ren tekst HTML-information; indeholdte script-tags udføres ved indsatning i DOM.
  • "script": Returnerer ren tekst JavaScript-kode. Resultaterne gemmes ikke automatisk. Medmindre "cache"-parametret er sat. Bemærk: Ved fjernanmodninger (ikke på samme domæne), konverteres alle POST-anmodninger til GET-anmodninger. (Fordi DOM's script-tag bruges til at indlæse.)
  • "json": Returnerer JSON-data.
  • "jsonp": JSONP-format. Når der bruges JSONP-format til at kalde funktionen, som "myurl?callback=?", vil jQuery automatisk erstatte ? med det korrekte funktionnavn for at udføre callback-funktionen.
  • "text": Returnerer ren tekststreng
error

Type: Funktion

Standardværdi: automatisk afgørelse (xml eller html). Kald denne funktion, hvis anmodningen fejler.

Der er tre parametre: XMLHttpRequest-objektet, fejlmeddelelsen, (valgfrit) den fangete undtagelse.

Hvis der opstår en fejl, kan fejlmeddelelsen (anden parameter) være "null", "timeout", "error", "notmodified" og "parsererror".

Dette er en Ajax-hændelse.

global

Type: Boolesk

Om den globale AJAX-tilsagn skal udløses. Standardværdi: true. Sæt til false for ikke at udløse globale AJAX-tilsagn, såsom ajaxStart eller ajaxStop kan bruges til at kontrollere forskellige AJAX-tilsagn.

ifModified

Type: Boolesk

Indhent nye data kun, når serverdata ændres. Standardværdi: false. Brug HTTP-pakken Last-Modified-hovedinformation til at vurdere. I jQuery 1.4 kontrolleres det også, om serveren specificerer 'etag', for at bestemme, om dataene ikke er blevet ændret.

jsonp

Type: Streng

Omskriv navnet på callback-funktionen i en jsonp-anmodning. Denne værdi bruges til at erstatte "callback"-delen i URL-parametrene i GET- eller POST-anmodninger som "callback=?", f.eks. {jsonp:'onJsonPLoad'} vil føre til, at "onJsonPLoad=?" sendes til serveren.

jsonpCallback

Type: Streng

Angiv en callback-funktion til jsonp-anmodninger. Denne værdi bruges til at erstatte jQuery's automatisk genererede tilfældige funktionnavn. Dette bruges primært til at lade jQuery generere unikke funktionnavne, hvilket gør det lettere at administrere anmodninger og lettere at levere callback-funktioner og fejlhåndtering. Du kan også specificere dette callback-funktionnavn, når du vil lade browseren cache GET-anmodninger.

password

Type: Streng

Bruges til at svare på HTTP-adgangsautentificeringsforespørgsler adgangskode

processData

Type: Boolesk

Standardværdi: true. Som standard konverteres data, der sendes via data-indstillingen, hvis det er et objekt (teknisk set ikke en streng), til en forespørgselssogningsstreng for at passe til standardindholdstypen "application/x-www-form-urlencoded". Hvis du vil sende DOM-træinformation eller anden information, du ikke ønsker at konvertere, sæt det til false.

scriptCharset

Type: Streng

Kun når dataType for anmodningen er "jsonp" eller "script", og type er "GET", bruges det til at tvunget ændre charset. Bruges normalt kun, når indholdskodingen er forskellig mellem lokalt og eksternt indhold.

success

Type: Funktion

Callback-funktion efter succesfuld anmodning.

Parameter: Data, der returneres af serveren og behandles efter dataType-parametret; en streng, der beskriver tilstanden.

Dette er en Ajax-hændelse.

traditional

Type: Boolesk

Hvis du vil bruge en traditionel måde til at sekventere data, så sæt det til true. Se værktøjskassen under jQuery.param-metoden.

timeout

Type: Tal

Indstil anmodningstidsudløbstid (millisekunder). Denne indstilling vil overskrive den globale indstilling.

type

Type: Streng

Standardværdi: "GET")). Anmodningsmetode ("POST" eller "GET"), standard er "GET". Bemærk: Andre HTTP-anmodningsmetoder som PUT og DELETE kan også bruges, men kun delvis understøttet af nogle browsere.

url

Type: Streng

Standardværdi: Nuværende sideadresse. Adressen, hvor anmodningen sendes.

username

Type: Streng

Bruges til at svare på HTTP-adgangsautentificeringsforespørgsler brugernavn.

xhr

Type: Funktion

Der skal returneres et XMLHttpRequest-objekt. Standard i IE er ActiveXObject, mens det i andre tilfælde er XMLHttpRequest. Bruges til at overskrive eller levere en forbedret XMLHttpRequest-objekt. Denne parameter var ikke tilgængelig før jQuery 1.3.

Kaldfunktioner

Hvis man skal behandle dataene, som $.ajax() modtager, skal man bruge kaldfunktioner: beforeSend, error, dataFilter, success, complete.

beforeSend

Kaldes før afsendelse af forespørgslen og indsender et XMLHttpRequest som parameter.

error

Kaldes, når forespørgslen fejler. Indsender XMLHttpRequest-objektet, en streng, der beskriver fejltypen, samt et undtagelsesobjekt (hvis der er et)

dataFilter

Kaldes efter succes. Indsender de returnerede data samt værdien af "dataType"-parametret. Og det er nødvendigt at returnere nye data (muligvis behandlede) til success-kaldfunktionen.

success

Kaldes efter forespørgslen. Indsender dataene efter returnering samt en streng, der indeholder succeskoden.

complete

Kald denne funktion efterfulgt af en succes eller fejl, uanset om det lykkes eller fejler. Indsend XMLHttpRequest-objektet samt en streng, der indeholder succes- eller fejlkoder.

Data-type

Functionen $.ajax() afhænger af informationen, som serveren leverer, for at håndtere de returnerede data. Hvis serveren rapporterer, at dataene er XML, kan resultaterne bruges med almindelige XML-metoder eller jQuery-søgere. Hvis andre typer ses, såsom HTML, behandles dataene som tekst.

Med dataType-indstillingen kan man også specificere andre forskellige datahåndteringsmetoder. Blandt andet kan man specificere html, json, jsonp, script eller text.

For text- og xml-typer behandles dataene ikke. Dataene overføres simpelt hen til success-kaldfunktionen ved hjælp af XMLHttpRequest's responseText- eller responseHTML-ejenskaber.

Bemærk:Vi skal sikre os, at den MIME-type, som webserveren rapporterer, matcher den dataType, vi har valgt. For eksempel skal serveren erklære text/xml eller application/xml for XML for at opnå ens resultater.

Hvis angivet som html-type, vil alt indlejret JavaScript blive udført, før HTML returneres som en streng. På samme måde vil servergenereret JavaScript blive udført først, hvis script-type er angivet, og derefter returneres skriptet som tekstdata.

Hvis json-typen er specificeret, vil de indhentede data parses som et JavaScript-objekt, og det opbyggede objekt returneres som resultat. For at opnå dette forsøger det først at bruge JSON.parse(). Hvis browseren ikke understøtter det, bruges en funktion til at bygge det.

JSON-data er en struktureret dataform, der kan parses meget nemt med JavaScript. Hvis datafilen findes på en ekstern server (forskellige domæner, også kendt som cross-domain datahentning), skal jsonp-typen bruges. Ved brug af denne type oprettes en forespørgselstingstekstparameter callback=? og tilføjes til forespørgsels-URL'en. Serveren skal tilføje navnet på callback-funktionen til JSON-dataene for at fuldføre en gyldig JSONP-forespørgsel. Hvis det er nødvendigt at specificere navnet på callback-funktionens parameter for at erstatte standarden callback, kan dette gøres ved at indstille jsonp-tilvalget i $.ajax().

Bemærk:JSONP er en udvidelse af JSON-formatet. Det kræver nogle server-side kode til at detektere og håndtere forespørgselstingstekstparametre.

Hvis script- eller jsonp-typen er specificeret, bruges det faktisk <script>-tagget i stedet for XMLHttpRequest-objektet, når data modtages fra serveren. I dette tilfælde returnerer $.ajax() ikke længere et XMLHttpRequest-objekt, og heller ikke eventhåndteringsfunktioner som beforeSend.

Send data til serveren

Som standard bruger Ajax-forespørgsler GET-metoden. Hvis POST-metoden skal bruges, kan type-tilvalget indstilles. Dette tilvalg påvirker også, hvordan indholdet i data-tilvalget sendes til serveren.

data-tilvalget kan enten indeholde en forespørgselstingstekst, såsom key1=value1&key2=value2, eller en mappe, såsom {key1: 'value1', key2: 'value2'}. Hvis den sidste form bruges, vil dataene blive konverteret til en forespørgselstingstekst, når de sendes fra afsenderen. Denne behandlingsproces kan undgås ved at sætte processData-tilvalget til false. Hvis vi ønsker at sende et XML-objekt til serveren, kan denne behandling muligvis ikke være passende, og i dette tilfælde skal contentType-tilvalget også ændres til en anden passende MIME-type for at erstatte standarden application/x-www-form-urlencoded.

Avancerede indstillinger

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