jQuery ajax - ajax() 方法

jQuery Ajax 参考手册

实例

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

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

语法

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

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

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

参数

options

Typ: Object

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

async

Typ: Wahrheitswert

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

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

beforeSend(XHR)

Typ: Funktion

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

XMLHttpRequest 对象是唯一的参数。

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

cache

Typ: Wahrheitswert

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

jQuery 1.2 新功能。

complete(XHR, TS)

Typ: Funktion

Callback-Funktion nach Abschluss des Requests (wird nach Erfolg oder Misserfolg des Requests aufgerufen).

Parameter: XMLHttpRequest-Objekt und ein String, der den Request-Typ beschreibt.

Dies ist ein Ajax-Ereignis.

contentType

Typ: Zeichenkette

Standardwert: "application/x-www-form-urlencoded". Inhaltencodierungstyp, der beim Senden von Informationen an den Server verwendet wird.

Standardwert ist für die meisten Fälle geeignet. Wenn Sie $.ajax() einen bestimmten content-type übergeben, wird er sicherlich an den Server gesendet (selbst wenn keine Daten gesendet werden müssen).

context

Typ: Object

Dieses Objekt wird verwendet, um den Kontext der Ajax-zugehörigen Callback-Funktionen zu setzen. Das bedeutet, dass das this innen in der Callback-Funktion auf dieses Objekt zeigt (wenn dieser Parameter nicht gesetzt wird, zeigt this auf die options-Parameter, die bei der Aufrufung dieser AJAX-Anfrage übergeben wurden). Zum Beispiel, wenn ein DOM-Element als Kontextparameter angegeben wird, wird der Kontext der success-Callback-Funktion auf dieses DOM-Element gesetzt.

So ähnlich:

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

Typ: Zeichenkette

Daten, die an den Server gesendet werden. Wird automatisch in das Format der Anfragezeichenkette konvertiert. Wird in GET-Anfragen an den URL angehängt. Siehe die Beschreibung der Option processData, um diese automatische Konvertierung zu verhindern. Muss im Key/Value-Format vorliegen. Wenn es sich um ein Array handelt, konvertiert jQuery automatisch verschiedene Werte in denselben Namen. Zum Beispiel wird {foo:["bar1", "bar2"]} in '&foo=bar1&foo=bar2' umgewandelt.

dataFilter

Typ: Funktion

Funktion zur Vorverarbeitung der ursprünglichen Daten, die von Ajax zurückgegeben werden. Bietet die Parameter data und type: data sind die ursprünglichen Daten, die von Ajax zurückgegeben werden, und type ist der dataType-Parameter, der bei der Aufrufung von jQuery.ajax bereitgestellt wird. Der zurückgegebene Wert wird von jQuery weiterverarbeitet.

dataType

Typ: Zeichenkette

Erwartete Datenart, die der Server zurückgibt. Wird nichts angegeben, erkennt jQuery dies automatisch anhand der MIME-Informationen des HTTP-Pakets, z.B. wird der XML-MIME-Typ als XML erkannt. In Version 1.4 wird JSON zu einem JavaScript-Objekt generiert, und script führt diesen Skript aus. Anschließend werden die vom Server zurückgegebenen Daten gemäß diesem Wert geparst und an die Callback-Funktion weitergegeben. Verfügbare Werte:

  • "xml": Gibt XML-Dokumente zurück, die von jQuery verarbeitet werden können.
  • "html": Gibt reine HTML-Informationen zurück; enthaltene Script-Tags werden beim Einfügen in das DOM ausgeführt.
  • "script": Gibt reinen JavaScript-Code zurück. Wird nicht automatisch zwischengespeichert. Es sei denn, der Parameter "cache" wurde gesetzt. Hinweis: Bei Remote-Anfragen (nicht im selben Dom) werden alle POST-Anfragen in GET-Anfragen umgewandelt. (Da wird das DOM-Script-Tag verwendet, um zu laden).
  • "json": Gibt JSON-Daten zurück.
  • "jsonp": JSONP-Format. Wenn eine Funktion mit JSONP-Format aufgerufen wird, wie "myurl?callback=?", ersetzt jQuery automatisch ? durch den richtigen Funktionsnamen, um die Callback-Funktion auszuführen.
  • "text": Gibt eine reine Textzeichenkette zurück
error

Typ: Funktion

Standardwert: Automatische Erkennung (xml oder html). Diese Funktion wird aufgerufen, wenn die Anfrage fehlgeschlagen ist.

Es gibt drei Parameter: XMLHttpRequest-Objekt, Fehlerinformation, (optional) erfasste Ausnahme-Objekte.

Falls ein Fehler auftritt, kann der Fehlerinformation (zweiter Parameter) neben null auch "timeout", "error", "notmodified" und "parsererror" sein.

Dies ist ein Ajax-Ereignis.

global

Typ: Wahrheitswert

Ob globale AJAX-Ereignisse ausgelöst werden. Standardwert: true. Wenn auf false gesetzt, werden keine globalen AJAX-Ereignisse ausgelöst, wie z.B. ajaxStart oder ajaxStop, die zur Steuerung verschiedener Ajax-Ereignisse verwendet werden können.

ifModified

Typ: Wahrheitswert

Daten werden nur abgerufen, wenn die Daten auf dem Server geändert wurden. Standardwert: false. Verwendet HTTP-Paket-Header "Last-Modified" zur Bestimmung. In jQuery 1.4 wird auch der von dem Server angegebene 'etag' überprüft, um zu bestimmen, ob die Daten nicht geändert wurden.

jsonp

Typ: Zeichenkette

In einer jsonp-Anfrage wird der Name der Callback-Funktion neu definiert. Dieser Wert wird verwendet, um den Teil "callback" in GET- oder POST-Anfragen wie "callback=?" zu ersetzen, z.B. {jsonp:'onJsonPLoad'} führt dazu, dass "onJsonPLoad=?" an den Server gesendet wird.

jsonpCallback

Typ: Zeichenkette

Für jsonp-Anfragen einen Callback-Funktionennamen angeben. Dieser Wert wird verwendet, um den von jQuery automatisch generierten zufälligen Funktionsnamen zu ersetzen. Dies wird hauptsächlich verwendet, um jQuery einzigartige Funktionsnamen zu generieren, um die Verwaltung von Anfragen zu erleichtern und die Bereitstellung von Callback-Funktionen und Fehlerbehandlung zu erleichtern. Sie können auch diesen Callback-Funktionennamen angeben, wenn Sie möchten, dass der Browser GET-Anfragen cachen möchte.

password

Typ: Zeichenkette

Passwort für die Antwort auf HTTP-Authentifizierungsanfragen.

processData

Typ: Wahrheitswert

Standardwert: true. Standardmäßig werden Daten, die durch den data-Option übergeben werden und technisch nicht als Zeichenkette sind, in einen Query-String umgewandelt, um mit dem Standardinhaltstyp "application/x-www-form-urlencoded" zu arbeiten. Wenn Sie DOM-Bauminformationen oder andere nicht umzuwandeln wollende Informationen senden möchten, setzen Sie es auf false.

scriptCharset

Typ: Zeichenkette

Wird nur verwendet, wenn dataType "jsonp" oder "script" ist und type "GET" ist, um den charset obligatorisch zu ändern. Es wird normalerweise nur verwendet, wenn die Inhaltskodierung von lokalem und fernem Inhalt unterschiedlich ist.

success

Typ: Funktion

Rückruffunktion nach erfolgreicher Anfrage.

Parameter: Daten, die vom Server zurückgegeben werden und nach dem dataType-Parameter verarbeitet werden; Zeichenkette zur Beschreibung des Status.

Dies ist ein Ajax-Ereignis.

traditional

Typ: Wahrheitswert

Wenn Sie eine traditionelle Art der Serialisierung der Daten verwenden möchten, dann setzen Sie es auf true. Siehe jQuery.param unter Werkzeuge.

timeout

Typ: Zahl

Setzen Sie die Anfrageüberschreitungszeit (in Millisekunden). Diese Einstellung überschreibt die globale Einstellung.

type

Typ: Zeichenkette

Standardwert: "GET"). Anfrageart ("POST" oder "GET"), Standard ist "GET". Beachten Sie: Andere HTTP-Anfragearten wie PUT und DELETE können ebenfalls verwendet werden, aber nur von einigen Browsern unterstützt.

url

Typ: Zeichenkette

Standardwert: aktuelle Seite Adresse. Die Adresse der gesendeten Anfrage.

username

Typ: Zeichenkette

Benutzername für die Antwort auf HTTP-Authentifizierungsanfragen.

xhr

Typ: Funktion

Es muss ein XMLHttpRequest-Objekt zurückgegeben werden. Standardmäßig ist es in IE ActiveXObject und in anderen Fällen XMLHttpRequest. Es wird verwendet, um einen überarbeiteten oder erweiterten XMLHttpRequest-Objekt bereitzustellen. Dieser Parameter war in jQuery 1.3 nicht verfügbar.

Rückruffunktionen

Um die von $.ajax() erhaltenen Daten zu verarbeiten, ist es erforderlich, Callback-Funktionen wie beforeSend, error, dataFilter, success und complete zu verwenden.

beforeSend

Diese Funktion wird aufgerufen, bevor die Anfrage gesendet wird und übergeben Sie einen XMLHttpRequest als Parameter.

error

Diese Funktion wird aufgerufen, wenn die Anfrage fehlschlägt. Übergeben Sie den XMLHttpRequest-Objekt, einen String, der den FehlerTyp beschreibt, und ein Exception-Objekt (wenn vorhanden).

dataFilter

Diese Funktion wird aufgerufen, wenn die Anfrage erfolgreich ist. Übergeben Sie die zurückgegebenen Daten und den Wert des Parameters "dataType". Und es muss neue Daten (möglicherweise verarbeitet) zurückgegeben werden, die an die success-Rückruffunktion übergeben werden.

success

Diese Funktion wird aufgerufen, wenn die Anfrage abgeschlossen ist. Übergeben Sie die zurückgegebenen Daten und einen String, der den Erfolgscode enthält.

complete

Diese Funktion wird aufgerufen, wenn die Anfrage abgeschlossen ist, egal ob erfolgreich oder fehlerhaft. Übergeben Sie den XMLHttpRequest-Objekt und einen String, der den Erfolg oder Fehlercode enthält.

Datenart

Die Funktion $.ajax() hängt von den Informationen ab, die der Server bereitstellt, um die zurückgegebenen Daten zu verarbeiten. Wenn der Server angibt, dass die zurückgegebenen Daten XML sind, können die Ergebnisse mit normalen XML-Methoden oder jQuery-Selektoren durchsucht werden. Wenn andere Typen wie HTML erkennbar sind, werden die Daten als Text behandelt.

Mit der Option dataType können auch andere Arten der Datenverarbeitung angegeben werden. Neben reinem XML können auch html, json, jsonp, script oder text angegeben werden.

Dabei werden die Daten für die Typen text und xml nicht verarbeitet. Die Daten werden einfach an die success-Rückruffunktion übergeben, indem die responseText- oder responseHTML-Attribute des XMLHttpRequests weitergegeben werden.

Hinweis:Wir müssen sicherstellen, dass der von der Webserver berichtete MIME-Typ mit dem gewählten dataType übereinstimmt. Zum Beispiel muss der Server text/xml oder application/xml angeben, um ein konsistentes Ergebnis zu erzielen, wenn XML angegeben wird.

Wenn die html-Typen angegeben werden, wird jeder eingebettete JavaScript vor der Rückgabe des HTML als String ausgeführt. Ähnlich wird auch der Serverseitig generierte JavaScript vor der Rückgabe als Textdaten ausgeführt, wenn der script-Typ angegeben wird.

Wenn der Typ 'json' festgelegt ist, wird die empfangene Daten als JavaScript-Objekt analysiert und das erstellte Objekt als Ergebnis zurückgegeben. Um dies zu erreichen, versucht es zunächst, JSON.parse() zu verwenden. Wenn der Browser dies nicht unterstützt, wird eine Funktion verwendet, um dies zu erreichen.

JSON-Daten sind eine strukturierte Datenform, die leicht durch JavaScript analysiert werden kann. Wenn die Daten datei auf einem Remote-Server gespeichert ist (Domain ist unterschiedlich, also Daten über verschiedene Domänen zu erhalten), muss der Typ 'jsonp' verwendet werden. Bei Verwendung dieses Typs wird ein Suchzeichenkette-Parameter 'callback=?' erstellt, der am Ende der URL angehängt wird. Der Server sollte den Namen der Callback-Funktion vor den JSON-Daten hinzufügen, um eine gültige JSONP-Anfrage abzuschließen. Wenn der Name des Callback-Funktionparameters ersetzt werden soll, indem der Standard 'callback' durch die Option 'jsonp' von $.ajax() festgelegt wird.

Hinweis:JSONP ist eine Erweiterung des JSON-Formates. Es erfordert einige Serverseitigen Code, um die Parameter der Suchzeichenkette zu erkennen und zu verarbeiten.

Wenn der Typ 'script' oder 'jsonp' angegeben ist, wird bei der Empfangnahme von Daten vom Server tatsächlich das <script>-Tag und nicht das XMLHttpRequest-Objekt verwendet. In diesem Fall gibt $.ajax() kein XMLHttpRequest-Objekt zurück und überträgt auch keine Ereignisbehandlungsfunktionen, wie z.B. 'beforeSend'.

Daten senden an den Server

Standardmäßig verwendet die Ajax-Anfrage die Methode GET. Wenn die Methode POST verwendet werden soll, kann der Wert des Parameters 'type' festgelegt werden. Diese Option beeinflusst auch, wie der Inhalt der Option 'data' an den Server gesendet wird.

Der 'data'-Option kann sowohl ein Suchstring enthalten, wie z.B. key1=value1&key2=value2, als auch eine Zuordnung, wie z.B. {key1: 'value1', key2: 'value2'}. Wenn die letztere Form verwendet wird, wird das Datenpaket durch den Sender in einen Suchstring umgewandelt. Dieser Prozess kann auch durch das Setzen der Option 'processData' auf 'false' vermieden werden. Wenn wir einen XML-Objekt an den Server senden möchten, ist diese Verarbeitung möglicherweise nicht geeignet. Und in diesem Fall sollten wir auch den Wert der Option 'contentType' ändern, indem wir andere angemessene MIME-Typen anstelle des Standardtyps 'application/x-www-form-urlencoded' verwenden.

Erweiterte Optionen

Die global-Option wird verwendet, um die von der Antwort registrierten Callback-Funktionen zu verhindern, wie .ajaxSend, oder ajaxError, und ähnliche Methoden. Dies ist in einigen Fällen nützlich, zum Beispiel wenn sehr häufig und kurzlebig Anfragen gesendet werden, kann dies in ajaxSend deaktiviert werden.

Wenn der Server HTTP-Authentifizierung benötigt, können Benutzername und Passwort über die username und password-Optionen eingerichtet werden.

Ajax-Anfragen sind zeitlich begrenzt, daher können Fehlerwarnungen nach der Erfassung und Verarbeitung verwendet werden, um die Benutzererfahrung zu verbessern. Der Timeout-Parameter wird normalerweise bei seinem Standardwert belassen oder global über jQuery.ajaxSetup eingestellt, was selten für spezifische Anfragen erforderlich ist, um den Timeout-Parameter neu zu konfigurieren.

Standardmäßig werden Anfragen immer gesendet, aber der Browser kann Daten aus seinem Cache abrufen. Um die Verwendung der Ergebnisse aus dem Cache zu verhindern, kann der cache-Parameter auf false gesetzt werden. Wenn Sie überprüfen möchten, ob die Daten seit der letzten Anfrage geändert wurden und ein Fehler gemeldet werden soll, wenn dies der Fall ist, kann der ifModified-Parameter auf true gesetzt werden.

scriptCharset ermöglicht es, Anfragen für den <script>-Tag eine spezifische Zeichensatz zu setzen, die für Skripte oder jsonp-artige Daten verwendet wird. Dies ist besonders nützlich, wenn der Zeichensatz des Skripts und der Seite unterschiedlich ist.

Der erste Buchstabe von Ajax ist die Initialkonsonant von asynchron, was bedeutet, dass alle Operationen parallel sind und keine festgelegte Reihenfolge der Fertigstellung haben. Der async-Parameter von $.ajax() ist immer auf true gesetzt, was bedeutet, dass andere Code nach dem Start der Anfrage weiterhin ausgeführt werden kann. Es wird dringend empfohlen, diesen Parameter nicht auf false zu setzen, da dies bedeutet, dass alle Anfragen nicht mehr asynchron sind und dies auch den Browser lahmlegen kann.

$.ajax Funktion gibt das von ihr erstellte XMLHttpRequest-Objekt zurück. In der Regel behandelt jQuery intern und erstellt dieses Objekt, aber Benutzer können auch einen selbst erstellten xhr-Objekt über die xhr-Option übergeben. Das zurückgegebene Objekt wird normalerweise weggeworfen, bietet aber eine niedrigere Benutzeroberfläche, um Anfragen zu überwachen und zu steuern. Zum Beispiel kann der Aufruf von .abort() auf dem Objekt Anfragen vor ihrem Abschluss anhalten.

jQuery Ajax 参考手册