diff options
author | Peter Bengtsson <mail@peterbe.com> | 2020-12-08 14:42:52 -0500 |
---|---|---|
committer | Peter Bengtsson <mail@peterbe.com> | 2020-12-08 14:42:52 -0500 |
commit | 074785cea106179cb3305637055ab0a009ca74f2 (patch) | |
tree | e6ae371cccd642aa2b67f39752a2cdf1fd4eb040 /files/pt-br/web/api/xmlhttprequest | |
parent | da78a9e329e272dedb2400b79a3bdeebff387d47 (diff) | |
download | translated-content-074785cea106179cb3305637055ab0a009ca74f2.tar.gz translated-content-074785cea106179cb3305637055ab0a009ca74f2.tar.bz2 translated-content-074785cea106179cb3305637055ab0a009ca74f2.zip |
initial commit
Diffstat (limited to 'files/pt-br/web/api/xmlhttprequest')
10 files changed, 2367 insertions, 0 deletions
diff --git a/files/pt-br/web/api/xmlhttprequest/abort/index.html b/files/pt-br/web/api/xmlhttprequest/abort/index.html new file mode 100644 index 0000000000..52c1a52068 --- /dev/null +++ b/files/pt-br/web/api/xmlhttprequest/abort/index.html @@ -0,0 +1,118 @@ +--- +title: XMLHttpRequest.abort() +slug: Web/API/XMLHttpRequest/abort +tags: + - AJAX + - API + - HTTP + - HttpRequest + - Referencia + - XMLHttpRequest + - cancelando +translation_of: Web/API/XMLHttpRequest/abort +--- +<p>{{APIRef('XMLHttpRequest')}}</p> + +<p>O método <strong>XMLHttpRequest.abort()</strong> aborta a requisição se ela já tiver sido enviada. Quando uma requisição é abortada, o seu readyState é modificado para 0 (Desativado), mas o evento <a href="/pt-BR/docs/Web/Events/readystatechange">readystatechange</a> não é disparado.</p> + +<h2 id="Sitaxe">Sitaxe</h2> + +<pre class="syntaxbox">xhrInstance.abort();</pre> + +<h3 id="Parâmetros">Parâmetros</h3> + +<p>Nenhum.</p> + +<h3 id="Retorno">Retorno</h3> + +<p>Nenhum.</p> + +<h2 id="Exemplo">Exemplo</h2> + +<pre class="brush: js">var xhr = new XMLHttpRequest(), + method = "GET", + url = "https://developer.mozilla.org/"; +xhr.open(method,url,true); + +xhr.send(); + +xhr.abort(); +</pre> + +<h2 id="Especificações">Especificações</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th scope="col">Especificação</th> + <th scope="col">Status</th> + <th scope="col">Comentário</th> + </tr> + <tr> + <td>{{SpecName('XMLHttpRequest', '#the-abort()-method')}}</td> + <td>{{Spec2('XMLHttpRequest')}}</td> + <td>WHATWG living standard</td> + </tr> + </tbody> +</table> + +<h2 id="Compatibilidade_entre_navegadores">Compatibilidade entre navegadores</h2> + +<div>{{CompatibilityTable}}</div> + +<div id="compat-desktop"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Chrome</th> + <th>Firefox (Gecko)</th> + <th>Internet Explorer</th> + <th>Opera</th> + <th>Safari (WebKit)</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatChrome(1)}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatIe('5')}}<sup>[1]</sup><br> + {{CompatIe('7')}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatSafari('1.2')}}</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Chrome for Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatUnknown}}</td> + <td>1.0</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<p>[1] Esse recurso foi implementado através de ActiveXObject (). O Internet Explorer implementa o padrão XMLHttpRequest desde a versão 7.</p> + +<h2 id="Veja_também">Veja também</h2> + +<ul> + <li><a href="/pt-BR/docs/Web/API/XMLHttpRequest/Usando_XMLHttpRequest">Usando o XMLHttpRequest</a></li> +</ul> diff --git a/files/pt-br/web/api/xmlhttprequest/index.html b/files/pt-br/web/api/xmlhttprequest/index.html new file mode 100644 index 0000000000..de045c5314 --- /dev/null +++ b/files/pt-br/web/api/xmlhttprequest/index.html @@ -0,0 +1,724 @@ +--- +title: XMLHttpRequest +slug: Web/API/XMLHttpRequest +tags: + - AJAX + - Fixit + - HTTP + - MakeBrowserAgnostic + - NeedsCleanup + - NeedsMobileBrowserCompatibility + - NeedsTranslation + - TopicStub + - XMLHttpRequest +translation_of: Web/API/XMLHttpRequest +--- +<p>{{APIRef("XMLHttpRequest")}}</p> + +<p><code>XMLHttpRequest</code> é um objeto que fornece funcionalidade ao cliente para transferir dados entre um cliente e um servidor. Ele fornece uma maneira fácil de recuperar dados de um URL sem ter que fazer uma atualização de página inteira. Isso permite que uma página da Web atualize apenas uma parte do conteúdo sem interromper o que o usuário esteja fazendo. XMLHttpRequest é usado constantemente na programação de <a href="/pt-BR/docs/AJAX">AJAX</a>.</p> + +<p><code>XMLHttpRequest</code> foi originalmente projetado pela Microsoft e adotado pela Mozilla, Apple e Google. Está sendo padronizado pela <a href="https://xhr.spec.whatwg.org/">WHATWG</a>. Apesar do nome, XMLHttpRequest pode ser usado para recuperar qualquer tipo de dados, e não apenas XML, suportando também, protocolos diferentes de <a href="/en/HTTP" title="en/HTTP">HTTP</a> (incluindo file e ftp ).</p> + +<p>Para criar uma instância de XMLHttpRequest , basta fazer isso:</p> + +<pre>var myRequest = new XMLHttpRequest(); +</pre> + +<p>Para obter detalhes sobre como usar XMLHttpRequest , consulte <a class="internal" href="/en/DOM/XMLHttpRequest/Using_XMLHttpRequest" title="En/Using XMLHttpRequest">Usando XMLHttpRequest</a>.</p> + +<h2 id="Métodos">Métodos</h2> + +<table class="standard-table"> + <tbody> + <tr> + <td><code><a class="internal" href="/en/DOM/XMLHttpRequest#XMLHttpRequest()" title="/en/DOM/XMLHttpRequest#XMLHttpRequest()">XMLHttpRequest</a>(JSObject objParameters);</code></td> + </tr> + <tr> + <td><code>void <a class="internal" href="/en/DOM/XMLHttpRequest#abort()" title="en/DOM/XMLHttpRequest#abort()">abort</a>();</code></td> + </tr> + <tr> + <td><code>DOMString <a class="internal" href="/en/DOM/XMLHttpRequest#getAllResponseHeaders()" title="en/DOM/XMLHttpRequest#getAllResponseHeaders()">getAllResponseHeaders</a>();</code></td> + </tr> + <tr> + <td><code>DOMString? <a class="internal" href="/en/DOM/XMLHttpRequest#getResponseHeader()" title="en/DOM/XMLHttpRequest#getResponseHeader()">getResponseHeader</a>(DOMString header);</code></td> + </tr> + <tr> + <td><code>void <a class="internal" href="/en/DOM/XMLHttpRequest#open()" title="en/DOM/XMLHttpRequest#open()">open</a>(DOMString method, DOMString url, optional boolean async, optional DOMString? user, optional DOMString? password);</code></td> + </tr> + <tr> + <td><code>void <a class="internal" href="/en/DOM/XMLHttpRequest#overrideMimeType()" title="en/DOM/XMLHttpRequest#overrideMimeType()">overrideMimeType</a>(DOMString mime);</code></td> + </tr> + <tr> + <td><code>void <a class="internal" href="/en/DOM/XMLHttpRequest#send()" title="en/DOM/XMLHttpRequest#send()">send</a>();</code><br> + <code>void <a class="internal" href="/en/DOM/XMLHttpRequest#send()" title="en/DOM/XMLHttpRequest#send()">send</a>(ArrayBuffer data);</code><br> + <code>void <a class="internal" href="/en/DOM/XMLHttpRequest#send()" title="en/DOM/XMLHttpRequest#send()">send</a>(Blob data);</code><br> + <code>void <a class="internal" href="/en/DOM/XMLHttpRequest#send()" title="en/DOM/XMLHttpRequest#send()">send</a>(Document data);</code><br> + <code>void <a class="internal" href="/en/DOM/XMLHttpRequest#send()" title="en/DOM/XMLHttpRequest#send()">send</a>(DOMString? data);</code><br> + <code>void <a class="internal" href="/en/DOM/XMLHttpRequest#send()" title="en/DOM/XMLHttpRequest#send()">send</a>(FormData data);</code></td> + </tr> + <tr> + <td><code>void <a class="internal" href="/en/DOM/XMLHttpRequest#setRequestHeader()" title="en/DOM/XMLHttpRequest#setRequestHeader()">setRequestHeader</a>(DOMString header, DOMString value);</code></td> + </tr> + <tr> + <th>Métodos não-padrão</th> + </tr> + <tr> + <td><code>[noscript] void <a class="internal" href="/en/DOM/XMLHttpRequest#init()" title="en/DOM/XMLHttpRequest#init()">init</a>(in nsIPrincipal principal, in nsIScriptContext scriptContext, in nsPIDOMWindow ownerWindow);</code></td> + </tr> + <tr> + <td><code>[noscript] void <a class="internal" href="/en/DOM/XMLHttpRequest#openRequest()" title="en/DOM/XMLHttpRequest#openRequest()">openRequest</a>(in AUTF8String method, in AUTF8String url, in boolean async, in AString user, in AString password); </code></td> + </tr> + <tr> + <td><code>void <a class="internal" href="/en/DOM/XMLHttpRequest#sendAsBinary()" title="en/DOM/XMLHttpRequest#sendAsBinary()">sendAsBinary</a>(in DOMString body);</code></td> + </tr> + </tbody> +</table> + +<h2 id="Propriedades">Propriedades</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th>Atributo</th> + <th>Tipo</th> + <th>Descrição</th> + </tr> + <tr id="onreadystatechange"> + <td> + <p><code>onreadystatechange</code></p> + </td> + <td><code>Function?</code></td> + <td> + <p>A função de objeto JavaScript que é chamado sempre que o atributo readyState sofre alteração. A função de callback é chamada a partir da thread existente na interface de usuário.</p> + + <div class="warning"><strong>Aviso:</strong> Este não deve ser usado com chamadas síncronas e não deve ser utilizado a partir do código nativo.</div> + </td> + </tr> + <tr id="readyState"> + <td><code>readyState</code></td> + <td><code>retorna o cabeçalho da requisição.</code></td> + <td> + <p> </p> + + <table class="standard-table"> + <tbody> + <tr> + <td class="header">Valor</td> + <td class="header">Estado</td> + <td class="header">Descrição</td> + </tr> + <tr> + <td><code>0</code></td> + <td><code>UNSENT</code></td> + <td><code>open() não foi chamado ainda.</code></td> + </tr> + <tr> + <td><code>1</code></td> + <td><code>OPENED</code></td> + <td><code>send() não foi chamado ainda.</code></td> + </tr> + <tr> + <td><code>2</code></td> + <td><code>HEADERS_RECEIVED</code></td> + <td><code>send() foi chamado, e cabeçalhos e status estão disponíveis.</code></td> + </tr> + <tr> + <td><code>3</code></td> + <td><code>LOADING</code></td> + <td>Download; responseText contém dados parciais.</td> + </tr> + <tr> + <td><code>4</code></td> + <td><code>DONE</code></td> + <td>A operação está concluída.</td> + </tr> + </tbody> + </table> + </td> + </tr> + <tr id="response"> + <td><code>response</code></td> + <td>ArrayBuffer, Document,Blob, DOMString</td> + <td> + <p>Retorna um objeto JavaScript de tipo {{domxref("ArrayBuffer")}}, {{domxref("Blob")}} ou {{domxref("Document")}}, de acordo com o que estiver contido no <code><a href="#responseType">responseType</a>. </code>Retorna <code>null</code> se a request não esteja completa ou não obteve sucesso.</p> + </td> + </tr> + <tr id="responseText"> + <td><code>responseText</code> {{ReadOnlyInline()}}</td> + <td><code>DOMString</code></td> + <td>A resposta à <em>request</em>, em formato texto, retorna null se a solicitação não teve êxito ou que ainda não foi enviada.</td> + </tr> + <tr id="responseType"> + <td><code>responseType</code></td> + <td><code>XMLHttpRequestResponseType</code></td> + <td> + <p>Pode ser configurado para alterar o tipo de resposta.</p> + + <table class="standard-table" style="width: auto;"> + <tbody> + <tr> + <td class="header">Valor</td> + <td class="header">Tipo de dados de <code>resposta</code> de propriedade</td> + </tr> + <tr> + <td><code>""</code> (string vazia)</td> + <td>String (este é o padrão)</td> + </tr> + <tr> + <td><code>"arraybuffer"</code></td> + <td><a href="/en/JavaScript_typed_arrays/ArrayBuffer" title="en/JavaScript typed arrays/ArrayBuffer"><code>ArrayBuffer</code></a></td> + </tr> + <tr> + <td><code>"blob"</code></td> + <td>{{ domxref("Blob") }}</td> + </tr> + <tr> + <td><code>"document"</code></td> + <td>{{ domxref("Document") }}</td> + </tr> + <tr> + <td><code>"json"</code></td> + <td>Objeto JavaScript, analisado a partir de uma seqüência de caracteres JSON retornado pelo servidor.</td> + </tr> + <tr> + <td><code>"text"</code></td> + <td>String</td> + </tr> + <tr> + <td><code>"moz-blob"</code></td> + <td>Usado pelo Firefox para permitir recuperar dados parciais do tipo {{ domxref("Blob") }},de eventos de progresso. Isso permite que o manipulador de eventos de progresso iniciar o processamento de dados enquanto ele ainda está sendo recebido.</td> + </tr> + <tr> + <td><code>"moz-chunked-text"</code></td> + <td> + <p>Semelhante ao "text" , mas o <em>streaming </em>ainda está fluindo. Isto significa que o valor na response , só está disponível durante a expedição do "progress" do evento e contém apenas os dados recebidos desde a última "progress" do evento.</p> + + <p>Quando response é acessado durante um evento "progress", este contém uma string com os dados. Caso contrário, retorna null .</p> + + <p>Este modo atualmente só funciona no Firefox.</p> + </td> + </tr> + <tr> + <td><code>"moz-chunked-arraybuffer"</code></td> + <td> + <p>Semelhante ao <code>"arraybuffer"</code>, mas está fluindo. Isto significa que o valor na response , só está disponível durante a expedição do "progress" do evento e contém apenas os dados recebidos desde a última "progress" do evento.</p> + + <p>Quando response é acessado durante um "progress" evento que contém uma seqüência com os dados. Caso contrário, retorna null .</p> + + <p>Este modo atualmente só funciona no Firefox.</p> + + <p>.</p> + </td> + </tr> + </tbody> + </table> + + <div class="note"><strong>Nota:</strong> Começando com 11,0 Gecko (Firefox 11.0 / 11.0 Thunderbird / SeaMonkey 2.8), bem como WebKit construir 528, esses navegadores não permitem que você use o atributo responseType ao executar solicitações síncronas. Tentativas de fazer isso geram uma exceção do tipo NS_ERROR_DOM_INVALID_ACCESS_ERR. Esta mudança foi proposta para padronização junto à W3C.</div> + </td> + </tr> + <tr id="responseXML"> + <td><code>responseXML</code> {{ReadOnlyInline()}}</td> + <td><code>Document?</code></td> + <td> + <p>A resposta ao pedido como um DOM <code><a class="internal" href="/en/DOM/document" title="En/DOM/Document">Document</a></code> objeto, ou null se o pedido não foi bem sucedida, ainda não foi enviado, ou não pode ser analisado como XML ou HTML. A resposta é analisado como se fosse um <code>text/html</code> stream. Quando o responseType está definido para "document" e que a solicitação tenha sido feita de forma assíncrona, a resposta é analisado como se fosse um <code>text/html</code> stream.</p> + + <div class="note"><strong>Nota:</strong> Se o servidor não se aplica o text/xml cabeçalho Content-Type, você pode usar overrideMimeType() para forçar XMLHttpRequest para analisá-lo como XML de qualquer maneira.</div> + </td> + </tr> + <tr id="status"> + <td><code>status</code> {{ReadOnlyInline()}}</td> + <td><code>unsigned short</code></td> + <td>O status de resposta da requisição. Este é o retorno do codigo da requisição HTTP (por exemplo, status é 200 qual a solicitação for bem-sucedida).</td> + </tr> + <tr id="statusText"> + <td><code>statusText</code> {{ReadOnlyInline()}}</td> + <td><code>DOMString</code></td> + <td>A cadeia de resposta retornado pelo servidor HTTP. Ao contrário do status , o que inclui todo o texto da mensagem de resposta (" 200 OK ", por exemplo).</td> + </tr> + <tr id="timeout"> + <td><code>timeout</code></td> + <td><code>unsigned long</code></td> + <td> + <p> <br> + O número de milissegundos de um pedido pode tomar antes de ser automaticamente encerrada. Um valor de 0 (que é o padrão) significa que não há tempo limite.</p> + + <div class="note"><strong>Nota:</strong> Você não pode usar um tempo limite para solicitações síncronas com uma janela proprietária.</div> + </td> + </tr> + <tr id="upload"> + <td><code>upload</code></td> + <td><code>XMLHttpRequestUpload</code></td> + <td>O processo de upload pode ser rastreado através da ação de retorno de um evento para upload.</td> + </tr> + <tr id="withCredentials"> + <td><code>withCredentials</code></td> + <td><code>boolean</code></td> + <td> + <p>Indica se ou não de cross-site Access-Control solicitações devem ser feitas usando credenciais, como cookies ou cabeçalhos de autorização. O padrão é false .</p> + + <div class="note"><strong>Nota:</strong> Esta não afeta as solicitações no mesmo local.</div> + + <div class="note"><strong>Nota:</strong> Começando com 11,0 Gecko (Firefox 11.0 / 11.0 Thunderbird / SeaMonkey 2.8), Gecko não permite que você use os atributos withCredentials ao realizar solicitações síncronas. Ao tentar fazer isso o sistema gera uma exceção do tipo NS_ERROR_DOM_INVALID_ACCESS_ERR.</div> + </td> + </tr> + </tbody> +</table> + +<h3 id="Propriedades_não-padrão">Propriedades não-padrão</h3> + +<table class="standard-table"> + <tbody> + <tr> + <th>Attribute</th> + <th>Type</th> + <th>Description</th> + </tr> + <tr id="channel"> + <td><code>channel</code> {{ReadOnlyInline()}}</td> + <td>{{Interface("nsIChannel")}}</td> + <td>O canal utilizado pelo objecto aquando da execução do pedido. Esta é null se o canal não foi criado ainda. No caso de um pedido de múltiplas partes, isto é o canal inicial, não as diferentes partes do pedido de várias partes. <strong>Requer privilégios elevados para o acesso.</strong></td> + </tr> + <tr id="mozAnon"> + <td><code>mozAnon</code> {{ReadOnlyInline()}}</td> + <td><code>boolean</code></td> + <td> + <p>Se for verdadeiro (true) o pedido será enviado sem cabeçalhos de cookies e autenticação.</p> + </td> + </tr> + <tr id="mozSystem"> + <td><code>mozSystem</code> {{ReadOnlyInline()}}</td> + <td><code>boolean</code></td> + <td> + <p>Se for verdadeiro (true) , a política de mesma origem não será aplicada sobre o pedido.</p> + </td> + </tr> + <tr id="mozBackgroundRequest"> + <td><code>mozBackgroundRequest</code></td> + <td><code>boolean</code></td> + <td> + <p>Indica se o objeto representa uma solicitação de serviço de fundo. Se true , nenhum grupo carga está associada com o pedido, e diálogos de segurança estão impedidos de ser mostrado para o usuário. <strong>Requer privilégios elevados para o acesso.</strong></p> + + <p>Nos casos em que uma caixa de diálogo de segurança (como a autenticação ou uma notificação certificado ruim) normalmente seriam mostrados, o pedido simplesmente falhar em seu lugar.</p> + + <div class="note"><strong>Nota: </strong>Esta propriedade deve ser definida antes de chamar open().</div> + </td> + </tr> + <tr id="mozResponseArrayBuffer"> + <td><code>mozResponseArrayBuffer</code> {{ obsolete_inline("6") }} {{ReadOnlyInline()}}</td> + <td><a href="/en/JavaScript_typed_arrays/ArrayBuffer" title="en/JavaScript typed arrays/ArrayBuffer"><code>ArrayBuffer</code></a></td> + <td>A resposta ao pedido, como uma matriz de JavaScript digitado. Esta é NULL se o pedido não foi bem-sucedida, ou se não foi enviada ainda.</td> + </tr> + <tr id="multipart"> + <td><code>multipart</code> {{ obsolete_inline("22") }}</td> + <td><code>boolean</code></td> + <td> + <p><strong>Este Gecko somente recurso foi removido no Firefox / Gecko 22.</strong> Por favor Utilize <a href="/en-US/docs/Server-sent_events" title="/en-US/docs/Server-sent_events">Server-Sent Events</a>, <a href="/en-US/docs/WebSockets" title="/en-US/docs/WebSockets">Web Sockets</a> ou <code>responseText</code> de eventos de progresso em seu lugar.</p> + + <p>Indica se ou não a resposta está prevista para ser uma corrente de, possivelmente, vários documentos XML. Se definido como true , o tipo de conteúdo da resposta inicial deve ser multipart/x-mixed-replace ou ocorrerá um erro. Todos os pedidos devem ser assíncrona.</p> + + <p>Isso permite o suporte para servidor push; para cada documento XML que está escrito a este pedido, um novo documento XML DOM é criado eo onload manipulador é chamado entre os documentos.</p> + + <div class="note"><strong>Nota:</strong> Quando este estiver definido, o onload manipulador e outros manipuladores de eventos não são repostas após a primeira XmlDocument é carregado, eo onload manipulador é chamado após cada parte da resposta é recebida.</div> + </td> + </tr> + </tbody> +</table> + +<h2 id="Construtor">Construtor</h2> + +<h3 id="XMLHttpRequest()" name="XMLHttpRequest()">XMLHttpRequest()</h3> + +<p>O construtor inicia um XMLHttpRequest. Ele deve ser chamado antes de quaisquer outras chamadas de método.</p> + +<p>Gecko/Firefox 16 acrescenta um parâmetro não-padrão para o construtor que pode ativar o modo anônimo (veja <a href="https://bugzilla.mozilla.org/show_bug.cgi?id=692677" title="692677 – Relax same-origin XHR restrictions for privileged applications">Bug 692677</a>). Definir o mozAnon bandeira de true eficácia se assemelha a <a href="http://www.w3.org/TR/2012/WD-XMLHttpRequest-20120117/#dom-anonxmlhttprequest" title="see AnonXMLHttpRequest in the XMLHttpRequest specification"><code>AnonXMLHttpRequest()</code></a> construtor descrito na especificação XMLHttpRequest que não tenha sido implementado em qualquer navegador ainda (em setembro de 2012).</p> + +<pre>XMLHttpRequest ( + JSObject objParameters +);</pre> + +<h5 id="Parâmetros_(não-padrão)">Parâmetros (não-padrão)</h5> + +<dl> + <dt><code>objParameters</code></dt> + <dd>Há dois sinalizadores que você pode definir: + <dl> + <dt><code>mozAnon</code></dt> + <dd>Boolean: Definir esse sinalizador de true fará com que o navegador para não expor a origem e as <a href="http://www.w3.org/TR/2012/WD-XMLHttpRequest-20120117/#user-credentials" title="Defintion of “User credentials” in the XMLHttpRequest specification.">credenciais do usuário</a> ao buscar recursos. Mais importante, isto significa que os cookies não será enviado a menos que explicitamente adicionado usando setRequestHeader.</dd> + <dt><code>mozSystem</code></dt> + <dd>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<em> <a href="https://bugzilla.mozilla.org/show_bug.cgi?id=692677#c68" title="Bug 692677 comment 68">só funciona em privilegiados (revisto) Apps</a>;ele não funciona em páginas da web arbitrários carregados no Firefox.</em></dd> + </dl> + </dd> +</dl> + +<h2 id="Métodos_2">Métodos</h2> + +<h3 id="abort()" name="abort()">abort()</h3> + +<p>Aborta o pedido, se já foi enviada.</p> + +<h3 id="getAllResponseHeaders()" name="getAllResponseHeaders()">getAllResponseHeaders()</h3> + +<pre>DOMString getAllResponseHeaders();</pre> + +<p>Retorna todos os cabeçalhos de resposta como uma string, ou null se nenhuma resposta foi recebida.<strong> Nota:</strong> 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.</p> + +<h3 id="getResponseHeader()" name="getResponseHeader()">getResponseHeader()</h3> + +<pre>DOMString? getResponseHeader(DOMString <var>header</var>);</pre> + +<p>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.</p> + +<h3 id="open()" name="open()">open()</h3> + +<p>Inicializa um pedido. Este método é para ser usado a partir do código JavaScript; para inicializar um pedido do código nativo, use <a class="internal" href="/en/nsIXMLHttpRequest#openRequest()" title="/en/XMLHttpRequest#openRequest()"><code>openRequest()</code></a> em seu lugar.</p> + +<div class="note"><strong>Nota:</strong> Chamar esse método uma solicitação já está ativo (aquele para o qual open() ou openRequest() já foi chamado) é o equivalente de chamar abort().</div> + +<pre>void open( + DOMString <var>method</var>, + DOMString <var>url</var>, + optional boolean <var>async</var>, + optional DOMString <var>user</var>, + optional DOMString <var>password</var> +); +</pre> + +<h6 id="Parameters">Parameters</h6> + +<dl> + <dt><code>method</code></dt> + <dd>O método HTTP para usar, como "GET", "POST", "PUT", "DELETE", etc. ignorado para URLs não-HTTP (S).</dd> + <dt><code>url</code></dt> + <dd>O URL para o qual enviar a solicitação.</dd> + <dt><code>async</code></dt> + <dd>Um parâmetro booleano opcional, por padrão true , indicando se a operação deve ou não ser executada 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 true se o multipart atributo for true , ou uma exceção será lançada.</dd> + <dt><code>user</code></dt> + <dd>O nome de usuário opcional para usar para fins de autenticação; por padrão, essa é uma seqüência vazia.</dd> + <dt><code>password</code></dt> + <dd>A senha opcional para usar para fins de autenticação; por padrão, essa é uma seqüência vazia.</dd> +</dl> + +<h3 id="overrideMimeType()" name="overrideMimeType()">overrideMimeType()</h3> + +<p>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 método deve ser chamado antes send() .</p> + +<pre>void overrideMimeType(DOMString <var>mimetype</var>);</pre> + +<h3 id="send()" name="send()">send()</h3> + +<p>Envia a solicitação. Se o pedido é assíncrono (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é a resposta chegar.</p> + +<div class="note"><strong>Nota:</strong> Qualquer ouvintes de eventos que pretende definir tem de ser definida antes de chamar send().</div> + +<pre>void send(); +void send(ArrayBuffer <var>data</var>); +void send(Blob <var>data</var>); +void send(Document <var>data</var>); +void send(DOMString? <var>data</var>); +void send(FormData <var>data</var>);</pre> + +<h6 id="Notas">Notas</h6> + +<p>Se os dados são um Document , ele é serializado antes de serem enviados. Ao enviar um documento, as versões do Firefox antes da versão 3 sempre enviavam a solicitação usando codificação UTF-8; <a href="/en/Firefox_3" rel="internal" title="en/Firefox_3">Firefox 3</a> envia corretamente o documento usando a codificação especificada por body.xmlEncoding , ou UTF-8 se nenhum encoding é especificado.</p> + +<p>Se são 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 <a class="internal" href="/en/nsIXMLHttpRequest#setRequestHeader()" title="/en/XMLHttpRequest#setRequestHeader()"><code>setRequestHeader()</code></a> método antes de chamar send().</p> + +<p>A melhor maneira de enviar conteúdo binário (como em arquivos de upload) está usando<a href="/en-US/docs/JavaScript/Typed_arrays/ArrayBuffer" title="/en-US/docs/JavaScript/Typed_arrays/ArrayBuffer">ArrayBuffers</a> ou <a href="/en-US/docs/DOM/Blob" title="/en-US/docs/DOM/Blob">Blobs</a> em conjuncton com o send() método. No entanto, se você quiser enviar uma <a href="/en-US/docs/JavaScript/Reference/Global_Objects/JSON/stringify" title="/en-US/docs/JavaScript/Reference/Global_Objects/JSON/stringify">stringifiable</a> dados brutos, use o <a href="/en-US/docs/DOM/XMLHttpRequest#sendAsBinary()" title="/en-US/docs/DOM/XMLHttpRequest#sendAsBinary()"><code>sendAsBinary()</code></a> método em vez disso.</p> + +<h3 id="setRequestHeader()" name="setRequestHeader()">setRequestHeader()</h3> + +<p>Define o valor de uma solicitação HTTP header. Você deve chamar setRequestHeader() após open() , mas antes de send().</p> + +<pre>void setRequestHeader( + DOMString <var>header</var>, + DOMString <var>value</var> +); +</pre> + +<h6 id="Parametros">Parametros</h6> + +<dl> + <dt><code>header</code></dt> + <dd>O nome do cabeçalho cujo valor deve ser definido.</dd> + <dt><code>value</code></dt> + <dd>O valor definido como o corpo do cabeçalho.</dd> +</dl> + +<h3 id="Métodos_não-padrão">Métodos não-padrão</h3> + +<h4 id="init()">init()</h4> + +<p>Inicializa o objeto para uso a partir do código C ++.</p> + +<div class="warning"><strong>Nota:</strong> Este método não deve ser chamado a partir do JavaScript.</div> + +<pre>[noscript] void init( + in nsIPrincipal principal, + in nsIScriptContext scriptContext, + in nsPIDOMWindow ownerWindow +); +</pre> + +<h5 id="Parametros_2">Parametros</h5> + +<dl> + <dt><code>principal</code></dt> + <dd>O principal a ser usado para o pedido; não deve ser null.</dd> + <dt><code>scriptContext</code></dt> + <dd>O contexto de script a ser usada para o pedido; não deve ser null.</dd> + <dt><code>ownerWindow</code></dt> + <dd>A janela associada com o pedido; pode ser <code>null</code>.</dd> +</dl> + +<h4 id="openRequest()">openRequest()</h4> + +<p>Inicializa um pedido. Este método é para ser usado a partir do código nativo; para inicializar um pedido do código JavaScript, usar <code><a class="internal" href="/en/nsIXMLHttpRequest#open()" title="/en/XMLHttpRequest#open()">open()</a> em seu lugar. Consulte a documentação do open() .</code></p> + +<h4 id="sendAsBinary()">sendAsBinary()</h4> + +<p>Uma variante do send() método que envia dados binários.</p> + +<pre>void sendAsBinary( + in DOMString body +); +</pre> + +<p>Este método, usado em conjuncton com o <a href="/en-US/docs/DOM/FileReader#readAsBinaryString()" title="/en-US/docs/DOM/FileReader#readAsBinaryString()"><code>readAsBinaryString</code></a> método do <a href="/en-US/docs/DOM/FileReader" title="/en-US/docs/DOM/FileReader"><code>FileReader</code></a> API tornar possível <a href="https://developer.mozilla.org/en-US/docs/DOM/XMLHttpRequest/Using_XMLHttpRequest#Submitting_forms_and_uploading_files" title="/en-US/docs/DOM/XMLHttpRequest/Using_XMLHttpRequest#Submitting_forms_and_uploading_files">read and <strong>upload</strong> any type of file</a> e para <a href="/en-US/docs/JavaScript/Reference/Global_Objects/JSON/stringify" title="/en-US/docs/JavaScript/Reference/Global_Objects/JSON/stringify">stringify</a> os dados brutos.</p> + +<h5 id="Parametros_3">Parametros</h5> + +<dl> + <dt><code>body</code></dt> + <dd>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).</dd> +</dl> + +<h5 id="sendAsBinary()_polyfill"><code>sendAsBinary()</code> polyfill</h5> + +<p>Desde sendAsBinary() é um recurso experimental, aqui está uma polyfill para navegadores que não suportam o sendAsBinary() método, mas o apoio <a href="/en-US/docs/JavaScript/Typed_arrays" title="/en-US/docs/JavaScript/Typed_arrays">typed arrays</a>.</p> + +<pre class="brush: js">/*\ +|*| +|*| :: 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); */ + }; +}</pre> + +<div class="note"><strong>Nota:</strong> É possível construir este polyfill colocar dois tipos de dados como argumento para send() : um <a href="/en-US/docs/JavaScript/Typed_arrays/ArrayBuffer" title="/en-US/docs/JavaScript/Typed_arrays/ArrayBuffer"><code>ArrayBuffer</code></a> (ui8Data.buffer - o código comentado) ou um ArrayBufferView ( ui8Data , que é uma <a href="/en-US/docs/JavaScript/Typed_arrays/Uint8Array" title="/en-US/docs/JavaScript/Typed_arrays/Uint8Array">typed array of 8-bit unsigned integers</a> – descomentada código). No entanto, no Google Chrome, quando você tenta enviar uma ArrayBuffer , a seguinte mensagem de aviso aparecerá: ArrayBuffer is deprecated in XMLHttpRequest.send(). Use ArrayBufferView instead. ArrayBuffer is deprecated in XMLHttpRequest.send(). Use ArrayBufferView instead.</div> + +<h2 id="Notas_2">Notas</h2> + +<ul> + <li class="note">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 <code><a class="linkification-ext" href="/about:config" title="Linkification: about:config">about:config</a></code>.</li> + <li class="note">Do Gecko 7 cabeçalhos estabelecidos pela {{ manch("setRequestHeader") }} asão enviados com o pedido, quando na sequência de um redirecionamento. Anteriormente, estes cabeçalhos não iria ser enviado.</li> + <li class="note"><code>XMLHttpRequest é implementado em Gecko usando os</code> {{ interface("nsIXMLHttpRequest") }}, {{ interface("nsIXMLHttpRequestEventTarget") }}, e {{ interface("nsIJSXMLHttpRequest") }} interfaces.</li> +</ul> + +<h4 class="note" id="Eventos">Eventos</h4> + +<p><code>onreadystatechange</code> como uma propriedade do <code>XMLHttpRequest</code> instância é suportado em todos os navegadores.</p> + +<p>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 {{ interface("nsIXMLHttpRequestEventTarget") }} and <a href="/en/DOM/XMLHttpRequest/Using_XMLHttpRequest" title="En/XMLHttpRequest/Using_XMLHttpRequest">Using XMLHttpRequest</a>.</p> + +<p>avegadores mais recentes, incluindo o Firefox, também suporta ouvir as XMLHttpRequest eventos via padrão <code><a href="/en/DOM/element.addEventListener" title="element.addEventListener">addEventListener</a></code> APIs Além de definir on* propriedades para uma função de manipulador.</p> + +<h2 id="Browser_Compatibility" name="Browser_Compatibility">Compatibilidade do navegador</h2> + +<p>{{ CompatibilityTable() }}</p> + +<div id="compat-desktop"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Chrome</th> + <th>Firefox (Gecko)</th> + <th>Internet Explorer</th> + <th>Opera</th> + <th>Safari (WebKit)</th> + </tr> + <tr> + <td>Basic support (XHR1)</td> + <td>1</td> + <td>1.0</td> + <td>5 (via ActiveXObject)<br> + 7 (XMLHttpRequest)</td> + <td>{{ CompatVersionUnknown() }}</td> + <td>1.2</td> + </tr> + <tr> + <td><code>send(ArrayBuffer)</code></td> + <td>9</td> + <td>9</td> + <td>{{ compatUnknown() }}</td> + <td>11.60</td> + <td>{{ compatUnknown() }}</td> + </tr> + <tr> + <td><code>send(Blob)</code></td> + <td>7</td> + <td>3.6</td> + <td>{{ compatUnknown() }}</td> + <td>12</td> + <td>{{ compatUnknown() }}</td> + </tr> + <tr> + <td><code>send(FormData)</code></td> + <td>6</td> + <td>4</td> + <td>{{ compatUnknown() }}</td> + <td>12</td> + <td>{{ compatUnknown() }}</td> + </tr> + <tr> + <td><code>sendAsBinary(DOMString)</code></td> + <td>{{ compatNo() }} – use the <a href="#sendAsBinary%28%29_polyfill" title="sendAsBinary() polyfill">polyfill</a></td> + <td>1.9</td> + <td>{{ compatUnknown() }}</td> + <td>{{ compatUnknown() }}</td> + <td>{{ compatUnknown() }}</td> + </tr> + <tr> + <td><code>response</code></td> + <td>10</td> + <td>6</td> + <td>10</td> + <td>11.60</td> + <td>{{ compatUnknown() }}</td> + </tr> + <tr> + <td><code>responseType</code> = 'arraybuffer'</td> + <td>10</td> + <td>6</td> + <td>10</td> + <td>11.60</td> + <td>{{ compatUnknown() }}</td> + </tr> + <tr> + <td><code>responseType</code> = 'blob'</td> + <td>19</td> + <td>6</td> + <td>10</td> + <td>12</td> + <td>{{ compatUnknown() }}</td> + </tr> + <tr> + <td><code>responseType</code> = 'document'</td> + <td>18</td> + <td>11</td> + <td>10</td> + <td>{{ CompatNo() }}</td> + <td>{{ CompatNo() }}</td> + </tr> + <tr> + <td><code>responseType</code> = 'json'</td> + <td>{{ CompatNo() }}</td> + <td>10</td> + <td>{{ CompatNo() }}</td> + <td>12</td> + <td>{{ CompatNo() }}</td> + </tr> + <tr> + <td>Progress Events</td> + <td>7</td> + <td>3.5</td> + <td>10</td> + <td>12</td> + <td>{{ compatUnknown() }}</td> + </tr> + <tr> + <td><code>withCredentials</code></td> + <td>3</td> + <td>3.5</td> + <td>10</td> + <td>12</td> + <td>4</td> + </tr> + <tr> + <td><code>timeout</code></td> + <td>{{ CompatNo() }}</td> + <td>12.0</td> + <td>8</td> + <td>{{ compatUnknown() }}</td> + <td>{{ CompatNo() }}</td> + </tr> + <tr> + <td><code>responseType</code> = 'moz-blob'</td> + <td>{{ CompatNo() }}</td> + <td>12.0</td> + <td>{{ CompatNo() }}</td> + <td>{{ CompatNo() }}</td> + <td>{{ CompatNo() }}</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Chrome for Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Phone</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{ CompatUnknown() }}</td> + <td>0.16</td> + <td>{{ CompatVersionUnknown() }}</td> + <td>{{ CompatUnknown() }}</td> + <td>{{ CompatUnknown() }}</td> + <td>{{ CompatUnknown() }}</td> + </tr> + </tbody> +</table> +</div> + +<h3 id="Notas_Gecko">Notas Gecko</h3> + +<p>Gecko 11.0 {{ geckoRelease("11.0") }} removeu o suporte para o uso do <code>responseType</code> e <code>withCredentials</code> atribui ao realizar solicitações síncronas. Tentativa de fazer isso gera uma <code>NS_ERROR_DOM_INVALID_ACCESS_ERR</code> exception. Esta mudança foi proposta para o W3C para a normalização.</p> + +<p>Gecko 12.0 {{ geckoRelease("12.0") }} e suporte posteriormente usando XMLHttpRequest para ler a partir <a href="/en/data_URIs" title="en/data_URIs"><code>data:</code> URLs</a>.</p> + +<h2 id="Veja_também">Veja também</h2> + +<ul> + <li>MDN artigos sobre XMLHttpRequest: + <ul> + <li><a href="/en/AJAX/Getting_Started" title="en/AJAX/Getting_Started">AJAX - Getting Started</a></li> + <li><a href="/en/DOM/XMLHttpRequest/Using_XMLHttpRequest" title="En/Using XMLHttpRequest">Using XMLHttpRequest</a></li> + <li><a href="/en/HTML_in_XMLHttpRequest" title="en/HTML_in_XMLHttpRequest">HTML in XMLHttpRequest</a></li> + <li><a href="/en/DOM/XMLHttpRequest/FormData" title="en/XMLHttpRequest/FormData"><code>FormData</code></a></li> + </ul> + </li> + <li>XMLHttpRequest referencias da W3C e navegador fornecedores: + <ul> + <li><a class="external" href="http://www.w3.org/TR/XMLHttpRequest1/">W3C: XMLHttpRequest</a> (base features)</li> + <li><a class="external" href="http://dvcs.w3.org/hg/xhr/raw-file/tip/Overview.html" title="http://dvcs.w3.org/hg/xhr/raw-file/tip/Overview.html">W3C: XMLHttpRequest</a> (latest editor's draft with extensions to the base functionality, formerly XMLHttpRequest Level 2</li> + <li><a class="external" href="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/xmlsdk/html/xmobjxmlhttprequest.asp">Microsoft documentation</a></li> + <li><a class="external" href="http://developer.apple.com/internet/webcontent/xmlhttpreq.html">Apple developers' reference</a></li> + </ul> + </li> + <li><a class="external" href="http://jibbering.com/2002/4/httprequest.html">"Using the XMLHttpRequest Object" (jibbering.com)</a></li> + <li><a class="external" href="http://www.peej.co.uk/articles/rich-user-experience.html">XMLHttpRequest - REST and the Rich User Experience</a></li> + <li><a class="external" href="http://www.html5rocks.com/en/tutorials/file/xhr2/">HTML5 Rocks - New Tricks in XMLHttpRequest2</a></li> +</ul> + +<p>{{ languages( { "es": "es/XMLHttpRequest", "fr": "fr/XMLHttpRequest", "it": "it/XMLHttpRequest", "ja": "ja/XMLHttpRequest", "ko": "ko/XMLHttpRequest", "pl": "pl/XMLHttpRequest", "zh-cn": "zh-cn/DOM/XMLHttpRequest" } ) }}</p> diff --git a/files/pt-br/web/api/xmlhttprequest/onreadystatechange/index.html b/files/pt-br/web/api/xmlhttprequest/onreadystatechange/index.html new file mode 100644 index 0000000000..b67e816ae4 --- /dev/null +++ b/files/pt-br/web/api/xmlhttprequest/onreadystatechange/index.html @@ -0,0 +1,120 @@ +--- +title: XMLHttpRequest.onreadystatechange +slug: Web/API/XMLHttpRequest/onreadystatechange +tags: + - AJAX + - API + - Evento + - Manipulador de eventos + - XHR + - XMLHttpRequest +translation_of: Web/API/XMLHttpRequest/onreadystatechange +--- +<div>{{APIRef}}</div> + +<p>Um <a href="https://developer.mozilla.org/en-US/docs/Web/API/EventHandler" title="A possible way to get notified of Events of a particular type (such as click) for a given object is to specify an event handler using:"><code>EventHandler</code></a> é chamado sempre que o atributo <code>readyState</code> é modificado. O callback é chamado a partir da interface do usuário. A propriedade <strong><code>XMLHttpRequest.onreadystatechange</code></strong> contém o manipulador de eventos que é chamado quando o evento <a href="/pt-BR/docs/Web/Events/readystatechange">readystatechange</a> é disparado, ou seja, toda vez que a propriedade {{domxref("XMLHttpRequest.readyState", "readyState")}} do {{domxref("XMLHttpRequest")}} é modificada.</p> + +<div class="warning"> +<p><strong>Atenção:</strong> Isso não deve ser usado com solicitações síncronas e não deve ser usado como código nativo.</p> +</div> + +<p>O evento <code>readystatechange</code> não será chamado quando a <code>XMLHttpRequest</code> request for cancelada pelo método <a href="/pt-BR/docs/Web/API/XMLHttpRequest/abort">abort()</a>.</p> + +<div class="note"> +<p><strong>Atualização</strong>: Está disparando na última versão de navegadores (Firefox 51.0.1, Opera 43.0.2442.991, Safari 10.0.3 (12602.4.8), Chrome 54.0.2840.71, Edge, IE11). Exemplo <a href="https://jsfiddle.net/merksam/ve5oc0gn/">aqui</a> - <em>basta recarregar a página algumas vezes</em>.</p> +</div> + +<h2 id="Syntax" name="Syntax">Sitaxe</h2> + +<pre class="syntaxbox"><em>XMLHttpRequest</em>.onreadystatechange = <em>callback</em>;</pre> + +<h3 id="Valores">Valores</h3> + +<ul> + <li><code><em>callback</em></code> é a função que será executada quando o readyState mudar.</li> +</ul> + +<h2 id="Example" name="Example">Exemplo</h2> + +<pre class="brush: js">var xhr = new XMLHttpRequest(), + method = "GET", + url = "https://developer.mozilla.org/"; + +xhr.open(<em>method</em>, <em>url</em>, true); +xhr.onreadystatechange = function () { + if(xhr.readyState === XMLHttpRequest.DONE && xhr.status === 200) { + console.log(xhr.responseText); + } + }; +xhr.send();</pre> + +<h2 id="Especificação">Especificação</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th scope="col">Especificação</th> + <th scope="col">Status</th> + <th scope="col">Comentário</th> + </tr> + <tr> + <td>{{SpecName('XMLHttpRequest', '#handler-xhr-onreadystatechange')}}</td> + <td>{{Spec2('XMLHttpRequest')}}</td> + <td>WHATWG living standard</td> + </tr> + </tbody> +</table> + +<h2 id="Compatibilidade_entre_navegadores">Compatibilidade entre navegadores</h2> + +<p>{{CompatibilityTable}}</p> + +<div id="compat-desktop"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Chrome</th> + <th>Firefox (Gecko)</th> + <th>Internet Explorer</th> + <th>Opera</th> + <th>Safari</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatChrome(1)}}</td> + <td>{{CompatGeckoDesktop(1.0)}}</td> + <td>{{CompatIe(7)}}<sup>[1]</sup></td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatSafari(1.2)}}</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Chrome for Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatUnknown}}</td> + <td>1.0</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<p>[1] Internet Explorer versão 5 e 6 suportam chamadas ajax usando <code>ActiveXObject()</code>.</p> diff --git a/files/pt-br/web/api/xmlhttprequest/open/index.html b/files/pt-br/web/api/xmlhttprequest/open/index.html new file mode 100644 index 0000000000..131d78d21f --- /dev/null +++ b/files/pt-br/web/api/xmlhttprequest/open/index.html @@ -0,0 +1,72 @@ +--- +title: XMLHttpRequest.open() +slug: Web/API/XMLHttpRequest/open +tags: + - Referencia + - metodo +translation_of: Web/API/XMLHttpRequest/open +--- +<div>{{APIRef('XMLHttpRequest')}}</div> + +<p>O {{domxref("XMLHttpRequest")}} método<code><strong>open()</strong></code> inicializa uma nova requisição, ou reinicializa uma requisição já existente.</p> + +<div class="note"><strong>Note:</strong> Chamar este método para uma requisição já ativada (uma que <code>open()</code> já tenha sido chamada) é equivalente a chamar {{domxref("XMLHttpRequest.abort", "abort()")}}.</div> + +<h2 id="Sintaxe">Sintaxe</h2> + +<pre class="syntaxbox"><em>XMLHttpRequest</em>.open(<var>method</var>,<var> url</var>) +<em>XMLHttpRequest</em>.open(<var>method</var>,<var> url</var>,<var> async)</var> +<em>XMLHttpRequest</em>.open(<var>method</var>,<var> url</var>,<var> async</var>,<var> user</var>) +<em>XMLHttpRequest</em>.open(<var>method</var>,<var> url</var>,<var> async</var>,<var> user</var>,<var> password</var>) +</pre> + +<h3 id="Parâmetros">Parâmetros</h3> + +<dl> + <dt><code>method</code></dt> + <dd>O <a href="/en-US/docs/Web/HTTP/Methods">método de requisição HTTP</a> para ser usado, como <code>"GET"</code>, <code>"POST"</code>, <code>"PUT"</code>, <code>"DELETE"</code>, etc. Ignorado para URLs não-HTTP(S).</dd> + <dt><code>url</code></dt> + <dd>Um {{domxref("DOMString")}} representando a URL para enviar a requisição.</dd> + <dt><code>async</code> {{optional_inline}}</dt> + <dd>Parâmetro booleano opcional, valor padrão <code>true</code>, indica quando realizar a operação de forma assíncrona. Se este valor for <code>false</code>, o método <code>send()</code> não retorna nada até que a resposta da requisição seja recebida. Se o valor for <code>true</code>, notificação de uma transação concluída é provida usando event listeners. Isso <em>deve</em> ser verdadeiro se o atributo <code>multipart</code> é <code>true</code>, ou uma exceção será lançada. + <div class="note"><strong>Nota:</strong> Requisições Síncronas no thread principal podem ser facilmente disruptivas para a experiência de usuário e devem ser evitadas; de fato, muitos navegadores descontinuaram inteiramente o suporte para XHR síncrono no thread principal. Requisições síncronas são permitidas nos {{domxref("Worker")}}s.</div> + </dd> + <dt><code>user</code> {{optional_inline}}</dt> + <dd>O nome de usuário opcional para ser usado em autenticação; por padrão, isso é o valor <code>null</code>.</dd> + <dt><code>password</code> {{optional_inline}}</dt> + <dd>A senha de usuário opcional para ser usado em autenticação; por padrão, isso é o valor <code>null</code>.</dd> +</dl> + +<h2 id="Especificações">Especificações</h2> + +<table class="standard-table"> + <thead> + <tr> + <th scope="col">Especificação</th> + <th scope="col">Status</th> + <th scope="col">Comentário</th> + </tr> + </thead> + <tbody> + <tr> + <td>{{SpecName('XMLHttpRequest', '#the-open()-method', 'open()')}}</td> + <td>{{Spec2('XMLHttpRequest')}}</td> + <td> + <p>Padrão WHATWG</p> + </td> + </tr> + </tbody> +</table> + +<h2 id="Compatibilidade_de_Navegador">Compatibilidade de Navegador</h2> + +<p class="hidden">A tabela de compatibilidade nessa página é gerada por dados estruturados. Se voce gostaria de contribuir para os dados, favor verificar <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> e nos envie um <em>pull request</em>.</p> + +<p>{{Compat("api.XMLHttpRequest.open")}}</p> + +<h2 id="Veja_também">Veja também</h2> + +<ul> + <li><a href="/en-US/docs/Web/API/XMLHttpRequest/Using_XMLHttpRequest">Usando XMLHttpRequest</a></li> + <li>Métodos Relacionados ao {{domxref("XMLHttpRequest")}}: {{domxref("XMLHttpRequest.setRequestHeader", "setRequestHeader()")}},{{domxref("XMLHttpRequest.send", "send()")}}, e {{domxref("XMLHttpRequest.abort", "abort()")}}</li> +</ul> diff --git a/files/pt-br/web/api/xmlhttprequest/readystate/index.html b/files/pt-br/web/api/xmlhttprequest/readystate/index.html new file mode 100644 index 0000000000..77474ae587 --- /dev/null +++ b/files/pt-br/web/api/xmlhttprequest/readystate/index.html @@ -0,0 +1,154 @@ +--- +title: XMLHttpRequest.readyState +slug: Web/API/XMLHttpRequest/readyState +tags: + - AJAX + - Property + - Reference + - XML + - XMLHttpRequest +translation_of: Web/API/XMLHttpRequest/readyState +--- +<p>{{APIRef('XMLHttpRequest')}}</p> + +<p>A propriedade <strong>XMLHttpRequest.readyState</strong> retorna o estado de um XMLHttpRequest. Uma requisição <abbr title="XMLHttpRequest">XHR</abbr> que existe em um dos seguintes estados:</p> + +<table class="standard-table"> + <tbody> + <tr> + <td class="header">Valor</td> + <td class="header">Estado</td> + <td class="header">Descrição</td> + </tr> + <tr> + <td><code>0</code></td> + <td><code>UNSENT</code></td> + <td>Um cliente foi criado. Mas o método <code>open()</code> não foi chamado ainda.</td> + </tr> + <tr> + <td><code>1</code></td> + <td><code>OPENED</code></td> + <td><code>O método open() foi chamado</code>.</td> + </tr> + <tr> + <td><code>2</code></td> + <td><code>HEADERS_RECEIVED</code></td> + <td><code>o método send()</code> foi chamado e os cabeçalhos e status estão disponíveis .</td> + </tr> + <tr> + <td><code>3</code></td> + <td><code>LOADING</code></td> + <td>Baixando e <code>responseText</code> contem os dados parciais.</td> + </tr> + <tr> + <td><code>4</code></td> + <td><code>DONE</code></td> + <td>Operação concluída.</td> + </tr> + </tbody> +</table> + +<dl> + <dt>UNSENT</dt> + <dd>O XMLHttpRequest foi criado. Mas o método open() não foi chamado ainda.</dd> + <dt>OPENED</dt> + <dd>O método open() foi invocado. Durante esse estado, os headers da requisição podem ser inseridos usando o método <a href="/en-US/docs/Web/API/XMLHttpRequest/setRequestHeader">setRequestHeader()</a> e o método <a href="/en-US/docs/Web/API/XMLHttpRequest/send">send()</a> pode ser chamado, iniciando a busca.</dd> + <dt>HEADERS_RECEIVED</dt> + <dd>O método send() foi chamado e os cabeçalhos de respostas foram recebidos.</dd> + <dt>LOADING</dt> + <dd>A resposta da requisição está sendo recebida. se o <code><a href="/en-US/docs/Web/API/XMLHttpRequest/responseType">responseType</a></code> for "text" ou um texto em branco, o <code><a href="/en-US/docs/Web/API/XMLHttpRequest/responseText">responseText</a></code> terá o texto parcial da resposta conforme seu carregamento.</dd> + <dt>DONE</dt> + <dd>A Operação de busca está completa. Isso pode significar que a trasferência foi concluída com êxito ou que falhou.</dd> +</dl> + +<div class="note"> +<p>Os nomes de estado são diferentes no Internet Explorer. Ao invés de <code>UNSENT</code>, <code>OPENED</code>,<code> HEADERS_RECEIVED</code>,<code> LOADING <font face="Open Sans, Arial, sans-serif">e </font></code><code>DONE, os nomes usados são: READYSTATE_UNINITIALIZED</code> (0), <code>READYSTATE_LOADING</code> (1), <code>READYSTATE_LOADED</code> (2), <code>READYSTATE_INTERACTIVE</code> (3) e <code>READYSTATE_COMPLETE</code> (4).</p> +</div> + +<h2 id="Exemplo">Exemplo</h2> + +<pre class="brush: js">var xhr = new XMLHttpRequest(); +console.log('UNSENT', xhr.readyState); // readyState will be 0 + +xhr.open('GET', '/api', true); +console.log('OPENED', xhr.readyState); // readyState will be 1 + +xhr.onprogress = function () { + console.log('LOADING', xhr.readyState); // readyState will be 3 +}; + +xhr.onload = function () { + console.log('DONE', xhr.readyState); // readyState will be 4 +}; + +xhr.send(null); +</pre> + +<h2 id="Especificações">Especificações</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th scope="col">Especificação</th> + <th scope="col">Status</th> + <th scope="col">Commentários</th> + </tr> + <tr> + <td>{{SpecName('XMLHttpRequest', '#states')}}</td> + <td>{{Spec2('XMLHttpRequest')}}</td> + <td>WHATWG living standard</td> + </tr> + </tbody> +</table> + +<h2 id="Compatibilidade_entre_navegadores">Compatibilidade entre navegadores</h2> + +<div>{{CompatibilityTable}}</div> + +<div id="compat-desktop"> +<table class="compat-table"> + <tbody> + <tr> + <th>Suporte</th> + <th>Chrome</th> + <th>Firefox (Gecko)</th> + <th>Internet Explorer</th> + <th>Opera</th> + <th>Safari (WebKit)</th> + </tr> + <tr> + <td>Suporte básico</td> + <td>{{CompatChrome(1)}}</td> + <td>{{CompatGeckoDesktop("1.0")}}<sup>[1]</sup></td> + <td>{{CompatIe(7)}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatSafari("1.2")}}</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Suporte</th> + <th>Android</th> + <th>Chrome para Android</th> + <th>Firefox Mobile (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + </tr> + <tr> + <td>Suporte básico</td> + <td>{{CompatUnknown}}</td> + <td>1.0</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> diff --git a/files/pt-br/web/api/xmlhttprequest/requisicoes_sincronas_e_assincronas/index.html b/files/pt-br/web/api/xmlhttprequest/requisicoes_sincronas_e_assincronas/index.html new file mode 100644 index 0000000000..81b8fb8d3e --- /dev/null +++ b/files/pt-br/web/api/xmlhttprequest/requisicoes_sincronas_e_assincronas/index.html @@ -0,0 +1,234 @@ +--- +title: Requisições síncronas e assíncronas +slug: Web/API/XMLHttpRequest/Requisicoes_sincronas_e_assincronas +translation_of: Web/API/XMLHttpRequest/Synchronous_and_Asynchronous_Requests +--- +<p><code>XMLHttpRequest</code> suporta comunicações síncronas e assíncronas. No geral, entretando, requisições assíncronas devem prevalecer sobre requisições síncronas por questões de performance.</p> + +<p>Requisições síncronas podem bloquear a execução do codigo, gerando um "congelamento" da tela, prejudicando a experiência do usuário. </p> + +<h2 id="Requisição_assíncrona">Requisição assíncrona</h2> + +<p>Se você usa <code>XMLHttpRequest</code> de uma extensão, você deveria usá-la de forma assíncrona. Neste caso, você recebe um callback quando os dados forem recebidos, o que permite que o browser continue seu trabalho normalmente enquanto sua requisição estiver sendo processada.</p> + +<h3 id="Exemplo_envie_um_arquivo_para_o_console_de_log">Exemplo: envie um arquivo para o console de log</h3> + +<p>Esse é o exemplo mais simples de uso do <code>XMLHttpRequest assíncrono.</code></p> + +<pre class="brush: js">var xhr = new XMLHttpRequest(); +xhr.open("GET", "/bar/foo.txt", true); +xhr.onload = function (e) { + if (xhr.readyState === 4) { + if (xhr.status === 200) { + console.log(xhr.responseText); + } else { + console.error(xhr.statusText); + } + } +}; +xhr.onerror = function (e) { + console.error(xhr.statusText); +}; +xhr.send(null); </pre> + +<p>A Linha 2 define o terceiro parâmetro como true, indicando que a requisição deve ser tratada assincronamente.</p> + +<p>A Linha 3 cria um objeto função do tipo <em>event handler </em>e atribui ele ao atributo <strong>onload<em> </em></strong>da requisição.</p> + +<p>Na LInha 4, Este <em>handler </em>verifica o estado da requisição, através da variável <em>readyState, </em>para ver se a transação está completa, e se o status do HTTP é 200. Em caso positivo lê o conteúdo recebido. Se um erro ocorrer, uma mensagem de erro será exibida no console.</p> + +<p>A requisição é, de fato, realizada na Linha 15. A rotina de <em>callback</em> é invocada quando o estado da requisição muda.</p> + +<h3 id="Exemplo_Criando_uma_função_standard_para_ler_arquivos_externos">Exemplo: Criando uma função standard para ler arquivos externos</h3> + +<p>Em alguns casos, você pode precisar ler muitos arquivos externos. Esta é uma função padrão que utiliza o objeto <code>XMLHttpRequest</code> de forma assíncrona para alternar o conteúdo do arquivo legível para um listener especificado.</p> + +<pre class="brush: js">function xhrSuccess () { this.callback.apply(this, this.arguments); } + +function xhrError () { console.error(this.statusText); } + +function loadFile (sURL, fCallback /*, argumentToPass1, argumentToPass2, etc. */) { + var oReq = new XMLHttpRequest(); + oReq.callback = fCallback; + oReq.arguments = Array.prototype.slice.call(arguments, 2); + oReq.onload = xhrSuccess; + oReq.onerror = xhrError; + oReq.open("get", sURL, true); + oReq.send(null); +} +</pre> + +<p>Uso:</p> + +<pre class="brush: js">function showMessage (sMsg) { + alert(sMsg + this.responseText); +} + +loadFile("message.txt", showMessage, "New message!\n\n"); +</pre> + +<p>A assinatura da função <em><strong>loadFile</strong></em> declara (i) uma URL de destino que será lida (via HTTP GET), (ii) uma função de callback para executar na conclusão bem-sucedida da instância xhr, e (iii) uma lista opcional de argumentos adicionais que são "passados através" do objeto XHR caso a função de callback seja bem-sucedida.</p> + +<p>A linha 1 declara uma função que será invocada quando a operação XHR for completada com sucesso. Isso, por sua vez, invoca uma função de callback especificada na invocação da função loadFile (neste caso, a função showMessage) que foi atribuída a propriedade do objeto XHR (Linha 7). Os argumentos adicionais (caso existam) fornecem a invocação da função loadFile são "aplicados" para a execução da função de callback..</p> + +<p>A linha 3 declara uma função que será invocada quando a operação XHR não for completada com sucesso.</p> + +<p>A linha 7 define no objeto XHR the success callback function given as the second argument to loadFile.</p> + +<p>Line 8 slices the arguments array given to the invocation of loadFile. Starting with the third argument, all remaining arguments are collected, assigned to the arguments property of the variable oReq, passed to the success callback function xhrSuccess., and ultimately supplied to the callback function (in this case, showMessage) which is invoked by function xhrSuccess.</p> + +<p>Line 9 designates the function xhrSuccess as the callback to be invoked when the onload event fires, that is, when the XHR sucessfully completes. </p> + +<p>Line 10 designates the function xhrError as the callback to be invoked when the XHR requests fails to complete.</p> + +<p>Line 11 specifies <code>true</code> for its third parameter to indicate that the request should be handled asynchronously.</p> + +<p>Line 12 actually initiates the request.</p> + +<h3 id="Example_using_a_timeout">Example: using a timeout</h3> + +<p>You can use a timeout to prevent hanging your code forever while waiting for a read to occur. This is done by setting the value of the <code>timeout</code> property on the <code>XMLHttpRequest</code> object, as shown in the code below:</p> + +<pre class="brush: js">function loadFile(sUrl, timeout, callback){ + + var args = arguments.slice(3); + var xhr = new XMLHttpRequest(); + xhr.ontimeout = function () { + console.error("The request for " + url + " timed out."); + }; + xhr.onload = function() { + if (xhr.readyState === 4) { + if (xhr.status === 200) { + callback.apply(xhr, args); + } else { + console.error(xhr.statusText); + } + } + }; + xhr.open("GET", url, true); + xhr.timeout = timeout; + xhr.send(null); +}</pre> + +<p>Notice the addition of code to handle the "timeout" event by setting the <code>ontimeout</code> handler.</p> + +<p>Usage:</p> + +<pre class="brush: js">function showMessage (sMsg) { + alert(sMsg + this.responseText); +} + +loadFile("message.txt", 2000, showMessage, "New message!\n"); +</pre> + +<p>Here, we're specifying a timeout of 2000 ms.</p> + +<div class="note"> +<p><strong>Note:</strong> Support for <code>timeout</code> was added in {{Gecko("12.0")}}.</p> +</div> + +<h2 id="Synchronous_request">Synchronous request</h2> + +<div class="note"><strong>Note:</strong> Starting with Gecko 30.0 {{ geckoRelease("30.0") }}, synchronous requests on the main thread have been deprecated due to the negative effects to the user experience.</div> + +<p>Em casos raros, o uso do método síncrono é preferível ao invés do método assíncrono.</p> + +<h3 id="Example_HTTP_synchronous_request">Example: HTTP synchronous request</h3> + +<p>This example demonstrates how to make a simple synchronous request.</p> + +<pre class="brush: js">var request = new XMLHttpRequest(); +request.open('GET', '/bar/foo.txt', false); // `false` makes the request synchronous +request.send(null); + +if (request.status === 200) { + console.log(request.responseText); +} +</pre> + +<p>Line 3 sends the request. The <code>null</code> parameter indicates that no body content is needed for the <code>GET</code> request.</p> + +<p>Line 5 checks the status code after the transaction is completed. If the result is 200 -- HTTP's "OK" result -- the document's text content is output to the console.</p> + +<h3 id="Example_Synchronous_HTTP_request_from_a_Worker">Example: Synchronous HTTP request from a <code>Worker</code></h3> + +<p>One of the few cases in which a synchronous request does not usually block execution is the use of <code>XMLHttpRequest</code> within a <code><a href="/en/DOM/Worker" title="/en/DOM/Worker">Worker</a></code>.</p> + +<p><code><strong>example.html</strong></code> (the main page):</p> + +<pre class="brush: html"><!doctype html> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> +<title>MDN Example</title> +<script type="text/javascript"> + var worker = new Worker("myTask.js"); + worker.onmessage = function(event) { + alert("Worker said: " + event.data); + }; + + worker.postMessage("Hello"); +</script> +</head> +<body></body> +</html> +</pre> + +<p><code><strong>myFile.txt</strong></code> (the target of the synchronous <code><a href="/en/DOM/XMLHttpRequest" title="/en/XMLHttpRequest">XMLHttpRequest</a></code> invocation):</p> + +<pre>Hello World!! +</pre> + +<p><code><strong>myTask.js</strong></code> (the <code><a href="/en/DOM/Worker" title="/en/DOM/Worker">Worker</a></code>):</p> + +<pre class="brush: js">self.onmessage = function (event) { + if (event.data === "Hello") { + var xhr = new XMLHttpRequest(); + xhr.open("GET", "myFile.txt", false); // synchronous request + xhr.send(null); + self.postMessage(xhr.responseText); + } +}; +</pre> + +<div class="note"><strong>Note:</strong> The effect, because of the use of the <code>Worker</code>, is however asynchronous.</div> + +<p>It could be useful in order to interact in background with the server or to preload some content. See <a class="internal" href="/En/DOM/Using_web_workers" title="en/Using DOM workers">Using web workers</a> for examples and details.</p> + +<h3 id="Adapting_Sync_XHR_usecases_to_the_Beacon_API">Adapting Sync XHR usecases to the Beacon API</h3> + +<p>There are some cases in which the synchronous usage of XMLHttpRequest was not replaceable, like during the <a class="internal" href="/en/DOM/window.onunload" title="en/DOM/window.onunload"><code>window.onunload</code></a> and <a class="internal" href="/en/DOM/window.onbeforeunload" title="en/DOM/window.onbeforeunload"><code>window.onbeforeunload</code></a> events. The <a href="/en-US/docs/Web/API/Navigator/sendBeacon">navigator.sendBeacon</a> API can support these usecases typically while delivering a good UX.</p> + +<p><span>The following example (from the <a href="/en-US/docs/Web/API/Navigator/sendBeacon">sendBeacon docs</a>) shows a theoretical analytics code that attempts to submit data to a server by using a synchronous XMLHttpRequest in an unload handler. This results in the unload of the page to be delayed.</span></p> + +<pre class="brush: js">window.addEventListener('unload', logData, false); + +function logData() { + var client = new XMLHttpRequest(); + client.open("POST", "/log", false); // third parameter indicates sync xhr. :( + client.setRequestHeader("Content-Type", "text/plain;charset=UTF-8"); + client.send(analyticsData); +} +</pre> + +<p>Using the <strong><code>sendBeacon()</code></strong> method, the data will be transmitted asynchronously to the web server when the User Agent has had an opportunity to do so, <strong>without delaying the unload or affecting the performance of the next navigation.</strong></p> + +<p>The following example shows a theoretical analytics code pattern that submits data to a server using the by using the <strong><code>sendBeacon()</code></strong> method.</p> + +<pre class="brush: js">window.addEventListener('unload', logData, false); + +function logData() { + navigator.sendBeacon("/log", analyticsData); +} +</pre> + +<h2 id="See_also">See also</h2> + +<ul> + <li><a href="/en-US/docs/Web/API/XMLHttpRequest" title="https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest"><code>XMLHttpRequest</code></a></li> + <li><a href="/en-US/docs/Web/API/XMLHttpRequest/Using_XMLHttpRequest" title="https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest/Using_XMLHttpRequest">Using XMLHttpRequest</a></li> + <li><a href="/en-US/docs/AJAX" title="/en-US/docs/AJAX">AJAX</a></li> + <li><code><a href="/en-US/docs/Web/API/Navigator/sendBeacon">navigator.sendBeacon</a></code></li> +</ul> + +<p>{{ languages( {"zh-cn": "zh-cn/DOM/XMLHttpRequest/Synchronous_and_Asynchronous_Requests" } ) }}</p> diff --git a/files/pt-br/web/api/xmlhttprequest/send/index.html b/files/pt-br/web/api/xmlhttprequest/send/index.html new file mode 100644 index 0000000000..21fa359025 --- /dev/null +++ b/files/pt-br/web/api/xmlhttprequest/send/index.html @@ -0,0 +1,129 @@ +--- +title: XMLHttpRequest.send() +slug: Web/API/XMLHttpRequest/send +tags: + - AJAX + - API + - Método HTTP + - NeedsExample + - Referencia + - Requisição HTTP + - Requisição XHR + - XHR + - XMLHttpRequest + - send +translation_of: Web/API/XMLHttpRequest/send +--- +<p>{{APIRef('XMLHttpRequest')}}</p> + +<p>O método <code><strong>send()</strong></code>, do {{domxref("XMLHttpRequest")}}, envia uma requisição para o servidor.Se a solicitação for assíncrona (que é o padrão), esse método retornará assim que a solicitação for enviada e o resultado for entregue usando eventos. Se a solicitação for síncrona, esse método não retornará até que a resposta chegue.</p> + +<p><code>send()</code> aceita um parâmetro opcional que permite especificar o corpo da solicitação; isso é usado principalmente para solicitações como {{HTTPMethod("PUT")}}. Se o método de solicitação for {{HTTPMethod("GET")}} ou {{HTTPMethod("HEAD")}}, o parâmetro <code>body</code> será ignorado e o corpo da solicitação será definido como <code>null</code>.</p> + +<p>Se nenhum cabeçalho {{HTTPHeader("Accept")}} tiver sido definido usando {{domxref("XMLHttpRequest.setRequestHeader", "setRequestHeader()")}}, um cabeçalho <code>Accept</code> com o tipo <code>"*/*"</code> (qualquer tipo) é enviado.</p> + +<h2 id="Sintaxe">Sintaxe</h2> + +<pre class="syntaxbox"><var>XMLHttpRequest</var>.send(<var>body</var>) +</pre> + +<h3 id="Parâmetros">Parâmetros</h3> + +<dl> + <dt><code>body</code> {{optional_inline}}</dt> + <dd>Um corpo de dados a ser enviado na solicitação XHR. Isso pode ser: + <ul> + <li>Um {{domxref("Document")}}, caso em que é serializado antes de ser enviado.</li> + <li>Um <code>BodyInit</code>, que <a href="https://fetch.spec.whatwg.org/#bodyinit">conforme a espeficicação Fetch</a>, pode ser um objeto {{domxref("Blob")}}, {{domxref("BufferSource")}}, {{domxref("FormData")}}, {{domxref("URLSearchParams")}}, {{domxref("ReadableStream")}} ou {{domxref("USVString")}}.</li> + </ul> + Se nenhum valor for espeficicado para o corpo, o valor padrão de <code>null</code> é usado.</dd> +</dl> + +<p>A melhor maneira de enviar conteúdo binário (por exemplo, em uploads de arquivos) é usando um {{domxref("ArrayBufferView")}} ou {{domxref("Blob")}} em conjunto com o método <code>send()</code>.</p> + +<h3 id="Valor_retornado">Valor retornado</h3> + +<p><code>undefined.</code></p> + +<h3 id="Exceções">Exceções</h3> + +<table class="standard-table"> + <thead> + <tr> + <th scope="col">Exceção</th> + <th scope="col">Descrição</th> + </tr> + </thead> + <tbody> + <tr> + <td><code>InvalidStateError</code></td> + <td><code>send()</code> já foi invocado para a requisição, e/ou a requisição está completa.</td> + </tr> + <tr> + <td><code>NetworkError</code></td> + <td>O tipo de recurso a ser buscada é um {{domxref("Blob")}} e o método não é <code>GET</code>.</td> + </tr> + </tbody> +</table> + +<h2 id="Exemplo_GET">Exemplo: GET</h2> + +<pre class="syntaxbox">var xhr = new XMLHttpRequest(); +xhr.open('GET', '/server', true); + +xhr.onload = function () { + // Requisição finalizada. Faça o processamento aqui. +}; + +xhr.send(null); +// xhr.send('string'); +// xhr.send(new Blob()); +// xhr.send(new Int8Array()); +// xhr.send(document);</pre> + +<h2 id="Exemplo_POST">Exemplo: POST</h2> + +<pre class="syntaxbox">var xhr = new XMLHttpRequest(); +xhr.open("POST", '/server', true); + +// Envia a informação do cabeçalho junto com a requisição. +xhr.setRequestHeader("Content-Type", "application/x-www-form-urlencoded"); + +xhr.onreadystatechange = function() { // Chama a função quando o estado mudar. + if (this.readyState === XMLHttpRequest.DONE && this.status === 200) { + // Requisição finalizada. Faça o processamento aqui. + } +} +xhr.send("foo=bar&lorem=ipsum"); +// xhr.send(new Int8Array()); +// xhr.send(document);</pre> + +<h2 id="Especificações">Especificações</h2> + +<table class="standard-table"> + <thead> + <tr> + <th scope="col">Especificação</th> + <th scope="col">Status</th> + <th scope="col">Comentário</th> + </tr> + </thead> + <tbody> + <tr> + <td>{{SpecName('XMLHttpRequest', '#the-send()-method', 'send()')}}</td> + <td>{{Spec2('XMLHttpRequest')}}</td> + <td>WHATWG living standard</td> + </tr> + </tbody> +</table> + +<h2 id="Compatibilidade_com_os_navegadores">Compatibilidade com os navegadores</h2> + +<div>{{Compat("api.XMLHttpRequest.send")}}</div> + +<h2 id="Veja_também">Veja também</h2> + +<ul> + <li><a href="/pt-BR/docs/Web/API/XMLHttpRequest/Usando_XMLHttpRequest">Usando XMLHttpRequest</a></li> + <li><a href="/pt-BR/docs/Web/API/XMLHttpRequest/HTML_in_XMLHttpRequest">Obter arquivo HTML usando XMLHttpRequest</a></li> +</ul> diff --git a/files/pt-br/web/api/xmlhttprequest/setrequestheader/index.html b/files/pt-br/web/api/xmlhttprequest/setrequestheader/index.html new file mode 100644 index 0000000000..246692fa09 --- /dev/null +++ b/files/pt-br/web/api/xmlhttprequest/setrequestheader/index.html @@ -0,0 +1,77 @@ +--- +title: XMLHttpRequest.setRequestHeader() +slug: Web/API/XMLHttpRequest/setRequestHeader +tags: + - API + - Cabeçalho HTTP + - HTTP + - XHR + - XMLHttpRequest + - header + - metodo + - setRequestHeader +translation_of: Web/API/XMLHttpRequest/setRequestHeader +--- +<div>{{APIRef('XMLHttpRequest')}}</div> + +<div> </div> + +<p>O método <code><strong>setRequestHeader()</strong></code> de {{domxref("XMLHttpRequest")}} define o valor do cabeçalho de uma requisição HTTP. Ao usar <code>setRequestHeader()</code>, você deve chamá-lo depois de chamar o método {{domxref("XMLHttpRequest.open", "open()")}}, mas antes de chamar o método {{domxref("XMLHttpRequest.send", "send()")}}. Se esse método é chamado muitas vezes com o mesmo cabeçalho, os valores são somados em um único cabeçalho de requisição HTTP.</p> + +<p>A cada vez que você chama <code>setRequestHeader()</code> depois de ter chamado-o pelo menos uma vez, o texto especificado é somado ao final do conteúdo do cabeçalho existente.</p> + +<p>Se nenhum cabeçalho {{HTTPHeader("Accept")}} foi definido usando este método, um cabeçalho <code>Accept</code> com o tipo <code>"*/*"</code> é enviado com a requisição quando {{domxref("XMLHttpRequest.send", "send()")}} é chamado.</p> + +<p>Por razões de segurança, alguns cabeçalhos só podem ser controlados pelo agente do usuário. Esses cabeçalhos incluem o cabeçalho {{Glossary("Forbidden_header_name", "forbidden header names", 1)}} e o cabeçalho {{Glossary("Forbidden_response_header_name", "forbidden response header names", 1)}}.</p> + +<div class="note"> +<p><strong>Observação:</strong> Para seu campos personalizados, você pode encontrar uma exceção "<strong>not allowed by Access-Control-Allow-Headers in preflight response</strong>" quando você envia requisições através de domínios. Neste caso, você precisa definir o cabeçalho {{HTTPHeader("Access-Control-Allow-Headers")}} no seu cabeçalho de resposta no lado do servidor.</p> +</div> + +<h2 id="Sintaxe">Sintaxe</h2> + +<pre class="syntaxbox"><em>XMLHttpRequest</em>.setRequestHeader(<var>header</var>, <var>value</var>) +</pre> + +<h3 id="Parâmetros">Parâmetros</h3> + +<dl> + <dt><code>header</code></dt> + <dd>O nome do cabeçalho cujo valor está para ser definido.</dd> + <dt><code>value</code></dt> + <dd>O valor a ser definido como o corpo do cabeçalho.</dd> +</dl> + +<h3 id="Valor_de_retorno">Valor de retorno</h3> + +<p><code>undefined</code>.</p> + +<h2 id="Especificações">Especificações</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th scope="col">Especificação</th> + <th scope="col">Status</th> + <th scope="col">Comentário</th> + </tr> + <tr> + <td>{{SpecName('XMLHttpRequest', '#the-setRequestHeader()-method', 'setRequestHeader()')}}</td> + <td>{{Spec2('XMLHttpRequest')}}</td> + <td>WHATWG living standard</td> + </tr> + </tbody> +</table> + +<h2 id="Compatibilidade_com_navegadores">Compatibilidade com navegadores</h2> + + + +<p>{{Compat("api.XMLHttpRequest.setRequestHeader")}}</p> + +<h2 id="Veja_também">Veja também</h2> + +<ul> + <li><a href="/en-US/docs/Web/API/XMLHttpRequest/Using_XMLHttpRequest">Usando XMLHttpRequest</a></li> + <li><a href="/en-US/docs/Web/API/XMLHttpRequest/HTML_in_XMLHttpRequest">HTML em XMLHttpRequest</a></li> +</ul> diff --git a/files/pt-br/web/api/xmlhttprequest/timeout/index.html b/files/pt-br/web/api/xmlhttprequest/timeout/index.html new file mode 100644 index 0000000000..d80b67d77d --- /dev/null +++ b/files/pt-br/web/api/xmlhttprequest/timeout/index.html @@ -0,0 +1,51 @@ +--- +title: XMLHttpRequest.timeout +slug: Web/API/XMLHttpRequest/timeout +translation_of: Web/API/XMLHttpRequest/timeout +--- +<div>{{APIRef('XMLHttpRequest')}}</div> + +<p>A propriedade <code><strong>XMLHttpRequest.timeout</strong></code> é um <code>unsigned long</code> que representa o número de milisegundos que uma requisição deve esperar até ser automaticamente terminada. O valor padrão para essa propriedade é 0, o que significa que o navegador deverá esperar uma resposta indefinidamente. A propriedade Timeout não deveria ser usada para requisições XMLHttpRequests síncronas em um {{Glossary('document environment')}} ou uma exceção do tipo <code>InvalidAccessError</code> será lançada. Quando um timeout ocorre, o evento <a href="/en-US/docs/Web/Events/timeout">timeout</a> é disparado. {{gecko_minversion_inline("12.0")}}</p> + +<dl> + <dd> + <div class="note"><strong>Nota:</strong> Você não pode usar um timeout para requisições síncronas dentro de uma janela.</div> + </dd> + <dd><a href="/en-US/docs/Web/API/XMLHttpRequest/Synchronous_and_Asynchronous_Requests#Example_using_a_timeout">Utilizando um timeout com uma requisição assíncrona</a> </dd> +</dl> + +<p>No Internet Explorer, a propriedade timeout pode ser usada apenas depois de o método <a href="/en-US/docs/Web/API/XMLHttpRequest/open">open()</a> ter sido invocado e antes de se chamar o método <a href="/en-US/docs/Web/API/XMLHttpRequest/send">send()</a>.</p> + +<h2 id="Exemplo">Exemplo</h2> + +<pre class="brush: js">var xhr = new XMLHttpRequest(); +xhr.open('GET', '/server', true); + +xhr.timeout = 2000; // tempo em milisegundos + +xhr.onload = function () { + // Requisição finalizada. O processamento deve ser colocado aqui. +}; + +xhr.ontimeout = function (e) { + // Timeout na chamada XMLHttpRequest. Ação de timeout aqui. +}; + +xhr.send(null);</pre> + +<h2 id="Especificações">Especificações</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th scope="col">Especificação</th> + <th scope="col">Status</th> + <th scope="col">Comentários</th> + </tr> + <tr> + <td>{{SpecName('XMLHttpRequest', '#the-timeout-attribute')}}</td> + <td>{{Spec2('XMLHttpRequest')}}</td> + <td>WHATWG living standard</td> + </tr> + </tbody> +</table> diff --git a/files/pt-br/web/api/xmlhttprequest/usando_xmlhttprequest/index.html b/files/pt-br/web/api/xmlhttprequest/usando_xmlhttprequest/index.html new file mode 100644 index 0000000000..b541e64bc1 --- /dev/null +++ b/files/pt-br/web/api/xmlhttprequest/usando_xmlhttprequest/index.html @@ -0,0 +1,688 @@ +--- +title: Usando XMLHttpRequest +slug: Web/API/XMLHttpRequest/Usando_XMLHttpRequest +translation_of: Web/API/XMLHttpRequest/Using_XMLHttpRequest +--- +<p><a href="/en-US/docs/DOM/XMLHttpRequest" title="XMLHttpRequest"><code>XMLHttpRequest</code></a> torna o envio de requisições HTTP muito fácil. Basta criar uma instância do objeto, abrir uma url e enviar uma requisição. O <a href="/en-US/docs/HTTP/HTTP_response_codes" title="HTTP response codes">status</a> <a href="/en-US/docs/HTTP/HTTP_response_codes" title="HTTP response codes">HTTP </a>do resultado assim como o seu conteúdo estarão disponíveis quando a transação for completada. Esta página descreve alguns casos comuns de uso desse poderoso objeto JavaScript.</p> + +<pre class="brush: js">function reqListener () { + console.log(this.responseText); +}; + +var oReq = new XMLHttpRequest(); +oReq.onload = reqListener; +oReq.open("get", "yourFile.txt", true); +oReq.send();</pre> + +<h2 id="Tipos_de_Requisições">Tipos de Requisições</h2> + +<p>Uma requisição feita via XMLHttpRequest pode buscar dados de duas maneiras, sícrona e assíncrona. <span style="line-height: 1.5;">O tipo de requisição é dado pelo argumento <code>async</code> que é opcional (terceiro argumento) e é definido no método XMLHttpRequest </span><a href="/en-US/docs/DOM/XMLHttpRequest#open()" style="line-height: 1.5;" title="DOM/XMLHttpRequest#open()">open()</a><span style="line-height: 1.5;">. Se esse argumento for <code>true</code> ou não especificado, o <code>XMLHttpRequest</code> será processado de maneira assíncrona, caso contrário o processamento será síncrono. Uma discussão detalhada e demonstrações desses dois tipos podem ser encontradas na página </span><a href="/en-US/docs/DOM/XMLHttpRequest/Synchronous_and_Asynchronous_Requests" style="line-height: 1.5;" title="Synchronous and Asynchronous Requests">requisições síncronas e assíncronas</a><span style="line-height: 1.5;">. No geral a melhor prática é a das solicitações assíncronas.</span></p> + +<h2 id="Manipulando_Respostas">Manipulando Respostas</h2> + +<p>Existem vários tipos de <a href="http://www.w3.org/TR/XMLHttpRequest2/#response" title="http://www.w3.org/TR/XMLHttpRequest2/#response">atributos de resposta</a> definidos pela especificação da W3C para o XMLHttpRequest. Eles informam ao cliente que efetuou a requisição XMLHttpRequest informações importantes sobre o status da resposta. Em alguns casos onde se lida com tipos de resposa de não-texto, os tipos de resposta podem envolver alguma manipulação e/ou análise conforme descrito nas seções seguintes<span style="line-height: 1.572;">.</span></p> + +<h3 id="Analisando_e_manipulando_a_propriedade_responseXML">Analisando e manipulando a propriedade <code>responseXML</code></h3> + +<p>Se você utiliza o <code>XMLHttpRequest </code>para obter o conteúdo de um documento XML remoto, a propriedade <code>responseXML</code> será um objeto DOM que contém um documento XML, o que pode dificultar a manipulação e análise.</p> + +<p>As cinco formas mais utilizadas para análisar e manipular um arquivo XML são:</p> + +<ol> + <li>Usando <a href="/en-US/docs/XPath" title="XPath">XPath</a> para análisar parte deles.</li> + <li>Usando <a href="/en-US/docs/JXON" title="JXON">JXON</a> para converter em um Objeto JavaScript.</li> + <li>Manualmente <a href="/en-US/docs/Parsing_and_serializing_XML" title="Parsing_and_serializing_XML">Parsing and serializing XML</a> para strings ou objetos.</li> + <li>Usando <a href="/en-US/docs/XMLSerializer" title="XMLSerializer">XMLSerializer</a> para serializar <strong>árvores do DOM para strings ou para arquivos</strong>.</li> + <li><a href="/en-US/docs/JavaScript/Reference/Global_Objects/RegExp" title="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/regexp">RegExp </a>pode ser usado se você souber de antemão qual é o conteúdo do XML. Você pode remover quebras de linhas, usando a RegExp para procurar as quebras de linha. No entanto, este é o "último método", caso o código do XML sofra alterações, o método se torna falho.</li> +</ol> + +<h3 id="Analisando_e_manipulando_uma_propriedade_responseText_contendo_um_documento_HTML">Analisando e manipulando uma propriedade <code>responseText</code> contendo um documento HTML</h3> + +<div class="note"><strong>Nota:</strong> A especificação W3C do <a href="http://dvcs.w3.org/hg/xhr/raw-file/tip/Overview.html">XMLHttpRequest</a> permite analisar HTML através da propriedade <code>XMLHttpRequest.responseXML</code> . Leia o artigo sobre <a href="https://developer.mozilla.org/en-US/docs/HTML_in_XMLHttpRequest" title="HTML_in_XMLHttpRequest">HTML in XMLHttpRequest</a> para maiores detalhes.</div> + +<p>Se você usa o <code>XMLHttpRequest</code> para recuperar o conteúdo de uma página HTML remota, a propriedade <code>responseText</code> será uma string contendo um a "sopa" de todos as tags HTML, o que pode ser difícil de manipular e analizar. Existem três formas básicas para analizar esta sopa de string HTML:</p> + +<ol> + <li>Use a propriedade <code>XMLHttpRequest.responseXML</code>.</li> + <li>Introduza o conteúdo dentro do corpo de um <a href="https://developer.mozilla.org/en-US/docs/Web/API/DocumentFragment">document fragment</a> Através de <code>fragment.body.innerHTML</code> e percorra o fragmento do DOM.</li> + <li><a href="https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/RegExp" title="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/regexp">RegExp </a>pode se usada se você sempre conhece o conteúdo HTML <code>responseText </code>de que tem em mãos. Você pode quere remover quebras de linha, se você usar RegExp para varrer no que diz respeito a quebra de linhas. Contudo, este método é um "último recurso" uma vez que se o código HTML mudar um pouco, o método provavelmente irá falhar.</li> +</ol> + +<h2 id="Manipulação_de_dados_binários"><span class="short_text" id="result_box" lang="pt"><span class="hps">Manipulação</span> <span class="hps">de dados binários</span></span></h2> + +<p>Apesar de <code>XMLHttpRequest</code> ser mais comumente usado para enviar e receber dados textual, <span id="result_box" lang="pt"><span class="hps">ele pode</span> <span class="hps">ser</span> <span class="hps">utilizado</span> <span class="hps">para enviar</span> <span class="hps">e</span> <span class="hps">receber</span> <span class="hps">conteúdo binário</span></span>.<span id="result_box" lang="pt"><span class="hps"> Existem vários</span> <span class="hps">métodos</span> <span class="hps">bem</span> <span class="hps">testados</span> <span class="hps">para</span> <span class="alt-edited hps">forçar</span> <span class="hps">a</span> <span class="hps">resposta</span> <span class="hps">de</span> <span class="hps">um XMLHttpRequest</span> <span class="hps">para</span> <span class="hps">o envio de dados</span> <span class="hps">binário</span></span>. Eles envolvem a utilização do método .overrideMimeType() sobre o objeto XMLHttpRequest e é uma solução viável.</p> + +<pre class="brush:js">var oReq = new XMLHttpRequest(); +oReq.open("GET", url, true); +// recupera dados não processados como uma string binária +oReq.overrideMimeType("text/plain; charset=x-user-defined"); +/* ... */ +</pre> + +<p>A especificação XMLHttpRequest Level 2 adiciona novo <a href="http://www.w3.org/TR/XMLHttpRequest2/#the-responsetype-attribute" title="http://www.w3.org/TR/XMLHttpRequest2/#the-responsetype-attribute">responseType attributes</a> que tornam o envio e recebimento de dados muito mais fácil.</p> + +<pre class="brush:js">var oReq = new XMLHttpRequest(); + +oReq.open("GET", url, true); +oReq.responseType = "arraybuffer"; +oReq.onload = function(e) { + var arraybuffer = oReq.response; // não é responseText + /* ... */ +} +oReq.send(); +</pre> + +<p>Para mais exemplos confira a página <a href="/en-US/docs/DOM/XMLHttpRequest/Sending_and_Receiving_Binary_Data" title="DOM/XMLHttpRequest/Sending_and_Receiving_Binary_Data">Sending and Receiving Binary Data</a>.</p> + +<h2 id="Monitorando_o_progresso">Monitorando o progresso</h2> + +<p><code>XMLHttpRequest</code> <span id="result_box" lang="pt"><span class="hps">fornece a capacidade de</span> <span class="hps">ouvir vários</span> <span class="hps">eventos que podem</span> <span class="hps">ocorrer</span> <span class="hps">enquanto o</span> <span class="hps">pedido está sendo processado</span></span>. <span id="result_box" lang="pt"><span class="alt-edited">Isso inclui notificações periódicas de progresso, notificações de erro e assim por diante</span></span>.</p> + +<p>Suporte para evento de progresso DOM monitorando a conexão <code>XMLHttpRequest</code> transfers siga a Web API <a href="http://dev.w3.org/2006/webapi/progress/Progress.html" title="http://dev.w3.org/2006/webapi/progress/Progress.html">specification for progress events</a>: estes eventos implementam a interface {{domxref("ProgressEvent")}} .</p> + +<pre class="brush:js">var oReq = new XMLHttpRequest(); + +oReq.addEventListener("progress", updateProgress, false); +oReq.addEventListener("load", transferComplete, false); +oReq.addEventListener("error", transferFailed, false); +oReq.addEventListener("abort", transferCanceled, false); + +oReq.open(); + +// ...A transferência foi cancelada pelo usuário + +// <span id="result_box" lang="pt"><span class="hps">progresso</span> <span class="alt-edited hps">de transferências do</span> <span class="hps">servidor para o cliente</span> <span class="atn hps">(</span><span>downloads)</span></span> +function updateProgress (oEvent) { + if (oEvent.lengthComputable) { + var percentComplete = oEvent.loaded / oEvent.total; + // ... + } else { + // <span id="result_box" lang="pt"><span class="hps">Não é possível</span> <span class="hps">calcular</span> <span class="hps">informações de progresso</span> <span class="alt-edited hps">uma vez que</span> <span class="alt-edited hps">a dimensão total</span> <span class="alt-edited hps">é desconhecida</span></span> + } +} + +function transferComplete(evt) { + alert("<span class="short_text" id="result_box" lang="pt"><span class="hps">A</span> <span class="alt-edited hps">transferência foi concluída</span></span>."); +} + +function transferFailed(evt) { + alert("<span class="short_text" id="result_box" lang="pt"><span class="alt-edited hps">Um erro ocorreu</span> <span class="hps">durante a transferência</span> <span class="hps">do arquivo</span></span>."); +} + +function transferCanceled(evt) { + alert("<span class="short_text" id="result_box" lang="pt"><span class="hps">A transferência</span> <span class="hps">foi cancelada</span> <span class="hps">pelo usuário</span></span>."); +}</pre> + +<p>Lines 3-6 adiciona receptores de eventos (event listeners) para os vários que são enviados ao executar uma transferência de dados usando <code>XMLHttpRequest</code>.</p> + +<div class="note"><strong>Nota:</strong> Você precisa adicionar os receptores de eventos (event listeners) antes de chamar <code>open()</code> sobre a requisição. Caso contrário, os eventos de prograsso não dispararão..</div> + +<p>O manipulador de evento de prograsso, especificado pela função <code>updateProgress()</code> neste exemplo, recebe o número total de bytes para transferir, bem como o número de bytes transferidos até o momento em total de eventos e campos carregados . No entanto, se o campo lengthComputable é false, o comprimento total não é conhecido e será zero..</p> + +<p><span id="result_box" lang="pt"><span class="alt-edited">Eventos de progresso existem para ambos as transferências de download e upload.</span></span> The download events are fired on the <code>XMLHttpRequest</code> object itself, as shown in the above sample. The upload events are fired on the <code>XMLHttpRequest.upload</code> object, as shown below:</p> + +<pre class="brush:js">var oReq = new XMLHttpRequest(); + +oReq.upload.addEventListener("progress", updateProgress, false); +oReq.upload.addEventListener("load", transferComplete, false); +oReq.upload.addEventListener("error", transferFailed, false); +oReq.upload.addEventListener("abort", transferCanceled, false); + +oReq.open(); +</pre> + +<div class="note"><strong>Nota:</strong> <span id="result_box" lang="pt"><span class="alt-edited hps">eventos de progresso</span> <span class="hps">não estão disponíveis para</span> <span class="hps">o arquivo</span></span><code>:</code> protocol.</div> + +<div class="note"><strong>Nota</strong>: Atualmente, existem bugs em aberto para o evento de progresso que continua fetando a versão 25 do Firefox sobre <a href="https://bugzilla.mozilla.org/show_bug.cgi?id=908375">OS X</a> e <a href="https://bugzilla.mozilla.org/show_bug.cgi?id=786953">Linux</a>.</div> + +<div class="note"> +<p><strong>Nota:</strong> Iniciando no {{Gecko("9.0")}}, <span id="result_box" lang="pt"><span class="hps">eventos de progresso</span> <span class="alt-edited hps">agora podem</span> <span class="alt-edited hps">ser invocados</span> <span class="alt-edited hps">a entrar para</span> <span class="hps">cada</span> <span class="hps">pedaço de</span> <span class="hps">dados recebidos</span></span>, <span id="result_box" lang="pt"><span class="alt-edited">incluindo o último bloco, nos casos em que o último pacote é recebido e a conexão fechada antes do evento progresso ser disparado</span></span>. Neste caso, o evento de progresso é automaticamente <span id="result_box" lang="pt"><span class="hps">acionado quando o</span> <span class="alt-edited hps">evento load</span> <span class="hps">ocorre para</span> <span class="alt-edited hps">esse pacote</span></span>. <span id="result_box" lang="pt"><span class="alt-edited">Isso permite que você agora acompanhe de forma confiável apenas observando o evento de progresso</span></span></p> +</div> + +<div class="note"> +<p><strong>Nota:</strong> A partir do {{Gecko("12.0")}}, se o seu evento de progresso e chamado com um <code>responseType</code> de "moz-blob", o valor da resposta será um {{domxref("Blob")}} <span class="short_text" id="result_box" lang="pt"><span class="hps">contendo</span> <span class="hps">os</span> <span class="hps">dados recebidos</span> <span class="hps">até agora</span></span>r.</p> +</div> + +<p>POde-se também detectar todas as três condições de fim de carga (<code>abort</code>, <code>load</code>, or <code>error</code>) usando o evento <code>loadend</code>:</p> + +<pre class="brush:js">req.addEventListener("loadend", loadEnd, false); + +function loadEnd(e) { + alert("<span class="short_text" id="result_box" lang="pt"><span class="hps">A</span> <span class="hps">transferência</span> <span class="alt-edited hps">terminou</span></span> (<span class="short_text" id="result_box" lang="pt"><span class="hps">embora</span> <span class="hps">não sabemos</span> <span class="hps">se ele</span> <span class="hps">conseguiu</span> <span class="hps">ou não</span></span>)."); +} +</pre> + +<p><span id="result_box" lang="pt"><span class="alt-edited hps">Note que</span> <span class="hps">não há nenhuma</span> <span class="hps">maneira de ter certeza</span> <span class="alt-edited hps">a partir da</span> <span class="hps">informação recebida</span> <span class="hps">pelo evento</span> <span class="hps">loadend</span> <span class="hps">sobre qual</span> <span class="hps">condição</span> <span class="hps">causou a</span> <span class="hps">operação</span> <span class="alt-edited hps">de encerrar</span><span>;</span> <span class="hps">no entanto, você</span> <span class="hps">pode usar isso para</span> <span class="hps">lidar com tarefas</span> <span class="hps">que</span> <span class="hps">precisam ser realizadas</span> <span class="hps">em todos os cenários</span> <span class="hps">de fim-de</span><span class="atn">-</span><span>transferência.</span></span></p> + +<h2 id="Submitting_forms_and_uploading_files">Submitting forms and uploading files</h2> + +<p>Instances of <code>XMLHttpRequest</code> can be used to submit forms in two ways:</p> + +<ul> + <li>using nothing but <em>pure</em> AJAX,</li> + <li>using the <a href="/en-US/docs/DOM/XMLHttpRequest/FormData" title="DOM/XMLHttpRequest/FormData"><code>FormData</code></a> API.</li> +</ul> + +<p>The <strong>second way</strong> (using the <a href="/en-US/docs/DOM/XMLHttpRequest/FormData" title="DOM/XMLHttpRequest/FormData"><code>FormData</code></a> API) is the simplest and the fastest, but has the disadvantage that <strong>the data thus collected can not be <a href="/en-US/docs/JavaScript/Reference/Global_Objects/JSON/stringify" title="/en-US/docs/JavaScript/Reference/Global_Objects/JSON/stringify">stringified</a></strong>: they are in every way <em>a blob</em>. It is the best solution for simple cases.<br> + The <strong>first way</strong> (<em>pure</em> AJAX) is instead the most complex, but in compensation is also the most flexible and powerful: it lends itself to wider uses and <strong>the data thus collected can be <a href="/en-US/docs/JavaScript/Reference/Global_Objects/JSON/stringify" title="/en-US/docs/JavaScript/Reference/Global_Objects/JSON/stringify">stringified</a></strong><strong> and reused for other purposes</strong> such as, for example, populating the <em>status object</em> during a <a href="/en-US/docs/DOM/Manipulating_the_browser_history" title="/en-US/docs/DOM/Manipulating_the_browser_history">manipulation of the browser history</a>, or other.</p> + +<h3 id="Using_nothing_but_pure_AJAX">Using nothing but <em>pure</em> AJAX</h3> + +<p>Submitting forms without the <a href="/en-US/docs/DOM/XMLHttpRequest/FormData" title="DOM/XMLHttpRequest/FormData"><code>FormData</code></a> API does not require other APIs, except that, only <strong>if you want to upload one or more files</strong>, the <a href="/en-US/docs/DOM/FileReader" title="/en-US/docs/DOM/FileReader"><code>FileReader</code></a> API.</p> + +<h4 id="A_brief_introduction_to_the_submit_methods">A brief introduction to the submit methods</h4> + +<p>An html {{ HTMLElement("form") }} can be sent in four ways:</p> + +<ul> + <li>using the <code>POST</code> method and setting the <code>enctype</code> attribute to <code>application/x-www-form-urlencoded</code> (default);</li> + <li>using the <code>POST</code> method and setting the <code>enctype</code> attribute to <code>text/plain</code>;</li> + <li>using the <code>POST</code> method and setting the <code>enctype</code> attribute to <code>multipart/form-data</code>;</li> + <li>using the <code>GET</code> method (in this case the <code>enctype</code> attribute will be ignored).</li> +</ul> + +<p>Now, consider to submit a form containing only two fields, named <code>foo</code> and <code>baz</code>. If you are using the <code>POST</code> method, the server will receive a string similar to one of the following three ones depending on the encoding type you are using:</p> + +<ul> + <li> + <p>Method: <code>POST</code>; Encoding type: <code>application/x-www-form-urlencoded</code> (default):</p> + + <pre>Content-Type: application/x-www-form-urlencoded + +foo=bar&baz=The+first+line.&#37;0D%0AThe+second+line.%0D%0A</pre> + </li> + <li> + <p>Method: <code>POST</code>; Encoding type: <code>text/plain</code>:</p> + + <pre>Content-Type: text/plain + +foo=bar +baz=The first line. +The second line.</pre> + </li> + <li> + <p>Method: <code>POST</code>; Encoding type: <code>multipart/form-data</code>:</p> + + <pre style="height: 100px; overflow: auto;">Content-Type: multipart/form-data; boundary=---------------------------314911788813839 + +-----------------------------314911788813839 +Content-Disposition: form-data; name="foo" + +bar +-----------------------------314911788813839 +Content-Disposition: form-data; name="baz" + +The first line. +The second line. + +-----------------------------314911788813839--</pre> + </li> +</ul> + +<p>Instead, if you are using the <code>GET</code> method, a string like the following will be simply added to the URL:</p> + +<pre>?foo=bar&baz=The%20first%20line.%0AThe%20second%20line.</pre> + +<h4 id="A_little_vanilla_framework">A little <em>vanilla</em> framework</h4> + +<p>All these things are done automatically by the web browser whenever you submit a {{ HTMLElement("form") }}. But if you want to do the same things using JavaScript you have to instruct the interpreter about <em>all</em> things. So, how to send forms in <em>pure</em> AJAX is too complex to be explained in detail here. For this reason we posted here <strong>a complete (but still didactic) framework</strong>, which is able to use all the four ways of <em>submit</em> and, also, to <strong>upload files</strong>:</p> + +<div style="height: 400px; margin-bottom: 12px; overflow: auto;"> +<pre class="brush: html"><!doctype html> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> +<title>Sending forms with pure AJAX &ndash; MDN</title> +<script type="text/javascript"> + +"use strict"; + +/*\ +|*| +|*| :: 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); */ + }; +} + +/*\ +|*| +|*| :: AJAX Form Submit Framework :: +|*| +|*| https://developer.mozilla.org/en-US/docs/DOM/XMLHttpRequest/Using_XMLHttpRequest +|*| +|*| This framework is released under the GNU Public License, version 3 or later. +|*| http://www.gnu.org/licenses/gpl-3.0-standalone.html +|*| +|*| Syntax: +|*| +|*| AJAXSubmit(HTMLFormElement); +\*/ + +var AJAXSubmit = (function () { + + function ajaxSuccess () { + /* console.log("AJAXSubmit - Success!"); */ + alert(this.responseText); + /* you can get the serialized data through the "submittedData" custom property: */ + /* alert(JSON.stringify(this.submittedData)); */ + } + + function submitData (oData) { + /* the AJAX request... */ + var oAjaxReq = new XMLHttpRequest(); + oAjaxReq.submittedData = oData; + oAjaxReq.onload = ajaxSuccess; + if (oData.technique === 0) { + /* method is GET */ + oAjaxReq.open("get", oData.receiver.replace(/(?:\?.*)?$/, oData.segments.length > 0 ? "?" + oData.segments.join("&") : ""), true); + oAjaxReq.send(null); + } else { + /* method is POST */ + oAjaxReq.open("post", oData.receiver, true); + if (oData.technique === 3) { + /* enctype is multipart/form-data */ + var sBoundary = "---------------------------" + Date.now().toString(16); + oAjaxReq.setRequestHeader("Content-Type", "multipart\/form-data; boundary=" + sBoundary); + oAjaxReq.sendAsBinary("--" + sBoundary + "\r\n" + oData.segments.join("--" + sBoundary + "\r\n") + "--" + sBoundary + "--\r\n"); + } else { + /* enctype is application/x-www-form-urlencoded or text/plain */ + oAjaxReq.setRequestHeader("Content-Type", oData.contentType); + oAjaxReq.send(oData.segments.join(oData.technique === 2 ? "\r\n" : "&")); + } + } + } + + function processStatus (oData) { + if (oData.status > 0) { return; } + /* the form is now totally serialized! do something before sending it to the server... */ + /* doSomething(oData); */ + /* console.log("AJAXSubmit - The form is now serialized. Submitting..."); */ + submitData (oData); + } + + function pushSegment (oFREvt) { + this.owner.segments[this.segmentIdx] += oFREvt.target.result + "\r\n"; + this.owner.status--; + processStatus(this.owner); + } + + function plainEscape (sText) { + /* how should I treat a text/plain form encoding? what characters are not allowed? this is what I suppose...: */ + /* "4\3\7 - Einstein said E=mc2" ----> "4\\3\\7\ -\ Einstein\ said\ E\=mc2" */ + return sText.replace(/[\s\=\\]/g, "\\$&"); + } + + function SubmitRequest (oTarget) { + var nFile, sFieldType, oField, oSegmReq, oFile, bIsPost = oTarget.method.toLowerCase() === "post"; + /* console.log("AJAXSubmit - Serializing form..."); */ + this.contentType = bIsPost && oTarget.enctype ? oTarget.enctype : "application\/x-www-form-urlencoded"; + this.technique = bIsPost ? this.contentType === "multipart\/form-data" ? 3 : this.contentType === "text\/plain" ? 2 : 1 : 0; + this.receiver = oTarget.action; + this.status = 0; + this.segments = []; + var fFilter = this.technique === 2 ? plainEscape : escape; + for (var nItem = 0; nItem < oTarget.elements.length; nItem++) { + oField = oTarget.elements[nItem]; + if (!oField.hasAttribute("name")) { continue; } + sFieldType = oField.nodeName.toUpperCase() === "INPUT" ? oField.getAttribute("type").toUpperCase() : "TEXT"; + if (sFieldType === "FILE" && oField.files.length > 0) { + if (this.technique === 3) { + /* enctype is multipart/form-data */ + for (nFile = 0; nFile < oField.files.length; nFile++) { + oFile = oField.files[nFile]; + oSegmReq = new FileReader(); + /* (custom properties:) */ + oSegmReq.segmentIdx = this.segments.length; + oSegmReq.owner = this; + /* (end of custom properties) */ + oSegmReq.onload = pushSegment; + this.segments.push("Content-Disposition: form-data; name=\"" + oField.name + "\"; filename=\""+ oFile.name + "\"\r\nContent-Type: " + oFile.type + "\r\n\r\n"); + this.status++; + oSegmReq.readAsBinaryString(oFile); + } + } else { + /* enctype is application/x-www-form-urlencoded or text/plain or method is GET: files will not be sent! */ + for (nFile = 0; nFile < oField.files.length; this.segments.push(fFilter(oField.name) + "=" + fFilter(oField.files[nFile++].name))); + } + } else if ((sFieldType !== "RADIO" && sFieldType !== "CHECKBOX") || oField.checked) { + /* field type is not FILE or is FILE but is empty */ + this.segments.push( + this.technique === 3 ? /* enctype is multipart/form-data */ + "Content-Disposition: form-data; name=\"" + oField.name + "\"\r\n\r\n" + oField.value + "\r\n" + : /* enctype is application/x-www-form-urlencoded or text/plain or method is GET */ + fFilter(oField.name) + "=" + fFilter(oField.value) + ); + } + } + processStatus(this); + } + + return function (oFormElement) { + if (!oFormElement.action) { return; } + new SubmitRequest(oFormElement); + }; + +})(); + +</script> +</head> +<body> + +<h1>Sending forms with pure AJAX</h1> + +<h2>Using the GET method</h2> + +<form action="register.php" method="get" onsubmit="AJAXSubmit(this); return false;"> + <fieldset> + <legend>Registration example</legend> + <p> + First name: <input type="text" name="firstname" /><br /> + Last name: <input type="text" name="lastname" /> + </p> + <p> + <input type="submit" value="Submit" /> + </p> + </fieldset> +</form> + +<h2>Using the POST method</h2> +<h3>Enctype: application/x-www-form-urlencoded (default)</h3> + +<form action="register.php" method="post" onsubmit="AJAXSubmit(this); return false;"> + <fieldset> + <legend>Registration example</legend> + <p> + First name: <input type="text" name="firstname" /><br /> + Last name: <input type="text" name="lastname" /> + </p> + <p> + <input type="submit" value="Submit" /> + </p> + </fieldset> +</form> + +<h3>Enctype: text/plain</h3> + +<form action="register.php" method="post" enctype="text/plain" onsubmit="AJAXSubmit(this); return false;"> + <fieldset> + <legend>Registration example</legend> + <p> + Your name: <input type="text" name="user" /> + </p> + <p> + Your message:<br /> + <textarea name="message" cols="40" rows="8"></textarea> + </p> + <p> + <input type="submit" value="Submit" /> + </p> + </fieldset> +</form> + +<h3>Enctype: multipart/form-data</h3> + +<form action="register.php" method="post" enctype="multipart/form-data" onsubmit="AJAXSubmit(this); return false;"> + <fieldset> + <legend>Upload example</legend> + <p> + First name: <input type="text" name="firstname" /><br /> + Last name: <input type="text" name="lastname" /><br /> + Sex: + <input id="sex_male" type="radio" name="sex" value="male" /> <label for="sex_male">Male</label> + <input id="sex_female" type="radio" name="sex" value="female" /> <label for="sex_female">Female</label><br /> + Password: <input type="password" name="secret" /><br /> + What do you prefer: + <select name="image_type"> + <option>Books</option> + <option>Cinema</option> + <option>TV</option> + </select> + </p> + <p> + Post your photos: + <input type="file" multiple name="photos[]"> + </p> + <p> + <input id="vehicle_bike" type="checkbox" name="vehicle[]" value="Bike" /> <label for="vehicle_bike">I have a bike</label><br /> + <input id="vehicle_car" type="checkbox" name="vehicle[]" value="Car" /> <label for="vehicle_car">I have a car</label> + </p> + <p> + Describe yourself:<br /> + <textarea name="description" cols="50" rows="8"></textarea> + </p> + <p> + <input type="submit" value="Submit" /> + </p> + </fieldset> +</form> + +</body> +</html></pre> +</div> + +<p>To test it, please, create a<span class="long_text short_text" id="result_box" lang="en"><span class="hps"> </span></span>page named <strong>register.php</strong> (which is the <code>action</code> attribute of these sample forms) and just put the following <em><span class="long_text short_text" id="result_box" lang="en"><span class="hps">minimalistic </span></span></em>content:</p> + +<pre class="brush: php"><?php + + /* register.php */ + + header("Content-type: text/plain"); + + echo ":: data received via GET ::\n\n"; + print_r($_GET); + + echo "\n\n:: Data received via POST ::\n\n"; + print_r($_POST); + + echo "\n\n:: Data received as \"raw\" (text/plain encoding) ::\n\n"; + if (isset($HTTP_RAW_POST_DATA)) { echo $HTTP_RAW_POST_DATA; } + + echo "\n\n:: Files received ::\n\n"; + print_r($_FILES); + +?></pre> + +<p>The syntax of this script is the following:</p> + +<pre class="syntaxbox">AJAXSubmit(myForm);</pre> + +<div class="note"><strong>Note:</strong> This little <em>vanilla</em> framework <strong>uses the <a href="/en-US/docs/DOM/FileReader" title="/en-US/docs/DOM/FileReader"><code>FileReader</code></a> API</strong>, which is <em>a recent technique</em> (but only when there are files to upload, the <code>method</code> of the {{ HTMLElement("form") }} is <code>POST</code> and the <code>enctype</code> attribute is setted to <code>multipart/form-data</code>). For this reason, <strong>the <em>pure-AJAX</em> upload is to be considered an experimental technique</strong>. Instead, if you don't want to upload files, this framework will not use any recent API.<br> +Note also that <strong>the best way to send binary content is using <a href="/en-US/docs/JavaScript/Typed_arrays/ArrayBuffer" title="/en-US/docs/JavaScript/Typed_arrays/ArrayBuffer">ArrayBuffers</a> or <a href="/en-US/docs/DOM/Blob" title="/en-US/docs/DOM/Blob">Blobs</a> in conjuncton with the <a href="/en-US/docs/DOM/XMLHttpRequest#send%28%29" title="/en-US/docs/DOM/XMLHttpRequest#send()"><code>send()</code></a> method and, possibly, with the <a href="/en-US/docs/DOM/FileReader#readAsArrayBuffer()" title="/en-US/docs/DOM/FileReader#readAsArrayBuffer()"><code>readAsArrayBuffer()</code></a> method of the <a href="/en-US/docs/DOM/FileReader" title="/en-US/docs/DOM/FileReader"><code>FileReader</code></a> API</strong>. But, since the aim of this little script is to work with a <em><a href="/en-US/docs/JavaScript/Reference/Global_Objects/JSON/stringify" title="/en-US/docs/JavaScript/Reference/Global_Objects/JSON/stringify">stringifiable</a></em> raw data, we used the <a href="/en-US/docs/DOM/XMLHttpRequest#sendAsBinary%28%29" title="/en-US/docs/DOM/XMLHttpRequest#sendAsBinary()"><code>sendAsBinary()</code></a> method in conjunction with the <a href="/en-US/docs/DOM/FileReader#readAsBinaryString%28%29" title="/en-US/docs/DOM/FileReader#readAsBinaryString()"><code>readAsBinaryString()</code></a> method of the <a href="/en-US/docs/DOM/FileReader" title="/en-US/docs/DOM/FileReader"><code>FileReader</code></a> API. So, this is <strong>the best solution when working with a relatively few data which must be <a href="/en-US/docs/JavaScript/Reference/Global_Objects/JSON/stringify" title="/en-US/docs/JavaScript/Reference/Global_Objects/JSON/stringify">stringified</a> in order to be reused later</strong>. Anyhow, since working with strings instead of <a href="/en-US/docs/JavaScript/Typed_arrays" title="/en-US/docs/JavaScript/Typed_arrays">typed arrays</a> implies a greater waste of resources, this script makes sense only when you are dealing with <em>small</em> files (like images, documents, mp3, etc.). Otherwise, if you don't want to stringify the submitted or uploaded data, in addition to <a href="/en-US/docs/JavaScript/Typed_arrays" title="/en-US/docs/JavaScript/Typed_arrays">typed arrays</a>, consider also the use of <strong>the <a href="/en-US/docs/DOM/XMLHttpRequest/FormData" title="DOM/XMLHttpRequest/FormData"><code>FormData</code></a> API</strong>.</div> + +<h3 id="Using_FormData_objects">Using FormData objects</h3> + +<p>The <a href="/en-US/docs/DOM/XMLHttpRequest/FormData" title="DOM/XMLHttpRequest/FormData"><code>FormData</code></a> constructor lets you compile a set of key/value pairs to send using <code>XMLHttpRequest</code>. Its primarily intended for use in sending form data, but can be used independently from forms in order to transmit keyed data. The transmitted data is in the same format that the form's <code>submit()</code> method would use to send the data if the form's encoding type were set to "multipart/form-data". FormData objects can be utilized in a number of ways with an XMLHttpRequest. For examples and explanations of how one can utilize FormData with XMLHttpRequests see the <a href="/en-US/docs/DOM/XMLHttpRequest/FormData/Using_FormData_Objects" title="Using FormData Objects">Using FormData Objects</a> page. For didactic purpose only we post here <strong>a <em>translation</em> of <a href="#A_little_vanilla_framework" title="#A_little_vanilla_framework">the previous example</a> transformed so as to make use of the <code>FormData</code> API</strong>. Note the brevity of the code:</p> + +<div style="height: 400px; margin-bottom: 12px; overflow: auto;"> +<pre class="brush: html"><!doctype html> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> +<title>Sending forms with FormData &ndash; MDN</title> +<script type="text/javascript"> +"use strict"; + +function ajaxSuccess () { + alert(this.responseText); +} + +function AJAXSubmit (oFormElement) { + if (!oFormElement.action) { return; } + var oReq = new XMLHttpRequest(); + oReq.onload = ajaxSuccess; + if (oFormElement.method.toLowerCase() === "post") { + oReq.open("post", oFormElement.action, true); + oReq.send(new FormData(oFormElement)); + } else { + var oField, sFieldType, nFile, sSearch = ""; + for (var nItem = 0; nItem < oFormElement.elements.length; nItem++) { + oField = oFormElement.elements[nItem]; + if (!oField.hasAttribute("name")) { continue; } + sFieldType = oField.nodeName.toUpperCase() === "INPUT" ? oField.getAttribute("type").toUpperCase() : "TEXT"; + if (sFieldType === "FILE") { + for (nFile = 0; nFile < oField.files.length; sSearch += "&" + escape(oField.name) + "=" + escape(oField.files[nFile++].name)); + } else if ((sFieldType !== "RADIO" && sFieldType !== "CHECKBOX") || oField.checked) { + sSearch += "&" + escape(oField.name) + "=" + escape(oField.value); + } + } + oReq.open("get", oFormElement.action.replace(/(?:\?.*)?$/, sSearch.replace(/^&/, "?")), true); + oReq.send(null); + } +} +</script> +</head> +<body> + +<h1>Sending forms with FormData</h1> + +<h2>Using the GET method</h2> + +<form action="register.php" method="get" onsubmit="AJAXSubmit(this); return false;"> + <fieldset> + <legend>Registration example</legend> + <p> + First name: <input type="text" name="firstname" /><br /> + Last name: <input type="text" name="lastname" /> + </p> + <p> + <input type="submit" value="Submit" /> + </p> + </fieldset> +</form> + +<h2>Using the POST method</h2> +<h3>Enctype: application/x-www-form-urlencoded (default)</h3> + +<form action="register.php" method="post" onsubmit="AJAXSubmit(this); return false;"> + <fieldset> + <legend>Registration example</legend> + <p> + First name: <input type="text" name="firstname" /><br /> + Last name: <input type="text" name="lastname" /> + </p> + <p> + <input type="submit" value="Submit" /> + </p> + </fieldset> +</form> + +<h3>Enctype: text/plain</h3> + +<p>The text/plain encoding is not supported by the FormData API.</p> + +<h3>Enctype: multipart/form-data</h3> + +<form action="register.php" method="post" enctype="multipart/form-data" onsubmit="AJAXSubmit(this); return false;"> + <fieldset> + <legend>Upload example</legend> + <p> + First name: <input type="text" name="firstname" /><br /> + Last name: <input type="text" name="lastname" /><br /> + Sex: + <input id="sex_male" type="radio" name="sex" value="male" /> <label for="sex_male">Male</label> + <input id="sex_female" type="radio" name="sex" value="female" /> <label for="sex_female">Female</label><br /> + Password: <input type="password" name="secret" /><br /> + What do you prefer: + <select name="image_type"> + <option>Books</option> + <option>Cinema</option> + <option>TV</option> + </select> + </p> + <p> + Post your photos: + <input type="file" multiple name="photos[]"> + </p> + <p> + <input id="vehicle_bike" type="checkbox" name="vehicle[]" value="Bike" /> <label for="vehicle_bike">I have a bike</label><br /> + <input id="vehicle_car" type="checkbox" name="vehicle[]" value="Car" /> <label for="vehicle_car">I have a car</label> + </p> + <p> + Describe yourself:<br /> + <textarea name="description" cols="50" rows="8"></textarea> + </p> + <p> + <input type="submit" value="Submit" /> + </p> + </fieldset> +</form> + +</body> +</html></pre> +</div> + +<div class="note"><strong>Note:</strong> As we said, <strong><code>FormData</code> objects are not <a href="/en-US/docs/JavaScript/Reference/Global_Objects/JSON/stringify" title="/en-US/docs/JavaScript/Reference/Global_Objects/JSON/stringify">stringifiable</a> objects</strong>. If you want to stringify a submitted data, use <a href="#A_little_vanilla_framework" title="#A_little_vanilla_framework">the previous <em>pure</em>-AJAX example</a>. Note also that, although in this example there are some <code>file</code> {{ HTMLElement("input") }} fields, <strong>when you submit a form through the <code>FormData</code> API you do not need to use the <a href="/en-US/docs/DOM/FileReader" title="/en-US/docs/DOM/FileReader"><code>FileReader</code></a> API also</strong>: files are automatically loaded and uploaded.</div> + +<h2 id="Cross-site_XMLHttpRequest">Cross-site XMLHttpRequest</h2> + +<p>Modern browsers support cross-site requests by implementing the web applications working group's <a href="/en-US/docs/HTTP_access_control" title="HTTP access control">Access Control for Cross-Site Requests</a> standard. As long as the server is configured to allow requests from your web application's origin, <code>XMLHttpRequest</code> will work. Otherwise, an <code>INVALID_ACCESS_ERR</code> exception is thrown.</p> + +<h2 id="Bypassing_the_cache">Bypassing the cache</h2> + +<p><span style="line-height: 1.572;">A, cross-browser compatible approach to bypassing the cache is to append a timestamp to the URL, being sure to include a "?" or "&" as appropriate. For example:</span></p> + +<pre>http://foo.com/bar.html -> http://foo.com/bar.html?12345 +http://foo.com/bar.html?foobar=baz -> http://foo.com/bar.html?foobar=baz&12345 +</pre> + +<p>Since the local cache is indexed by URL, this causes every request to be unique, thereby bypassing the cache.</p> + +<p>You can automatically adjust URLs using the following code:</p> + +<pre class="brush:js">var oReq = new XMLHttpRequest(); + +oReq.open("GET", url + ((/\?/).test(url) ? "&" : "?") + (new Date()).getTime(), true); +oReq.send(null);</pre> + +<h2 id="Security">Security</h2> + +<p>{{fx_minversion_note(3, "Versions of Firefox prior to Firefox 3 allowed you to set the preference <code>capability.policy..XMLHttpRequest.open</code> to <code>allAccess</code> to give specific sites cross-site access. This is no longer supported.")}}</p> + +<p>{{fx_minversion_note(5, "Versions of Firefox prior to Firefox 5 could use <code>netscape.security.PrivilegeManager.enablePrivilege(\"UniversalBrowserRead\");</code> to request cross-site access. This is no longer supported, even though it produces no warning and permission dialog is still presented.")}}</p> + +<p>The recommended way to enable cross-site scripting is to use the <code>Access-Control-Allow-Origin </code> HTTP header in the response to the XMLHttpRequest.</p> + +<h3 id="XMLHttpRequests_being_stopped">XMLHttpRequests being stopped</h3> + +<p>If you end up with an XMLHttpRequest having <code>status=0</code> and <code>statusText=null</code>, it means that the request was not allowed to be performed. It was <code><a href="http://www.w3.org/TR/XMLHttpRequest/#dom-xmlhttprequest-unsent" title="http://www.w3.org/TR/XMLHttpRequest/#dom-xmlhttprequest-unsent">UNSENT</a></code>. A likely cause for this is when the <a href="http://www.w3.org/TR/XMLHttpRequest/#xmlhttprequest-origin" style="outline: 1px dotted; outline-offset: 0pt;"><code>XMLHttpRequest</code> origin</a> (at the creation of the XMLHttpRequest) has changed when the XMLHttpRequest is then <code>open()</code>. This case can happen for example when one has an XMLHttpRequest that gets fired on an onunload event for a window: the XMLHttpRequest gets in fact created when the window to be closed is still there, and then the request is sent (ie <code>open()</code>) when this window has lost its focus and potentially different window has gained focus. The way to avoid this problem is to set a listener on the new window "activate" event that gets set when the old window has its "unload" event fired.</p> + +<h2 id="Using_XMLHttpRequest_from_JavaScript_modules_XPCOM_components">Using XMLHttpRequest from JavaScript modules / XPCOM components</h2> + +<p>Instantiating <code>XMLHttpRequest</code> from a <a href="/en-US/docs/JavaScript_code_modules/Using" title="https://developer.mozilla.org/en/JavaScript_code_modules/Using_JavaScript_code_modules">JavaScript module</a> or an XPCOM component works a little differently; it can't be instantiated using the <code>XMLHttpRequest()</code> constructor. The constructor is not defined inside components and the code results in an error. The best way to work around this is to use the XPCOM component constructor.</p> + +<pre class="brush:js">const XMLHttpRequest = Components.Constructor("@mozilla.org/xmlextras/xmlhttprequest;1"); +var oReq = XMLHttpRequest();</pre> + +<p>Unfortunately in versions of Gecko prior to Gecko 16 there is a bug which can cause requests created this way to be cancelled for no reason. If you need your code to work on Gecko 15 or earlier, you can get the XMLHttpRequest constructor from the hidden DOM window like so.</p> + +<pre class="brush:js">const { XMLHttpRequest } = Components.classes["@mozilla.org/appshell/appShellService;1"] + .getService(Components.interfaces.nsIAppShellService) + .hiddenDOMWindow; +var oReq = XMLHttpRequest(); +</pre> + +<h2 id="See_also">See also</h2> + +<ol> + <li><a href="/en-US/docs/AJAX/Getting_Started" title="AJAX/Getting_Started">MDC AJAX introduction</a></li> + <li><a href="/en-US/docs/HTTP_access_control" title="HTTP access control">HTTP access control</a></li> + <li><a href="/en-US/docs/How_to_check_the_security_state_of_an_XMLHTTPRequest_over_SSL" title="How to check the security state of an XMLHTTPRequest over SSL">How to check the security state of an XMLHTTPRequest over SSL</a></li> + <li><a href="http://www.peej.co.uk/articles/rich-user-experience.html">XMLHttpRequest - REST and the Rich User Experience</a></li> + <li><a href="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/xmlsdk/html/xmobjxmlhttprequest.asp">Microsoft documentation</a></li> + <li><a href="http://developer.apple.com/internet/webcontent/xmlhttpreq.html">Apple developers' reference</a></li> + <li><a href="http://jibbering.com/2002/4/httprequest.html">"Using the XMLHttpRequest Object" (jibbering.com)</a></li> + <li><a href="http://www.w3.org/TR/XMLHttpRequest/">The XMLHttpRequest Object: W3C Specification</a></li> + <li><a href="http://dev.w3.org/2006/webapi/progress/Progress.html" title="http://dev.w3.org/2006/webapi/progress/Progress.html">Web Progress Events specification</a></li> +</ol> |