jQuery.ajax()

The $.ajax() function under underzes all Ajax requests sent by jQuery. É frequentemente desnecessário chamar directamente esta função, uma vez que várias alternativas de nível superior como $.get() e .load() estão disponíveis e são mais fáceis de usar. Se opções menos comuns forem necessárias, porém, $.ajax() podem ser utilizadas de forma mais flexível.

Na sua forma mais simples, a função $.ajax() pode ser chamada sem argumentos:

$.ajax();

Nota: As configurações padrão podem ser definidas globalmente usando a função $.ajaxSetup().

Este exemplo, sem usar opções, carrega o conteúdo da página actual, mas não faz nada com o resultado. Para utilizar o resultado, pode implementar uma das funções de retorno de chamada.

O objecto jqXHR

O objecto jQuery XMLHttpRequest (jqXHR) devolvido por $.ajax() a partir de jQuery 1.5 é um superconjunto do objecto XMLHttpRequest nativo do navegador. Por exemplo, contém responseText e responseXML propriedades, bem como um método getResponseHeader(). Quando o mecanismo de transporte é algo diferente do XMLHttpRequest (por exemplo, uma etiqueta de script para um pedido JSONP) o objecto jqXHR simula a funcionalidade nativa XHR sempre que possível.

As de jQuery 1.5.1, o objecto jqXHR também contém o método overrideMimeType() (também estava disponível em jQuery 1.4.x, mas foi temporariamente removido em jQuery 1.5). O método .overrideMimeType() pode ser usado no método beforeSend() função callback, por exemplo, para modificar o cabeçalho do tipo de conteúdo de resposta:

Os objectos jqXHR devolvidos por $.ajax() a partir de jQuery 1.5 implementar a interface Promise, dando-lhes todas as propriedades, métodos, e comportamento de uma Promise (ver Objecto diferido para mais informações). Estes métodos tomam um ou mais argumentos de função que são chamados quando o $.ajax() pedido termina. Isto permite atribuir várias chamadas de retorno num único pedido, e mesmo atribuir chamadas de retorno após o pedido ter sido concluído. (Se o pedido já estiver completo, a chamada de retorno é imediatamente despedida.) Os métodos de promessa disponíveis do objecto jqXHR incluem:

O this referência dentro de todas as chamadas de retorno é o objecto no context opção passada para $.ajax nas definições; se context não estiver especificado, this é uma referência às próprias configurações do Ajax.

Para compatibilidade retroactiva com XMLHttpRequest, um objecto jqXHR irá expor as seguintes propriedades e métodos:

• readyState
• responseXML e/ou responseText quando o pedido subjacente respondeu com xml e/ou texto, respectivamente
• status
• statusText (pode ser uma cadeia vazia em HTTP/2)
• abort( )
• getAllResponseHeaders() como uma cadeia
• getResponseHeader( name )
• overrideMimeType( mimeType )
• setRequestHeader( name, value ) que se afasta do padrão ao substituir o valor antigo pelo novo em vez de concatenar o novo valor com o antigo
• statusCode( callbacksByStatusCode )

No onreadystatechange mecanismo é fornecido, no entanto, desde donefailalways, e statusCode cobrem todos os requisitos concebíveis.

Linhas de funções de retorno

O beforeSenderrordataFiltersuccess e complete opções todas aceitam funções de chamada de retorno que são invocadas nos momentos apropriados.

As de jQuery 1.5, as fail e done, e, a partir de jQuery 1.6, always os ganchos de callback são filas geridas primeiro a entrar, primeiro a sair, permitindo mais do que uma callback para cada gancho. Ver Métodos de objectos diferidos, que são implementados internamente para estes $.ajax() ganchos de callback.

Os ganchos de revogação fornecidos por $.ajax() são os seguintes:

1. beforeSend a opção de revogação é invocada; recebe o objecto jqXHR e o objecto settings como parâmetros.
2. error opção callback é invocada, se o pedido falhar. Recebe o jqXHR, uma string indicando o tipo de erro, e um objecto de excepção, se aplicável. Alguns erros integrados fornecerão uma cadeia de caracteres como objecto de excepção: “abort”, “timeout”, “No Transport”.
3. dataFilter a opção callback é invocada imediatamente após a recepção bem sucedida dos dados de resposta. Recebe os dados devolvidos e o valor de dataType, e deve devolver os dados (possivelmente alterados) para transmitir a success.
4. success opção de retorno é invocada, se o pedido for bem sucedido. Recebe os dados devolvidos, uma string contendo o código de sucesso, e o objecto jqXHR.
5. Promise callbacks – .done().fail().always(), e .then() – são invocados, na ordem em que são registados.
6. complete a opção callback dispara, quando o pedido termina, seja em falha ou em sucesso. Recebe o objecto jqXHR, bem como uma string contendo o código de sucesso ou erro.

Tipos de dados

Diferentes tipos de resposta a $.ajax() chamada são sujeitos a diferentes tipos de pré-processamento antes de serem passados ao responsável pelo sucesso. O tipo de pré-processamento depende por defeito do Tipo de Conteúdo da resposta, mas pode ser definido explicitamente usando a opção dataType. Se a opção dataType for fornecida, o cabeçalho Content-Type da resposta será desconsiderado.

Os tipos de dados disponíveis são texthtmlxmljsonjsonp, e script.

se text ou html for especificado, não ocorre nenhum pré-processamento. Os dados são simplesmente transmitidos ao manipulador de sucesso, e disponibilizados através do objecto responseText propriedade do objecto jqXHR.

Se xml for especificado, a resposta é analisada utilizando jQuery.parseXML antes de ser passada, como um XMLDocument, para o manipulador de sucesso. O documento XML é disponibilizado através do responseXML propriedade do jqXHR objecto.

Se json for especificado, a resposta é analisada usando , antes de ser passada, como um objecto, ao manipulador de sucesso. O objecto parsed JSON é disponibilizado através do objecto responseJSON propriedade do objecto jqXHR.

se script for especificado, $.ajax() executará o JavaScript que é recebido do servidor antes de o passar para o manipulador de sucesso como uma string.

se jsonp for especificado, $.ajax() anexará automaticamente um parâmetro de query string de (por defeito) callback=? ao URL. O parâmetro jsonp e jsonpCallback propriedades das definições passadas para $.ajax() podem ser usadas para especificar, respectivamente, o nome do parâmetro da cadeia de consulta e o nome da função de retorno de chamada JSONP. O servidor deve retornar um JavaScript válido que passe a resposta JSON para a função de retorno de chamada. $.ajax() executará o JavaScript retornado, chamando a função de retorno de chamada JSONP, antes de passar o objecto JSON contido na resposta ao $.ajax() manipulador de sucesso.

Para mais informações sobre o JSONP, ver o post original detalhando a sua utilização.

Enviar Dados ao Servidor

Por defeito, os pedidos Ajax são enviados utilizando o método GET HTTP. Se o método POST for necessário, o método pode ser especificado definindo um valor para a opção type. Esta opção afecta a forma como o conteúdo da opção data é enviado para o servidor. Os dados POST serão sempre transmitidos para o servidor utilizando o conjunto de caracteres UTF-8, segundo o padrão XMLHTTPRequest do W3C.

A opção data pode conter ou uma cadeia de consulta do formulário key1=value1&key2=value2, ou um objecto do formulário {key1: 'value1', key2: 'value2'}. Se este último formulário for utilizado, os dados são convertidos numa cadeia de consulta usando jQuery.param(), antes de serem enviados. Este processamento pode ser contornado definindo processData a false. O processamento pode ser indesejável se desejar enviar um objecto XML para o servidor; neste caso, alterar a opção contentType de application/x-www-form-urlencoded para um tipo MIME mais apropriado.

Opções Avançadas

O global opção impede os manipuladores registados usando .ajaxSend().ajaxError(), e métodos semelhantes de disparo quando este pedido os desencadearia. Isto pode ser útil, por exemplo, para suprimir um indicador de carga que foi implementado com .ajaxSend(), se os pedidos forem frequentes e breves. Com o script de domínio cruzado e pedidos JSONP, a opção global é automaticamente definida para false. Veja as descrições destes métodos abaixo para mais detalhes.

Se o servidor executa autenticação HTTP antes de fornecer uma resposta, o par de nome de utilizador e palavra-passe pode ser enviado através do par username e password options.

As requisições de Ajax são limitadas no tempo, pelo que os erros podem ser apanhados e tratados para proporcionar uma melhor experiência ao utilizador. Os intervalos de tempo dos pedidos são normalmente deixados no seu padrão ou definidos como padrão global usando $.ajaxSetup() em vez de serem anulados para pedidos específicos com o timeout option.

Por padrão, os pedidos são sempre emitidos, mas o navegador pode servir resultados fora da sua cache. Para proibir a utilização dos resultados em cache, definir cache para false. Para causar o pedido de denúncia de falha se o activo não tiver sido modificado desde o último pedido, definir ifModified a true.

O scriptCharset permite que o conjunto de caracteres seja explicitamente especificado para pedidos que utilizam um <script> tag (ou seja, um tipo de script ou jsonp). Isto é útil se o script e a página anfitriã tiverem conjuntos de caracteres diferentes.

A primeira letra em Ajax significa “assíncrono”, o que significa que a operação ocorre em paralelo e que a ordem de conclusão não é garantida. O async opção para $.ajax() padrão para true, indicando que a execução do código pode continuar após o pedido ser feito. A definição desta opção para false (e assim fazendo a chamada já não assíncrona) é fortemente desencorajada, pois pode fazer com que o browser fique sem resposta.

O $.ajax() função retorna o XMLHttpRequest objecto que cria. Normalmente jQuery trata da criação deste objecto internamente, mas uma função personalizada para fabricar um pode ser especificada usando a opção xhr. O objecto devolvido pode geralmente ser descartado, mas fornece uma interface de nível inferior para observar e manipular o pedido. Em particular, chamando .abort() sobre o objecto suspenderá o pedido antes de este estar completo.

Extendendo Ajax

As de jQuery 1.5, a implementação de jQuery Ajax inclui pré-filtros, transportes, e conversores que permitem estender Ajax com grande flexibilidade.

Using Converters

$.ajax() conversores suportam tipos de dados cartográficos para outros tipos de dados. Se, contudo, desejar mapear um tipo de dados personalizado a um tipo conhecido (por exemplo json), deve adicionar uma correspondência entre a resposta Tipo de conteúdo e o tipo de dados real usando o contents opção:

Este objecto extra é necessário porque a resposta Tipo de conteúdo e tipos de dados nunca têm uma correspondência estrita um-para-um (daí a expressão regular).

Para converter a partir de um tipo suportado (e.g textjson) para um tipo de dados personalizado e vice-versa, utilizar outro conversor de passagem:

O acima permite agora passar de text a mycustomtype e depois mycustomtype a json.