Usando XMLHttpRequest

Baseline Widely available *

This feature is well established and works across many devices and browser versions. Its been available across browsers since julho de 2015.

* Some parts of this feature may have varying levels of support.

Learn more
See full compatibility

XMLHttpRequest torna o envio de requisies HTTP muito fcil. Basta criar uma instncia do objeto, abrir uma url e enviar uma requisio. O status HTTPdo resultado assim como o seu contedo estaro disponveis quando a transao for completada. Esta pgina descreve alguns casos comuns de uso desse poderoso objeto JavaScript.

function reqListener() {
  console.log(this.responseText);
}

var oReq = new XMLHttpRequest();
oReq.onload = reqListener;
oReq.open("get", "yourFile.txt", true);
oReq.send();

Tipos de Requisies

Uma requisio feita via XMLHttpRequest pode buscar dados de duas maneiras, scrona e assncrona. O tipo de requisio dado pelo argumento async que opcional (terceiro argumento) e definido no mtodo XMLHttpRequest open(). Se esse argumento for true ou no especificado, o XMLHttpRequest ser processado de maneira assncrona, caso contrrio o processamento ser sncrono. Uma discusso detalhada e demonstraes desses dois tipos podem ser encontradas na pgina requisies sncronas e assncronas. No geral a melhor prtica a das solicitaes assncronas.

Manipulando Respostas

Existem vrios tipos de atributos de resposta definidos pela especificao da W3C para o XMLHttpRequest. Eles informam ao cliente que efetuou a requisio XMLHttpRequest informaes importantes sobre o status da resposta. Em alguns casos onde se lida com tipos de resposa de no-texto, os tipos de resposta podem envolver alguma manipulao e/ou anlise conforme descrito nas sees seguintes.

Analisando e manipulando a propriedade `responseXML`

Se voc utiliza o XMLHttpRequest para obter o contedo de um documento XML remoto, a propriedade responseXML ser um objeto DOM que contm um documento XML, o que pode dificultar a manipulao e anlise.

As cinco formas mais utilizadas para anlisar e manipular um arquivo XML so:

Usando XPath para anlisar parte deles.
Usando JXON para converter em um Objeto JavaScript.
Manualmente Parsing and serializing XML para strings ou objetos.
Usando XMLSerializer para serializar rvores do DOM para strings ou para arquivos.
RegExppode ser usado se voc souber de antemo qual o contedo do XML. Voc pode remover quebras de linhas, usando a RegExp para procurar as quebras de linha. No entanto, este o "ltimo mtodo", caso o cdigo do XML sofra alteraes, o mtodo se torna falho.

Analisando e manipulando uma propriedade `responseText` contendo um documento HTML

Nota: A especificao W3C do XMLHttpRequest permite analisar HTML atravs da propriedade XMLHttpRequest.responseXML . Leia o artigo sobre HTML in XMLHttpRequest para maiores detalhes.

Se voc usa o XMLHttpRequest para recuperar o contedo de uma pgina HTML remota, a propriedade responseText ser uma string contendo um a "sopa" de todos as tags HTML, o que pode ser difcil de manipular e analizar. Existem trs formas bsicas para analizar esta sopa de string HTML:

Use a propriedade XMLHttpRequest.responseXML.
Introduza o contedo dentro do corpo de um document fragment Atravs de fragment.body.innerHTML e percorra o fragmento do DOM.
RegExp pode se usada se voc sempre conhece o contedo HTML responseTextde que tem em mos. Voc pode quere remover quebras de linha, se voc usar RegExp para varrer no que diz respeito a quebra de linhas. Contudo, este mtodo um "ltimo recurso" uma vez que se o cdigo HTML mudar um pouco, o mtodo provavelmente ir falhar.

Manipulao de dados binrios

Apesar de XMLHttpRequest ser mais comumente usado para enviar e receber dados textual, ele pode ser utilizado para enviar e receber contedo binrio. Existem vrios mtodos bem testados para forar a resposta de um XMLHttpRequest para o envio de dados binrio. Eles envolvem a utilizao do mtodo .overrideMimeType() sobre o objeto XMLHttpRequest e uma soluo vivel.

var oReq = new XMLHttpRequest();
oReq.open("GET", url, true);
// recupera dados no processados como uma string binria
oReq.overrideMimeType("text/plain; charset=x-user-defined");
/* ... */

A especificao XMLHttpRequest Level 2 adiciona novo responseType attributes que tornam o envio e recebimento de dados muito mais fcil.

var oReq = new XMLHttpRequest();

oReq.open("GET", url, true);
oReq.responseType = "arraybuffer";
oReq.onload = function (e) {
  var arraybuffer = oReq.response; // no  responseText
  /* ... */
};
oReq.send();

Para mais exemplos confira a pgina Sending and Receiving Binary Data.

Monitorando o progresso

XMLHttpRequest fornece a capacidade de ouvir vrios eventos que podem ocorrer enquanto o pedido est sendo processado. Isso inclui notificaes peridicas de progresso, notificaes de erro e assim por diante.

Suporte para evento de progresso DOM monitorando a conexo XMLHttpRequest transfers siga a Web API specification for progress events: estes eventos implementam a interface ProgressEvent .

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 transferncia foi cancelada pelo usurio

// progresso de transferncias do servidor para o cliente (downloads)
function updateProgress(oEvent) {
  if (oEvent.lengthComputable) {
    var percentComplete = oEvent.loaded / oEvent.total;
    // ...
  } else {
    // No  possvel calcular informaes de progresso uma vez que a dimenso total  desconhecida
  }
}

function transferComplete(evt) {
  alert("A transferncia foi concluda.");
}

function transferFailed(evt) {
  alert("Um erro ocorreu durante a transferncia do arquivo.");
}

function transferCanceled(evt) {
  alert("A transferncia foi cancelada pelo usurio.");
}

Lines 3-6 adiciona receptores de eventos (event listeners) para os vrios que so enviados ao executar uma transferncia de dados usando XMLHttpRequest.

Nota: Voc precisa adicionar os receptores de eventos (event listeners) antes de chamar open() sobre a requisio. Caso contrrio, os eventos de prograsso no dispararo..

O manipulador de evento de prograsso, especificado pela funo updateProgress() neste exemplo, recebe o nmero total de bytes para transferir, bem como o nmero de bytes transferidos at o momento em total de eventos e campos carregados . No entanto, se o campo lengthComputable false, o comprimento total no conhecido e ser zero..

Eventos de progresso existem para ambos as transferncias de download e upload. The download events are fired on the XMLHttpRequest object itself, as shown in the above sample. The upload events are fired on the XMLHttpRequest.upload object, as shown below:

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();

Nota: eventos de progresso no esto disponveis para o arquivo: protocol.

Nota: Atualmente, existem bugs em aberto para o evento de progresso que continua fetando a verso 25 do Firefox sobre OS X e Linux.

Nota: Iniciando no Gecko 9.0, eventos de progresso agora podem ser invocados a entrar para cada pedao de dados recebidos, incluindo o ltimo bloco, nos casos em que o ltimo pacote recebido e a conexo fechada antes do evento progresso ser disparado. Neste caso, o evento de progresso automaticamente acionado quando o evento load ocorre para esse pacote. Isso permite que voc agora acompanhe de forma confivel apenas observando o evento de progresso

Nota: A partir do Gecko 12.0, se o seu evento de progresso e chamado com um responseType de "moz-blob", o valor da resposta ser um Blob contendo os dados recebidos at agorar.

POde-se tambm detectar todas as trs condies de fim de carga (abort, load, or error) usando o evento loadend:

req.addEventListener("loadend", loadEnd, false);

function loadEnd(e) {
  alert(
    "A transferncia terminou (embora no sabemos se ele conseguiu ou no).",
  );
}

Note que no h nenhuma maneira de ter certeza a partir da informao recebida pelo evento loadend sobre qual condio causou a operao de encerrar; no entanto, voc pode usar isso para lidar com tarefas que precisam ser realizadas em todos os cenrios de fim-de-transferncia.

Submitting forms and uploading files

Instances of XMLHttpRequest can be used to submit forms in two ways:

using nothing but pure AJAX,
using the FormData API.

The second way (using the FormData API) is the simplest and the fastest, but has the disadvantage that the data thus collected can not be stringified: they are in every way a blob. It is the best solution for simple cases. The first way (pure AJAX) is instead the most complex, but in compensation is also the most flexible and powerful: it lends itself to wider uses and the data thus collected can be stringified and reused for other purposes such as, for example, populating the status object during a manipulation of the browser history, or other.

Using nothing but pure AJAX

Submitting forms without the FormData API does not require other APIs, except that, only if you want to upload one or more files, the FileReader API.

A brief introduction to the submit methods

An html <form> can be sent in four ways:

using the POST method and setting the enctype attribute to application/x-www-form-urlencoded (default);
using the POST method and setting the enctype attribute to text/plain;
using the POST method and setting the enctype attribute to multipart/form-data;
using the GET method (in this case the enctype attribute will be ignored).

Now, consider to submit a form containing only two fields, named foo and baz. If you are using the POST method, the server will receive a string similar to one of the following three ones depending on the encoding type you are using:

Method: POST; Encoding type: application/x-www-form-urlencoded (default):

Content-Type: application/x-www-form-urlencoded

foo=bar&baz=The+first+line.&#37;0D%0AThe+second+line.%0D%0A

Method: POST; Encoding type: text/plain:

Content-Type: text/plain

foo=bar
baz=The first line.
The second line.

Method: POST; Encoding type: multipart/form-data:

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--

Instead, if you are using the GET method, a string like the following will be simply added to the URL:

?foo=bar&baz=The%20first%20line.%0AThe%20second%20line.

A little vanilla framework

All these things are done automatically by the web browser whenever you submit a <form>. But if you want to do the same things using JavaScript you have to instruct the interpreter about all things. So, how to send forms in pure AJAX is too complex to be explained in detail here. For this reason we posted here a complete (but still didactic) framework, which is able to use all the four ways of submit and, also, to upload files:

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/pt-BR/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/pt-BR/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"
      >
      <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"
      >
      <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"
      >
      <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"
      >
      <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>

To test it, please, create a page named register.php (which is the action attribute of these sample forms) and just put the following minimalistic content:

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);

?>

The syntax of this script is the following:

AJAXSubmit(myForm);

Nota: This little vanilla framework uses the FileReader API, which is a recent technique (but only when there are files to upload, the method of the <form> is POST and the enctype attribute is setted to multipart/form-data). For this reason, the pure-AJAX upload is to be considered an experimental technique. Instead, if you don't want to upload files, this framework will not use any recent API. Note also that the best way to send binary content is using ArrayBuffers or Blobs in conjuncton with the send() method and, possibly, with the readAsArrayBuffer() method of the FileReader API. But, since the aim of this little script is to work with a stringifiable raw data, we used the sendAsBinary() method in conjunction with the readAsBinaryString() method of the FileReader API. So, this is the best solution when working with a relatively few data which must be stringified in order to be reused later. Anyhow, since working with strings instead of typed arrays implies a greater waste of resources, this script makes sense only when you are dealing with small files (like images, documents, mp3, etc.). Otherwise, if you don't want to stringify the submitted or uploaded data, in addition to typed arrays, consider also the use of the FormData API.

Using FormData objects

The FormData constructor lets you compile a set of key/value pairs to send using XMLHttpRequest. 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 submit() 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 Using FormData Objects page. For didactic purpose only we post here a translation of the previous example transformed so as to make use of the FormData API. Note the brevity of the code:

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"
      >
      <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"
      >
      <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"
      >
      <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>

Nota: As we said, FormData objects are not stringifiable objects. If you want to stringify a submitted data, use the previous pure-AJAX example. Note also that, although in this example there are some file <input> fields, when you submit a form through the FormData API you do not need to use the FileReader API also: files are automatically loaded and uploaded.

Cross-site XMLHttpRequest

Modern browsers support cross-site requests by implementing the web applications working group's Access Control for Cross-Site Requests standard. As long as the server is configured to allow requests from your web application's origin, XMLHttpRequest will work. Otherwise, an INVALID_ACCESS_ERR exception is thrown.

Bypassing the cache

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:

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

Since the local cache is indexed by URL, this causes every request to be unique, thereby bypassing the cache.

You can automatically adjust URLs using the following code:

var oReq = new XMLHttpRequest();

oReq.open(
  "GET",
  url + (/\?/.test(url) ? "&" : "?") + new Date().getTime(),
  true,
);
oReq.send(null);

Security

The recommended way to enable cross-site scripting is to use the Access-Control-Allow-Origin HTTP header in the response to the XMLHttpRequest.

XMLHttpRequests being stopped

If you end up with an XMLHttpRequest having status=0 and statusText=null, it means that the request was not allowed to be performed. It was UNSENT. A likely cause for this is when the XMLHttpRequest origin (at the creation of the XMLHttpRequest) has changed when the XMLHttpRequest is then open(). 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 open()) 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.

Using XMLHttpRequest from JavaScript modules / XPCOM components

Instantiating XMLHttpRequest from a JavaScript module or an XPCOM component works a little differently; it can't be instantiated using the XMLHttpRequest() 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.

const XMLHttpRequest = Components.Constructor(
  "@mozilla.org/xmlextras/xmlhttprequest;1",
);
var oReq = XMLHttpRequest();

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.

const { XMLHttpRequest } = Components.classes[
  "@mozilla.org/appshell/appShellService;1"
].getService(Components.interfaces.nsIAppShellService).hiddenDOMWindow;
var oReq = XMLHttpRequest();

Help improve MDN

Was this page helpful to you?

Yes No

Learn how to contribute

This page was last modified on 10 de abr. de 2026 by MDN contributors.

View this page on GitHub Report a problem with this content