XMLHttpRequest

XMLHttpRequest é um objeto JavaScript que foi projetado pela Microsoft e adotado pela Mozilla, Apple e Google. Este agora está sendo padronizado no W3C. Ele fornece uma maneira fácil de recuperar dados em uma URL. Apesar do nome, XMLHttpRequest pode ser usado para recuperar qualquer tipo de dados, e não apenas XML, suportando também, protocolos diferentes de HTTP (incluindo file e ftp ).

Para criar uma instância de XMLHttpRequest , basta fazer isso:

var myRequest = new XMLHttpRequest();

Para obter detalhes sobre como usar XMLHttpRequest , consulte Usando XMLHttpRequest.

Métodos

Propriedades

Propriedades não-padrão

Construtor

XMLHttpRequest()

O construtor inicia um XMLHttpRequest. Ele deve ser chamado antes de quaisquer outras chamadas de método.

Gecko/Firefox 16 acrescenta um parâmetro não-padrão para o construtor que pode ativar o modo anônimo (veja Bug 692677). Definir o mozAnon bandeira de true eficácia se assemelha a AnonXMLHttpRequest() construtor descrito na especificação XMLHttpRequest que não tenha sido implementado em qualquer navegador ainda (em setembro de 2012).

XMLHttpRequest (
  JSObject objParameters
);

Parâmetros (não-padrão)

objParameters

Há dois sinalizadores que você pode definir:

mozAnon

Boolean: Definir esse sinalizador de true fará com que o navegador para não expor a origem e as credenciais do usuário ao buscar recursos. Mais importante, isto significa que os cookies não será enviado a menos que explicitamente adicionado usando setRequestHeader.

mozSystem

Boolean: Definir esse sinalizador de true . permite fazer conexões entre sites sem a necessidade de o servidor para opt-in usando CORS requer a configuração mozAnon: true . Ou seja, este não pode ser combinada com o envio de cookies ou outras credenciais do usuário. Isso só funciona em privilegiados (revisto) Apps;ele não funciona em páginas da web arbitrários carregados no Firefox.

Métodos

abort()

Aborta o pedido, se já foi enviada.

getAllResponseHeaders()

DOMString getAllResponseHeaders();

Retorna todos os cabeçalhos de resposta como uma string, ou null se nenhuma resposta foi recebida. Nota: Para os pedidos de várias partes, isso retorna os cabeçalhos da parte atual da solicitação, não a partir do canal original.

getResponseHeader()

DOMString? getResponseHeader(DOMString header);

Retorna a string contendo o texto do cabeçalho especificado, ou null se quer a resposta ainda não foi recebida ou o cabeçalho não existe na resposta.

open()

Inicializa um pedido. Este método é para ser usado a partir do código JavaScript; para inicializar um pedido do código nativo, use openRequest() em seu lugar.​

void open(
   DOMString method,
   DOMString url,
   optional boolean async,
   optional DOMString user,
   optional DOMString password
);

Parameters

method

O método HTTP para usar, como "GET", "POST", "PUT", "DELETE", etc. ignorado para URLs não-HTTP (S).

url

O URL para o qual enviar a solicitação.

async

Um parâmetro booleano opcional, padronizando a true , indicando se ou não para executar a operação de forma assíncrona. Se esse valor for false , o send() método não retorna até que a resposta seja recebida. Se true , a notificação de uma transação concluída é fornecida usando ouvintes de evento. Isso deve ser verdade se o multipart atributo é true , ou uma exceção será lançada.

user

O nome de usuário opcional para usar para fins de autenticação; por padrão, essa é uma seqüência vazia.

password

A senha opcional para usar para fins de autenticação; por padrão, essa é uma seqüência vazia.

overrideMimeType()

Substitui o tipo de MIME retornado pelo servidor. Isto pode ser utilizado, por exemplo, para forçar uma corrente a ser tratada e analisada como text/xml, mesmo que o servidor não relatam como método. Este deve ser chamado antes send() .

void overrideMimeType(DOMString mimetype);

send()

Envia a solicitação. Se o pedido é assíncrona (que é o padrão), este método retorna assim que o pedido for enviado. Se o pedido é síncrono, este método não retorna até que a resposta chegou.

void send();
void send(ArrayBuffer data);
void send(Blob data);
void send(Document data);
void send(DOMString? data);
void send(FormData data);

Notas

Se os dados é um Document , ele é serializado antes de serem enviados. Ao enviar um documento, as versões do Firefox antes da versão 3 sempre enviar a solicitação usando codificação UTF-8; Firefox 3 envia corretamente o documento usando a codificação especificada por body.xmlEncoding , ou UTF-8 se nenhum encoding é especificado.

Se é uma nsIInputStream , deve ser compatível com nsIUploadChannel 's setUploadStream() método. Nesse caso, um cabeçalho Content-Length é adicionado ao pedido, com o seu valor obtido usando nsIInputStream 's available() método. Quaisquer cabeçalhos incluídos na parte superior da corrente são tratados como parte do corpo da mensagem. MIMEType da transmissão deve ser especificado definindo o cabeçalho Content-Type usando o setRequestHeader() método antes de chamar send().

A melhor maneira de enviar conteúdo binário (como em arquivos de upload) está usandoArrayBuffers ou Blobs  em conjuncton com o send() método. No entanto, se você quiser enviar uma stringifiable dados brutos, use o sendAsBinary() método em vez disso.

setRequestHeader()

Define o valor de uma solicitação HTTP header.You deve chamar setRequestHeader() após open() , mas antes de send().

void setRequestHeader(
   DOMString header,
   DOMString value
);

Parametros

header

O nome do cabeçalho cujo valor deve ser definido.

value

O valor definido como o corpo do cabeçalho.

Métodos não-padrão

init()

Inicializa o objeto para uso a partir do código C ++.

[noscript] void init(
   in nsIPrincipal principal,
   in nsIScriptContext scriptContext,
   in nsPIDOMWindow ownerWindow
);

Parametros

principal

O principal a ser usado para o pedido; não deve ser null.

scriptContext

O contexto de script a ser usada para o pedido; não deve ser null.

ownerWindow

A janela associada com o pedido; pode ser null.

openRequest()

Inicializa um pedido. Este método é para ser usado a partir do código nativo; para inicializar um pedido do código JavaScript, usar open() em seu lugar. Consulte a documentação do open() .

sendAsBinary()

Uma variante do send() método que envia dados binários.

void sendAsBinary(
   in DOMString body
);

Este método, usado em conjuncton com o readAsBinaryString  método do FileReader API tornar possível read and upload any type of file e para  stringify os dados brutos.

Parametros

body

O corpo da solicitação como um DOMString. Estes dados poderão ser convertidos para uma seqüência de caracteres de byte único por truncamento (removendo o byte de mais alta ordem de cada personagem).

sendAsBinary() polyfill

Desde sendAsBinary() é um recurso experimental, aqui está uma polyfill para navegadores que não suportam o sendAsBinary() método, mas o apoio typed arrays.

/*\
|*|
|*|  :: XMLHttpRequest.prototype.sendAsBinary() Polifyll ::
|*|
|*|  https://developer.mozilla.org/en-US/docs/DOM/XMLHttpRequest#sendAsBinary()
|*|
\*/

if (!XMLHttpRequest.prototype.sendAsBinary) {
  XMLHttpRequest.prototype.sendAsBinary = function (sData) {
    var nBytes = sData.length, ui8Data = new Uint8Array(nBytes);
    for (var nIdx = 0; nIdx < nBytes; nIdx++) {
      ui8Data[nIdx] = sData.charCodeAt(nIdx) & 0xff;
    }
    /* send as ArrayBufferView...: */
    this.send(ui8Data);
    /* ...or as ArrayBuffer (legacy)...: this.send(ui8Data.buffer); */
  };
}

Notas

• Por padrão, o Firefox 3 limita o número de XMLHttpRequest conexões por servidor a 6 (versões anteriores limitar esta para 2 por servidor). Alguns sites interativos podem manter um XMLHttpRequest conexão aberta, de modo que a abertura de várias sessões para esses sites pode resultar no navegador pendurado de tal forma que a janela já não repaints e controles não respondem. Este valor pode ser alterado através da edição do network.http.max-persistent-connections-per-server preferência no about:config.
• Do Gecko 7.0 cabeçalhos estabelecidos pela setRequestHeader() asão enviados com o pedido, quando na sequência de um redirecionamento. Anteriormente, estes cabeçalhos não iria ser enviado.
• XMLHttpRequest é implementado em Gecko usando os nsIXMLHttpRequest, nsIXMLHttpRequestEventTarget, e nsIJSXMLHttpRequest interfaces.

Eventos

onreadystatechange como uma propriedade do XMLHttpRequest instância é suportado em todos os navegadores.

Desde então, foram implementadas uma série de manipuladores de eventos adicionais em vários navegadores ( onload , onerror , onprogress , etc.). Estes são suportados no Firefox. Em particular, veja nsIXMLHttpRequestEventTarget and Using XMLHttpRequest.

avegadores mais recentes, incluindo o Firefox, também suporta ouvir as XMLHttpRequest eventos via padrão addEventListener APIs Além de definir on* propriedades para uma função de manipulador.

Compatibilidade do navegador

Notas Gecko

Gecko 11.0 (Firefox 11.0 / Thunderbird 11.0 / SeaMonkey 2.8) removeu o suporte para o uso do responseType e withCredentials atribui ao realizar solicitações síncronas. Tentativa de fazer isso gera uma NS_ERROR_DOM_INVALID_ACCESS_ERR exception. Esta mudança foi proposta para o W3C para a normalização.

Gecko 12.0 (Firefox 12.0 / Thunderbird 12.0 / SeaMonkey 2.9) e suporte posteriormente usando XMLHttpRequest para ler a partir data: URLs.

Veja também

• MDN artigos sobre XMLHttpRequest:
  • AJAX - Getting Started
  • Using XMLHttpRequest
  • HTML in XMLHttpRequest
  • FormData
• XMLHttpRequest referencias da W3C  e navegador fornecedores:
  • W3C: XMLHttpRequest (base features)
  • W3C: XMLHttpRequest (latest editor's draft with extensions to the base functionality, formerly XMLHttpRequest Level 2
  • Microsoft documentation
  • Apple developers' reference
• "Using the XMLHttpRequest Object" (jibbering.com)
• XMLHttpRequest - REST and the Rich User Experience
• HTML5 Rocks - New Tricks in XMLHttpRequest2