diff options
author | Peter Bengtsson <mail@peterbe.com> | 2020-12-08 14:41:45 -0500 |
---|---|---|
committer | Peter Bengtsson <mail@peterbe.com> | 2020-12-08 14:41:45 -0500 |
commit | 1109132f09d75da9a28b649c7677bb6ce07c40c0 (patch) | |
tree | 0dd8b084480983cf9f9680e8aedb92782a921b13 /files/es/web/api/xmlhttprequest | |
parent | 4b1a9203c547c019fc5398082ae19a3f3d4c3efe (diff) | |
download | translated-content-1109132f09d75da9a28b649c7677bb6ce07c40c0.tar.gz translated-content-1109132f09d75da9a28b649c7677bb6ce07c40c0.tar.bz2 translated-content-1109132f09d75da9a28b649c7677bb6ce07c40c0.zip |
initial commit
Diffstat (limited to 'files/es/web/api/xmlhttprequest')
8 files changed, 1591 insertions, 0 deletions
diff --git a/files/es/web/api/xmlhttprequest/abort/index.html b/files/es/web/api/xmlhttprequest/abort/index.html new file mode 100644 index 0000000000..de73cb1a5d --- /dev/null +++ b/files/es/web/api/xmlhttprequest/abort/index.html @@ -0,0 +1,120 @@ +--- +title: XMLHttpRequest.abort() +slug: Web/API/XMLHttpRequest/abort +tags: + - AJAX + - API + - HTTP + - HttpRequest + - Referencia + - XHR + - XMLHttpRequest + - abortar + - metodo +translation_of: Web/API/XMLHttpRequest/abort +--- +<p>{{APIRef('XMLHttpRequest')}}</p> + +<p>El método <strong>XMLHttpRequest.abort()</strong> aborta la petición si ha sido enviada. Cuando una petición se aborta, readyState se asigna a 0 (UNSENT), pero el evento <a href="/en-US/docs/Web/Events/readystatechange">readystatechange</a> no se lanza.</p> + +<h2 id="Sintaxis">Sintaxis</h2> + +<pre class="syntaxbox">xhrInstance.abort();</pre> + +<h3 id="Parámetros">Parámetros</h3> + +<p>Ninguno.</p> + +<h3 id="Valor_de_retorno">Valor de retorno</h3> + +<p>Vacío.</p> + +<h2 id="Ejemplo">Ejemplo</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="Especificaciones">Especificaciones</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th scope="col">Especificación</th> + <th scope="col">Estado</th> + <th scope="col">Comentario</th> + </tr> + <tr> + <td>{{SpecName('XMLHttpRequest', '#the-abort()-method')}}</td> + <td>{{Spec2('XMLHttpRequest')}}</td> + <td>WHATWG living standard</td> + </tr> + </tbody> +</table> + +<h2 id="Compatibilidad_con_navegadores">Compatibilidad con navegadores</h2> + +<div>{{CompatibilityTable}}</div> + +<div id="compat-desktop"> +<table class="compat-table"> + <tbody> + <tr> + <th>Mejora</th> + <th>Chrome</th> + <th>Firefox (Gecko)</th> + <th>Internet Explorer</th> + <th>Opera</th> + <th>Safari (WebKit)</th> + </tr> + <tr> + <td>Soporte básico</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>Mejora</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>Soporte 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> + +<p>[1] This feature was implemented via ActiveXObject(). Internet Explorer implementa el estándar XMLHttpRequest desde la versión 7.</p> + +<h2 id="Ver_también">Ver también</h2> + +<ul> + <li><a href="/en-US/docs/Web/API/XMLHttpRequest/Using_XMLHttpRequest">Uso de XMLHttpRequest</a></li> +</ul> diff --git a/files/es/web/api/xmlhttprequest/formdata/index.html b/files/es/web/api/xmlhttprequest/formdata/index.html new file mode 100644 index 0000000000..2ca830daf7 --- /dev/null +++ b/files/es/web/api/xmlhttprequest/formdata/index.html @@ -0,0 +1,84 @@ +--- +title: FormData +slug: Web/API/XMLHttpRequest/FormData +tags: + - API + - FormData + - Interfaz + - Referencia + - XMLHttpRequest +translation_of: Web/API/FormData +--- +<p>{{APIRef("XMLHttpRequest")}}</p> + +<p>La interfaz <strong><code>FormData</code></strong> proporciona una manera sencilla de construir un conjunto de parejas clave/valor que representan los campos de un formulario y sus valores, que pueden ser enviados fácilmente con el método {{domxref("XMLHttpRequest.send()")}}. Utiliza el mismo formato que usaría un formulario si el tipo de codificación fuera <code>"multipart/form-data"</code>.</p> + +<p>También puede pasarse directamente al constructor de {{domxref("URLSearchParams")}} si se quieren generar parámetros de consulta de la misma forma en que lo haría un {{HTMLElement("form")}} si usara un envío <code>GET</code> simple.</p> + +<p>Un objeto que implementa <code>FormData</code> puede usarse directamente en una estructura {{jsxref("Statements/for...of", "for...of")}}, en lugar de {{domxref('FormData.entries()', 'entries()')}}: <code>for (var p of myFormData)</code> es equivalente a <code>for (var p of myFormData.entries())</code>.</p> + +<div class="note"> +<p><strong>Nota</strong>: Esta característica está disponible en <a href="/es/docs/Web/API/Web_Workers_API">Web Workers</a>.</p> +</div> + +<h2 id="Constructor">Constructor</h2> + +<dl> + <dt>{{domxref("FormData.FormData","FormData()")}}</dt> + <dd>Crea un nuevo objeto <code>FormData</code>.</dd> +</dl> + +<h2 id="Métodos">Métodos</h2> + +<dl> + <dt>{{domxref("FormData.append()")}}</dt> + <dd>Agrega un nuevo valor a una clave existente dentro de un objeto <code>FormData</code>, o añade la clave si aún no existe.</dd> + <dt>{{domxref("FormData.delete()")}}</dt> + <dd>Elimina una pareja clave/valor de un objeto <code>FormData</code>.</dd> + <dt>{{domxref("FormData.entries()")}}</dt> + <dd>Devuelve un {{jsxref("Iteration_protocols","iterator")}} que permite recorrer todas las parejas clave/valor contenidas en este objeto.</dd> + <dt>{{domxref("FormData.get()")}}</dt> + <dd>Devuelve el primer valor asociado con una clave dada en un objeto <code>FormData</code>.</dd> + <dt>{{domxref("FormData.getAll()")}}</dt> + <dd>Devuelve un array con todos los valores asociados con una clave dada en un objeto <code>FormData</code>.</dd> + <dt>{{domxref("FormData.has()")}}</dt> + <dd>Devuelve un booleano que indica si un objeto <code>FormData</code> contiene una clave determinada.</dd> + <dt>{{domxref("FormData.keys()")}}</dt> + <dd>Devuelve un {{jsxref("Iteration_protocols", "iterator")}} que permite recorrer todas las claves de las parejas clave/valor contenidas en este objeto.</dd> + <dt>{{domxref("FormData.set()")}}</dt> + <dd>Establece un nuevo valor para una clave existente dentro de un objeto <code>FormData</code>, o agrega la clave/valor si aún no existe.</dd> + <dt>{{domxref("FormData.values()")}}</dt> + <dd>Devuelve un {{jsxref("Iteration_protocols", "iterator")}} que permite recorrer todos los valores contenidos en este objeto.</dd> +</dl> + +<h2 id="Especificaciones">Especificaciones</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th scope="col">Especificación</th> + <th scope="col">Estado</th> + <th scope="col">Comentario</th> + </tr> + <tr> + <td>{{SpecName('XMLHttpRequest','#interface-formdata','FormData')}}</td> + <td>{{Spec2('XMLHttpRequest')}}</td> + <td>FormData definido en XHR spec</td> + </tr> + </tbody> +</table> + +<h2 id="Compatibilidad_con_navegadores">Compatibilidad con navegadores</h2> + + + +<p>{{Compat("api.FormData")}}</p> + +<h2 id="Ver_también">Ver también</h2> + +<ul> + <li>{{domxref("XMLHTTPRequest")}}</li> + <li><a href="/en/DOM/XMLHttpRequest/Using_XMLHttpRequest" title="En/Using XMLHttpRequest">Utilización de XMLHttpRequest</a></li> + <li><a href="/es/docs/Web/Guide/Usando_Objetos_FormData" title="en/DOM/XMLHttpRequest/FormData/Using_FormData_objects">Usando objetos FormData</a></li> + <li>{{HTMLElement("Form")}}</li> +</ul> diff --git a/files/es/web/api/xmlhttprequest/index.html b/files/es/web/api/xmlhttprequest/index.html new file mode 100644 index 0000000000..243b3220e6 --- /dev/null +++ b/files/es/web/api/xmlhttprequest/index.html @@ -0,0 +1,428 @@ +--- +title: XMLHttpRequest +slug: Web/API/XMLHttpRequest +tags: + - AJAX + - Todas_las_Categorías + - XMLHttpRequest + - páginas_a_traducir +translation_of: Web/API/XMLHttpRequest +--- +<p><code>XMLHttpRequest</code> es un objeto <a class="internal" href="/en/JavaScript" title="En/JavaScript">JavaScript</a> que fue diseñado por Microsoft y adoptado por Mozilla, Apple y Google. Actualmente es un <a class="external" href="http://www.w3.org/TR/XMLHttpRequest/" title="http://www.w3.org/TR/XMLHttpRequest/">estándar de la W3C</a>. Proporciona una forma fácil de obtener información de una URL sin tener que recargar la página completa. Una página web puede actualizar sólo una parte de la página sin interrumpir lo que el usuario está haciendo. <code style="font-size: 14px;">XMLHttpRequest</code> es ampliamente usado en la programación AJAX.</p> + +<p><span style="line-height: 1.5;">A pesar de su nombre, </span><code style="font-size: 14px;">XMLHttpRequest</code><span style="line-height: 1.5;"> puede ser usado para recibir cualquier tipo de dato, no solo XML, y admite otros formatos además de </span><a href="/en/HTTP" style="line-height: 1.5;" title="en/HTTP">HTTP</a><span style="line-height: 1.5;"> (incluyendo </span><code style="font-size: 14px;">file</code><span style="line-height: 1.5;"> y </span><code style="font-size: 14px;">ftp</code><span style="line-height: 1.5;">).</span></p> + +<p>Para crear una instancia de <code>XMLHttpRequest</code>, debes hacer lo siguiente:</p> + +<pre>var req = new XMLHttpRequest(); +</pre> + +<p>Para obtener más información de cómo usar <code>XMLHttpRequest</code>, mira <a class="internal" href="/Es/XMLHttpRequest/Using_XMLHttpRequest" title="En/Using XMLHttpRequest">Usar XMLHttpRequest</a>.</p> + +<div class="note"><strong>Nota:</strong> De forma predeterminada, Firefox 3 limita la cantidad de conexiones de <code>XMLHttpRequest</code> por servidor a 6 (las versiones previas limitan a 2 conexiones por servidor). Algunos sitios web interactivos pueden mantener una conexión <code>XMLHttpRequest</code> abierta, así que abrir múltiples sesiones a esos sitios puede derivar en congelamientos del navegador de una forma que la ventana no se actualiza y los controles no responden. Este valor puede ser cambiado al editar la preferencia <code>network.http.max-persistent-connections-per-server</code> en <code><a class="linkification-ext" href="/about:config" title="Linkification: about:config">about:config</a></code>.</div> + +<h2 id="Resumen_del_método">Resumen del método</h2> + +<table class="standard-table"> + <tbody> + <tr> + <td><code>void <a class="internal" href="/en/XMLHttpRequest#abort()" title="/En/XMLHttpRequest#abort()">abort</a>();</code></td> + </tr> + <tr> + <td><code>string <a class="internal" href="/en/XMLHttpRequest#getAllResponseHeaders()" title="/en/XMLHttpRequest#getAllResponseHeaders()">getAllResponseHeaders</a>();</code></td> + </tr> + <tr> + <td><code>ACString <a class="internal" href="/en/XMLHttpRequest#getResponseHeader()" title="/en/XMLHttpRequest#getResponseHeader()">getResponseHeader</a>(in AUTF8String header);</code></td> + </tr> + <tr> + <td><code>[noscript] void <a class="internal" href="/en/XMLHttpRequest#init()" title="/en/XMLHttpRequest#init()">init</a>(in nsIPrincipal principal, in nsIScriptContext scriptContext, in nsPIDOMWindow ownerWindow);</code></td> + </tr> + <tr> + <td><code>void <a class="internal" href="/en/XMLHttpRequest#open()" title="/en/XMLHttpRequest#open()">open</a>(in AUTF8String method, in AUTF8String url);</code></td> + </tr> + <tr> + <td><code>[noscript] void <a class="internal" href="/en/XMLHttpRequest#openRequest()" title="/en/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/XMLHttpRequest#overrideMimeType()" title="/en/XMLHttpRequest#overrideMimeType()">overrideMimeType</a>(in AUTF8String mimetype);</code></td> + </tr> + <tr> + <td><code>void <a class="internal" href="/en/XMLHttpRequest#send()" title="/en/XMLHttpRequest#send()">send</a>([optional] in nsIVariant body);</code></td> + </tr> + <tr> + <td><code>void <a class="internal" href="/en/XMLHttpRequest#sendAsBinary()" title="/en/XMLHttpRequest#sendAsBinary()">sendAsBinary</a>(in DOMString body); {{ fx_minversion_inline(3) }}</code></td> + </tr> + <tr> + <td><code>void <a class="internal" href="/en/XMLHttpRequest#setRequestHeader()" title="/en/XMLHttpRequest#setRequestHeader()">setRequestHeader</a>(in AUTF8String header, in AUTF8String value);</code></td> + </tr> + </tbody> +</table> + +<h2 id="Propiedades">Propiedades</h2> + +<table class="standard-table"> + <tbody> + <tr> + <td class="header">Atributo</td> + <td class="header">Tipo</td> + <td class="header">Descripción</td> + </tr> + <tr> + <td><code>channel</code></td> + <td>{{ Interface("nsIChannel") }}</td> + <td>El canal es usado por el objeto cuando se produce el pedido. Esto da <code>null</code> si el canal aún no fue creado. En el caso de un pedido de múltiples partes, este es el canal inicial, no las diferentes partes del pedido múltiple. <strong>Es necesario tener privilegios elevados para acceder; sólo lectura.</strong> {{ Non-standard_inline() }}</td> + </tr> + <tr> + <td><code>mozBackgroundRequest</code></td> + <td><code>booleano</code></td> + <td> + <p>Indica si el objeto representa o no un pedido de un servicio de fondo. Si es <code>true</code>, no se asocia una carga de grupo con el pedido, y los diálogos de seguridad no se muestran al usuario. <strong>Es necesario tener privilegios elevados para acceder. </strong>{{ Non-standard_inline() }}</p> + + <p>En los casos en que un diálogo de seguridad debe ser mostrado (como en una autentficación o la notificación de un certificado no válido), el pedido simplemente falla.</p> + </td> + </tr> + <tr> + <td><code>mozResponseArrayBuffer</code> {{ non-standard_inline() }}</td> + <td><a href="/en/JavaScript_typed_arrays/ArrayBuffer" title="en/JavaScript typed arrays/ArrayBuffer"><code>ArrayBuffer</code></a></td> + <td>La respuesta al pedido en la forma de un arreglo de JavaScript. Esto es NULL si el pedido no fue exitoso o si todavía no ha sido enviado. <strong>Sólo lectura.</strong></td> + </tr> + <tr> + <td><code>multipart</code></td> + <td><code>booleano</code></td> + <td> + <p>Indica cuando se espera que la respuesta sea o no una serie de mútiples documentos XML. Si se define como <code>true</code>, el tipo de contenido de la respuesta inicial debe ser <code>multipart/x-mixed-replace</code> u ocurrirá un error. Todos los pedidos deben ser asincrónicos.</p> + + <p>Esto permite el uso del push del servidor; para cada documento XML que se escribe para este pedido, se crea un nuevo XMLDOMdocument y se llama al manejador <code>onload</code> entre cada documento.</p> + + <div class="note"><strong>Nota:</strong> Cuando esto se elige, el manejador <code>onload</code> y otros manejadores de eventos no son reiniciados después de que el primer XMLdocument es cargado, y el manejador <code>onload</code> es llamado después de que cada parte de la respuesta es recibida.</div> + </td> + </tr> + <tr id="onreadystatechange"> + <td> + <p><code>onreadystatechange</code></p> + </td> + <td>{{ Interface("nsIDOMEventListener") }}</td> + <td> + <p>Una función del objeto JavaScript que se llama cuando el atributo <code>readyState</code> cambia. El callback se llama desde la interfaz del usuario.</p> + + <div class="warning"><strong>Aviso: </strong>Esto no debe ser usado desde código nativo. Tampoco debes usarlo con pedidos sincrónicos.</div> + </td> + </tr> + <tr id="readyState"> + <td><code>readyState</code></td> + <td><code>long</code></td> + <td> + <p>El estado del pedido:</p> + + <table class="standard-table"> + <tbody> + <tr> + <td class="header">Valor</td> + <td class="header">Estado</td> + <td class="header">Descripción</td> + </tr> + <tr> + <td><code>0</code></td> + <td><code>UNINITIALIZED</code></td> + <td>todavía no se llamó a <code>open()</code>.</td> + </tr> + <tr> + <td><code>1</code></td> + <td><code>LOADING</code></td> + <td>todavía no se llamó a <code>send()</code>.</td> + </tr> + <tr> + <td><code>2</code></td> + <td><code>LOADED</code></td> + <td><code>send()</code> ya fue invocado, y los encabezados y el estado están disponibles.</td> + </tr> + <tr> + <td><code>3</code></td> + <td><code>INTERACTIVE</code></td> + <td>Descargando; <code>responseText</code> contiene información parcial.</td> + </tr> + <tr> + <td><code>4</code></td> + <td><code>COMPLETED</code></td> + <td>La operación está terminada.</td> + </tr> + </tbody> + </table> + </td> + </tr> + <tr id="responseText"> + <td><code>responseText</code></td> + <td><code>AString</code></td> + <td>La respuesta al pedido como texto, o <code>null</code> si el pedido no fue exitoso o todavía no se envió. <strong>Sólo lectura.</strong></td> + </tr> + <tr id="responseXML"> + <td><code>responseXML</code></td> + <td><code>nsIDOMDocument</code></td> + <td> + <p>La respuesta al pedido como un objeto DOM<code><a class="internal" href="/en/DOM/document" title="En/DOM/Document">Document</a></code>, o <code>null</code> si el pedido no fue exitoso, aún no fue enviado o no puede ser analizado como XML. La respuesta es analizada como si fuera <code>text/xml</code>. <strong>Sólo lectura.</strong></p> + + <div class="note"><strong>Nota:</strong> Si el servidor no aplica el encabezado de tipo de contenido <code>text/xml</code>, puedes usar <code>overrideMimeType()</code> para forzar a <code>XMLHttpRequest</code> a analizarlo como XML igualmente.</div> + </td> + </tr> + <tr id="status"> + <td><code>status</code></td> + <td><code>unsigned long</code></td> + <td>El estado de la respuesta al pedido. Éste es el código HTTPresult (por ejemplo, <code>status</code> es 200 por un pedido exitoso). <strong>Sólo lectura.</strong></td> + </tr> + <tr> + <td><code>statusText</code></td> + <td><code>AUTF8String</code></td> + <td>La cadena de respuesta que devuelve el HTTPserver. A diferencia de <code>status</code>, este incluye el texto completo del mensaje de respuesta ("<code>200 OK</code>", por ejemplo). <strong>Sólo lectura.</strong></td> + </tr> + <tr> + <td><code>upload</code></td> + <td>{{ Interface("nsIXMLHttpRequestUpload") }}</td> + <td>El proceso de subida puede ser rastreado al agregar un registro de evento a <code>upload</code>. {{ fx_minversion_inline(3.5) }}</td> + </tr> + <tr> + <td><code>withCredentials</code></td> + <td><code>booleano</code></td> + <td> + <p>Indica cuando el pedido de Access-Control entre sitios debe o no ser realizado usando credenciales como cookies o encabezados de autorización. {{ fx_minversion_inline(3.5) }}</p> + + <div class="note"><strong>Nota:</strong> Esto nunca afecta los pedidos en para el propio sitio.</div> + + <p>El valor predeterminado es <code>false</code>.</p> + </td> + </tr> + </tbody> +</table> + +<h2 id="Métodos">Métodos</h2> + +<h3 id="abort()">abort()</h3> + +<p>Aborta el pedido si éste ya fue enviado.</p> + +<pre>void abort(); +</pre> + +<h6 id="Parámetros">Parámetros</h6> + +<p>Ninguno.</p> + +<h3 id="getAllResponseHeaders()">getAllResponseHeaders()</h3> + +<p>Devuelve todos los encabezados de respuesta como una cadena.</p> + +<div class="note"><strong>Nota:</strong> Para pedidos multi partes, esto devuelve los encabezados de la parte <em>actual</em> del pedido, no del canal original.</div> + +<pre>string getAllResponseHeaders(); +</pre> + +<h6 id="Parámetros_2">Parámetros</h6> + +<p>Ninguno.</p> + +<h6 id="Valor_devuelto">Valor devuelto</h6> + +<p>El texto de todos los encabezados de respuesta, o <code>null</code> si no se ha recibido ninguna respuesta.</p> + +<h3 id="getResponseHeader()">getResponseHeader()</h3> + +<p>Devuelve el texto de un encabezado específico.</p> + +<pre>ACString getResponseHeader( + in AUTF8String header +); +</pre> + +<h6 id="Parámetros_3">Parámetros</h6> + +<dl> + <dt><code>header</code></dt> + <dd>El nombre del encabezado buscado.</dd> +</dl> + +<h6 id="Valor_devuelto_2">Valor devuelto</h6> + +<p>Una cadena que contiene el texto de un encabezado específico, o <code>null</code> tanto si la respuesta no se ha recibido o el encabezado no existe en la respuesta.</p> + +<h3 id="init()">init()</h3> + +<p>Inicializa el objeto para que sea usado desde código C++.</p> + +<div class="warning"><strong>Aviso:</strong> Este método <em>no</em> debe ser llamado desde JavaScript.</div> + +<pre>[noscript] void init( + in nsIPrincipal principal, + in nsIScriptContext scriptContext, + in nsPIDOMWindow ownerWindow +); +</pre> + +<h6 id="Parámetros_4">Parámetros</h6> + +<dl> + <dt><code>principal</code></dt> + <dd>El principal para usar en el pedido; no debe ser <code>null</code>.</dd> + <dt><code>scriptContext</code></dt> + <dd>El contexto del programa que usará en el pedido; no debe ser <code>null</code>.</dd> + <dt><code>ownerWindow</code></dt> + <dd>La ventana asociada con el pedido; puede ser <code>null</code>.</dd> +</dl> + +<h3 id="open()">open()</h3> + +<p>Inicializa el pedido. Este método es para ser usado desde código JavaScript, para inicializar un pedido desde código nativo, debes usar <a class="internal" href="/en/XMLHttpRequest#openRequest()" title="/en/XMLHttpRequest#openRequest()"><code>openRequest()</code></a>.</p> + +<div class="note"><strong>Nota:</strong> Llamar a este método en un pedido activo (uno para el cual <code>open()</code> o <code>openRequest()</code> ya han sido llamados) es equivalente a usar <code>abort()</code>.</div> + +<pre>void open( + in AUTF8String method, + in AUTF8String url, + [optional] in boolean async, + [optional] in AString user, + [optional] in AString password +); +</pre> + +<h6 id="Parámetros_5">Parámetros</h6> + +<dl> + <dt><code>method</code></dt> + <dd>El método HTTP a usar: tanto "POST" o "GET". Se ignora para urls que no son de HTTP.</dd> + <dt><code>url</code></dt> + <dd>La URL a la que se envía el pedido.</dd> + <dt><code>async</code></dt> + <dd><span id="result_box" lang="es"><span>Un parámetro booleano opcional, predeterminado es <code>true</code>, que indica si se debe o no realizar la operación de forma asíncrona.</span> <span>Si este valor es <code>false</code>, el método <code>send()</code> no se devuelve hasta que se reciba la respuesta completa.</span> <span>Si es <code>true</code>, la notificación de una transacción completada se proporciona mediante los oyentes de eventos.</span> <span>Esto debe ser <code>true</code> si el atributo <code>multipart</code> es verdadero o se lanzará una excepción.</span></span></dd> + <dt><code>user</code></dt> + <dd><span id="result_box" lang="es"><span>El nombre de usuario es opcional solo es usado con fines de autenticación,</span> <span>de forma predeterminada es una cadena vacía.</span></span></dd> + <dt><code>password</code></dt> + <dd><span id="result_box" lang="es"><span>La contraseña es opcional solo es usado con fines de autenticación,</span> <span>de forma predeterminada es una cadena vacía.</span></span></dd> +</dl> + +<h3 id="openRequest()">openRequest()</h3> + +<p>Inicia la peticion, este metodo est</p> + +<p><span id="result_box" lang="es"><span>Inicializa la peticion.</span> <span>Este método se utiliza desde el código nativo,</span> <span>para inicializar una solicitud desde el código JavaScript, utilice <code>open ()</code> en su lugar.</span></span></p> + +<div class="note"><strong>Nota:</strong> Calling this method an already active request (one for which <code>open()</code>or <code>openRequest()</code>has already been called) is the equivalent of calling <code>abort()</code>.</div> + +<pre>void open( + in AUTF8String method, + in AUTF8String url, + in boolean async, + in AString user, + in AString password +); +</pre> + +<h6 id="Parameters">Parameters</h6> + +<dl> + <dt><code>method</code></dt> + <dd>The HTTPmethod to use; either "POST"or "GET". Ignored for non-HTTPURLs.</dd> + <dt><code>url</code></dt> + <dd>The URLto which to send the request.</dd> + <dt><code>async</code></dt> + <dd>An optional boolean parameter, defaulting to <code>true</code>, indicating whether or not to perform the operation asynchronously. If this value is <code>false</code>, the <code>send()</code>method does not return until the response is received. If <code>true</code>, notification of a completed transaction is provided using event listeners. This <em>must</em> be true if the <code>multipart</code> attribute is <code>true</code>, or an exception will be thrown.</dd> + <dt><code>user</code></dt> + <dd>The optional user name to use for authentication purposes; by default, this is an empty string.</dd> + <dt><code>password</code></dt> + <dd>The optional password to use for authentication purposes; by default, this is an empty string.</dd> +</dl> + +<h3 id="overrideMimeType()">overrideMimeType()</h3> + +<p>Overrides the MIMEtype returned by the server.</p> + +<div class="note"><strong>Note:</strong> This method must be called before <code>send()</code>.</div> + +<pre>void overrideMimeType( + in AUTF8String mimetype +); +</pre> + +<h6 id="Parameters_2">Parameters</h6> + +<dl> + <dt><code>mimetype</code></dt> + <dd>The type that should be used instead of the one returned by the server, if any.</dd> +</dl> + +<h3 id="send()">send()</h3> + +<p>Sends the request. If the request is asynchronous (which is the default), this method returns as soon as the request is sent. If the request is synchronous, this method doesn't return until the response has arrived.</p> + +<div class="note"><strong>Note:</strong> Any event listeners you wish to set must be set before calling <code>send()</code>.</div> + +<pre>void send( + [optional] in nsIVariant body +); +</pre> + +<h6 id="Parameters_3">Parameters</h6> + +<dl> + <dt><code>body</code></dt> + <dd>This may be an <code>nsIDocument</code>, <code>nsIInputStream</code>, or a string (an <code>nsISupportsString</code> if called from native code) that is used to populate the body of a POST request. Starting with Gecko 1.9.2, you may also specify an DOM{{ domxref("File") }} , and starting with Gecko 2.0 {{ geckoRelease("2.0") }} you may also specify a <a href="/en/XMLHttpRequest/FormData" title="en/XMLHttpRequest/FormData"><code>FormData</code></a> object.</dd> +</dl> + +<h6 id="Notes">Notes</h6> + +<p>If the body is an <code>nsIDOMDocument</code>, it is serialized before being sent.</p> + +<p>If it's an <code>nsIInputStream</code>, it must be compatible with <code>nsIUploadChannel</code>'s <code>setUploadStream()</code>method. In that case, a Content-Length header is added to the request, with its value obtained using <code>nsIInputStream</code>'s <code>available()</code>method. Any headers included at the top of the stream are treated as part of the message body. The stream's MIMEtype should be specified by setting the Content-Type header using the <a class="internal" href="/en/XMLHttpRequest#setRequestHeader()" title="/en/XMLHttpRequest#setRequestHeader()"><code>setRequestHeader()</code></a>method prior to calling <code>send()</code>.</p> + +<h3 id="sendAsBinary()">sendAsBinary()</h3> + +<p>A variant of the <code>send()</code>method that sends binary data.</p> + +<pre>void sendAsBinary( + in DOMString body +); +</pre> + +<h6 id="Parameters_4">Parameters</h6> + +<dl> + <dt><code>body</code></dt> + <dd>The request body as a DOMstring. This data is converted to a string of single-byte characters by truncation (removing the high-order byte of each character).</dd> +</dl> + +<h3 id="setRequestHeader()">setRequestHeader()</h3> + +<p>Sets the value of an HTTPrequest header.</p> + +<div class="note"><strong>Note:</strong> You must call <a class="internal" href="/en/XMLHttpRequest#open()" title="/en/XMLHttpRequest#open()"><code>open()</code></a>before using this method.</div> + +<pre>void setRequestHeader( + in AUTF8String header, + in AUTF8String value +); +</pre> + +<h6 id="Parameters_5">Parameters</h6> + +<dl> + <dt><code>header</code></dt> + <dd>The name of the header whose value is to be set.</dd> + <dt><code>value</code></dt> + <dd>The value to set as the body of the header.</dd> +</dl> + +<h2 id="Implementation_notes">Implementation notes</h2> + +<p><code>XMLHttpRequest</code> is implemented in Gecko using the {{ interface("nsIJSXMLHttpRequest") }} and {{ interface("nsIXMLHttpRequest") }} interfaces.</p> + +<h2 id="See_also">See also</h2> + +<ul> + <li><a class="internal" href="/En/XMLHttpRequest/Using_XMLHttpRequest" title="En/Using XMLHttpRequest">Using XMLHttpRequest</a></li> + <li><a href="/en/XMLHttpRequest/FormData" title="en/XMLHttpRequest/FormData"><code>FormData</code></a></li> + <li><a href="/en/AJAX/Getting_Started" title="en/AJAX/Getting_Started">MDC AJAX introduction</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://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> + <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.w3.org/TR/XMLHttpRequest/">The XMLHttpRequest Object: W3C Working Draft</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": "cn/XMLHttpRequest" } ) }}</p> diff --git a/files/es/web/api/xmlhttprequest/onreadystatechange/index.html b/files/es/web/api/xmlhttprequest/onreadystatechange/index.html new file mode 100644 index 0000000000..7f35ad3e88 --- /dev/null +++ b/files/es/web/api/xmlhttprequest/onreadystatechange/index.html @@ -0,0 +1,109 @@ +--- +title: XMLHttpRequest.onreadystatechange +slug: Web/API/XMLHttpRequest/onreadystatechange +translation_of: Web/API/XMLHttpRequest/onreadystatechange +--- +<div>{{APIRef}}</div> + +<p>Un <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> que es invocado cada vez que cambia el atributo <code>readyState</code>. La retrollamada (callback) es invocada desde el hilo (thread) perteneciente a la interfaz de usuario. La propiedad <strong><code>XMLHttpRequest.onreadystatechange</code></strong> contiene el manejador del evento que es invocado cuando se dispara el evento {{event("readystatechange")}}, lo cual sucede cada vez que cambia el valor de la propiedad {{domxref("XMLHttpRequest.readyState", "readyState")}} de {{domxref("XMLHttpRequest")}}. La retrollamada (callback) es invocada desde el hilo perteneciente a la interfaz de usuario.</p> + +<div class="warning"> +<p><strong>Aviso:</strong> No debería ser usado con peticiones síncronas ni tampoco en código nativo.</p> +</div> + +<p>El evento <code>readystatechange</code> no se disparará cuando una petición <code>XMLHttpRequest</code> sea cancelada mediante el método <a href="/en-US/docs/Web/API/XMLHttpRequest/abort">abort()</a>.</p> + +<h2 id="Syntax" name="Syntax">Sintaxis</h2> + +<pre class="syntaxbox"><em>XMLHttpRequest</em>.onreadystatechange = <em>callback</em>;</pre> + +<h3 id="Valores">Valores</h3> + +<ul> + <li><code><em>callback</em></code> es la función de retrollamada que será ejecutada (invocada) cuando cambie el valor de la propiedad <code>readyState</code>.</li> +</ul> + +<h2 id="Example" name="Example">Ejemplo</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="Especificaciones">Especificaciones</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th scope="col">Specification</th> + <th scope="col">Status</th> + <th scope="col">Comment</th> + </tr> + <tr> + <td>{{SpecName('XMLHttpRequest', '#handler-xhr-onreadystatechange')}}</td> + <td>{{Spec2('XMLHttpRequest')}}</td> + <td>WHATWG living standard</td> + </tr> + </tbody> +</table> + +<h2 id="Compatibilidad_con_navegadores_Web">Compatibilidad con navegadores Web</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] Las versiones 5 y 6 admiten llamadas AJAX usando <code>ActiveXObject()</code>.</p> diff --git a/files/es/web/api/xmlhttprequest/responsetext/index.html b/files/es/web/api/xmlhttprequest/responsetext/index.html new file mode 100644 index 0000000000..d119565243 --- /dev/null +++ b/files/es/web/api/xmlhttprequest/responsetext/index.html @@ -0,0 +1,104 @@ +--- +title: XMLHttpRequest.responseText +slug: Web/API/XMLHttpRequest/responseText +translation_of: Web/API/XMLHttpRequest/responseText +--- +<div>{{draft}}</div> + +<div>{{APIRef('XMLHttpRequest')}}</div> + +<p>La propiedad <strong><code>XMLHttpRequest.responseText</code></strong> devuelve un <strong><code>DOMString</code></strong> que contiene la respuesta a la consulta como un texto o null si la consulta no tuvo exito o aun no ha sido completada. la propiedad <strong><code>responseText</code> </strong> tendra una respuesta parcial como retorno aunque la consulta no haya sido completada. si <strong>responseType</strong> contiene algo que no sea un string vacio o un "text", el acceso a <strong>responseText</strong> sera <strong>throw <code>InvalidStateError</code> exception</strong>.</p> + +<h2 id="Ejemplo._Lanza_una_excepción_InvalidStateError">Ejemplo. Lanza una excepción <strong><code>InvalidStateError</code></strong></h2> + +<pre class="brush: js">var xhr = new XMLHttpRequest(); +xhr.open('GET', '/server', true); + +// If specified, responseType must be empty string or "text" +xhr.responseType = 'text'; + +xhr.onload = function () { + if (xhr.readyState === xhr.DONE) { + if (xhr.status === 200) { + console.log(xhr.response); + console.log(xhr.responseText); + } + } +}; + +xhr.send(null);</pre> + +<h2 id="Especificaciones">Especificaciones</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th scope="col">Especificaciones</th> + <th scope="col">estado</th> + <th scope="col">Comentarios</th> + </tr> + <tr> + <td>{{SpecName('XMLHttpRequest', '#the-responsetext-attribute')}}</td> + <td>{{Spec2('XMLHttpRequest')}}</td> + <td>WHATWG living standard</td> + </tr> + </tbody> +</table> + +<h2 id="Compatibilidad_con_navegadores">Compatibilidad con navegadores</h2> + +<div>{{CompatibilityTable}}</div> + +<div id="compat-desktop"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Chrome</th> + <th>Edge</th> + <th>Firefox (Gecko)</th> + <th>Internet Explorer</th> + <th>Opera</th> + <th>Safari (WebKit)</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}<sup>[1]</sup></td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</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>Edge</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>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<p>[1] Anteriores a IE 10, El valo de XMLHttpRequest.responseText debe ser leido una vez que la consulta fuera completada.</p> diff --git a/files/es/web/api/xmlhttprequest/synchronous_and_asynchronous_requests/index.html b/files/es/web/api/xmlhttprequest/synchronous_and_asynchronous_requests/index.html new file mode 100644 index 0000000000..28675abd79 --- /dev/null +++ b/files/es/web/api/xmlhttprequest/synchronous_and_asynchronous_requests/index.html @@ -0,0 +1,232 @@ +--- +title: Solicitudes síncronas y asíncronas +slug: Web/API/XMLHttpRequest/Synchronous_and_Asynchronous_Requests +translation_of: Web/API/XMLHttpRequest/Synchronous_and_Asynchronous_Requests +--- +<p><code>XMLHttpRequest</code> soporta solicitudes síncronas y asíncronas, pero la mas preferida es la asíncrona por razones de rendimiento</p> + +<p><span id="result_box" lang="es"><span>Las solicitudes síncronas bloquean la ejecución del código, mientras se procesa la solicitud, dejando a la pantalla congelada y dando una experiencia de usuario poco agradable</span></span></p> + +<h2 id="Peticiones_asíncronas">Peticiones asíncronas</h2> + +<p><span id="result_box" lang="es"><span>Si se utiliza <code>XMLHttpRequest</code> de forma asíncrona, recibirá una devolución de llamada cuando los datos se hayan recibido .</span> <span>Esto permite que el navegador continúe funcionando de forma normal mientras se procesa la solicitud.</span></span></p> + +<h3 id="Ejemplo_Enviar_un_archivo_a_la_consola"><span id="result_box" lang="es"><span>Ejemplo: Enviar un archivo a la consola</span></span></h3> + +<p><span class="short_text" id="result_box" lang="es"><span>Este es el uso más simple de la asíncronia </span></span><code>XMLHttpRequest</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>En la linea 2, el ultimo parametro de <code>open()</code> , especifica <code>true</code> para indicar que la solicitud se tratara de forma asíncrona</p> + +<p>Line 3 creates an event handler function object and assigns it to the request's <code>onload</code> attribute. This handler looks at the request's <code>readyState</code> to see if the transaction is complete in line 4, and if it is, and the HTTP status is 200, dumps the received content. If an error occurred, an error message is displayed.</p> + +<p>Line 15 actually initiates the request. The callback routine is called whenever the state of the request changes.</p> + +<h3 id="Ejemplo_Creando_una_funcion_estandar_para_leer_archivos_externos.">Ejemplo: Creando una funcion estandar para leer archivos externos.</h3> + +<p>In some cases you must read many external files. This is a standard function which uses the <code>XMLHttpRequest</code> object asynchronously in order to switch the content of the read file to a specified listener.</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>Usage:</p> + +<pre class="brush: js">function showMessage (sMsg) { + alert(sMsg + this.responseText); +} + +loadFile("message.txt", showMessage, "New message!\n\n"); +</pre> + +<p>The signature of the utility function <em><strong>loadFile</strong></em> declares (i) a target URL to read (via HTTP GET), (ii) a function to execute on successful completion of the XHR operation, and (iii) an arbitrary list of additional arguments that are "passed through" the XHR object to the success callback function.</p> + +<p>Line 1 declares a function invoked when the XHR operation completes successfully. It, in turn, invokes the callback function specified in the invocation of the loadFile function (in this case, the function showMessage) which has been assigned to a property of the XHR object (Line 7). The additional arguments (if any) supplied to the invocation of function loadFile are "applied" to the running of the callback function.</p> + +<p>Line 3 declares a function invoked when the XHR operation fails to complete successfully.</p> + +<p>Line 7 stores on the XHR object 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>In rare cases, the use of a synchronous method is preferable to an asynchronous one.</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/es/web/api/xmlhttprequest/timeout/index.html b/files/es/web/api/xmlhttprequest/timeout/index.html new file mode 100644 index 0000000000..a9fec94792 --- /dev/null +++ b/files/es/web/api/xmlhttprequest/timeout/index.html @@ -0,0 +1,67 @@ +--- +title: XMLHttpRequest.timeout +slug: Web/API/XMLHttpRequest/timeout +tags: + - AJAX + - Propiedad + - Referencia + - XHR + - XHR asincrónico + - XMLHttpRequest + - XMLHttpRequest asincrónico + - tiempo de espera + - timeout +translation_of: Web/API/XMLHttpRequest/timeout +--- +<div>{{APIRef('XMLHttpRequest')}}</div> + +<p>La propiedad <code><strong>XMLHttpRequest.timeout</strong></code> es un <code>unsigned long</code> que representa el número de milisegundos que puede tomar una solicitud antes de que se finalice automáticamente. El valor por defecto es 0, lo que significa que no hay tiempo de espera (<em>timeout</em>). <em>Timeout</em> no debe utilizarse para solicitudes XMLHttpRequests sincrónicas usadas en un {{Glossary('document environment')}}, pues generará una excepción <code>InvalidAccessError</code>. Cuando ocurre un tiempo de espera, se dispara un evento <a href="/en-US/docs/Web/Events/timeout">timeout</a>. {{gecko_minversion_inline("12.0")}}</p> + +<dl> + <dd> + <div class="note"><strong>Nota:</strong> No puede usar un <em>timeout</em> para solicitudes sincrónicas con una ventana propietaria (<em>owning window</em>).</div> + </dd> + <dd><a href="/en-US/docs/Web/API/XMLHttpRequest/Synchronous_and_Asynchronous_Requests#Example_using_a_timeout">Uso de <em>timeout</em> con una solicitud asincrónica</a></dd> +</dl> + +<p>En Internet Explorer, la propiedad <em>timeout</em> se puede establecer solo después de llamar al método <a href="/en-US/docs/Web/API/XMLHttpRequest/open">open()</a> y antes de llamar al método <a href="/en-US/docs/Web/API/XMLHttpRequest/send">send()</a>.</p> + +<h2 id="Ejemplo">Ejemplo</h2> + +<pre class="brush: js">var xhr = new XMLHttpRequest(); +xhr.open('GET', '/server', true); + +xhr.timeout = 2000; // tiempo en milisegundos + +xhr.onload = function () { + // Solicitud finalizada. Haz el procesamiento aquí. +}; + +xhr.ontimeout = function (e) { + // Tiempo de espera del XMLHttpRequest agotado. Haz algo aquí. +}; + +xhr.send(null);</pre> + +<h2 id="Especificaciones">Especificaciones</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th scope="col">Especificación</th> + <th scope="col">Estado</th> + <th scope="col">Comentario</th> + </tr> + <tr> + <td>{{SpecName('XMLHttpRequest', '#the-timeout-attribute')}}</td> + <td>{{Spec2('XMLHttpRequest')}}</td> + <td>WHATWG living standard</td> + </tr> + </tbody> +</table> + +<h2 id="Compatibilidad_con_navegadores">Compatibilidad con navegadores</h2> + +<div class="hidden">La tabla de compatibilidad en esta página se genera a partir de datos estructurados. Si desea contribuir con los datos, consulte <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> y envíenos un <em>pull request</em>.</div> + +<p>{{Compat("api.XMLHttpRequest.timeout")}}</p> diff --git a/files/es/web/api/xmlhttprequest/using_xmlhttprequest/index.html b/files/es/web/api/xmlhttprequest/using_xmlhttprequest/index.html new file mode 100644 index 0000000000..c3d2b48e7f --- /dev/null +++ b/files/es/web/api/xmlhttprequest/using_xmlhttprequest/index.html @@ -0,0 +1,447 @@ +--- +title: Using XMLHttpRequest +slug: Web/API/XMLHttpRequest/Using_XMLHttpRequest +translation_of: Web/API/XMLHttpRequest/Using_XMLHttpRequest +--- +<p>{{APIRef("XMLHttpRequest")}}</p> + +<p><span class="seoSummary">En esta guía le echaremos un vistazo a cómo usar {{domxref("XMLHttpRequest")}} para enviar solicitudes <a href="https://wiki.developer.mozilla.org/en-US/docs/Web/HTTP">HTTP</a> con el objetivo de intercambiar datos entre el sitio web y el servidor.</span> Se incluyen ejemplos, tanto para los casos de uso comunes de <code>XMLHttpRequest</code>, como para los más inusuales.</p> + +<p>Para enviar una solicitud HTTP, cree un objeto <code>XMLHttpRequest</code>, abra una URL y envíe la solicitud. Una vez que la transacción haya sido completada, el objeto contendrá información útil tal como el cuerpo de la respuesta y el estado <a href="/en-US/docs/Web/HTTP/Status">HTTP</a> del resultado.</p> + +<pre class="brush: js">function reqListener () { + console.log(this.responseText); +} + +var oReq = new XMLHttpRequest(); +oReq.addEventListener("load", reqListener); +oReq.open("GET", "http://www.example.org/example.txt"); +oReq.send();</pre> + +<h2 id="Solicitudes_Síncronas_y_Asíncronas">Solicitudes Síncronas y Asíncronas</h2> + +<p><code>XMLHttpRequest</code> soporta tanto comunicaciones síncronas como asíncronas.</p> + +<div class="note"><strong>Nota:</strong> No deberias usar <code>XMLHttpRequests</code> síncronas porque, dada la naturaleza inherentemente asíncrona del intercambio de datos en las redes, hay multiples formas en que la memoria y eventos se puedan perder usando solicitudes síncronas.</div> + +<p>En versiones de Firefox anteriores a Firefox 3, (solicitudes) <code>XMLHttpRequest</code> síncronas bloqueaban la interfaz de usuario. Con tal de permitirle al usuario terminar solicitudes congeladas, Firefox 3 ya no lo hace.</p> + +<h3 id="Ejemplo_Solicitud_síncrona">Ejemplo: Solicitud síncrona</h3> + +<p>Este ejemplo demuestra como hacer una solicitud síncrona.</p> + +<pre class="script deki-transform">var req = new XMLHttpRequest(); +req.open('GET', 'http://www.mozilla.org/', false); +req.send(null); +if (req.status == 200) + dump(req.responseText);</pre> + +<p>En la línea 1 se instancia un objeto <code>XMLHttpRequest</code>. Después en la línea 2 se abre una nueva solicitud, especificando que una solicitud <code>GET</code> se utilizará para extraer la pagina de inicio de Mozilla.org, y que la operación no debe ser asíncrona.</p> + +<p>En la línea 3 se envía la solicitud. El parámetro <code>null</code> indica que la solicitud <code>GET</code> no necesita contenido en el cuerpo.</p> + +<p>En la línea 4 se verifica el código de estatus después de que la transacción se completa. Si el resultado es 200 -- El código HTTP para resultado "OK"-- el contenido de texto del documento se escribe en la consola.</p> + +<h3 id="Ejemplo_Solicitudes_síncronas_no-HTTP">Ejemplo: Solicitudes síncronas no-HTTP</h3> + +<p>A pesar de su nombre, <code>XMLHttpRequest</code> se puede usar para hacer solicitudes que no sean de HTTP. Este ejemplo muestra como usarlo para extraer un archivo del sistemas de archivos local.</p> + +<pre class="script">var req = new XMLHttpRequest(); +req.open('GET', '<a class="linkification-ext" title="Linkification: file:///home/user/file.json">file:///home/user/file.json</a>', false); +req.send(null); +if(req.status == 0) + dump(req.responseText);</pre> + +<p>La clave aqui es notar que el estado del resultado se compara con 0 en lugar de 200. Esto es porque los esquemas <code>file</code> y <code>ftp</code> no usan los codigos de resultado de HTTP.</p> + +<h3 id="Ejemplo_Solicitudes_asíncronas">Ejemplo: Solicitudes asíncronas</h3> + +<p>Si usas <code>XMLHttpRequest</code> desde una extensión, deberias usarla asíncronamente. En este caso, recibiras una llamada de regreso cuando se hallan recibido los datos, lo cual permite al navegador continuar trabajando con normalidad mientras se maneja tu solicitud.</p> + +<pre class="script">var req = new XMLHttpRequest(); +req.open('GET', 'http://www.mozilla.org/', true); +req.onreadystatechange = function (aEvt) { + if (req.readyState == 4) { + if(req.status == 200) + dump(req.responseText); + else + dump("Error loading page\n"); + } +}; +req.send(null); </pre> + +<p>La linea 2 especifica <code>true</code> en su tercer parametro indicando que la solicitud debe manejarse asíncronamente.</p> + +<p>Line 3 crea un objeto función para manejar eventos y lo asigna al atributo de la solicitud <code>onreadystatechange</code>. Este manejador observa el <code>readyState</code> de la solicitud verificando si la transacción se ha completado en la linea 4, si así es, y el estatus HTTP es 200, imprime el contenido recibido. Si ocurrió un error, se muestra un mensaje de error.</p> + +<p>La linea 11 de hecho inicia la solicitud. La función onreadystatechange es llamada siempre que el estado de una solicitud cambia.</p> + +<h2 id="Analizando_y_Manipulando_el_Texto_de_Respuesta_HTML">Analizando y Manipulando el Texto de Respuesta HTML</h2> + +<p>Si usas <code>XMLHttpRequest para obtener el contenido de una página</code> HTML remota, el <code>responseText </code>(texto de la respuesta) sera una cadena que contenga una "sopa" de etiquetas HTML, lo que puede ser dificil de analizar y manipular. Existen tres maneras principales de analizar estas cadenas HTML</p> + +<ol> + <li><a href="/en/Code_snippets/HTML_to_DOM#Safely_parsing_simple_HTML.c2.a0to_DOM" title="https://developer.mozilla.org/en/Code_snippets/HTML_to_DOM#Safely_parsing_simple_HTML.c2.a0to_DOM">Analizar con nsIScriptableUnescapeHTML </a>repidamente convertira la cadena HTML en DOM, al mismo tiempo que tira javascript y otros elementos avanzados, incluyendo la etiqueta <code><head></code> de la página.</li> + <li><a href="/es/Referencia_de_JavaScript_1.5/Objetos_globales/RegExp" title="es/Referencia de JavaScript 1.5/Objetos globales/RegExp">RegExp </a>se puede usar si de antemano conoces el HTML que vendra en el <code>responseText</code>. Quizas quieras remover los saltos de linea, si usas RegExp para escanear considerandolos. Sin embargo, este metodo es un "ultimo recurso" ya que si el HTML cambia ligeramente, posiblemente fallara.</li> + <li><a href="/en/Code_snippets/HTML_to_DOM#Using_a_hidden_iframe_element_to_parse_HTML_to_a_window%27s_DOM" title="https://developer.mozilla.org/en/Code_snippets/HTML_to_DOM#Using_a_hidden_iframe_element_to_parse_HTML_to_a_window's_DOM">Usar un hidden chrome o un content-level iframe</a> para cargar toda la pagina también se puede hacer para manipularla luego como DOM, sin embargo existen <a href="/En/Displaying_web_content_in_an_extension_without_security_issues" title="En/Displaying_web_content_in_an_extension_without_security_issues">riesgos de seguridad al dar a código remoto este nivel de acceso privilegiado</a>, que puede causar <a class="link-https" href="https://addons.mozilla.org/en-US/developers/docs/policies/reviews" title="https://addons.mozilla.org/en-US/developers/docs/policies/reviews">problemas </a>en la revisión de tu addon. Por ejemplo, si una pagina ejecuta el comando común "<code>document.location = redirecttothispage.html</code>" para cargar, esto se interpretara como cambiar la locación del navegador (<code>document.location</code> en una extensión) en contraposición a la locación de una página web (<code>content.document.location</code> en una extensión), y en consecuecia destruir todos los componentes del navegador. Alternativamente, y de algun modo mas seguro, una cadena <code>responseText adquirida mediante</code> <code>XMLHttpRequest se puede analizar con</code> RegExp para remover problemas de javascript, luego cargada en un iframe oculto previamente establecido:</li> +</ol> + +<pre>document.getElementById('hiddenXULiframe').contentWindow.document.body.innerHTML = req.responseText +</pre> + +<h2 id="Using_FormData_objects">Using FormData objects</h2> + +<p>{{ gecko_minversion_header("2") }}</p> + +<p>The <a href="/en/XMLHttpRequest/FormData" title="en/XMLHttpRequest/FormData"><code>FormData</code></a> object lets you compile a set of key/value pairs to send using <code>XMLHttpRequest</code>. It's 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".</p> + +<h3 id="Creating_a_FormData_object_from_scratch">Creating a FormData object from scratch</h3> + +<p>You can build a <code>FormData</code> object yourself, instantiating it then appending fields to it by calling its <a href="/en/XMLHttpRequest/FormData#append()" title="en/XMLHttpRequest/FormData#append()"><code>append()</code></a> method, like this:</p> + +<pre class="deki-transform">var formData = new FormData(); + +formData.append("username", "Groucho"); +formData.append("accountnum", 123456); +formData.append("afile", fileInputElement.files[0]); + +var xhr = new XMLHttpRequest(); +xhr.open("POST", "http://foo.com/submitform.php"); +xhr.send(formData); +</pre> + +<p>This example builds a <code>FormData</code> object containing values for fields named "username" and "accountnum", then uses the <code>XMLHttpRequest</code> method <a href="/en/XMLHttpRequest#send()" title="en/XMLHttpRequest#send()"><code>send()</code></a> to send the form's data.</p> + +<h3 id="Retrieving_a_FormData_object_from_an_HTML_form">Retrieving a FormData object from an HTML form</h3> + +<p>To construct a <code>FormData</code> object that contains the data from an existing {{ HTMLElement("form") }}, specify that form element when creating the <code>FormData</code> object:</p> + +<pre>newFormData = new FormData(someFormElement); +</pre> + +<p>For example:</p> + +<pre class="deki-transform">var formElement = document.getElementById("myFormElement"); +var xhr = new XMLHttpRequest(); +xhr.open("POST", "submitform.php"); +xhr.send(new FormData(formElement)); +</pre> + +<p>You can also add data to the <code>FormData</code> object between retrieving it from a form and sending it, like this:</p> + +<pre class="deki-transform">var formElement = document.getElementById("myFormElement"); +formData = new FormData(formElement); +formData.append("serialnumber", serialNumber++); +xhr.send(formData); +</pre> + +<p>This lets you augment the form's data before sending it along, to include additional information that's not necessarily user editable on the form.</p> + +<h3 id="Sending_files_using_a_FormData_object">Sending files using a FormData object</h3> + +<p>You can also send files using <code>FormData</code>. Simply include an {{ HTMLElement("input") }} element of type "file":</p> + +<pre class="deki-transform"><form enctype="multipart/form-data" method="post" name="fileinfo" id="fileinfo"> + <label>Your email address:</label> + <input type="email" autocomplete="on" autofocus name="userid" placeholder="email" required size="32" maxlength="64"><br /> + <label>Custom file ID:</label> + <input type="text" name="fileid" size="12" maxlength="32"><br /> + <label>File to stash:</label> + <input type="file" name="file" required> +</form> +<div id="output"></div> +<a href="javascript:sendForm()">Stash the file!</a> +</pre> + +<p>Then you can send it using code like the following:</p> + +<pre class="deki-transform">function sendForm() { + var output = document.getElementById("output"); + var data = new FormData(document.getElementById("fileinfo")); + + data.append("CustomField", "This is some extra data"); + + var xhr = new XMLHttpRequest(); + xhr.open("POST", "stash.pl", false) + xhr.send(data); + if (xhr.status == 200) { + output.innerHTML += "Uploaded!<br />"; + } else { + output.innerHTML += "Error " + xhr.status + " occurred uploading your file.<br />"; + } +} +</pre> + +<p>Note that this example is directing the output to a Perl CGI script running on the server, and handles HTTP errors, although not prettily.</p> + +<h2 id="Handling_binary_data">Handling binary data</h2> + +<p>Although <code>XMLHttpRequest</code> is most commonly used to send and receive textual data, it can be used to send and receive binary content.</p> + +<h3 id="Receiving_binary_data">Receiving binary data</h3> + +<p>The <code>load_binary_resource()</code> function shown below loads binary data from the specified URL, returning it to the caller.</p> + +<pre class="script">function load_binary_resource(url) { + var req = new XMLHttpRequest(); + req.open('GET', url, false); + //XHR binary charset opt by Marcus Granado 2006 [http://mgran.blogspot.com] + req.overrideMimeType('text/plain; charset=x-user-defined'); + req.send(null); + if (req.status != 200) return ''; + return req.responseText; +} +</pre> + +<p>The magic happens in line 5, which overrides the MIME type, forcing Firefox to treat it as plain text, using a user-defined character set. This tells Firefox not to parse it, and to let the bytes pass through unprocessed.</p> + +<pre class="script">var filestream = load_binary_resource(url); +var abyte = filestream.charCodeAt(x) & 0xff; // throw away high-order byte (f7)</pre> + +<p>The example above fetches the byte at offset <code>x</code> within the loaded binary data. The valid range for <code>x</code> is from 0 to <code>filestream.length-1</code>.</p> + +<p>See <a class="external" href="http://mgran.blogspot.com/2006/08/downloading-binary-streams-with.html">downloading binary streams with XMLHttpRequest</a> for a detailed explanation. See also <a href="/en/Code_snippets/Downloading_Files" title="en/Code_snippets/Downloading_Files">downloading files</a>.</p> + +<h3 id="Receiving_binary_data_using_JavaScript_typed_arrays">Receiving binary data using JavaScript typed arrays</h3> + +<p>{{ gecko_minversion_header("2.0") }}</p> + +<p>Gecko 2.0 {{ geckoRelease("2.0") }} adds a Gecko-specific <code>mozResponseArrayBuffer</code> property to the XMLHttpRequest object, which contains a <a href="/en/JavaScript_typed_arrays" title="en/JavaScript typed arrays">JavaScript typed array</a> representing the raw binary contents of the response from the server. This lets you read the binary data without taking any special steps.</p> + +<pre class="deki-transform">var xhr = new XMLHttpRequest(); +xhr.open("GET", "binary_file", false); +xhr.send(null); + +buffer = xhr.mozResponseArrayBuffer; +if (buffer) { + var byteArray = new UInt8Array(buffer); + for (var i=0; i<byteArray.byteLength; i++) { + // do something with each byte in the array + } +} +</pre> + +<p>This example reads a binary file and interprets it as 8-bit unsigned integers.</p> + +<h3 id="Sending_binary_data">Sending binary data</h3> + +<p>This example transmits binary content asynchronously, using the <code>POST</code> method.</p> + +<pre class="script">var req = new XMLHttpRequest(); +req.open("POST", url, true); +// set headers and mime-type appropriately +req.setRequestHeader("Content-Length", 741); +req.sendAsBinary(aBody);</pre> + +<p>Line 4 sets the Content-Length header to 741, indicating that the data is 741 bytes long. Obviously you need to change this value based on the actual size of the data being sent.</p> + +<p>Line 5 uses the <code>sendAsBinary()</code> method to initiate the request.</p> + +<p>You can also send binary content by passing an instance of the {{ interface("nsIFileInputStream") }} to <a class="internal" href="/en/XMLHttpRequest#send()" title="/En/XMLHttpRequest#send()"><code>send()</code></a>. In that case, you don't have to set the Content-Length header yourself, as the information is fetched from the stream automatically:</p> + +<pre class="script">// Make a stream from a file. +var stream = Components.classes["@mozilla.org/network/file-input-stream;1"] + .createInstance(Components.interfaces.nsIFileInputStream); +stream.init(file, 0x04 | 0x08, 0644, 0x04); // file is an nsIFile instance + +// Try to determine the MIME type of the file +var mimeType = "text/plain"; +try { + var mimeService = Components.classes["@mozilla.org/mime;1"] + .getService(Components.interfaces.nsIMIMEService); + mimeType = mimeService.getTypeFromFile(file); // file is an nsIFile instance +} +catch(e) { /* eat it; just use text/plain */ } + +// Send +var req = Components.classes["@mozilla.org/xmlextras/xmlhttprequest;1"] + .createInstance(Components.interfaces.nsIXMLHttpRequest); +req.open('PUT', url, false); /* synchronous! */ +req.setRequestHeader('Content-Type', mimeType); +req.send(stream); +</pre> + +<h2 id="Monitoring_progress">Monitoring progress</h2> + +<p><code>XMLHttpRequest</code> provides the ability to listen to various events that can occur while the request is being processed. This includes periodic progress notifications, error notifications, and so forth.</p> + +<h3 id="In_Firefox_3.5_and_later">In Firefox 3.5 and later</h3> + +<p>Firefox 3.5 adds support for DOM progress event monitoring of <code>XMLHttpRequest</code> transfers; this follows the Web API <a class="external" 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>.</p> + +<pre class="script">var req = new XMLHttpRequest(); + +req.addEventListener("progress", updateProgress, false); +req.addEventListener("load", transferComplete, false); +req.addEventListener("error", transferFailed, false); +req.addEventListener("abort", transferCanceled, false); + +req.open(); + +... + +// progress on transfers from the server to the client (downloads) +function updateProgress(evt) { + if (evt.lengthComputable) { + var percentComplete = evt.loaded / evt.total; + ... + } else { + // Unable to compute progress information since the total size is unknown + } +} + +function transferComplete(evt) { + alert("The transfer is complete."); +} + +function transferFailed(evt) { + alert("An error occurred while transferring the file."); +} + +function transferCanceled(evt) { + alert("The transfer has been canceled by the user."); +} +</pre> + +<p>Lines 3-6 add event listeners for the various events that are sent while performing a data transfer using <code>XMLHttpRequest</code>. See {{ interface("nsIDOMProgressEvent") }} and {{ interface("nsIXMLHttpRequestEventTarget") }} for details on these events.</p> + +<div class="note">Note: You need to add the event listeners before calling <code>open()</code> on the request. Otherwise the progress events will not fire.</div> + +<p>The progress event handler, specified by the <code>updateProgress()</code> function in this example, receives the total number of bytes to transfer as well as the number of bytes transferred so far in the event's <code>total</code> and <code>loaded</code> fields. However, if the <code>lengthComputable</code> field is false, the total length is not known and will be zero.</p> + +<p>Progress events exist for both download and upload transfers. 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="script">var req = new XMLHttpRequest(); + +req.upload.addEventListener("progress", updateProgress, false); +req.upload.addEventListener("load", transferComplete, false); +req.upload.addEventListener("error", transferFailed, false); +req.upload.addEventListener("abort", transferCanceled, false); + +req.open();</pre> + +<div class="note"><strong>Note:</strong> Progress events are not available for the <code>file:</code> protocol.</div> + +<h3 id="In_Firefox_3_and_earlier">In Firefox 3 and earlier</h3> + +<p>If, for example, you wish to provide progress information to the user while the document is being received, you can use code like this:</p> + +<pre class="script">function onProgress(e) { + var percentComplete = (e.position / e.totalSize)*100; + // ... +} + +function onError(e) { + alert("Error " + e.target.status + " occurred while receiving the document."); +} + +function onLoad(e) { + // ... +} +// ... +var req = new XMLHttpRequest(); +req.onprogress = onProgress; // or req.addEventListener("progress", onProgress, false); +req.open("GET", url, true); +req.onload = onLoad; // or req.addEventListener("load", onLoad, false); +req.onerror = onError; // or req.addEventListener("error", onError, false); +req.send(null); +</pre> + +<p>The <code>onprogress</code> event's attributes, <code>position</code> and <code>totalSize</code>, indicate the current number of bytes received and the total number of bytes expected, respectively.</p> + +<p>All of these events have their <code>target</code> attribute set to the <code>XMLHttpRequest</code> they correspond to.</p> + +<div class="note"><strong>Note:</strong> <a href="/en/Firefox_3_for_developers" title="en/Firefox_3_for_developers">Firefox 3</a> properly ensures that the values of the <code>target</code>, <code>currentTarget</code>, and <code>this</code> fields of the event object are set to reference the correct objects when calling event handlers for XML documents represented by <code>XMLDocument</code>. See {{ Bug(198595) }} for details.</div> + +<h2 id="Cross-site_XMLHttpRequest">Cross-site XMLHttpRequest</h2> + +<div class="geckoVersionNote"> +<p>Este artículo cubre características introducidas en Firefox 3.5.</p> +</div> + +<p>Firefox 3.5 supports cross-site requests by implementing the web applications working group's <a class="internal" href="/En/HTTP_access_control" title="en/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>Normally, <code>XMLHttpRequest</code> tries to retrieve content from the cache, if it's available. To bypass this, do the following:</p> + +<pre class="script">var req = new XMLHttpRequest(); +req.open('GET', url, false); +<strong>req.channel.loadFlags |= Components.interfaces.nsIRequest.LOAD_BYPASS_CACHE;</strong> +req.send(null);</pre> + +<div class="note"><strong>Note:</strong> This approach will only work in Gecko-based software, as the <code>channel</code> attribute is Gecko-specific.</div> + +<p>An alternate, cross-browser compatible approach is to append a timestamp to the URL, being sure to include a "?" or "&" as appropriate. For example:</p> + +<pre>http://foo.com/bar.html</pre> + +<p>becomes</p> + +<pre>http://foo.com/bar.html?12345</pre> + +<p>and</p> + +<pre>http://foo.com/bar.html?foobar=baz</pre> + +<p>becomes</p> + +<pre>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="script">var req = new XMLHttpRequest(); +req.open("GET", url += (url.match(/\?/) == null ? "?" : "&") + (new Date()).getTime(), false); +req.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> + +<h2 id="Downloading_JSON_and_JavaScript_from_extensions">Downloading JSON and JavaScript from extensions</h2> + +<p>For security reasons, extensions should never use <code><a href="/en/JavaScript/Reference/Global_Objects/eval" title="en/Core_JavaScript_1.5_Reference/Global_Functions/eval">eval()</a></code> to parse JSON or JavaScript code downloaded from the web. See <a href="/en/Downloading_JSON_and_JavaScript_in_extensions" title="en/Downloading_JSON_and_JavaScript_in_extensions">Downloading JSON and JavaScript in extensions</a> for details.</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/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. You'll need to create and use it using a different syntax.</p> + +<p>Instead of this:</p> + +<pre class="script">var req = new XMLHttpRequest(); +req.onprogress = onProgress; +req.onload = onLoad; +req.onerror = onError; +req.open("GET", url, true); +req.send(null); +</pre> + +<p>Do this:</p> + +<pre class="script">var req = Components.classes["@mozilla.org/xmlextras/xmlhttprequest;1"] + .createInstance(Components.interfaces.nsIXMLHttpRequest); +req.onprogress = onProgress; +req.onload = onLoad; +req.onerror = onError; +req.open("GET", url, true); +req.send(null); +</pre> + +<p>For C++ code you would need to <code>QueryInterface</code> the component to an <code>nsIEventTarget</code> in order to add event listeners, but chances are in C++ using a channel directly would be better.</p> + +<h2 id="See_also">See also</h2> + +<ol> + <li><a href="/en/AJAX/Getting_Started" title="en/AJAX/Getting_Started">MDC AJAX introduction</a></li> + <li><a class="internal" href="/En/HTTP_access_control" title="En/HTTP access control">HTTP access control</a></li> + <li><a class="internal" href="/En/How_to_check_the_security_state_of_an_XMLHTTPRequest_over_SSL" title="En/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 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://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> + <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.w3.org/TR/XMLHttpRequest/">The XMLHttpRequest Object: W3C Working Draft</a></li> + <li><a class="external" 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> + <li><a class="external" href="http://www.bluishcoder.co.nz/2009/06/05/reading-ogg-files-with-javascript.html" title="http://www.bluishcoder.co.nz/2009/06/05/reading-ogg-files-with-javascript.html">Reading Ogg files with JavaScript (Chris Double)</a></li> +</ol> |