jQuery.ajax()

La función $.ajax() es la base de todas las peticiones Ajax enviadas por jQuery. A menudo es innecesario llamar directamente a esta función, ya que existen varias alternativas de nivel superior como $.get() y .load() que están disponibles y son más fáciles de usar. Sin embargo, si se requieren opciones menos comunes, $.ajax() puede utilizarse de forma más flexible.

En su forma más simple, la función $.ajax() puede ser llamada sin argumentos:

$.ajax();

Nota: La configuración por defecto puede establecerse globalmente utilizando la función $.ajaxSetup().

Este ejemplo, sin opciones, carga el contenido de la página actual, pero no hace nada con el resultado. Para utilizar el resultado, puede implementar una de las funciones de devolución de llamada.

El objeto jqXHR

El objeto jQuery XMLHttpRequest (jqXHR) devuelto por $.ajax() a partir de jQuery 1.5 es un superconjunto del objeto XMLHttpRequest nativo del navegador. Por ejemplo, contiene las propiedades responseText y responseXML, así como un método getResponseHeader(). Cuando el mecanismo de transporte es algo distinto a XMLHttpRequest (por ejemplo, una etiqueta de script para una petición JSONP) el objeto jqXHR simula la funcionalidad nativa de XHR cuando es posible.

A partir de jQuery 1.5.1, el objeto jqXHR también contiene el método overrideMimeType() (también estaba disponible en jQuery 1.4.x, pero se eliminó temporalmente en jQuery 1.5). El método .overrideMimeType() puede utilizarse en la función de devolución de llamada beforeSend(), por ejemplo, para modificar la cabecera de tipo de contenido de la respuesta:

Los objetos jqXHR devueltos por $.ajax() a partir de jQuery 1.5 implementan la interfaz Promise, dándoles todas las propiedades, métodos y comportamiento de una Promise (ver objeto Deferred para más información). Estos métodos toman uno o más argumentos de función que son llamados cuando la solicitud $.ajax() termina. Esto permite asignar múltiples callbacks en una sola petición, e incluso asignar callbacks después de que la petición pueda haber terminado. (Si la solicitud ya está completa, la devolución de llamada se dispara inmediatamente). Los métodos Promise disponibles del objeto jqXHR incluyen:

La referencia this dentro de todas las devoluciones de llamada es el objeto de la opción context pasada a $.ajax en la configuración; si no se especifica contextthis es una referencia a la propia configuración de Ajax.

Por compatibilidad con el pasado con XMLHttpRequest, un objeto jqXHR expondrá las siguientes propiedades y métodos:

• readyState
• responseXML y/o responseText cuando la petición subyacente respondió con xml y/o texto, respectivamente
• status
• statusText (puede ser una cadena vacía en HTTP/2)
• abort( )
• getAllResponseHeaders() como cadena
• getResponseHeader( name )
• overrideMimeType( mimeType )
• setRequestHeader( name, value ) que se aparta del estándar sustituyendo el valor antiguo por el nuevo en lugar de concatenar el nuevo valor con el antiguo
• statusCode( callbacksByStatusCode )

No se proporciona ningún mecanismo onreadystatechange, sin embargo, ya que donefailalways, y statusCode cubren todos los requisitos concebibles.

Colas de funciones de devolución

Los beforeSenderrordataFiltersuccess y complete opciones todas aceptan funciones de devolución de llamada que se invocan en los momentos adecuados.

A partir de jQuery 1.5, los ganchos de devolución de llamada fail y done, y, a partir de jQuery 1.6, always son colas gestionadas por el primero en entrar, primero en salir, lo que permite más de una devolución de llamada para cada gancho. Consulte los métodos de objetos diferidos, que se implementan internamente para estos $.ajax() ganchos de devolución de llamada.

Los ganchos de devolución de llamada proporcionados por $.ajax() son los siguientes:

1. beforeSend opción de devolución de llamada se invoca; recibe el objeto jqXHR y el objeto settings como parámetros.
2. Se invoca la opción de callback error, si la petición falla. Recibe el jqXHR, una cadena que indica el tipo de error, y un objeto de excepción si es aplicable. Algunos errores incorporados proporcionarán una cadena como objeto de excepción: «abort», «timeout», «No Transport».
3. dataFilter la opción de callback se invoca inmediatamente después de la recepción exitosa de los datos de respuesta. Recibe los datos devueltos y el valor de dataType, y debe devolver los datos (posiblemente alterados) para pasarlos a success.
4. success opción de devolución de llamada se invoca, si la solicitud tiene éxito. Recibe los datos devueltos, una cadena que contiene el código de éxito, y el objeto jqXHR.
5. Las devoluciones de llamada de la promesa – .done().fail().always(), y .then() – se invocan, en el orden en que se registran.
6. La opción de callback complete se dispara, cuando la petición termina, ya sea en fallo o en éxito. Recibe el objeto jqXHR, así como una cadena que contiene el código de éxito o de error.

Tipos de datos

Los diferentes tipos de respuesta a la llamada $.ajax() son sometidos a diferentes tipos de preprocesamiento antes de ser pasados al controlador de éxito. El tipo de preprocesamiento depende por defecto del Content-Type de la respuesta, pero puede establecerse explícitamente mediante la opción dataType. Si se proporciona la opción dataType, no se tendrá en cuenta la cabecera Content-Type de la respuesta.

Los tipos de datos disponibles son texthtmlxmljsonjsonp, y script.

Si se especifica text o html, no se produce ningún preprocesamiento. Los datos simplemente se pasan al manejador de éxito, y se hacen disponibles a través de la propiedad responseText del objeto jqXHR.

Si se especifica xml, la respuesta se analiza con jQuery.parseXML antes de pasarla, como XMLDocument, al controlador de éxito. El documento XML está disponible a través de la propiedad responseXML del objeto jqXHR.

Si se especifica json, la respuesta se analiza utilizando jQuery.parseJSON antes de pasarla, como un objeto, al controlador de éxito. El objeto JSON analizado está disponible a través de la propiedad responseJSON del objeto jqXHR.

Si se especifica script$.ajax() ejecutará el JavaScript que se recibe del servidor antes de pasarlo al manejador de éxito como una cadena.

Si se especifica jsonp$.ajax() añadirá automáticamente un parámetro de cadena de consulta de (por defecto) callback=? a la URL. Las propiedades jsonp y jsonpCallback de la configuración pasada a $.ajax() pueden utilizarse para especificar, respectivamente, el nombre del parámetro de cadena de consulta y el nombre de la función de devolución de llamada JSONP. El servidor debe devolver un JavaScript válido que pase la respuesta JSON a la función callback. $.ajax() ejecutará el JavaScript devuelto, llamando a la función de devolución de llamada JSONP, antes de pasar el objeto JSON contenido en la respuesta al manejador de éxito $.ajax().

Para más información sobre JSONP, consulte el post original que detalla su uso.

Envío de datos al servidor

Por defecto, las peticiones Ajax se envían utilizando el método GET HTTP. Si se requiere el método POST, se puede especificar el método estableciendo un valor para la opción type. Esta opción afecta a cómo se envía el contenido de la opción data al servidor. Los datos POST siempre se transmitirán al servidor utilizando el conjunto de caracteres UTF-8, según el estándar XMLHTTPRequest del W3C.

La opción data puede contener una cadena de consulta de la forma key1=value1&key2=value2, o un objeto de la forma {key1: 'value1', key2: 'value2'}. Si se utiliza esta última forma, los datos se convierten en una cadena de consulta mediante jQuery.param() antes de ser enviados. Este procesamiento puede evitarse estableciendo processData como false. El procesamiento podría ser indeseable si desea enviar un objeto XML al servidor; en este caso, cambie la opción contentType de application/x-www-form-urlencoded a un tipo MIME más apropiado.

Opciones avanzadas

La opción global evita que los manejadores registrados con .ajaxSend().ajaxError() y métodos similares se disparen cuando esta solicitud los active. Esto puede ser útil para, por ejemplo, suprimir un indicador de carga que se implementó con .ajaxSend() si las peticiones son frecuentes y breves. En el caso de las solicitudes de script y JSONP entre dominios, la opción global se establece automáticamente en false. Consulte las descripciones de estos métodos a continuación para obtener más detalles.

Si el servidor realiza la autenticación HTTP antes de proporcionar una respuesta, el par de nombre de usuario y contraseña puede enviarse a través de las opciones username y password.

Las solicitudes Ajax tienen un tiempo de espera limitado, por lo que los errores pueden ser capturados y manejados para proporcionar una mejor experiencia de usuario. Los tiempos de espera de las peticiones suelen dejarse por defecto o establecerse como un valor global por defecto usando $.ajaxSetup() en lugar de anularse para peticiones específicas con la opción timeout.

Por defecto, las peticiones se emiten siempre, pero el navegador puede servir los resultados de su caché. Para no permitir el uso de los resultados de la caché, establezca cache en false. Para que la solicitud informe de un fallo si el activo no se ha modificado desde la última solicitud, establezca ifModified a true.

El scriptCharset permite especificar explícitamente el conjunto de caracteres para las solicitudes que utilizan una etiqueta <script> (es decir, un tipo de script o jsonp). Esto es útil si el script y la página anfitriona tienen conjuntos de caracteres diferentes.

La primera letra de Ajax significa «asíncrono», lo que significa que la operación ocurre en paralelo y el orden de finalización no está garantizado. La opción async a $.ajax() por defecto es true, lo que indica que la ejecución del código puede continuar después de la solicitud. Establecer esta opción a false (y, por tanto, hacer que la llamada deje de ser asíncrona) está totalmente desaconsejado, ya que puede hacer que el navegador deje de responder.

La función $.ajax() devuelve el objeto XMLHttpRequest que crea. Normalmente jQuery maneja la creación de este objeto internamente, pero se puede especificar una función personalizada para fabricar uno usando la opción xhr. El objeto devuelto generalmente puede ser descartado, pero proporciona una interfaz de nivel inferior para observar y manipular la solicitud. En particular, llamar a .abort() en el objeto detendrá la solicitud antes de que se complete.

Ampliar Ajax

A partir de jQuery 1.5, la implementación de Ajax de jQuery incluye prefiltros, transportes y convertidores que permiten extender Ajax con una gran flexibilidad.

Usando convertidores

$.ajax() los convertidores soportan el mapeo de tipos de datos a otros tipos de datos. Sin embargo, si quieres mapear un tipo de datos personalizado a un tipo conocido (por ejemplo json), debes añadir una correspondencia entre el Content-Type de la respuesta y el tipo de datos real utilizando la opción contents:

Este objeto extra es necesario porque los Content-Types de la respuesta y los tipos de datos nunca tienen una correspondencia estricta uno a uno (de ahí la expresión regular).

Para convertir de un tipo soportado (e.g textjson) a un tipo de datos personalizado y viceversa, utilice otro convertidor de paso:

Lo anterior permite ahora pasar de text a mycustomtype y luego mycustomtype a json.