Método ajax() de jQuery ajax

Manual de Referencia de jQuery Ajax

Ejemplo

Cargar un fragmento de texto mediante AJAX:

Código jQuery:}

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

Código HTML:

<div id="myDiv"><h2>Deje que AJAX cambie este texto</h2></div>
<button id="b01" type="button">Cambiar Contenido</button>

Prueba personalmente

Definición y uso

El método ajax() carga datos remotos a través de solicitudes HTTP.

Este es el método AJAX de nivel inferior de jQuery. Véase $.get, $.post, etc. para una implementación de nivel superior fácil de usar. $.ajax() devuelve el objeto XMLHttpRequest que ha creado. En la mayoría de los casos, no es necesario operar directamente con esta función, a menos que necesite operar opciones no comunes para obtener más flexibilidad.

En el caso más simple, $.ajax() se puede usar directamente sin parámetros.

Atención:Todas las opciones pueden ser configuradas globalmente a través de la función $.ajaxSetup().

sintaxis

jQuery.ajax([ajustes])
parámetros descripción
ajustes

Opcional. Conjunto de pares clave para configurar solicitudes Ajax.

Se puede configurar cualquier opción predeterminada a través de $.ajaxSetup().

parámetros

opciones

Tipo: Object

Opcional. Configuración de solicitud Ajax. Todas las opciones son opcionales.

async

Tipo: Booleano

Valor predeterminado: true. Bajo la configuración predeterminada, todas las solicitudes son asincrónicas. Si es necesario enviar solicitudes sincrónicas, configure esta opción como false.

Atención, las solicitudes sincrónicas bloquearán el navegador, y el usuario debe esperar a que se complete la solicitud antes de poder ejecutar otras operaciones.

beforeSend(XHR)

Tipo: Función

Se puede modificar el objeto XMLHttpRequest antes de enviar la solicitud, como agregar encabezados HTTP personalizados.

El objeto XMLHttpRequest es el único parámetro.

Este es un evento Ajax. Si se devuelve false, se puede cancelar esta solicitud Ajax.

cache

Tipo: Booleano

Valor predeterminado: true, cuando dataType es script y jsonp, el valor predeterminado es false. Establecer false no almacenará esta página en caché.

Nuevas características de jQuery 1.2.

complete(XHR, TS)

Tipo: Función

Función de devolución de llamada después de que se complete la solicitud (se llama después de que se complete la solicitud, ya sea que sea exitosa o fallida).

Parámetros: objeto XMLHttpRequest y una cadena que describe el tipo de solicitud.

Este es un evento Ajax.

contentType

Tipo: Cadenas

Valor predeterminado: "application/x-www-form-urlencoded". El tipo de codificación de contenido para enviar información al servidor.

El valor predeterminado es adecuado para la mayoría de los casos. Si se pasa explícitamente un content-type a $.ajax(), se enviará al servidor (incluso si no hay datos que enviar).

context

Tipo: Object

Este objeto se utiliza para establecer el contexto de las funciones de devolución de llamada relacionadas con Ajax. Es decir, hacer que this dentro de la función de devolución de llamada apunte a este objeto (si no se establece este parámetro, then this apunta a los parámetros options transmitidos al llamar a esta solicitud AJAX). Por ejemplo, si se especifica un elemento DOM como parámetro context, se establece el contexto de la función de devolución de llamada success para este elemento DOM.

como así:

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

Tipo: Cadenas

Los datos enviados al servidor. Se convertirán automáticamente al formato de cadena de solicitud. Se adjuntará al final de la URL en solicitudes GET. Consulte la descripción de las opciones processData para prohibir esta conversión automática. Debe estar en formato Key/Value. Si es un array, jQuery lo convertirá automáticamente para valores diferentes del mismo nombre. Por ejemplo, {foo: ["bar1", "bar2"]} se convertirá en '&foo=bar1&foo=bar2'.

dataFilter

Tipo: Función

La función de preprocesamiento de datos originales devueltos por Ajax. Proporciona dos parámetros: data es los datos originales devueltos por Ajax, y type es el parámetro dataType proporcionado al llamar a jQuery.ajax. El valor devuelto por la función se procesará adicionalmente por jQuery.

dataType

Tipo: Cadenas

El tipo de datos de retorno esperado del servidor. Si no se especifica, jQuery lo identificará automáticamente según la información MIME del paquete HTTP, por ejemplo, el tipo MIME XML se identificará como XML. En la versión 1.4, JSON generará un objeto JavaScript, mientras que script ejecutará este script. Luego, los datos devueltos por el servidor se analizarán según este valor y se transmitirán a la función de devolución de llamada. Los valores disponibles son:

  • "xml": devuelve un documento XML, que jQuery puede procesar.
  • "html": devuelve información HTML puro; las etiquetas script incluidas se ejecutarán al insertarse en el DOM.
  • "script": devuelve código JavaScript puro. No se almacenará automáticamente el resultado. A menos que se configure el parámetro "cache". Nota: en solicitudes remotas (no en el mismo dominio), todas las solicitudes POST se convertirán en solicitudes GET. (porque se usará la etiqueta script del DOM para cargar)
  • "json": devuelve datos JSON.
  • "jsonp": formato JSONP. Al llamar a la función con formato JSONP, como "myurl?callback=?", jQuery reemplazará automáticamente ? por el nombre de la función correcto para ejecutar la función de devolución de llamada.
  • "text": devuelve una cadena de texto pura
error

Tipo: Función

Valor predeterminado: auto (xml o html). Llama a esta función cuando falla la solicitud.

Tiene los siguientes tres parámetros: objeto XMLHttpRequest, información de error, (opcional) objeto de excepción capturado.

Si ocurre un error, la información de error (segundo parámetro) además de null, también puede ser "timeout", "error", "notmodified" y "parsererror".

Este es un evento Ajax.

global

Tipo: Booleano

¿Dispara eventos AJAX globales?. Valor predeterminado: true. Establecer a false no disparará eventos AJAX globales, como ajaxStart o ajaxStop se pueden usar para controlar diferentes eventos Ajax.

ifModified

Tipo: Booleano

Obtén nuevos datos solo cuando los datos del servidor cambian. Valor predeterminado: false. Se utiliza la información de encabezado Last-Modified del paquete HTTP para determinar. En jQuery 1.4, también verificará el 'etag' especificado por el servidor para determinar si los datos no han sido modificados.

jsonp

Tipo: Cadenas

Reescribe el nombre de la función de devolución de llamada en una solicitud jsonp. Este valor se utiliza para reemplazar la parte "callback" en los parámetros de URL de solicitudes GET o POST como "callback=?", por ejemplo {jsonp:'onJsonPLoad'} causará que se envíe "onJsonPLoad=?" al servidor.

jsonpCallback

Tipo: Cadenas

Especifique un nombre de función de retroalimentación para la solicitud jsonp. Este valor se utilizará para reemplazar el nombre de función generado aleatoriamente por jQuery. Esto se utiliza principalmente para que jQuery genere nombres de función únicos, lo que facilita la gestión de solicitudes y permite proporcionar funciones de retroalimentación y manejo de errores de manera más conveniente. También se puede especificar este nombre de función de retroalimentación cuando se desee que el navegador cachee solicitudes GET.

password

Tipo: Cadenas

Se utiliza para la respuesta de la contraseña de la solicitud de autenticación HTTP.

processData

Tipo: Booleano

Valor predeterminado: true. Por defecto, los datos pasados a través de la opción data, si es un objeto (tecnológicamente, siempre que no sea una cadena), se procesan para convertirse en una cadena de consulta, para coincidir con el tipo de contenido predeterminado "application/x-www-form-urlencoded". Si desea enviar información de un árbol DOM u otra información que no desee convertir, configure esto como false.

scriptCharset

Tipo: Cadenas

Sólo se utiliza para modificar forzadamente el charset cuando dataType es "jsonp" o "script" y type es "GET". Generalmente se utiliza cuando el contenido de codificación local y remoto es diferente.

success

Tipo: Función

Función de retroalimentación después de que la solicitud sea exitosa.

Parámetros: los datos devueltos por el servidor, procesados según el parámetro dataType; la cadena que describe el estado.

Este es un evento Ajax.

traditional

Tipo: Booleano

Si desea serializar los datos de manera tradicional, configure esto como true. Consulte el método jQuery.param en la categoría de herramientas.

timeout

Tipo: Número

Establecer el tiempo de espera de la solicitud (milisegundos). Esta configuración sobrescribirá la configuración global.

type

Tipo: Cadenas

Valor predeterminado: "GET")). Método de solicitud ("POST" o "GET"), predeterminado "GET". Nota: otros métodos de solicitud HTTP, como PUT y DELETE, también se pueden usar, pero solo son compatibles con algunos navegadores.

url

Tipo: Cadenas

Valor predeterminado: la dirección de la página actual. La dirección de envío de la solicitud.

username

Tipo: Cadenas

Se utiliza para la respuesta del nombre de usuario de la solicitud de autenticación HTTP.

xhr

Tipo: Función

Es necesario devolver un objeto XMLHttpRequest. Por defecto en IE es ActiveXObject y en otros casos XMLHttpRequest. Se utiliza para sobrescribir o proporcionar un objeto XMLHttpRequest mejorado. Este parámetro no estaba disponible antes de jQuery 1.3.

Funciones de callback

Si se necesita procesar los datos obtenidos con $.ajax(), se debe utilizar el callback: beforeSend, error, dataFilter, success, complete.

beforeSend

Llame a esta función antes de enviar la solicitud y transmítale un objeto XMLHttpRequest.

error

Llame a esta función cuando la solicitud falle. Introduzca el objeto XMLHttpRequest, una cadena que describa el tipo de error y un objeto de excepción (si lo hay).

dataFilter

Llame a esta función después de que la solicitud tenga éxito. Introduzca los datos devueltos y el valor del parámetro 'dataType'. Y debe devolver los nuevos datos (posiblemente procesados) que se transmitirán al callback de éxito.

success

Llame a esta función después de que se realice la solicitud. Introduzca los datos devueltos y una cadena que contenga un código de éxito.

complete

Llame a esta función después de que se complete la solicitud, sin importar si tiene éxito o no. Introduzca el objeto XMLHttpRequest y una cadena que contenga un código de éxito o error.

Tipo de datos

La función $.ajax() depende de la información proporcionada por el servidor para procesar los datos devueltos. Si el servidor informa que los datos devueltos son XML, los resultados se pueden recorrer con métodos XML comunes o selectores de jQuery. Si se detectan otros tipos, como HTML, los datos se tratan como texto.

A través de la opción dataType se puede especificar otros métodos de procesamiento de datos diferentes. Además del simple XML, también se puede especificar html, json, jsonp, script o text.

En el caso de los tipos text y xml, los datos devueltos no se procesan. Los datos se transmiten simplemente al callback de éxito mediante las propiedades responseText o responseHTML de XMLHttpRequest.

Atención:Debemos asegurarnos de que el tipo MIME reportado por el servidor web coincida con el dataType seleccionado. Por ejemplo, si es XML, el servidor debe declarar text/xml o application/xml para obtener resultados consistentes.

Si se especifica el tipo html, cualquier JavaScript incrustado se ejecutará antes de que el HTML se devuelva como una cadena. De manera similar, si se especifica el tipo script, también se ejecutará primero el JavaScript generado en el lado del servidor, antes de devolver el script como datos de texto.

Si se especifica como tipo 'json', los datos obtenidos se analizarán como un objeto JavaScript y se devolverá el objeto construido. Para lograr este objetivo, primero intenta usar JSON.parse(). Si el navegador no lo admite, se utiliza una función para construir.

Los datos JSON son una estructura de datos estructurada que se puede analizar fácilmente a través de JavaScript. Si los archivos de datos se almacenan en un servidor remoto (es decir, se obtienen datos de otro dominio, también conocido como acceso a datos de otro dominio), se debe utilizar el tipo 'jsonp'. Al usar este tipo, se crea un parámetro de cadena de consulta 'callback=?', que se agrega al final de la URL de la solicitud. El lado del servidor debe agregar el nombre de la función de devolución de llamada antes de los datos JSON para completar una solicitud JSONP válida. Si se desea especificar el nombre del parámetro de la función de devolución de llamada para reemplazar el predeterminado 'callback', se puede configurar el parámetro 'jsonp' de $.ajax().

Atención:JSONP es una extensión del formato JSON. Requiere algunos códigos en el lado del servidor para detectar y procesar los parámetros de la cadena de consulta.

Si se especifica el tipo 'script' o 'jsonp', cuando se recibe datos del servidor, se utiliza la etiqueta <script> en lugar del objeto XMLHttpRequest. En este caso, $.ajax() ya no devuelve un objeto XMLHttpRequest y ni siquiera pasa funciones de manejo de eventos, como 'beforeSend'.

Enviar datos al servidor

Por defecto, las solicitudes Ajax utilizan el método GET. Si se desea utilizar el método POST, se puede establecer el valor del parámetro 'type'. Esta opción también afecta a cómo se envía el contenido de la opción 'data' al servidor.

La opción 'data' puede contener una cadena de consulta, como key1=value1&key2=value2, o puede ser un mapeo, como {key1: 'value1', key2: 'value2'}. Si se utiliza la última forma, los datos se convertirán en una cadena de consulta en el transmisor. Este proceso también se puede evitar configurando la opción 'processData' en false. Si queremos enviar un objeto XML al servidor, este procesamiento puede no ser adecuado. Y en este caso, también deberíamos cambiar el valor de la opción 'contentType' a otro tipo MIME adecuado en lugar del predeterminado 'application/x-www-form-urlencoded'.

Opciones avanzadas

La opción global se utiliza para evitar que los funciones de retroalimentación de respuesta registradas, como .ajaxSend, o ajaxError, y métodos similares. Esto es útil en algunas situaciones, como cuando se envían solicitudes muy frecuentes y cortas, se puede deshabilitar esta en ajaxSend.

Si el servidor requiere autenticación HTTP, se puede usar el nombre de usuario y la contraseña a través de las opciones username y password para configurar.

Las solicitudes Ajax tienen un límite de tiempo, por lo que después de capturar y procesar las alertas de error, se puede utilizar para mejorar la experiencia del usuario. Generalmente se mantiene el valor predeterminado de este parámetro de tiempo de expiración, o se establece globalmente a través de jQuery.ajaxSetup, raramente se reestablece la opción timeout para solicitudes específicas.

Por defecto, siempre se enviará la solicitud, pero el navegador puede recuperar datos de su caché. Para prohibir el uso de los resultados de la caché, puede establecer el parámetro cache en false. Si desea que se reporte un error cuando los datos no hayan cambiado desde la última solicitud, puede establecer ifModified en true.

scriptCharset permite establecer un conjunto de caracteres específico para la solicitud de la etiqueta <script>, utilizado para scripts o datos similares a jsonp. Es particularmente útil cuando los scripts y el conjunto de caracteres de la página son diferentes.

La primera letra de Ajax es la inicial de asynchronous, lo que significa que todas las operaciones son paralelas y no tienen una secuencia de completamiento. El parámetro async de $.ajax() siempre se establece en true, lo que indica que otros códigos pueden ejecutarse mientras se inicia la solicitud. No se recomienda establecer esta opción en false, lo que significa que todas las solicitudes ya no son asincrónicas, lo que también puede llevar a que el navegador se bloquee.

$.ajax devuelve el objeto XMLHttpRequest que crea. Por lo general, jQuery maneja internamente y crea este objeto, pero el usuario también puede pasar un objeto xhr creado por sí mismo a través de la opción xhr. El objeto devuelto generalmente se desecha, pero aún se proporciona una interfaz de bajo nivel para observar y controlar la solicitud. Por ejemplo, llamar a .abort() en el objeto puede suspender la solicitud antes de que se complete.

Manual de Referencia de jQuery Ajax