Método jQuery ajax - ajax()

Manual de Referência do jQuery Ajax

Exemplo

Carregar um trecho de texto usando 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>Deixe o AJAX mudar este texto</h2></div>
<button id="b01" type="button">Mudar Conteúdo</button>

Experimente você mesmo

Definição e uso

O método ajax() carrega dados remotos através de solicitações HTTP.

Este método é a implementação AJAX de baixo nível do jQuery. Implementações de alto nível, fáceis de usar, incluem $.get, $.post, etc. $.ajax() retorna o objeto XMLHttpRequest que ele criou. Na maioria das vezes, você não precisa manipular diretamente essa função, a menos que precise manipular opções não comuns para obter mais flexibilidade.

No caso mais simples, $.ajax() pode ser usado diretamente sem qualquer parâmetro.

Atenção:Todos os opções podem ser configurados globalmente usando a função $.ajaxSetup().

Sintaxe

jQuery.ajax([settings])
Parâmetros Descrição
settings

Opcional. Conjunto de pares de chave-valor para configurar solicitações Ajax.

Qualquer opção pode ser configurada como valor padrão usando $.ajaxSetup().

Parâmetros

options

Tipo: Object

Opcional. Configurações de solicitação Ajax. Todas as opções são opcionais.

async

Tipo: Booleano

Valor padrão: true. Padrão, todas as solicitações são assíncronas. Se precisar enviar uma solicitação síncrona, defina essa opção como false.

Atenção, as solicitações síncronas trancarão o navegador, e outras operações do usuário devem esperar até que a solicitação seja concluída para serem executadas.

beforeSend(XHR)

Tipo: Função

Função para modificar o objeto XMLHttpRequest antes de enviar a solicitação, como adicionar cabeçalhos HTTP personalizados.

O objeto XMLHttpRequest é o único parâmetro.

Este é um evento Ajax. Se retornar false, a solicitação Ajax atual pode ser cancelada.

cache

Tipo: Booleano

Valor padrão: true, dataType para script e jsonp é false por padrão. Definir como false não armazenará essa página em cache.

Novas funcionalidades do jQuery 1.2.

complete(XHR, TS)

Tipo: Função

Função de callback chamada após a conclusão da solicitação (chamada após o sucesso ou falha da solicitação).

Parâmetros: objeto XMLHttpRequest e uma string que descreve o tipo de solicitação.

Este é um evento Ajax.

contentType

Tipo: String

Valor padrão: "application/x-www-form-urlencoded". O tipo de codificação de conteúdo ao enviar informações para o servidor.

O valor padrão é adequado para a maioria das situações. Se você passar explicitamente um content-type para o $.ajax(), ele será enviado para o servidor (mesmo que não haja dados para enviar).

context

Tipo: Object

Este objeto é usado para definir o contexto das funções de callback relacionadas ao Ajax. Isso significa que o this dentro da função de callback aponta para este objeto (se não for definido este parâmetro, o this aponta para o parâmetro options passado na chamada AJAX). Por exemplo, se for especificado um elemento DOM como parâmetro context, isso define o contexto da função de callback success para este elemento DOM.

assim:

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

Tipo: String

Os dados enviados para o servidor. Serão automaticamente convertidos para o formato de string de solicitação. Serão anexados ao final da URL em solicitações GET. Consulte as descrições das opções processData para desativar esta conversão automática. Deve ser no formato Key/Value. Se for um array, o jQuery automaticamente atribui o mesmo nome a diferentes valores. Por exemplo, {foo: ["bar1", "bar2"]} é convertido em '&foo=bar1&foo=bar2'.

dataFilter

Tipo: Função

Função de pré-processamento dos dados originais retornados pelo Ajax. Fornece os parâmetros data e type: data são os dados originais retornados pelo Ajax, e type é o parâmetro dataType fornecido ao jQuery.ajax. O valor retornado pela função será processado adicionalmente pelo jQuery.

dataType

Tipo: String

O tipo de dados esperado de volta do servidor. Se não for especificado, o jQuery automaticamente determina inteligentemente com base na informação MIME do pacote HTTP, por exemplo, o tipo MIME XML é reconhecido como XML. No 1.4, JSON gera um objeto JavaScript e script executa este script. Em seguida, os dados retornados pelo servidor são analisados com base neste valor e passados para a função de callback. Valores disponíveis:

  • "xml": retorna um documento XML, processável pelo jQuery.
  • "html": retorna informações HTML puro; os tags script incluídos serão executados ao serem inseridos no dom.
  • "script": retorna código JavaScript puro. Não armazenará automaticamente o resultado. A menos que o parâmetro "cache" seja definido. Nota: em solicitações remotas (não no mesmo domínio), todas as solicitações POST serão convertidas em GET (porque será usado o tag script do DOM para carregar).
  • "json": retorna dados JSON .
  • "jsonp": formato JSONP. Quando a função é chamada usando JSONP, como "myurl?callback=?", o jQuery automaticamente substituirá ? pelo nome correto da função para executar a função de callback.
  • "text": retorna uma string de texto puro
error

Tipo: Função

Valor padrão: auto-determinação (xml ou html). Chamar essa função quando a solicitação falhar.

Existem três parâmetros: objeto XMLHttpRequest, mensagem de erro, (opcional) objeto de exceção capturado.

Se ocorrer um erro, a mensagem de erro (segundo parâmetro) além de null, pode ser "timeout", "error", "notmodified" e "parsererror".

Este é um evento Ajax.

global

Tipo: Booleano

Se deve acionar eventos AJAX globais. Valor padrão: true. Definir como false não acionará eventos AJAX globais, como ajaxStart ou ajaxStop podem ser usados para controlar diferentes eventos Ajax.

ifModified

Tipo: Booleano

Obter novos dados apenas quando os dados do servidor forem alterados. Valor padrão: false. Usar a cabeçalha Last-Modified do pacote HTTP para determinar. No jQuery 1.4, também verificará o 'etag' especificado pelo servidor para determinar se os dados não foram modificados.

jsonp

Tipo: String

Reescrever o nome da função de callback em uma solicitação jsonp. Este valor é usado para substituir a parte "callback" do parâmetro URL em solicitações GET ou POST do tipo "callback=?", por exemplo, {jsonp:'onJsonPLoad'} resultará em "onJsonPLoad=?" sendo enviado ao servidor.

jsonpCallback

Tipo: String

Especifique um nome de função de chamada de volta para solicitações jsonp. Este valor será usado para substituir o nome de função gerado automaticamente pelo jQuery. Isso é principalmente usado para permitir que o jQuery gere nomes de função únicos, facilitando a gestão de solicitações, fornecendo funções de chamada de volta e tratamento de erros. Você também pode especificar este nome de função de chamada de volta para que o navegador cache solicitações GET.

password

Tipo: String

Usado para fornecer a senha que responde a uma solicitação de autenticação HTTP.

processData

Tipo: Booleano

Valor padrão: true. Padrão, dados passados através da opção data, se forem um objeto (teoricamente, qualquer coisa que não seja uma string), serão transformados em uma string de consulta para coincidir com o tipo de conteúdo padrão "application/x-www-form-urlencoded". Se você quiser enviar informações de um DOM ou outro tipo de informação que não deseja transformar, configure como false.

scriptCharset

Tipo: String

Usado apenas quando o dataType da solicitação é "jsonp" ou "script" e o tipo é "GET" para forçar a modificação do charset. Geralmente usado quando o conteúdo de codificação local e remoto é diferente.

success

Tipo: Função

Função de chamada de volta após a solicitação bem-sucedida.

Parâmetros: dados retornados pelo servidor, processados com base no parâmetro dataType; string que descreve o estado.

Este é um evento Ajax.

traditional

Tipo: Booleano

Se você quiser serializar dados de maneira tradicional, configure como true. Veja o método jQuery.param na seção Ferramentas.

timeout

Tipo: Número

Define o tempo de espera da solicitação (milissegundos). Esta configuração substitui a configuração global.

type

Tipo: String

Valor padrão: "GET")). Método de solicitação ("POST" ou "GET"), padrão é "GET". Nota: Outros métodos de solicitação HTTP, como PUT e DELETE, também podem ser usados, mas são suportados apenas por alguns navegadores.

url

Tipo: String

Valor padrão: endereço da página atual. Endereço da solicitação enviada.

username

Tipo: String

Usado para fornecer o nome de usuário que responde a uma solicitação de autenticação HTTP.

xhr

Tipo: Função

É necessário retornar um objeto XMLHttpRequest. Padrão no IE é ActiveXObject e em outras situações é XMLHttpRequest. Usado para reescrever ou fornecer um objeto XMLHttpRequest melhorado. Este parâmetro não estava disponível antes da jQuery 1.3.

Funções de callback

Para processar os dados obtidos com $.ajax(), é necessário usar funções de callback: beforeSend, error, dataFilter, success, complete.

beforeSend

Chamado antes de enviar a solicitação e passa o XMLHttpRequest como parâmetro.

error

Chamado quando ocorre um erro na solicitação. Passa o objeto XMLHttpRequest, uma string que descreve o tipo de erro e um objeto de exceção (se houver).

dataFilter

Chamado após a solicitação com sucesso. Passa os dados retornados e o valor do parâmetro "dataType". E deve retornar novos dados (possivelmente processados) para a função de callback success.

success

Chamado após a solicitação. Passa os dados retornados e uma string contendo o código de sucesso.

complete

Chame esta função após a conclusão da solicitação, seja com sucesso ou falha. Passa o objeto XMLHttpRequest e uma string contendo o código de sucesso ou erro.

Tipo de dados

A função $.ajax() depende das informações fornecidas pelo servidor para processar os dados de retorno. Se o servidor informar que os dados retornados são XML, o resultado pode ser percorrido usando métodos XML normais ou seletores jQuery. Se outro tipo for detectado, como HTML, os dados são tratados como texto.

Através da opção dataType, é possível especificar outros tipos de processamento de dados. Além do XML simples, pode-se especificar html, json, jsonp, script ou text.

Neste caso, os dados do tipo text e xml não são processados. Os dados são simplesmente passados para a função de callback success como o atributo responseText ou responseHTML do XMLHttpRequest.

Atenção:Devemos garantir que o tipo MIME reportado pelo servidor da web coincida com o dataType escolhido. Por exemplo, se for XML, o servidor deve declarar text/xml ou application/xml para obter resultados consistentes.

Se especificado como tipo html, qualquer JavaScript embutido será executado antes de o HTML ser retornado como uma string. Da mesma forma, se especificado o tipo script, o JavaScript gerado pelo servidor será executado primeiro, antes de retornar o script como dados de texto.

Se for especificado como tipo 'json', os dados obtidos serão analisados como um objeto JavaScript e o objeto construído será retornado como resultado. Para isso, ele tenta usar JSON.parse(). Se o navegador não suportar, usa uma função para construir.

Os dados JSON são uma estrutura de dados que pode ser facilmente analisada pelo JavaScript. Se o arquivo de dados estiver armazenado em um servidor remoto (domínio diferente, ou seja, dados obtidos de domínios diferentes), é necessário usar o tipo 'jsonp'. Usando esse tipo, será criado um parâmetro da string de consulta 'callback=?', que será adicionado ao final da URL da solicitação. O lado do servidor deve adicionar o nome da função de callback no início dos dados JSON para completar uma solicitação JSONP válida. Se desejar especificar o nome do parâmetro do callback para substituir o padrão 'callback', é possível ajustar o parâmetro 'jsonp' do $.ajax().

Atenção:JSONP é uma extensão do formato JSON. Ele requer alguns códigos no lado do servidor para detectar e lidar com os parâmetros da string de consulta.

Se for especificado o tipo 'script' ou 'jsonp', ao receber dados do servidor, na verdade é usado o tag <script> em vez do objeto XMLHttpRequest. Nesse caso, o $.ajax() não retorna um objeto XMLHttpRequest e nem passa eventos de manipulação, como beforeSend.

Enviar dados para o servidor

Por padrão, as requisições Ajax usam o método GET. Para usar o método POST, é possível definir o valor do parâmetro 'type'. Esta opção também afeta como o conteúdo da opção 'data' é enviado para o servidor.

A opção 'data' pode conter uma string de consulta, como 'key1=value1&key2=value2', ou um mapeamento, como '{key1: 'value1', key2: 'value2'}'. Se o último formato for usado, os dados serão convertidos em uma string de consulta no transmissor. Este processo também pode ser evitado ajustando a opção 'processData' para false. Se desejarmos enviar um objeto XML para o servidor, essa manipulação pode não ser apropriada. E nessa situação, também devemos alterar o valor da opção 'contentType', substituindo o MIME tipo padrão 'application/x-www-form-urlencoded' por outro apropriado.

Opções Avançadas

A opção global é usada para evitar a registro de callbacks de resposta, como .ajaxSend, ou ajaxError, e métodos semelhantes. Isso é útil em algumas situações, como quando as solicitações são enviadas muito frequentemente e brevemente, pode desativar isso no ajaxSend.

Se o servidor precisar de autenticação HTTP, pode usar o nome de usuário e senha para configurar através das opções username e password.

As solicitações Ajax são limitadas no tempo, então, após a captura e processamento do alerta de erro, pode ser usado para melhorar a experiência do usuário. O parâmetro de tempo de expiração geralmente mantém seu valor padrão, ou pode ser configurado globalmente através de jQuery.ajaxSetup, raramente configurado para solicitações específicas.

Pelo padrão, a solicitação sempre será enviada, mas o navegador pode recuperar dados do seu cache. Para proibir o uso dos resultados do cache, configure o parâmetro cache como false. Se desejar verificar se os dados não foram alterados desde a última solicitação e relatar um erro, configure ifModified como true.

scriptCharset permite configurar um conjunto de caracteres específico para a solicitação do <script> tag, usado para scripts ou dados semelhantes a jsonp. Quando o conjunto de caracteres do script e do página são diferentes, isso é especialmente útil.

A primeira letra de Ajax é a letra inicial de asynchronous, o que significa que todas as operações são paralelas e não há relação de precedência na ordem de conclusão. O parâmetro async do $.ajax() sempre é configurado como true, o que indica que, após o início da solicitação, outro código ainda pode ser executado. É altamente recomendável não configurar essa opção como false, o que significaria que todas as solicitações não seriam mais assíncronas, o que também levaria ao bloqueio do navegador.

$.ajax retorna o objeto XMLHttpRequest que ele cria. Normalmente, o jQuery só lida e cria este objeto internamente, mas o usuário também pode passar um objeto xhr que ele próprio criou através da opção xhr. O objeto retornado geralmente já é descartado, mas ainda oferece uma interface de nível inferior para observar e manipular a solicitação. Por exemplo, chamar o método .abort() no objeto pode suspender a solicitação antes de ser concluída.

Manual de Referência do jQuery Ajax