Méthode jQuery ajax - ajax()

manuel de référence Ajax jQuery

Exemple

Charger un texte via AJAX :

Code jQuery :

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

Code HTML :

<div id="myDiv"><h2>Laissez AJAX changer ce texte</h2></div>
<button id="b01" type="button">Changer le contenu</button>

Essayez-le vous-même

Définition et utilisation

La méthode ajax() charge des données distantes via des requêtes HTTP.

Cette méthode est l'implémentation AJAX de base de jQuery. Une implémentation de haut niveau simple et facile à utiliser est $.get, $.post, etc. $.ajax() retourne l'objet XMLHttpRequest qu'il crée. Dans la plupart des cas, vous n'avez pas besoin de manipuler directement cette fonction, sauf si vous avez besoin de manipuler des options non courantes pour obtenir plus de flexibilité.

Dans le cas le plus simple, $.ajax() peut être utilisé directement sans aucun paramètre.

Attention :Tous les options peuvent être configurés globalement via la fonction $.ajaxSetup().

Syntaxe

jQuery.ajax([settings]
Paramètres Description
settings

Optionnel. Ensemble de paires clé-valeur pour configurer la requête Ajax.

Vous pouvez définir la valeur par défaut de toute option via $.ajaxSetup().

Paramètres

options

Type : Objet

Optionnel. Configuration de la requête Ajax. Tous les options sont optionnels.

async

Type : Booléen

Valeur par défaut : true. Par défaut, toutes les requêtes sont asynchrones. Si vous avez besoin d'envoyer une requête synchronisée, définissez cette option sur false.

Attention, les requêtes synchrones verrouillent le navigateur, les autres opérations de l'utilisateur doivent attendre la fin de la requête pour être exécutées.

beforeSend(XHR)

Type : Fonction

Vous pouvez modifier l'objet XMLHttpRequest avant d'envoyer la requête, comme ajouter des en-têtes HTTP personnalisés.

L'objet XMLHttpRequest est le seul paramètre.

C'est un événement Ajax. Si vous retournez false, vous pouvez annuler cette requête Ajax.

cache

Type : Booléen

Valeur par défaut : true, dataType est script et jsonp par défaut false. Définir false ne cache pas cette page.

Nouvelles fonctionnalités de jQuery 1.2.

complete(XHR, TS)

Type : Fonction

Fonction de rappel appelée après la fin de la requête (appelée après le succès ou l'échec de la requête).

Paramètres : Objet XMLHttpRequest et une chaîne de caractères décrivant le type de requête.

C'est un événement Ajax.

contentType

Type : Chaîne de caractères

Valeur par défaut: "application/x-www-form-urlencoded". Le type de codage du contenu envoyé au serveur.

La valeur par défaut convient à la plupart des cas. Si vous passez explicitement un content-type à $.ajax(), il sera必定 envoyé au serveur (même s'il n'y a pas de données à envoyer).

context

Type : Objet

Cet objet est utilisé pour définir le contexte des fonctions de rappel Ajax. Cela signifie que le contexte this à l'intérieur de la fonction de rappel pointe vers cet objet (si ce paramètre n'est pas défini, then this pointe vers les paramètres options passés lors de l'appel à cette requête AJAX). Par exemple, en spécifiant un élément DOM comme paramètre context, le contexte de la fonction de rappel success est ainsi défini pour cet élément DOM.

Comme ceci :

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

Type : Chaîne de caractères

Les données envoyées au serveur. Elle sera automatiquement convertie en format de chaîne de requête. Elle sera ajoutée à l'URL pour les requêtes GET. Consultez les explications de l'option processData pour interdire cette conversion automatique. Il doit être au format Key/Value. Si c'est un tableau, jQuery le convertira automatiquement en une même clé pour différentes valeurs. Par exemple, {foo: ["bar1", "bar2"]} sera converti en '&foo=bar1&foo=bar2'.

dataFilter

Type : Fonction

Fonction de prétraitement des données originales retournées par Ajax. Elle fournit deux paramètres : data et type. data est les données originales retournées par Ajax, et type est le paramètre dataType fourni lors de l'appel à jQuery.ajax. La valeur retournée par la fonction sera traitée par jQuery.

dataType

Type : Chaîne de caractères

Le type de données attendu du serveur de retour. Si non spécifié, jQuery le déterminera automatiquement en fonction des informations MIME HTTP du paquet HTTP, par exemple, le type MIME XML est reconnu comme XML. Dans la version 1.4, JSON générera un objet JavaScript, et script l'exécutera. Ensuite, les données retournées par le serveur seront analysées en fonction de cette valeur et transmises à la fonction de rappel. Les valeurs disponibles sont:

  • "xml": retourne un document XML, pouvant être traité par jQuery.
  • "html": retourne des informations HTML texte ; les balises script incluses seront exécutées lors de l'insertion dans le DOM.
  • "script": retourne un code JavaScript texte pur. Il ne sera pas automatiquement mis en cache. Sauf si le paramètre "cache" est défini. Note : lors des requêtes distantes (qui ne sont pas dans le même domaine), toutes les requêtes POST seront converties en requêtes GET (parce que le script de DOM sera utilisé pour le chargement).
  • "json": retourne des données JSON .
  • "jsonp": format JSONP. Lorsque vous appellez une fonction en utilisant le format JSONP, comme "myurl?callback=?", jQuery remplacera automatiquement ? par le nom de la fonction correcte pour exécuter la fonction de rappel.
  • "text": retourne une chaîne de texte pure
error

Type : Fonction

Valeur par défaut : jugement automatique (xml ou html). Appel cette fonction en cas d'échec de la requête.

Il y a trois paramètres : l'objet XMLHttpRequest, l'information d'erreur, et (optionnel) l'objet d'exception capturé.

En cas d'erreur, en plus de null, l'information d'erreur (deuxième paramètre) peut être "timeout", "error", "notmodified" et "parsererror".

C'est un événement Ajax.

global

Type : Booléen

Déclencher ou non les événements AJAX globaux. Valeur par défaut : true. Définir sur false empêchera la déclencher les événements AJAX globaux, tels que ajaxStart ou ajaxStop, qui peuvent être utilisés pour contrôler différents événements Ajax.

ifModified

Type : Booléen

Obtenir de nouvelles données uniquement lorsque les données du serveur changent. Valeur par défaut : false. Utilisez l'entête HTTP Last-Modified pour le jugement. Dans jQuery 1.4, il vérifie également l'"etag" spécifié par le serveur pour déterminer si les données n'ont pas été modifiées.

jsonp

Type : Chaîne de caractères

Redéfinir le nom de la fonction de rappel dans une requête jsonp. Cette valeur est utilisée pour remplacer la partie "callback" dans les paramètres de l'URL des requêtes GET ou POST de type "callback=?", par exemple {jsonp:'onJsonPLoad'} entraînera l'envoi de "onJsonPLoad=?" au serveur.

jsonpCallback

Type : Chaîne de caractères

Spécifiez un nom de fonction de rappel pour la requête jsonp. Cette valeur sera utilisée pour remplacer le nom de fonction généré aléatoirement par jQuery. Cela permet à jQuery de générer des noms de fonctions uniques, ce qui rend la gestion des requêtes plus facile et permet de fournir plus facilement des fonctions de rappel et de gestion des erreurs. Vous pouvez également spécifier ce nom de fonction de rappel pour que le navigateur puisse mettre en cache les requêtes GET.

password

Type : Chaîne de caractères

Mot de passe utilisé pour répondre aux demandes d'authentification HTTP.

processData

Type : Booléen

Valeur par défaut : true. Par défaut, les données transmises via l'option data, si elles sont un objet (techniquement, ce n'est pas une chaîne de caractères), sont traitées et transformées en une chaîne de caractères de requête pour correspondre au type de contenu par défaut "application/x-www-form-urlencoded". Si vous souhaitez envoyer des informations sur l'arbre DOM ou d'autres informations que vous ne souhaitez pas transformer, configurez-le sur false.

scriptCharset

Type : Chaîne de caractères

Seulement utilisé lorsque dataType est "jsonp" ou "script", et type est "GET" pour forcer la modification du charset. Utilisé généralement lorsque le contenu de codage local et distant est différent.

success

Type : Fonction

Fonction de rappel après une requête réussie.

Paramètres : Données renvoyées par le serveur et traitées en fonction du paramètre dataType ; chaîne de caractères décrivant l'état.

C'est un événement Ajax.

traditional

Type : Booléen

Si vous souhaitez sérialiser les données de manière traditionnelle, configurez-le sur true. Veuillez consulter la méthode jQuery.param sous la catégorie outils.

timeout

Type : Nombre

Définir le temps d'attente de la requête (en millisecondes). Cette configuration remplacera la configuration globale.

type

Type : Chaîne de caractères

Valeur par défaut : "GET"). Méthode de requête ("POST" ou "GET"), la valeur par défaut est "GET". Note : D'autres méthodes de requête HTTP, telles que PUT et DELETE, peuvent également être utilisées, mais elles ne sont supportées que par certains navigateurs.

url

Type : Chaîne de caractères

Valeur par défaut : adresse de la page actuelle. Adresse de l'adresse de l'envoi de la requête.

username

Type : Chaîne de caractères

Utilisé pour la réponse aux demandes d'authentification HTTP de l'utilisateur.

xhr

Type : Fonction

Il faut retourner un objet XMLHttpRequest. Par défaut, sous IE, c'est ActiveXObject et dans d'autres cas, c'est XMLHttpRequest. Utilisé pour redéfinir ou fournir un objet XMLHttpRequest amélioré. Ce paramètre n'était pas disponible avant jQuery 1.3.

Fonctions de rappel

Pour traiter les données obtenues avec $.ajax(), il est nécessaire d'utiliser les fonctions de rappel : beforeSend, error, dataFilter, success, complete.

beforeSend

Appelée avant l'envoi de la requête et reçoit l'objet XMLHttpRequest comme paramètre.

error

Appelée en cas d'erreur de requête. Elle reçoit l'objet XMLHttpRequest, une chaîne décrivant le type d'erreur et un objet d'exception (s'il y en a un).

dataFilter

Appelée après une réussite de la requête. Elle reçoit les données retournées et la valeur du paramètre "dataType". Elle doit retourner de nouvelles données (peut-être traitées) à passer à la fonction de rappel success.

success

Appelée après la requête. Elle reçoit les données retournées et une chaîne contenant un code de succès.

complete

Appelée après la fin de la requête, qu'elle soit réussie ou en échec. Elle reçoit l'objet XMLHttpRequest et une chaîne contenant un code de succès ou d'erreur.

Type de données

La fonction $.ajax() dépend des informations fournies par le serveur pour traiter les données retournées. Si le serveur indique que les données retournées sont XML, le résultat peut être parcouru à l'aide de méthodes XML standard ou des sélecteurs jQuery. Si d'autres types sont détectés, par exemple HTML, les données sont traitées comme du texte.

Grâce à l'option dataType, il est possible de spécifier d'autres méthodes de traitement des données. Outre le simple XML, il est possible de spécifier html, json, jsonp, script ou text.

Les types text et xml retournent des données non traitées. Les données sont simplement transmises à la fonction de rappel success en utilisant les attributs responseText ou responseHTML de XMLHttpRequest.

Attention :Nous devons nous assurer que le type MIME signalé par le serveur web correspond au dataType sélectionné. Par exemple, pour XML, le serveur doit déclarer text/xml ou application/xml pour obtenir un résultat cohérent.

Si le type html est spécifié, tout JavaScript intégré sera exécuté avant que l'HTML ne soit retourné sous forme de chaîne. De même, si le type script est spécifié, le JavaScript généré côté serveur sera d'abord exécuté, puis le script sera retourné sous forme de données texte.

Si le type json est spécifié, les données obtenues seront analysées comme un objet JavaScript et l'objet construit sera retourné comme résultat. Pour cela, il essaie d'utiliser JSON.parse() d'abord. Si le navigateur ne le prend pas en charge, il utilise une fonction pour construire.

Les données JSON sont une structure de données structurées qui peuvent être facilement analysées par JavaScript. Si les fichiers de données que vous obtenez sont stockés sur un serveur distant (c'est-à-dire que vous récupérez des données en dehors de votre domaine), vous devez utiliser le type jsonp. En utilisant ce type, un paramètre de chaîne de requête callback=? est créé et ajouté à la fin de l'URL de la requête. Le serveur doit ajouter le nom de la fonction de rappel avant les données JSON pour effectuer une requête JSONP valide. Si vous souhaitez spécifier le nom du paramètre de la fonction de rappel pour remplacer le nom par défaut callback, vous pouvez le faire en définissant le paramètre jsonp de $.ajax().

Attention :JSONP est une extension du format JSON. Il nécessite des codes serveur pour détecter et traiter les paramètres de la chaîne de requête.

Si le type script ou jsonp est spécifié, alors lorsque des données sont reçues du serveur, ce sont des balises <script> qui sont utilisées plutôt qu'un objet XMLHttpRequest. Dans ce cas, $.ajax() ne retourne plus un objet XMLHttpRequest et ne transmet pas de fonctions de gestion des événements, telles que beforeSend.

Envoyer des données au serveur

Par défaut, les requêtes Ajax utilisent la méthode GET. Pour utiliser la méthode POST, vous pouvez définir la valeur du paramètre type. Cette option affecte également la manière dont le contenu de l'option data est envoyé au serveur.

L'option 'data' peut contenir une chaîne de requête, par exemple key1=value1&key2=value2, ou une carte, par exemple {key1: 'value1', key2: 'value2'}. Si la dernière forme est utilisée, les données seront converties en une chaîne de requête avant d'être envoyées. Ce processus peut également être évité en définissant l'option processData sur false. Si nous souhaitons envoyer un objet XML au serveur, ce traitement peut ne pas être approprié. Dans ce cas, nous devrions également modifier la valeur de l'option contentType en utilisant un autre type MIME approprié pour remplacer le défaut application/x-www-form-urlencoded.

options avancées

L'option global est utilisée pour empêcher les fonctions de rappel enregistrées en réponse, telles que .ajaxSend, ou ajaxError, et d'autres méthodes similaires. Cela peut être utile dans certaines situations, par exemple lorsque les requêtes envoyées sont très fréquentes et courtes, on peut désactiver cette option dans ajaxSend.

Si le serveur nécessite une authentification HTTP, vous pouvez utiliser les options username et password pour définir un nom d'utilisateur et un mot de passe.

Les requêtes Ajax sont limitées dans le temps, donc après que les avertissements d'erreur ont été capturés et traités, elles peuvent être utilisées pour améliorer l'expérience utilisateur. Le paramètre timeout est généralement laissé à sa valeur par défaut, ou configuré globalement via jQuery.ajaxSetup, rarement réinitialisé pour une requête spécifique.

Par défaut, la requête est toujours envoyée, mais le navigateur peut potentiellement récupérer des données à partir de son cache. Pour interdire l'utilisation des résultats du cache, il est possible de configurer le paramètre cache sur false. Si vous souhaitez signaler une erreur si les données n'ont pas été modifiées depuis la dernière requête, vous pouvez configurer ifModified sur true.

scriptCharset permet de définir un jeu de caractères spécifique pour les requêtes de l'étiquette <script>, utilisé pour les scripts ou les données jsonp. Cela est particulièrement utile lorsque les caractères du script et du jeu de caractères de la page ne sont pas les mêmes.

La première lettre d'Ajax est la lettre initiale de 'asynchronous', ce qui signifie que toutes les opérations sont exécutées en parallèle et qu'il n'y a pas d'ordre de priorité entre elles. Le paramètre async de $.ajax() est toujours configuré sur true, ce qui indique que d'autres codes peuvent toujours être exécutés après le début de la requête. Il est fortement déconseillé de configurer cette option sur false, ce qui signifie que toutes les requêtes ne seront plus asynchrones, ce qui peut également bloquer le navigateur.

$.ajax renvoie l'objet XMLHttpRequest qu'il crée. Habituellement, jQuery ne traite et ne crée que cet objet en interne, mais l'utilisateur peut également transmettre un objet xhr qu'il a créé via l'option xhr. L'objet retourné est généralement jeté, mais il fournit toujours une interface de bas niveau pour observer et contrôler la requête. Par exemple, appeler .abort() sur l'objet peut suspendre la requête avant qu'elle ne soit terminée.

manuel de référence Ajax jQuery