XML DOM - Oggetto XMLHttpRequest

Oggetto XMLHttpRequest

L'oggetto XMLHttpRequest offre un accesso completo al protocollo HTTP, inclusa la capacità di fare richieste POST e HEAD e richieste GET ordinarie. XMLHttpRequest può restituire la risposta del server web in modo sincrono o asincrono e può restituire il contenuto come testo o come un documento DOM.

Nonostante il nome XMLHttpRequest, non è limitato all'uso con documenti XML: può ricevere qualsiasi tipo di documento di testo.

l'oggetto XMLHttpRequest è chiamato AJAX è una funzione chiave dell'architettura delle applicazioni web.

supporto del browser

XMLHttpRequest riceve un supporto abbastanza buono da parte di tutti i browser moderni. L'unica dipendenza del browser riguarda la creazione dell'oggetto XMLHttpRequest. In IE 5 e IE 6, è necessario utilizzare il costruttore specifico di IE ActiveXObject(). Come nel Oggetto XMLHttpRequest Descritto in questa sezione.

Standardizzazione W3C

L'oggetto XMLHttpRequest non è stato standardizzato, ma la W3C ha iniziato il lavoro di standardizzazione, e il contenuto di questa guida è basato sul lavoro di bozza di standardizzazione.

L'implementazione attuale di XMLHttpRequest è abbastanza coerente. Ma c'è una lieve differenza rispetto allo standard. Ad esempio, un'implementazione potrebbe restituire null, mentre lo standard richiede una stringa vuota, o un'implementazione potrebbe impostare readyState a 3 senza garantire che tutte le intestazioni di risposta siano disponibili.

Proprietà

readyState

Stato della richiesta HTTP. Quando un XMLHttpRequest viene creato per la prima volta, il valore di questa proprietà parte da 0 e aumenta fino a ricevere una risposta HTTP completa.

Ogni uno degli stati ha un nome informale associato. La tabella seguente elenca gli stati, i nomi e il loro significato:

Stato Nome Descrizione
0 Uninitialized Stato iniziale. L'oggetto XMLHttpRequest è stato creato o è stato ripristinato con il metodo abort().
1 Open Il metodo open() è stato chiamato, ma il metodo send() non è stato chiamato. La richiesta non è stata ancora inviata.
2 Sent Il metodo Send() è stato chiamato, la richiesta HTTP è stata inviata al server Web. Non è stata ricevuta alcuna risposta.
3 Receiving Tutte le intestazioni di risposta sono state ricevute. Il corpo della risposta è iniziato a riceversi ma non è ancora completo.
4 Loaded La risposta HTTP è stata completamente ricevuta.

Il valore di readyState non decresce, a meno che non venga chiamato il metodo abort() o open() durante il processo di elaborazione della richiesta. Ogni volta che il valore di questo attributo aumenta, viene scatenato l'handler dell'evento onreadystatechange.

responseText

Il corpo della risposta ricevuta fino ad ora dal server (escluso l'intestazione), o una stringa vuota se non è stata ricevuta ancora alcuna dati.

Se readyState è minore di 3, questo attributo è una stringa vuota. Quando readyState è 3, questo attributo restituisce la parte della risposta ricevuta fino ad ora. Se readyState è 4, questo attributo contiene il corpo della risposta completo.

Se la risposta contiene un'intestazione di codifica di caratteri specifica per il corpo della risposta, utilizza quella codifica. Altrimenti, si assume che venga utilizzato Unicode UTF-8.

responseXML

La risposta alla richiesta, analizzata come XML e utilizzata come Oggetto Documentrestituito.

status

restituito dal server Codice di stato HTTP, come 200 per indicare un successo, e 404 per indicare un errore "Not Found". La lettura di questo attributo quando readyState è minore di 3 provoca un'eccezione.

statusText

Questa proprietà specifica il codice di stato HTTP della richiesta utilizzando il nome invece del numero. Ad esempio, quando lo stato è 200, è "OK", e quando lo stato è 404, è "Not Found". Come l'attributo status, la lettura di questo attributo quando readyState è minore di 3 provoca un'eccezione.

Gestore degli eventi

onreadystatechange

La funzione di gestione degli eventi chiamata ogni volta che l'attributo readyState cambia. Quando readyState è 3, può anche essere chiamata più volte.

Metodo

abort()

Annulla la risposta corrente, chiude la connessione e termina qualsiasi attività di rete in sospeso.

Questo metodo riporta l'oggetto XMLHttpRequest a uno stato readyState di 0 e annulla tutte le attività di rete in sospeso. Ad esempio, se una richiesta è durata troppo a lungo e la risposta non è più necessaria, è possibile chiamare questo metodo.

getAllResponseHeaders()

Restituisce le intestazioni di risposta HTTP come stringhe non解析ate.

Se readyState è minore di 3, questo metodo restituisce null. Altrimenti, restituisce tutte le intestazioni di risposta HTTP inviate dal server. Le intestazioni vengono restituite come stringhe singole, una per riga. Ogni riga è separata da un carattere di newline "\r\n".

getResponseHeader()

Restituisce il valore dell'intestazione HTTP HTTP specificata. Il parametro è il nome dell'intestazione HTTP da restituire. È possibile specificare il nome dell'intestazione in qualsiasi maiuscolo o minuscolo, e la comparazione con l'intestazione di risposta non è sensibile alle maiuscole e minuscole.

Il valore di ritorno di questo metodo è il valore dell'intestazione HTTP HTTP specificata, se non è stata ricevuta questa intestazione o se readyState è minore di 3, è una stringa vuota. Se sono stati ricevuti più intestazioni con il nome specificato, i valori delle intestazioni vengono collegati e restituiti, separati da virgola e spazio tra i valori delle intestazioni.

open()

Inizializza i parametri della richiesta HTTP, come URL e metodo HTTP, ma non invia la richiesta.

send()

Invia una richiesta HTTP utilizzando i parametri passati al metodo open() e il corpo di richiesta opzionale passato a questo metodo.

setRequestHeader()

Imposta o aggiunge una richiesta HTTP a una richiesta aperta ma non inviata.

XMLHttpRequest.open()

Inizializzare i parametri della richiesta HTTP

Sintassi

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

Il parametro method è il metodo HTTP utilizzato per la richiesta. I valori includono GET, POST e HEAD.

Il parametro url è l'oggetto della richiesta. La maggior parte dei browser implementano una politica di sicurezza di origine e richiedono che questo URL abbia lo stesso nome host e porta del testo che contiene lo script.

Il parametro async indica che la richiesta dovrebbe essere eseguita asincronamente. Se questo parametro è false, la richiesta è sincrona e le chiamate successive a send() bloccano fino a quando la risposta non è completamente ricevuta. Se questo parametro è true o omesso, la richiesta è asincrona e di solito richiede un gestore di eventi onreadystatechange.

I parametri username e password sono opzionali e forniscono l'autenticazione necessaria per l'autorizzazione richiesto da url. Se specificati, sovrascrivono qualsiasi qualifica specificata nell'url.

Spiegazione

Questo metodo inizializza i parametri della richiesta per l'uso successivo del metodo send(). Imposta readyState a 1, elimina tutti gli header di richiesta specificati in precedenza e tutti gli header di risposta ricevuti in precedenza, e imposta i parametri responseText, responseXML, status e statusText ai loro valori predefiniti. È sicuro chiamare questo metodo quando readyState è 0 (quando l'oggetto XMLHttpRequest è stato creato o chiamato il metodo abort()) e quando readyState è 4 (dopo aver ricevuto la risposta). Quando viene chiamato per qualsiasi altro stato, il comportamento del metodo open() è determinato dalla specifica.

Oltre a salvare i parametri della richiesta per il metodo send() e a ripristinare l'oggetto XMLHttpRequest per un riutilizzo, il metodo open() non ha altri comportamenti. È importante notare che quando questo metodo viene chiamato, l'implementazione solitamente non apre una connessione di rete al server web.

XMLHttpRequest.send()

Inviare una richiesta HTTP

Sintassi

send(body)

Se il metodo HTTP specificato tramite la chiamata a open() è POST o PUT, il parametro body specifica il corpo della richiesta come stringa o Oggetto DocumentSe il corpo della richiesta non è necessario, questo parametro è null. Per qualsiasi altro metodo, questo parametro non è disponibile e dovrebbe essere null (alcune implementazioni non permettono di omettere questo parametro).

Spiegazione

Questo metodo invia una richiesta HTTP. Se non è stata chiamata precedentemente open(), o più specificamente, se lo stato readyState non è 1, send() lancia un'eccezione. Altrimenti, invia una richiesta HTTP che si compone dei seguenti elementi:

  • Il metodo HTTP, l'URL e le qualifiche di autenticazione specificati nella chiamata precedente a open() (se presenti).
  • L'intestazione di richiesta specificata nella chiamata precedente a setRequestHeader() (se presente).
  • Passato a questo metodo body Parametri

Una volta pubblicata la richiesta, send() imposta lo stato readyState a 2 e scatena l'handler dell'evento onreadystatechange.

Se il parametro async della chiamata precedente a open() è false, questo metodo blocca e non restituisce nulla, fino a quando lo stato readyState non è 4 e la risposta del server è stata completamente ricevuta. Altrimenti, se il parametro async è true, o se questo parametro è omesso, send() restituisce immediatamente e, come illustrato in seguito, la risposta del server viene elaborata in un thread in background.

Se il server risponde con una reindirizzamento HTTP, il metodo send() o il thread in background seguono automaticamente il reindirizzamento. Quando tutti gli intestazioni di risposta HTTP sono stati ricevuti, send() o il thread in background imposta lo stato readyState a 3 e scatena l'handler dell'evento onreadystatechange. Se la risposta è lunga, send() o il thread in background possono scatenare l'handler dell'evento onreadystatechange nello stato 3: questo può essere utilizzato come indicatore di progresso del download. Infine, quando la risposta è completa, send() o il thread in background imposta lo stato readyState a 4 e scatena per l'ultima volta l'handler dell'evento.

XMLHttpRequest.setRequestHeader()

Sintassi

setRequestHeader(name, value)

Il parametro name è il nome dell'intestazione da impostare. Questo parametro non dovrebbe includere spazi, due punti o newline.

Il parametro value è il valore dell'intestazione. Questo parametro non dovrebbe includere newline.

Spiegazione

Il metodo setRequestHeader() specifica un intestazione di richiesta HTTP, che dovrebbe essere inclusa nella richiesta pubblicata tramite chiamate successive a send(). Questo metodo può essere chiamato solo quando lo stato readyState è 1, ad esempio, dopo aver chiamato open(), ma prima di chiamare send().

Se è stato specificato un intestazione con nome specificato, il nuovo valore di questa intestazione è: il valore precedentemente specificato, più una virgola, uno spazio e il valore specificato da questa chiamata.

Se la chiamata open() specifica una qualifica di autenticazione, XMLHttpRequest invia automaticamente un appropriato header di richiesta Authorization. Tuttavia, puoi utilizzare setRequestHeader() per aggiungere questo header. Allo stesso modo, se il server web ha salvato e trasmesso un cookie associato all'URL passato a open(), il relativo header Cookie o Cookie2 viene automaticamente incluso nella richiesta. Puoi aggiungere questi cookie ai header chiamando setRequestHeader(). XMLHttpRequest può anche fornire un valore predefinito per l'header User-Agent. Se lo fa, qualsiasi valore specificato per questo header verrà aggiunto alla fine di questo valore predefinito.

Alcuni header di richiesta vengono impostati automaticamente da XMLHttpRequest invece che da questo metodo per conformarsi al protocollo HTTP. Questo include i seguenti header relativi agli agenti proxy:

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