path: root/files/pt-pt/web/guide/ajax/getting_started/index.html

---
title: Primeiros Passos
slug: Web/Guide/AJAX/Getting_Started
tags:
  - AJAX
  - API
  - Avançado
  - JavaScript
  - Mecânica da Web
  - XMLHttpRequest
translation_of: Web/Guide/AJAX/Getting_Started
original_slug: Web/Guide/AJAX/Como_começar
---
<p class="summary">Este artigo guia-o através do essencial do AJAX e oferece-lhe dois exemplos práticos simples para poder começar.</p>

<h3 id="O_que_é_AJAX">O que é AJAX?</h3>

<p>AJAX (JavaScript Assíncrono e XML) em poucas palavras, é a utilização do objeto <code><a href="/pt-PT/docs/Web/API/XMLHttpRequest">XMLHttpRequest</a></code> para comunicar com os servidores. Este pode enviar e receber informação em vários formatos, incluindo JSON, XML, HTML e ficheiros de texto. A característica mais atraente do AJAX é a sua natureza 'assíncrona', o que significa que este pode comunicar com o servidor, trocar dados, e atualizar a página sem ter que recarregar a página.</p>

<p>As duas principais funcionalidades do AJAX são as seguintes:</p>

<ul>
 <li>Efetuar pedidos ao servidor sem ter de recarregar a página</li>
 <li>Receber e trabalhar com dados a partir do servidor</li>
</ul>

<h3 id="Passo_1_-_Como_efetuar_um_pedido_de_HTTP">Passo 1 - Como efetuar um pedido de HTTP</h3>

<p>Para fazer uma requisição HTTP ao servidor usando JavaScript, você precisa de uma instância de uma classe que disponibilize essa funcionalidade. Tal classe foi primeiro introduzida no Internet Explorer sob a forma de um objecto ActiveX chamado <code>XMLHTTP</code>. Depois, o Mozilla, o Safari e outros browsers fizeram o mesmo, implementando uma classe de nome <code>XMLHttpRequest</code> que suporta os métodos e as propriedades do objecto ActiveX original da Microsoft.</p>

<p>Por isso, para criar uma instância (objeto) da classe pretendida compatível com multiplos navegadores, você pode fazer:</p>

<pre>if (window.XMLHttpRequest) { // Mozilla, Safari, ...
    http_request = new XMLHttpRequest();
} else if (window.ActiveXObject) { // IE
    http_request = new ActiveXObject("Microsoft.XMLHTTP");
}

</pre>

<p>(só a título de exemplo, o código acima é uma versão simplificada do código a ser usado para a criação de uma instância XMLHTTP. Para um exemplo mais "vida real", dê uma olhada ao 3º passo deste artigo.)</p>

<p>Algumas versões de alguns browsers Mozilla não irão funcionar bem se a resposta do servidor não possuir um cabeçalho mime-type XML. Para satisfazer isto, você pode usar uma chamada extra a um método para ultrapassar o cabeçalho enviado pelo servidor, só no caso de não ser no formato <code>text/xml</code>.</p>

<pre>http_request = new XMLHttpRequest();
http_request.overrideMimeType('text/xml');
</pre>

<p>A próxima coisa a ser feita é decidir o que quer fazer após receber a resposta do servidor ao seu pedido. Nesta etapa só precisa de dizer ao objecto pedido HTTP que função JavaScript irá processar a resposta. Isto é feito definindo a propriedade <code>onreadystatechange</code> do objeto ao nome da função JavaScript que pretende utilizar, por exemplo:</p>

<p><code>http_request.onreadystatechange = NomedaFunção;</code></p>

<p>Note-se que não existem chaves após o nome da função e não são passados parâmetros. Também, em vez de dar um nome a função, você pode usar a técnica JavaScript de definir funções na hora (chamadas funções anônimas) e definir as ações que vão processar a resposta logo, por exemplo:</p>

<pre>http_request.onreadystatechange = function(){
    // processar resposta do servidor
};
</pre>

<p>Em seguida, após ter declarado o que vai acontecer mal receba a resposta, você precisa de consumar o pedido. Precisa de chamar os métodos <code>open()</code> e <code>send()</code> da classe pedido HTTP, por exemplo:</p>

<pre>http_request.open('GET', 'http://www.dominio.com.br/arquivo.extensao', true);
http_request.send(null);
</pre>

<ul>
 <li>O primeiro parâmetro da chamada do método <code>open()</code> é o método pedido HTML – GET, POST, HEAD ou outro método qualquer que queira usar e que seja suportado pelo seu servidor. Mantenha o nome do método em maiúsculas para obedecer às normas HTTP senão certos browsers (como o Firefox) podem não processar o pedido. Para obter mais informação sobre os possíveis métodos pedido HTTP pode dar uma olhadela em <a class="external" href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html">W3C specs</a></li>
 <li>O segundo parâmetro é a URL da página que está a pedir. Como medida de segurança, não pode efectuar pedidos de páginas de domínios externos. Certifique-se que usa o nome exacto do domínio em todas as suas páginas ou irá receber um erro "Permissão Negada" quando efectua uma chamada <code>open()</code>. Um erro comum é aceder ao seu domínio através de domínio.tld ao mesmo tempo que tenta chamar páginas com www.domínio.tld.</li>
 <li>O terceiro parâmetro define se o pedido é assíncrono. Se <code>TRUE</code>, a execução da função JavaScript irá continuar enquanto que a resposta do servidor ainda não foi recebida. Isto é o A de AJAX.</li>
</ul>

<p>O parâmetro do método <code>send()</code> pode ser costituido por quaisquer dados que pretenda enviar ao servidor ao enviar (POST) o pedido. Os dados devem estar sob a forma de uma linha de texto de pergunta, tipo:</p>

<p><code>name=value&amp;anothername=othervalue&amp;so=on</code></p>

<p>ou em vários outros formatos, incluindo JSON, SOAP, etc.</p>

<p>Note-se que se pretende enviar (POST) dados, você deve alterar o tipo MIME do pedido usando a seguinte linha:</p>

<pre>http_request.setRequestHeader('Content-Type', 'application/x-www-form-urlencoded');
</pre>

<p>De outra forma o servidor irá ignorar os dados (post).</p>

<p>Pode-se também colocar o charset desejado assim:</p>

<pre>http_request.setRequestHeader('Content-Type',
                           "application/x-www-form-urlencoded; charset=iso-8859-1");
</pre>

<p>Outro ponto importante é controle do cache, pois caso haja necessidadde de reenviar a consulta, pode ser que o objeto retorne o que está no cache do navegador. Para evitar esse tipo de transtorno as linhas abaixo eliminam essas possibilidades:</p>

<pre> http_request.setRequestHeader("Cache-Control",
                               "no-store, no-cache, must-revalidate");
http_request.setRequestHeader("Cache-Control",
                              "post-check=0, pre-check=0");
http_request.setRequestHeader("Pragma", "no-cache");
</pre>

<h3 id="Passo_2_-_Manipular_a_resposta_do_servidor">Passo 2 - Manipular a resposta do servidor</h3>

<p>Lembre-se que quando estava a enviar o pedido, você providenciou o nome de uma função JavaScript que é criada para lidar com a resposta.</p>

<p><code>http_request.onreadystatechange = nameOfTheFunction;</code></p>

<p>Vamos a ver o que é que esta função deve fazer. Primeiro, a função precisa de verificar o estado do pedido. Se o estado possui o valor 4, isso significa que a totalidade da resposta do servidor foi recebida e que pode continuar a processá-la à vontade.</p>

<pre>if (http_request.readyState == 4) {
    // everything is good, the response is received
} else {
    // still not ready
}
</pre>

<p>A lista completa dos valores <code>readyState</code> é a seguinte:</p>

<ul>
 <li>0 (não inicializado)</li>
 <li>1 (a carregar)</li>
 <li>2 (carregado)</li>
 <li>3 (interativo)</li>
 <li>4 (completo)</li>
</ul>

<p>(<a class="external" href="http://msdn.microsoft.com/workshop/author/dhtml/reference/properties/readystate_1.asp">Source</a>)</p>

<p>A próxima coisa a verificar é o código do estado da resposta HTTP do servidor. Todos os códigos possíveis estão listados na <a class="external" href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html">página W3C</a>. Para os nossos objectivos nós só estamos interessados na resposta <code>200 OK</code>.</p>

<pre>if (http_request.status == 200) {
    // perfect!
} else {
    // there was a problem with the request,
    // for example the response may be a 404 (Not Found)
    // or 500 (Internal Server Error) response codes
}
</pre>

<p>Depois de verificar o estado do pedido e o código do estado HTTP da resposta, compete-lhe a si fazer aquilo que quer fazer com os dados que o servidor lhe enviou. Tem duas opções para aceder a esses dados:</p>

<ul>
 <li><code>http_request.responseText</code> – irá devolver a resposta do servidor como uma linha de texto</li>
 <li><code>http_request.responseXML</code> – irá devolver a resposta do servidor como um objecto <code>XMLDocument</code> que pode percorrer usando as funções DOM de JavaScript.</li>
</ul>

<p> </p>

<h3 id="Passo_3_–_Um_exemplo_simples">Passo 3 – Um exemplo simples</h3>

<p>Vamos agora pôr tudo junto e efectuar um simples pedido HTTP. O nosso JavaScript vai pedir um documento HTML, <code>teste.html</code>, que contém o texto "Sou um teste." e então vamos <code>alert()</code> os conteúdos do ficheiro <code>teste.html</code>.</p>

<pre>&lt;script type="text/javascript" language="javascript"&gt;

    var http_request = false;

    function makeRequest(url) {

        http_request = false;

        if (window.XMLHttpRequest) { // Mozilla, Safari,...
            http_request = new XMLHttpRequest();
            if (http_request.overrideMimeType) {
                http_request.overrideMimeType('text/xml');
                // See note below about this line
            }
        } else if (window.ActiveXObject) { // IE
            try {
                http_request = new ActiveXObject("Msxml2.XMLHTTP");
            } catch (e) {
                try {
                    http_request = new ActiveXObject("Microsoft.XMLHTTP");
                } catch (e) {}
            }
        }

        if (!http_request) {
            alert('Giving up :( Cannot create an XMLHTTP instance');
            return false;
        }
        http_request.onreadystatechange = alertContents;
        http_request.open('GET', url, true);
        http_request.send(null);

    }

    function alertContents() {

        if (http_request.readyState == 4) {
            if (http_request.status == 200) {
                alert(http_request.responseText);
            } else {
                alert('There was a problem with the request.');
            }
        }

    }
&lt;/script&gt;
&lt;span
    style="cursor: pointer; text-decoration: underline"
    onclick="makeRequest('test.html')"&gt;
        Make a request
&lt;/span&gt;
</pre>

<p>Neste exemplo:</p>

<ul>
 <li>O utilizador clicka no atalho "efectuar pedido" no browser;</li>
 <li>Isto chama a função <code>makeRequest()</code> com um parâmetro -- o nome <code>teste.html</code> de um ficheiro HTML no mesmo directório;</li>
 <li>O pedido é feito e então (<code>onreadystatechange</code>) a execução é passada a <code>alertContents()</code>;</li>
 <li><code>alertContents()</code> verifica se a resposta foi recebida e se é um OK e então alerta (<code>alert()</code>) os conteúdos do ficheiro <code>test.html</code>.</li>
</ul>

<p>Você pode testar o exemplo <a class="external" href="http://www.w3clubs.com/mozdev/httprequest_test.html">aqui</a> e pode ver o ficheiro de teste <a class="external" href="http://www.w3clubs.com/mozdev/test.html">aqui</a>.</p>

<div class="note"><strong>Nota</strong>: <span id="result_box" lang="pt"><span class="hps"><span id="result_box" lang="pt"><span class="alt-edited hps">Se você está enviando</span> <span class="alt-edited hps">uma solicitação para um</span> <span class="hps">pedaço de código</span> <span class="alt-edited hps">que retornará</span> <span class="hps">XML</span><span>, ao invés de</span> <span class="hps">um arquivo</span> <span class="hps">XML</span> <span class="hps">estático</span><span>, é necessário definir</span> <span class="hps">alguns</span> <span class="hps">cabeçalhos de resposta</span> <span class="hps">se a sua página</span> <span class="alt-edited hps">deve trabalhar</span> <span class="alt-edited hps">com o Internet Explorer</span><span>, além de</span> <span class="hps">Mozilla.</span> <span class="hps">Se</span> <span class="hps">você não definir</span> <span class="hps">cabeçalho</span> <code><span class="hps">Content-Type</span><span>: application /</span> <span class="hps">xml</span></code><span>, o IE irá</span> <span class="hps">lançar um erro</span> <span class="hps">JavaScript,</span> <span class="atn hps">"</span><span>Objeto esperado</span><span>"</span><span>,</span> <span class="hps">após a linha</span> <span class="hps">onde você tentar</span> <span class="hps">acessar um elemento</span> <span class="hps">XML.</span></span>.</span></span></div>

<div class="note"><strong>Nota 2</strong>: <span id="result_box" lang="pt"><span class="hps">Se</span> <span class="hps">você não definir</span> <span class="hps">cabeçalho</span> <code><span class="atn hps">Cache-</span><span>Control: no</span><span>-cache</span></code> <span class="alt-edited hps">o navegador</span> <span class="alt-edited hps">armazenará em cache</span> <span class="hps">a resposta</span> <span class="alt-edited hps">e jamais</span> <span class="alt-edited hps">voltará a submeter</span> <span class="hps">o pedido</span><span>, tornando</span> <span class="hps">a depuração</span> <span class="atn hps">"</span><span class="alt-edited">desafiadora".</span> <span class="alt-edited hps">Também é</span> <span class="alt-edited hps">possível acrescentar</span> <span class="hps">um parâmetro</span> <span class="hps">GET</span> <span class="hps">adicional</span> <span class="hps">sempre</span> <span class="hps">diferente,</span> <span class="hps">como o</span> <span class="hps">timestamp</span> <span class="hps">ou</span> <span class="hps">um número aleatório</span> <span class="atn hps">(</span><span>veja</span> <a href="https://developer.mozilla.org/en/DOM/XMLHttpRequest/Using_XMLHttpRequest#Bypassing_the_cache" title="https://developer.mozilla.org/En/XMLHttpRequest/Using_XMLHttpRequest#Bypassing_the_cache">bypassing the cache</a><span class="hps">).</span></span></div>

<div class="note"><strong>Nota 3</strong>: <span id="result_box" lang="pt"><span class="hps">Se a variável</span> <span class="hps">httpRequest</span> <span class="alt-edited hps">é utilizada</span> <span class="hps">globalmente</span><span class="alt-edited">, funções</span> <span class="alt-edited hps">concorrentes</span> <span class="hps">chamando</span> <code><span class="hps">makeRequest</span> </code><span class="alt-edited hps"><code>()</code> podem</span> <span class="alt-edited hps">sobrescrever</span> <span class="hps">o outro,</span> <span class="hps">causando</span> <span class="hps">uma condição de corrida</span><span>.</span> <span class="hps">Declarando</span> <span class="hps">o</span> <span class="hps">httpRequest</span> <span class="hps">variável local para</span> <span class="hps">um <a href="https://developer.mozilla.org/en/JavaScript/Guide/Closures" title="https://developer.mozilla.org/en/JavaScript/Guide/Closures">closure</a></span> <span class="hps">contendo as funções</span> <span class="hps">AJAX</span> <span class="hps">impede</span> <span class="hps">a condição de corrida</span><span>.</span></span></div>

<div class="note"><strong>Nota 4</strong>: Caso ocorra um erro de comunicação (tal como a queda de do servidor web), uma exceção será lançada no método <code>onreadystatechange</code> quando o campo <code>status</code> for acessado. Tenha a certeza de envolver sua declaração <code>if..then</code> dentro de um bloco <code>try...catch</code>. (Veja: {{ Bug(238559) }}).</div>

<h3 id="Passo_4_–_Trabalhar_com_a_resposta_XML">Passo 4 – Trabalhar com a resposta XML</h3>

<p>No exemplo anterior, após termos recebido a resposta ao pedido HTTP, nós usamos a propriedade <code>reponseText</code> do objecto de pedido e continha os conteúdos do ficheiro <code>test.html</code>. Agora vamos experimentar a propriedade <code>responseXML</code>.</p>

<p>Antes de tudo, vamos criar um documento XML válido que vamos pedir mais à frente. O documento (test.xml) contém o seguinte:</p>

<p> </p>

<pre>&lt;?xml version="1.0" ?&gt;
&lt;root&gt;
    I'm a test.
&lt;/root&gt;
</pre>

<p>No guião só precisamos de alterar a linha do pedido com:</p>

<pre>...
onclick="makeRequest('test.xml')"&gt;
...
</pre>

<p>Então em <code>alertContents()</code> nós precisamos de substituir a linha de alerta (<code>alert(http_request.responseText);</code>) com:</p>

<pre>var xmldoc = http_request.responseXML;
var root_node = xmldoc.getElementsByTagName('root').item(0);
alert(root_node.firstChild.data);
</pre>

<p>Este código pega o objeto <code>XMLDocument</code> obtido por <code>responseXML</code> e utiliza métodos DOM para acessar alguns dados contidos no documento XML. Você pode ver o <code>test.xml</code> <a class="external" href="http://www.w3clubs.com/mozdev/test.xml">aqui</a> e o script de teste atualizado <a class="external" href="http://www.w3clubs.com/mozdev/httprequest_test_xml.html">aqui</a>.</p>

<p><span class="comment">Categorias</span></p>

<p><span class="comment">Interwiki Language Links</span></p>

<h3 id="Passo_5_–_Tabalhar_com_dados">Passo 5 – Tabalhar com dados</h3>

<p>Finalmente, vamos enviar algum dado para o servidor e obter a resposta. Desta vez, nosso JavaScript solicitará um página dinâmica (<code>test.php</code>)  que receberá os dados que enviamos e retornará um string computada - "<code>Hello, [user data]!</code>" - visualizada através de <code>alert().</code></p>

<p>Primeiro, vamos adicionar uma text box em nosso HTML de modo que o usuário possa digitar o seu nome:</p>

<pre class="brush: html">&lt;label&gt;Your name:
  &lt;input type="text" id="ajaxTextbox" /&gt;
&lt;/label&gt;
&lt;span id="ajaxButton" style="cursor: pointer; text-decoration: underline"&gt;
  Make a request
&lt;/span&gt;</pre>

<p>Vamos, também, adicionar uma linha para nosso manipulador de eventos obter os dados do usuário da text box e enviá-lo para função <code>makeRequest()</code> juntamente com a URL do nosso script do lado do servidor (server-side):</p>

<pre class="brush: js">document.getElementById("ajaxButton").onclick = function() {
      var userName = document.getElementById("ajaxTextbox").value;
      makeRequest('test.php',userName);
  };</pre>

<p><span id="result_box" lang="pt"><span class="hps">Precisamos</span> <span class="hps">modificar</span> <code><span class="hps">makeRequest</span> </code><span class="hps"><code>()</code> para aceitar</span> <span class="hps">os dados do usuário</span> <span class="hps">e</span> <span class="hps">passá-lo para</span> <span class="hps">o servidor</span></span>. Vamos mudar o método de requisição de <code>GET</code> para <code>POST</code>, e incluir nossos dados como um parâmetro na chamada para <code>httpRequest.send()</code>:</p>

<pre class="brush: js">function makeRequest(url, userName) {

    ...

    httpRequest.onreadystatechange = alertContents;
    httpRequest.open('POST', url);
    httpRequest.setRequestHeader('Content-Type', 'application/x-www-form-urlencoded');
    httpRequest.send('userName=' + encodeURIComponent(userName));
  }
</pre>

<p>A função <code>alertContents()</code> pode ser escrita da mesma forma que se encontrava no <strong>Passo 3</strong> para alertar (<code>alert()</code>) nossa string computada,  se isso for tudo o que o servidor retorna. No entanto, vamos dizer que  o servidor irá retornar tanto a sequência computada como o dados original do usuário. Portanto, se o usuário digitou "Jane" na text box, a resposta do servidor ficaria assim:</p>

<p><code>{"userData":"Jane","computedString":"Hi, Jane!"}</code></p>

<p><span class="short_text" id="result_box" lang="pt"><span class="hps">Para utilizar</span> <span class="hps">estes dados</span> <span class="hps">dentro de </span></span><code>alertContents()</code>, nós não podemos simplesmente exibir com <code>alert()</code>  a propriedade <code>responseText</code>. Temos que analisar (parse it)  <code>computedString</code> a propriedade que queremos:</p>

<pre class="brush: js">function alertContents() {
    if (httpRequest.readyState === 4) {
      if (httpRequest.status === 200) {
        var response = JSON.parse(httpRequest.responseText);
        alert(response.computedString);
    } else {
      alert('There was a problem with the request.');
    }
}</pre>

<p><code>Para mais métodos DOM, certifique-se que consulta os documentos sobre a <a class="external" href="/pt-PT/docs/DOM/DOM_Reference">implementação de DOM da Mozilla</a></code></p>