XML DOM - XMLHttpRequest-objektet

XMLHttpRequest objekt

XMLHttpRequest-objektet gir full tilgang til HTTP-protokollen, inkludert evnen til å gjøre POST- og HEAD-forespørsler samt vanlige GET-forespørsler. XMLHttpRequest kan returnere svaret fra webserveren synkront eller asynkront, og kan returnere innhold som tekst eller i form av et DOM-dokument.

Selv om det heter XMLHttpRequest, er det ikke begrenset til å bruke det sammen med XML-dokumenter: Det kan motta dokumenter i hvilken som helst tekstform.

XMLHttpRequest-objektet er navngitt AJAX er en nøkkelfunksjon i arkitekturen til Web-applikasjoner.

nettleserstøtte

XMLHttpRequest får god støtte fra de fleste moderne nettlesere. Den eneste avhengigheten av nettleseren er opprettelsen av XMLHttpRequest-objektet. I IE 5 og IE 6 må spesifikke IE-konstruktører brukes, som ActiveXObject(). Som i XMLHttpRequest objekt som dette afsnit præsenterer.

W3C-standardisering

XMLHttpRequest-objektet er ikke standardiseret, men W3C har begyndt standardiseringsarbejdet, og indholdet af denne vejledning er baseret på standardiseringsarbejdets udkast.

Den nuværende XMLHttpRequest-implementering er meget ens. Men der er små forskelle i forhold til standarden. For eksempel kan en implementering returnere null, mens standarden kræver en tom streng, eller implementeringen kan sætte readyState til 3 uden at garantere, at alle svarets hoveder er tilgængelige.

Egenskab

readyState

HTTP-anmodningens tilstand. Når en XMLHttpRequest oprettes, starter værdien af denne egenskab fra 0, indtil den fulde HTTP-svar modtages, øges denne værdi til 4.

Hver af de 5 tilstande har en tilhørende uformel navn. Tabellen nedenfor viser tilstande, navne og betydninger:

Tilstand Navn Beskrivelse
0 Uninitialized Initialiseret tilstand. XMLHttpRequest-objektet er blevet oprettet eller genindstillet af abort() metoden.
1 Open open() metoden er blevet kaldt, men send() metoden er ikke blevet kaldt. Anmodningen er endnu ikke blevet sendt.
2 Sent Send() metoden er blevet kaldt, HTTP-anmodningen er blevet sendt til webserveren. Ingen respons er modtaget.
3 Receiving Alle svarets hoveder er blevet modtaget. Responskroppen begynder at modtages, men er endnu ikke færdig.
4 Loaded HTTP-svaret er fuldt modtaget.

Værdien af readyState vil ikke falde, medmindre abort() eller open() metoden kaldes under behandlingen af en anmodning. Hver gang værdien af denne egenskab øges, udløses onreadystatechange eventhandleren.

responseText

Indtil videre den del af svaret, der er modtaget af serveren (inklusive hoveder), eller hvis der endnu ikke er modtaget data, er en tom streng.

Hvis readyState er mindre end 3, er denne egenskab en tom streng. Når readyState er 3, returnerer denne egenskab den del af svaret, der allerede er modtaget. Hvis readyState er 4, gemmes den fulde responskrop i denne egenskab.

Hvis svaret indeholder en hovedkilde til den specificerede tegnkodning for responskroppen, brug denne kodning. Ellers antages det, at bruge Unicode UTF-8.

responseXML

Responsen til anmodningen, analyseret som XML og som Dokumentobjektreturnere.

status

returneret af serveren HTTP-statuskode, såsom 200 for succes og 404 for "Ikke Fundet"-fejl. Læsning af denne egenskab med readyState mindre end 3 vil forårsage en undtagelse.

statusText

Denne egenskab specificerer HTTP-forespørgselsstatuskoden ved navn i stedet for ved nummer. Det vil sige, når status er 200, er det "OK", og når status er 404, er det "Ikke Fundet". Som status-attributten kan læsning af denne egenskab med readyState mindre end 3 forårsage en undtagelse.

Eventhandler

onreadystatechange

Kaldes af en eventhandlerfunktion, hver gang readyState-attributten ændres. Når readyState er 3, kan den også kalde flere gange.

Metode

abort()

Annuller den aktuelle respons, luk forbindelsen og afslut alle uafsluttede netaktiviteter.

Denne metode nulstiller XMLHttpRequest-objektet til en readyState på 0 og annullerer alle uafsluttede netaktiviteter. For eksempel kan denne metode kaldes, hvis en forespørgsel har brugt for meget tid, og svaret ikke længere er nødvendigt.

getAllResponseHeaders()

Returner HTTP-svarshovede som uafhængige strenger.

Hvis readyState er mindre end 3, returnerer denne metode null. ellers returnerer den alle HTTP-svarshovede, der er sendt af serveren. Hovederne returneres som en enkelt streng, en hoved pr. linje. Hver linje adskilles af en linjeskiftstegn "\r\n".

getResponseHeader()

Returner værdien for den specificerede HTTP-svarshoved. Parametret er navnet på den HTTP-svarshoved, der skal returneres. Man kan bruge hvilken som helst skriftstørrelse til at specificere hovednavnet, og sammenligningen med svarhovedet er ikke følsom over for store og små bogstaver.

Værdien returneret af denne metode er værdien for den specificerede HTTP-svarshoved, hvis denne hoved ikke er modtaget eller hvis readyState er mindre end 3, er det en tom streng. Hvis flere hoveder med navnet modtages, bliver værdierne forbundet og returneret, adskilt af kommaer og mellemrum mellem værdierne for hver hoved.

open()

Initialiser HTTP-forespørgselsparametrene, såsom URL og HTTP-metode, men send ikke forespørgslen.

send()

Send HTTP-forespørgsel ved hjælp af parameterne overført til open() metoden samt den valgfri forespørgselshoved, der overføres til denne metode.

setRequestHeader()

Indstil eller tilføj en HTTP-forespørgsel til en åben men ikke sendt forespørgsel.

XMLHttpRequest.open()

Initialiser HTTP-anmodningsparametre

Syntaks

open(method, url, async, username, password)

Parametret method er HTTP-metoden, der bruges til anmodningen. Værdierne inkluderer GET, POST og HEAD.

Parametret url er anmodningens hovedindhold. De fleste browsere implementerer en same-origin-sikkerhedspolitik og kræver, at denne URL har samme vært og port som teksten, der indeholder scriptet.

Parametret async indikerer, at anmodningen skal udføres asynkront. Hvis denne parameter er false, er anmodningen synkron, og efterfølgende kald til send() blokerer, indtil svaret er fuldt modtaget. Hvis denne parameter er true eller undlades, er anmodningen asynkron, og det kræves normalt en onreadystatechange-hændelseshåndterer.

Parametrene username og password er valgfrie og giver autentificeringskvalifikationer for den nødvendige autorisering af url. Hvis de specificeres, vil de overskrive eventuelle kvalifikationer, der er specificeret i url selv.

Beskrivelse

Denne metode initialiserer anmodningsparametrene til brug med send()-metoden senere. Den sætter readyState til 1, sletter alle tidligere specificerede anmodningshoveder samt alle tidligere modtagne responshoveder, og sætter parameterne responseText, responseXML, status og statusText til deres standardværdier. Det er sikkert at kalde denne metode, når readyState er 0 (når XMLHttpRequest-objektet netop er oprettet eller abort()-metoden kaldes) samt når readyState er 4 (når svaret er modtaget). Når denne metode kaldes for nogen anden tilstand, bestemmer open()-metodens adfærd sig efter specificeret.

Besides at gemme de parametre, der bruges af send()-metoden, og at nulstille XMLHttpRequest-objektet til genbrug, udfører open()-metoden ingen andre handlinger. Det skal bemærkes, at når denne metode kaldes, åbner implementeringen normalt ikke en netforbindelse til webserveren.

XMLHttpRequest.send()

Send en HTTP-anmodning

Syntaks

send(body)

Hvis HTTP-metoden specificeret ved at kalde open() er POST eller PUT, specificerer body-parametret anmodningskroppen som en streng eller DokumentobjektHvis det ikke er nødvendigt, skal denne parameter være null. For alle andre metoder er denne parameter utilgængelig og skal være null (nogle implementeringer tillader ikke at undlade denne parameter).

Beskrivelse

Denne metode udløser en HTTP-forespørgsel. Hvis open() er blevet kaldt tidligere, eller mere specifikt, hvis readyState ikke er 1, kaster send() en undtagelse. Ellers sender den en HTTP-forespørgsel, der består af følgende dele:

  • HTTP-metoden, URL og autentificeringskvalifikationer, der blev specificeret ved tidligere kald til open() (hvis der er noget).
  • Forespørgselshovedet, der blev specificeret ved tidligere kald til setRequestHeader() (hvis der er noget).
  • Kommunikation til denne metode body Parameterer.

Når forespørgslen er blevet sendt, sætter send() readyState til 2 og udløser onreadystatechange eventhandleren.

Hvis parameteren async for den tidligere kaldede open() er false, blokerer denne metode og returnerer ikke, indtil readyState er 4 og serverens svar er fuldt modtaget. Ellers, hvis async parameteren er true, eller parameteren er udeladt, returnerer send() straks, og som det vil blive beskrevet senere, håndteres serverens svar i en baggrundsproces.

Hvis serverens respons indeholder en HTTP-omdirigering, følger send() metoden eller baggrundsproces automatisk omdirigeringen. Når alle HTTP-svarhoveder er modtaget, sætter send() eller baggrundsproces readyState til 3 og udløser onreadystatechange eventhandleren. Hvis svaret er længere, kan send() eller baggrundsproces udløse onreadystatechange eventhandleren i status 3: Dette kan bruges som en downloadprognostiker. Til sidst, når svaret er fuldt modtaget, sætter send() eller baggrundsproces readyState til 4 og udløser eventhandleren sidst gang.

XMLHttpRequest.setRequestHeader()

Syntaks

setRequestHeader(name, value)

Parameteren name er navnet på det hoved, der skal indstilles. Denne parameter bør ikke inkludere mellemrum, kolon eller linjeskift.

Parameteren value er værdien for hovedet. Denne parameter bør ikke inkludere linjeskift.

Beskrivelse

Metoden setRequestHeader() specificerer en HTTP-forespørgselshoved, som skal inkluderes i forespørgslen, der sendes ved hjælp af den efterfølgende send() kald. Denne metode kan kun kaldes, når readyState er 1, for eksempel efter at have kaldt open(), men før send() er kaldt.

Hvis en hovedet med specificeret navn allerede er blevet angivet, er den nye værdi for dette hoved: den tidligere specificerede værdi, plus komma, mellemrum og den værdi, der er angivet ved denne kald.

Hvis open() kaldet specificerer en autentificeringskvalifikation, sender XMLHttpRequest automatisk en passende Authorization forespørgselshoved. Men du kan bruge setRequestHeader() til at tilføje dette hoved. På samme måde, hvis webserveren allerede har gemt og overført en cookie, der er relateret til URL'en, der gives til open(), indeholder den passende Cookie- eller Cookie2-hoved også automatisk forespørgslen. Disse cookie'er kan tilføjes til hovedet ved at kalde setRequestHeader(). XMLHttpRequest kan også tilbyde en standardværdi for User-Agent-hovedet. Hvis det gør det, vil alle værdier, du specificerer for dette hoved, tilføjes til denne standardværdi.

Nogle forespørgselshoveder indstilles automatisk af XMLHttpRequest i stedet for ved denne metode for at overholde HTTP-protokollen. Dette inkluderer følgende og proxyrelaterede hoveder:

  • Host
  • Connection
  • Keep-Alive
  • Accept-charset
  • Accept-Encoding
  • If-Modified-Since
  • If-None-Match
  • If-Range
  • Range