Metoda jQuery ajax - ajax()

Podręcznik referencyjny jQuery Ajax

Przykład

Załadowanie fragmentu tekstu za pomocą AJAX:

Kod jQuery:}

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

Kod HTML:

<div id="myDiv"><h2>Chcę, aby AJAX zmienił ten tekst</h2></div>
<button id="b01" type="button">Zmień treść</button>

Spróbuj sam

Definicja i użycie

Metoda ajax() ładuje zdalne dane za pomocą żądania HTTP.

To jest metoda jQuery do wewnętrznego realizowania AJAX. Prosta i łatwa w użyciu wyższa warstwa realizacji to $.get, $.post itp. Funkcja $.ajax() zwraca utworzony obiekt XMLHttpRequest. W większości przypadków nie musisz bezpośrednio obsługiwać tej funkcji, chyba że potrzebujesz obsługi rzadko używanych opcji, aby uzyskać więcej elastyczności.

W najprostszym przypadku, $.ajax() można używać bez żadnych parametrów.

Uwaga:Wszystkie opcje można globalnie ustawić za pomocą funkcji $.ajaxSetup().

Gramatyka

jQuery.ajax([settings]
Parametry Opis
settings

Opcjonalne. Zestaw klucz-wartość do konfiguracji żądania AJAX.

Można ustawić domyślne wartości dla dowolnych opcji za pomocą $.ajaxSetup().

Parametry

options

Typ: Obiekt

Opcjonalne. Ustawienia żądania AJAX. Wszystkie opcje są opcjonalne.

async

Typ: Logika

Domyślna wartość: true. W domyślnych ustawieniach wszystkie żądania są asynchroniczne. Jeśli需要发送同步请求，请将此选项设置为 false.

Uwaga, żądania synchroniczne zablokują przeglądarkę, inne operacje użytkownika muszą czekać na zakończenie żądania.

beforeSend(XHR)

Typ: Funkcja

Przed wysłaniem żądania można modyfikować obiekt XMLHttpRequest, np. dodawać niestandardowe nagłówki HTTP.

Obiekt XMLHttpRequest jest jedynym parametrem.

To jest wydarzenie AJAX. Jeśli zwróci false, można anulować bieżące żądanie AJAX.

cache

Typ: Logika

Domyślna wartość: true, dataType na script i jsonp domyślnie ustawione na false. Ustawienie na false spowoduje, że strona nie będzie缓存.

Nowe funkcje jQuery 1.2.

complete(XHR, TS)

Typ: Funkcja

Funkcja zwrotna wywoływana po zakończeniu żądania (zarówno w przypadku sukcesu, jak i porażki).

Parametry: Obiekt XMLHttpRequest i ciąg znaków opisujący typ żądania.

To jest wydarzenie Ajax.

contentType

Typ: Ciąg znaków

Domyślna wartość: "application/x-www-form-urlencoded". Typ kodowania treści wysyłanej do serwera.

Domyślna wartość jest odpowiednia dla większości przypadków. Jeśli wyraźnie przekazano typ content-type do $.ajax(), to zostanie wysłany do serwera (nawet jeśli nie ma danych do wysłania).

context

Typ: Obiekt

Ten obiekt służy do ustawiania kontekstu funkcji zwrotnych związanych z Ajax. Innymi słowy, ustawia kontekst this w funkcji zwrotnej na ten obiekt (jeśli nie ustawiono tego parametru, then this wskazuje na parametr options przekazany przy wywołaniu tego AJAX request). Na przykład, jeśli określono element DOM jako parametr context, to ustawia kontekst funkcji zwrotnej success na ten element DOM.

Tak wygląda:

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

Typ: Ciąg znaków

Dane wysyłane do serwera. Automatycznie przekształcane w format ciągów znaków żądania. W żądaniach GET dodawane są do adresu URL. Sprawdź opis opcji processData, aby zablokować to automatyczne przekształcanie. Muszą być w formacie Key/Value. Jeśli jest to tablica, jQuery automatycznie przypisze ten sam nazwę do różnych wartości. Na przykład {foo:["bar1", "bar2"]} jest przekształcane na '&foo=bar1&foo=bar2'.

dataFilter

Typ: Funkcja

Funkcja przetwarzania danych oryginalnych zwracanych przez Ajax. Dostarcza dwa parametry: data to oryginalne dane zwracane przez Ajax, a type to parametr dataType podany w jQuery.ajax. Wartość zwrócona przez funkcję zostanie dalszo przetworzona przez jQuery.

dataType

Typ: Ciąg znaków

Typ danych zwracanych przez serwer. Jeśli nie określono, jQuery automatycznie rozpoznaje typ MIME pakietu HTTP, np. typ MIME XML jest rozpoznawany jako XML. W wersji 1.4 JSON tworzy obiekt JavaScript, a script wykona ten skrypt. Następnie dane zwracane przez serwer są analizowane na podstawie tej wartości i przekazywane do funkcji zwrotnej. Dostępne wartości:

  • "xml": zwraca dokument XML, który można przetwarzać za pomocą jQuery.
  • "html": zwraca tekst HTML; zawarte znaczniki script będą wykonywane podczas wstawiania do DOM.
  • "script": zwraca czysty kod JavaScript. Rezultaty nie są automatycznie buforowane. Opcjonalnie można ustawić parametr "cache". Uwaga: w przypadku zewnętrznych żądań (nie w tej samej domenie), wszystkie żądania POST będą przekształcane na GET (ponieważ będzie używany znacznik script DOM do ładowania).
  • "json": zwraca dane JSON.
  • "jsonp": format JSONP. Używając formatu JSONP do wywołania funkcji, np. "myurl?callback=?", jQuery automatycznie zastąpi ? poprawną nazwą funkcji, aby wykonać funkcję zwrotną.
  • "text": zwraca ciąg znaków tekstowych
error

Typ: Funkcja

Domyślna wartość: automatyczne rozpoznawanie (xml lub html). Wywoływana w przypadku niepowodzenia żądania.

Mają trzy parametry: obiekt XMLHttpRequest, informacja o błędzie, (opcjonalnie) obiekt wyjątku ujęty.

W przypadku wystąpienia błędu, informacje o błędzie (drugi parametr) oprócz null mogą być "timeout", "error", "notmodified" i "parsererror".

To jest wydarzenie Ajax.

global

Typ: Logika

Czy wywołać globalne wydarzenia AJAX. Domyślna wartość: true. Ustawienie na false uniemożliwi wywołanie globalnych wydarzeń AJAX, takich jak ajaxStart lub ajaxStop, które można używać do kontroli różnych wydarzeń AJAX.

ifModified

Typ: Logika

Pobieranie nowych danych tylko gdy dane na serwerze się zmieniają. Domyślna wartość: false. Używane są nagłówki Last-Modified pakietu HTTP do oceny. W jQuery 1.4, również sprawdzane jest 'etag' określone przez serwer, aby upewnić się, że dane nie zostały zmodyfikowane.

jsonp

Typ: Ciąg znaków

Zmiana nazwy funkcji zwrotnej w żądaniu jsonp. Ta wartość jest używana do zastąpienia części "callback" w parametrze URL w żądaniach GET lub POST, takich jak "callback=?", np. {jsonp:'onJsonPLoad'} spowoduje przekazanie "onJsonPLoad=?" do serwera.

jsonpCallback

Typ: Ciąg znaków

Określa nazwę funkcji zwrotnej dla żądań jsonp. Ta wartość zastąpi automatycznie generowaną przez jQuery nazwę funkcji. To głównie służy do generowania unikalnych nazw funkcji, co ułatwia zarządzanie żądaniami oraz dostarczanie funkcji zwrotnych i obsługi błędów. Możesz również określić nazwę funkcji zwrotnej, aby umożliwić przeglądarce buforowanie żądań GET.

password

Typ: Ciąg znaków

Używane do odpowiedzi na żądania uwierzytelniania HTTP hasła

processData

Typ: Logika

Domyślna wartość: true. Domyślnie, dane przekazane za pomocą opcji data, jeśli są obiektem (technicznie, jeśli nie są ciagiem znaków), są przetwarzane na ciąg zapytania, aby pasować do domyślnego typu zawartości "application/x-www-form-urlencoded". Jeśli chcesz wysłać informacje o drzewie DOM lub inne dane, które nie powinny być przetwarzane, ustaw na false.

scriptCharset

Typ: Ciąg znaków

Używane tylko, gdy dataType wynosi "jsonp" lub "script", a type wynosi "GET", aby przymusowo zmienić charset. Zwykle używane, gdy kodowanie zawartości lokalnej i zdalnej jest różne.

success

Typ: Funkcja

Funkcja zwrotna po pomyślnym zakończeniu żądania.

Parametry: dane zwrócone przez serwer, przetworzone na podstawie parametru dataType; ciąg opisujący stan.

To jest wydarzenie Ajax.

traditional

Typ: Logika

Jeśli chcesz używać tradycyjnego sposobu serializacji danych, ustaw na true. Zobacz metodę jQuery.param w kategorii narzędzi.

timeout

Typ: Liczba

Ustawia czas wygaśnięcia żądania (w milisekundach). Ta konfiguracja zastępuje globalne ustawienia.

type

Typ: Ciąg znaków

Domyślna wartość: "GET")). Metoda żądania ("POST" lub "GET"), domyślnie "GET". Uwaga: inne metody żądania HTTP, takie jak PUT i DELETE, mogą być używane, ale są obsługiwane przez tylko niektóre przeglądarki.

url

Typ: Ciąg znaków

Domyślna wartość: adres strony. Adres wysyłania żądania.

username

Typ: Ciąg znaków

Używane do odpowiedzi na żądania uwierzytelniania HTTP użytkownika.

xhr

Typ: Funkcja

Wymaga zwrócenia obiektu XMLHttpRequest. Domyślnie w IE jest ActiveXObject, a w innych przypadkach XMLHttpRequest. Używane do przepisania lub dostarczenia ulepszonego obiektu XMLHttpRequest. Ten parametr jest niedostępny przed jQuery 1.3.

Funkcje callback

Aby przetwarzać dane uzyskane z $.ajax(), należy używać funkcji callback: beforeSend, error, dataFilter, success, complete.

beforeSend

Wywołaj przed wysłaniem żądania i przekazuj obiekt XMLHttpRequest jako parametr.

error

Wywołaj po wystąpieniu błędu. Przekazuj obiekt XMLHttpRequest, ciąg znaków opisujący typ błędu oraz obiekt wyjątku (jeśli istnieje).

dataFilter

Wywołaj po udanym zakończeniu żądania. Przekazuj zwrócone dane oraz wartość parametru "dataType". I musisz zwrócić nowe dane (może być przetworzone) do funkcji success callback.

success

Wywołaj po zakończeniu żądania. Przekazuj zwrócone dane oraz ciąg znaków zawierający kod powodzenia.

complete

Wywołaj tę funkcję po zakończeniu żądania, niezależnie od powodzenia lub porażki. Przekazuj obiekt XMLHttpRequest oraz ciąg znaków zawierający kod powodzenia lub błędu.

Typ danych

Funkcja $.ajax() polega na informacji dostarczanej przez serwer do przetwarzania zwróconych danych. Jeśli serwer zgłosi, że zwracane dane są XML, wynik można przeszukać za pomocą normalnych metod XML lub selektorów jQuery. Jeśli widoczny jest inny typ, np. HTML, dane są traktowane jako tekst.

Przez opcję dataType można również określić inne metody przetwarzania danych. Poza prostym XML, można określić html, json, jsonp, script lub text.

Dla typów text i xml zwracane dane nie są przetwarzane. Dane są po prostu przekazywane do funkcji success callback za pomocą właściwości responseText lub responseHTML XMLHttpRequest.

Uwaga:Musimy upewnić się, że typ MIME zgłaszany przez serwer stron internetowych pasuje do wybranego dataType. Na przykład, w przypadku XML, serwer musi zadeklarować text/xml lub application/xml, aby uzyskać spójne wyniki.

Jeśli określono typ html, wszelkie wtyczkowe JavaScript będą wykonywane przed zwróceniem HTML jako ciąg znaków. Podobnie, jeśli określono typ script, serwerzejski JavaScript zostanie najpierw wykonany, a następnie skrypt jako dane tekstowe zostanie zwrócony.

Jeśli określono typ 'json', dane uzyskane będą interpretowane jako obiekt JavaScript, a skonstruowany obiekt zostanie zwrócony jako wynik. W celu osiągnięcia tego, najpierw próbuje się użyć JSON.parse(). Jeśli przeglądarka nie obsługuje tego, używa się funkcji do budowania.

Dane JSON są strukturyzowanymi danymi, które można łatwo przetworzyć za pomocą JavaScript. Jeśli plik danych znajduje się na zdalnym serwerze (inny domena, czyli dane poza domeną), należy użyć typu 'jsonp'. Użycie tego typu tworzy parametr ciągów zapytania 'callback=?', który jest dodawany do końca adresu URL żądania. Serwer powinien dodać nazwę funkcji zwrotnej przed danymi JSON, aby wykonać poprawne żądanie JSONP. Aby określić nazwę parametru funkcji zwrotnej zamiast domyślnego 'callback', można ustawić parametr 'jsonp' w $.ajax().

Uwaga:JSONP jest rozszerzeniem formatu JSON. Wymaga to pewnych kodów serwerowych do wykrywania i przetwarzania parametrów ciągów zapytania.

Jeśli określono typ 'script' lub 'jsonp', to przy odbiorze danych z serwera używany jest znacznik <script> zamiast obiektu XMLHttpRequest. W takim przypadku $.ajax() nie zwraca obiektu XMLHttpRequest i nie przekazuje funkcji obsługi zdarzeń, takich jak 'beforeSend'.

Wysyłanie danych do serwera

Domyślnie, żądania Ajax używają metody GET. Jeśli chcemy użyć metody POST, możemy ustawić wartość parametru 'type'. Ta opcja wpływa również na sposób, w jaki zawartość opcji 'data' jest wysyłana do serwera.

Opcja 'data' może zawierać ciąg zapytania, na przykład 'key1=value1&key2=value2', lub mapę, na przykład '{key1: 'value1', key2: 'value2'}'. Jeśli używana jest druga forma, dane będą przekształcane w ciąg zapytania na serwerze. Proces ten można uniknąć, ustawiając opcję 'processData' na wartość 'false'. Jeśli chcemy wysłać obiekt XML do serwera, ten proces może nie być odpowiedni. W takim przypadku powinniśmy również zmienić wartość opcji 'contentType' na inny odpowiedni typ MIME, zamiast domyślnego 'application/x-www-form-urlencoded'.

Zaawansowane opcje

Opcja global jest używana do zablokowania zarejestrowanych odpowiedzi zwrotnych, takich jak .ajaxSend, lub ajaxError, oraz podobnych metod. Jest to przydatne w niektórych przypadkach, np. gdy wysyłane żądania są bardzo częste i krótkie, można włączyć to w ajaxSend.

Jeśli serwer wymaga uwierzytelnienia HTTP, można użyć nazwy użytkownika i hasła do ustawienia opcji username i password.

Żądania Ajax są ograniczone czasowo, więc po przechwyceniu i przetworzeniu błędu można poprawić doświadczenie użytkownika. Parametr timeout zazwyczaj pozostawia się w wartości domyślnej, lub ustawia się go globalnie za pomocą jQuery.ajaxSetup, rzadko ustawia się go dla konkretnego żądania.

Domyślnie, żądania są zawsze wysyłane, ale przeglądarka może pobrać dane z jej pamięci podręcznej. Aby zabronić użycia wyników z pamięci podręcznej, można ustawić parametr cache na false. Jeśli chcemy, aby raportowano błąd, jeśli dane nie uległy zmianie od ostatniego żądania, można ustawić ifModified na true.

scriptCharset pozwala ustawić dla żądania <script> specyficzny zestaw znaków, używany do skryptów lub danych jsonp. Jest to szczególnie przydatne, gdy skrypt i zestaw znaków strony są różne.

Pierwsza litera Ajax to początkowa litera słowa asynchronous, co oznacza, że wszystkie operacje są równoległe i nie ma związku z kolejnością ich zakończenia. Parametr async w $.ajax() zawsze jest ustawiony na true, co oznacza, że po rozpoczęciu żądania inne kod wciąż może być wykonywany. Nie zaleca się ustawiania tej opcji na false, co oznaczałoby, że wszystkie żądania nie będą już asynchroniczne, co mogłoby spowodować zablokowanie przeglądarki.

$.ajax funkcja zwraca obiekt XMLHttpRequest, który utworzyła. Zwykle jQuery przetwarza wewnętrznie i tworzy ten obiekt, ale użytkownik może przekazać własny obiekt xhr za pomocą opcji xhr. Zwracany obiekt jest zazwyczaj odrzucany, ale dostarcza również interfejs niskopoziomowy do monitorowania i manipulowania żądaniem. Na przykład, wywołanie metody .abort() na obiekcie może wstrzymać żądanie przed jego zakończeniem.

Podręcznik referencyjny jQuery Ajax