jQuery ajax - metodo ajax()

Manuale di riferimento per jQuery Ajax

Esempio

Carica un pezzo di testo tramite AJAX:

Codice jQuery:}

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

Codice HTML:

<div id="myDiv"><h2>Lascia che AJAX cambi questo testo</h2></div>
<button id="b01" type="button">Cambia Contenuto</button>

Prova personalmente

Definizione e uso

Il metodo ajax() carica dati remoti tramite richieste HTTP.

Questo metodo è l'implementazione AJAX di basso livello di jQuery. Una versione più semplice e utilizzabile è $.get, $.post, ecc. $.ajax() restituisce l'oggetto XMLHttpRequest creato. Di solito non è necessario manipolare direttamente questa funzione, a meno che non si necessiti di opzioni non comuni per ottenere maggiore flessibilità.

Nel caso più semplice, $.ajax() può essere utilizzato senza alcun parametro.

Attenzione:Tutte le opzioni possono essere configurate globalmente utilizzando la funzione $.ajaxSetup().

Sintassi

jQuery.ajax([settings]
Parametri Descrizione
settings

Opzionale. Set di chiavi-valori utilizzato per configurare la richiesta Ajax.

Qualsiasi opzione può essere impostata come valore predefinito utilizzando $.ajaxSetup().

Parametri

options

Tipo: Oggetto

Opzionale. Impostazioni della richiesta Ajax. Tutte le opzioni sono opzionali.

async

Tipo: Booleano

Valore predefinito: true. Di default, tutte le richieste sono asincrone. Se si desidera inviare una richiesta sincrona, impostare questa opzione a false.

Attenzione, le richieste同步 bloccano il browser, altre operazioni dell'utente devono aspettare la completazione della richiesta.

beforeSend(XHR)

Tipo: Funzione

Funzione che può essere utilizzata prima di inviare la richiesta, come aggiungere intestazioni HTTP personalizzate.

L'oggetto XMLHttpRequest è l'unico parametro.

Questo è un evento Ajax. Se restituisce false, l'invio di questa richiesta Ajax può essere annullato.

cache

Tipo: Booleano

Valore predefinito: true, per dataType script e jsonp il valore predefinito è false. Impostando a false non verrà memorizzata questa pagina.

Nuove funzionalità di jQuery 1.2.

complete(XHR, TS)

Tipo: Funzione

Funzione di callback chiamata dopo il completamento della richiesta (chiamata sia dopo il successo che dopo il fallimento della richiesta).

Parametri: Oggetto XMLHttpRequest e una stringa che descrive il tipo di richiesta.

Questo è un evento Ajax.

contentType

Tipo: Stringa

Valore predefinito: "application/x-www-form-urlencoded". Tipo di codifica del contenuto inviato al server.

Valore predefinito adatto nella maggior parte dei casi. Se si passa esplicitamente un content-type a $.ajax(), esso verrà sicuramente inviato al server (anche se non ci sono dati da inviare).

context

Tipo: Oggetto

Questo oggetto viene utilizzato per impostare il contesto delle funzioni di callback relative a Ajax. Questo significa che il this all'interno della funzione di callback si riferisce a questo oggetto (se non viene impostato questo parametro, then this si riferisce ai parametri options passati durante la chiamata AJAX). Ad esempio, se si specifica un elemento DOM come parametro context, si imposta il contesto della funzione di callback di successo per questo elemento DOM.

Ecco come fare:

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

Tipo: Stringa

Dati inviati al server. Verranno automaticamente convertiti nel formato di stringa di richiesta. Verranno aggiunti alla fine dell'URL per le richieste GET. Consultare la descrizione delle opzioni processData per disabilitare questa conversione automatica. Deve essere in formato Key/Value. Se è un array, jQuery lo trasformerà automaticamente in valori corrispondenti allo stesso nome. Ad esempio, {foo: ["bar1", "bar2"]} viene trasformato in '&foo=bar1&foo=bar2'.

dataFilter

Tipo: Funzione

Funzione di pre-elaborazione dei dati originali restituiti da Ajax. Fornisce due parametri: data è i dati originali restituiti da Ajax, type è il parametro dataType fornito durante la chiamata a jQuery.ajax. Il valore restituito dalla funzione sarà ulteriormente elaborato da jQuery.

dataType

Tipo: Stringa

Il tipo di dati di ritorno atteso dal server. Se non specificato, jQuery determinerà automaticamente in base alle informazioni MIME HTTP del pacchetto HTTP, ad esempio, il tipo MIME XML viene riconosciuto come XML. In 1.4, JSON genererà un oggetto JavaScript, mentre script eseguirà questo script. Successivamente, i dati di ritorno del server saranno analizzati in base a questo valore e trasmessi alla funzione di callback. Valori disponibili:

  • "xml": restituisce un documento XML, trattabile con jQuery.
  • "html": restituisce informazioni HTML testuali; i tag script inclusi verranno eseguiti al momento dell'inserimento nel DOM.
  • "script": restituisce codice JavaScript puro. Non viene automaticamente cacheato i risultati. A meno che non sia impostato il parametro "cache". Attenzione: nelle richieste remote (non nello stesso dominio), tutte le richieste POST vengono trasformate in GET (poiché verrà utilizzato il tag script del DOM).
  • "json": restituisce dati JSON.
  • "jsonp": formato JSONP. Quando si chiama una funzione in formato JSONP, come "myurl?callback=?", jQuery sostituirà automaticamente ? con il nome della funzione corretto per eseguire la funzione di callback.
  • "text": restituisce una stringa di testo puro
error

Tipo: Funzione

Valore predefinito: automatico (xml o html). Chiamata quando la richiesta fallisce.

Ha tre parametri: oggetto XMLHttpRequest, messaggio di errore, (opzionale) oggetto eccezione catturato.

Se si verifica un errore, oltre a null, il messaggio di errore (secondo parametro) può essere "timeout", "error", "notmodified" e "parsererror".

Questo è un evento Ajax.

global

Tipo: Booleano

Determina se viene scatenato l'evento AJAX globale. Valore predefinito: true. Impostando false non verranno scatenati gli eventi AJAX globali, come ad esempio ajaxStart o ajaxStop possono essere utilizzati per controllare diversi eventi Ajax.

ifModified

Tipo: Booleano

Raccogliere nuovi dati solo quando i dati del server cambiano. Valore predefinito: false. Utilizza l'header HTTP Last-Modified per determinare. In jQuery 1.4, controlla anche l'"etag" specificato dal server per determinare che i dati non sono stati modificati.

jsonp

Tipo: Stringa

Riscrivi il nome della funzione di callback in una richiesta jsonp. Questo valore viene utilizzato per sostituire la parte "callback" dei parametri URL nelle richieste GET o POST di tipo "callback=?", ad esempio {jsonp:'onJsonPLoad'} causerà che "onJsonPLoad=?" venga trasmesso al server.

jsonpCallback

Tipo: Stringa

Specificare un nome di callback per la richiesta jsonp. Questo valore verrà utilizzato per sostituire il nome di funzione casuale generato automaticamente da jQuery. Questo viene principalmente utilizzato per far sì che jQuery generi nomi di funzione unici, rendendo più facile gestire le richieste e fornire funzioni di callback e gestione degli errori. Puoi anche specificare questo nome di callback per evitare che il browser cache la richiesta GET.

password

Tipo: Stringa

Utilizzato per rispondere a richieste di autenticazione HTTP per la password

processData

Tipo: Booleano

Valore predefinito: true. Di default, i dati trasmessi tramite l'opzione data, se sono un oggetto (tecnicamente, qualsiasi cosa non sia una stringa), vengono trasformati in una stringa query per abbinarsi al tipo di contenuto predefinito "application/x-www-form-urlencoded". Se si desidera inviare informazioni su un DOM o altri dati non desiderati per la trasformazione, impostare su false.

scriptCharset

Tipo: Stringa

Viene utilizzato solo quando il dataType della richiesta è "jsonp" o "script" e il tipo è "GET" per forzare la modifica del charset. Di solito viene utilizzato quando il contenuto di codifica locale e remoto è diverso.

success

Tipo: Funzione

Funzione di callback eseguita con successo la richiesta.

Parametri: dati restituiti dal server e trattati in base al parametro dataType; stringa che descrive lo stato.

Questo è un evento Ajax.

traditional

Tipo: Booleano

Se si desidera serializzare i dati in modo tradizionale, impostare su true. Si prega di consultare il metodo jQuery.param nella sezione strumenti.

timeout

Tipo: Numero

Imposta il tempo di scadenza della richiesta (millisecondi). Questa impostazione sovrascriverà la configurazione globale.

type

Tipo: Stringa

Valore predefinito: "GET")). Modalità di richiesta ("POST" o "GET"), predefinita a "GET". Attenzione: altri metodi di richiesta HTTP, come PUT e DELETE, possono essere utilizzati, ma sono supportati solo da parte dei browser.

url

Tipo: Stringa

Valore predefinito: indirizzo della pagina corrente. Indirizzo dell'indirizzo di invio della richiesta.

username

Tipo: Stringa

Utilizzato per rispondere a richieste di autenticazione HTTP per il nome utente.

xhr

Tipo: Funzione

È necessario restituire un oggetto XMLHttpRequest. Di default in IE è ActiveXObject mentre in altri casi è XMLHttpRequest. Utilizzato per sovrascrivere o fornire un oggetto XMLHttpRequest migliorato. Questo parametro non era disponibile prima della jQuery 1.3.

Callback function

Per elaborare i dati ricevuti da $.ajax(), è necessario utilizzare i callback: beforeSend, error, dataFilter, success, complete.

beforeSend

Chiamare questa funzione prima di inviare la richiesta e passare l'oggetto XMLHttpRequest come parametro.

error

Chiamare questa funzione quando la richiesta fallisce. Passare l'oggetto XMLHttpRequest, una stringa che descrive il tipo di errore e un oggetto di eccezione (se presente).

dataFilter

Chiamare questa funzione dopo il successo della richiesta. Passare i dati di ritorno e il valore del parametro dataType. E deve restituire i nuovi dati (che potrebbero essere elaborati) che vengono trasmessi al callback success.

success

Chiamare questa funzione dopo la richiesta. Passare i dati di ritorno e una stringa che contiene un codice di successo.

complete

Chiamare questa funzione dopo la completazione della richiesta, indipendentemente dal successo o dal fallimento. Passare l'oggetto XMLHttpRequest e una stringa che contiene un codice di successo o di errore.

Tipo di dati

La funzione $.ajax() dipende dalle informazioni fornite dal server per elaborare i dati di ritorno. Se il server riporta che i dati di ritorno sono XML, i risultati possono essere esaminati con metodi XML standard o con i selettori di jQuery. Se si vedono altri tipi, come HTML, i dati vengono trattati come testo.

Attraverso l'opzione dataType è possibile specificare diversi modi di elaborazione dei dati. Oltre a XML puro, è possibile specificare html, json, jsonp, script o text.

Tra cui i tipi text e xml, i dati restituiti non vengono elaborati. I dati vengono semplicemente trasmessi al callback success con l'attributo responseText o responseHTML di XMLHttpRequest.

Attenzione:Dobbiamo assicurarci che il tipo MIME riportato dal server web corrisponda al dataType scelto. Ad esempio, per XML, il server deve dichiarare text/xml o application/xml per ottenere risultati coerenti.

Se specificato come tipo html, qualsiasi JavaScript incorporato verrà eseguito prima che l'HTML venga restituito come stringa. Allo stesso modo, se specificato il tipo script, il JavaScript generato dal server verrà eseguito prima di restituire il script come dati di testo.

Se viene specificato come tipo json, i dati ricevuti vengono interpretati come un oggetto JavaScript e l'oggetto costruito viene restituito come risultato. Per raggiungere questo obiettivo, tenta prima di utilizzare JSON.parse(). Se il browser non supporta, utilizza una funzione per costruire.

I dati JSON sono una struttura dati strutturata che può essere facilmente解析ata con JavaScript. Se il file dei dati è conservato su un server remoto (domini diversi, ovvero dati获取越域), è necessario utilizzare il tipo jsonp. Utilizzando questo tipo, viene creato un parametro della stringa di query callback=? che viene aggiunto alla fine dell'URL della richiesta. Il server deve aggiungere il nome della funzione di callback prima dei dati JSON per completare una richiesta JSONP valida. Se si desidera specificare il nome del parametro della funzione di callback per sostituire il valore predefinito callback, è possibile impostare il parametro jsonp di $.ajax().

Attenzione:JSONP è un'estensione del formato JSON. Richiede alcune codice sul lato del server per rilevare e gestire i parametri della stringa di query.

Se è stato specificato lo script o il tipo jsonp, allora quando si ricevono dati dal server, viene utilizzato il tag <script> invece dell'oggetto XMLHttpRequest. In questo caso, $.ajax() non restituisce un oggetto XMLHttpRequest e non trasmette funzioni di gestione degli eventi, come beforeSend.

Inviare dati al server

Per impostazione predefinita, le richieste Ajax utilizzano il metodo GET. Per utilizzare il metodo POST, è possibile impostare il valore del parametro 'type'. Questa opzione influisce anche su come i contenuti dell'opzione 'data' vengono inviati al server.

L'opzione 'data' può contenere una stringa di query, ad esempio key1=value1&key2=value2, o una mappatura, ad esempio {key1: 'value1', key2: 'value2'}. Se viene utilizzata la seconda forma, i dati vengono convertiti in una stringa di query dal trasmettitore. Questo processo può essere evitato anche impostando l'opzione 'processData' su false. Se si desidera inviare un oggetto XML al server, questa elaborazione potrebbe non essere appropriata. Inoltre, in questo caso, dovremmo anche modificare il valore dell'opzione 'contentType' utilizzando altri tipi MIME appropriati rispetto al predefinito application/x-www-form-urlencoded.

Opzioni avanzate

L'opzione global è utilizzata per impedire la registrazione dei callback di risposta, come .ajaxSend, o ajaxError, e metodi simili. Questo è utile in alcuni casi, come quando vengono inviate richieste molto frequenti e brevi, quando è possibile disabilitare questa funzione in ajaxSend.

Se il server richiede autenticazione HTTP, è possibile impostare il nome utente e la password tramite le opzioni username e password.

Le richieste Ajax sono limitate nel tempo, quindi dopo che l'avviso di errore è stato catturato e gestito, può essere utilizzato per migliorare l'esperienza utente. Il parametro timeout di default viene solitamente mantenuto, o impostato globalmente tramite jQuery.ajaxSetup, raramente impostato per una richiesta specifica.

Per impostazione predefinita, la richiesta viene sempre inviata, ma il browser potrebbe recuperare i dati dal suo cache. Per impedire l'uso dei risultati del cache, è possibile impostare il parametro cache su false. Se si desidera che venga segnalato un errore quando i dati non sono stati modificati dall'ultima richiesta, è possibile impostare ifModified su true.

scriptCharset consente di impostare un set di caratteri specifico per la richiesta del tag <script>, utilizzato per script o dati simili a jsonp. Quando lo script e il set di caratteri della pagina sono diversi, questo è particolarmente utile.

La lettera A di Ajax sta per asynchronous, il che significa che tutte le operazioni sono eseguite in parallelo e non c'è una sequenza di completamento. Il parametro async di $.ajax() è sempre impostato su true, il che indica che il codice restante può essere eseguito dopo l'inizio della richiesta. Non si consiglia fortemente di impostare questa opzione su false, il che significa che tutte le richieste non saranno più asincrone, il che potrebbe anche bloccare il browser.

$.ajax restituisce l'oggetto XMLHttpRequest creato da essa. Di solito jQuery gestisce internamente e crea questo oggetto, ma l'utente può anche passare un oggetto xhr creato autonomamente tramite l'opzione xhr. L'oggetto restituito di solito viene scartato, ma fornisce un'interfaccia di basso livello per osservare e controllare la richiesta. Ad esempio, chiamare .abort() sull'oggetto può sospendere la richiesta prima che sia completata.

Manuale di riferimento per jQuery Ajax