Usando geolocation - APIs da Web

Usando geolocation
==================

A **API geolocation** permite que o usuário forneça sua localização a aplicativos web se ele desejar. Por questões de privacidade, o usuário é perguntado se permite fornecer informações de localização.

O objeto geolocation
--------------------

O aplicativo de geolocalização é utilizado através de um objeto filho chamado `geolocation` localizado dentro do objeto `navigator`. Se o objeto existe, os serviços de geolocalização estarão disponíveis. Você pode adicionalmente testar a presença da geolocalização:

```js
if ("geolocation" in navigator) {
  /\* geolocation is available \*/
} else {
  alert(
    "I'm sorry, but geolocation services are not supported by your browser.",
  );
}
```

Ao iniciar no Gecko 1.9.2 (Firefox 3.6), add-ons podem obter o objeto de geolocalização obtendo a referência para o serviço de geolocaliazação como se ve a seguir:

```js
var geolocation = Components.classes["@mozilla.org/geolocation;1"].getService(
  Components.interfaces.nsIDOMGeoGeolocation,
);
```

### Obtendo a posição atual

Para obter a localização atual do usuário, você pode utiliza o método `getCurrentPosition()`. Isto inicia uma requisição assíncrona para identificar a posição do usuário, e consulta o hardware de localização para conseguir informações atualizadas. Quando a posição é determinada, uma rotina específica de retorno é executada. Você pode opcionalmente gerar uma segunda rotina de retorno se um erro ocorrer. Um terceiro, e opcional, parâmetro é a interface "opções" onde você pode configurar o tempo máximo da posição recebida e o tempo a se esperar por uma solicitação.

Use `getCurrentPosition()` se você deseja uma única posição rapidamente, independente da precisão. Dispositivos com GPS, por exemplo, podem levar um minuto ou mais para conseguir a localização, e portanto dados menos precisos (localização do IP location ou rede wifi) podem retornar do método `getCurrentPosition()`.

```js
navigator.geolocation.getCurrentPosition(function (position) {
  do\_something(position.coords.latitude, position.coords.longitude);
});
```

O exemplo acima irá fazer a função the `do_something()` executar quando a localização for obtida.

### Verificando a posição atual

Se os dados de posição mudam (sejam pelo movimento do dispositivo ou se uma informação mais precisa for recebida), se pode configurar um retorno que é feito com esta informação de posição atual. Isto é feito usando a função `watchPosition()`, a qual tem os mesmos parâmetros de entrada da função `getCurrentPosition()`. Seu retorno é chamada múltiplas vezes, permitindo que o navegador ou atualize sua posição enquanto você se move, ou forneça uma localização mais precisa enquanto diferentes técnicas são usadas para localizar sua posição. O erro do retorno, o qual é opcional assim como no `getCurrentPosition()`, é chamado uma única vez, se nenhum resultado válido retornar.

O `watchPosition()` pode ser usado sem que não haja a chamada inicial de `getCurrentPosition()`.

```js
var watchID = navigator.geolocation.watchPosition(function (position) {
  do\_something(position.coords.latitude, position.coords.longitude);
});
```

O método `watchPosition()` retorna um número de ID que pode ser usado para identificar a `posição` solicitada; você pode usar esse valor em conjunto com o método `clearWatch()`, parando a localização do usuário.
```

navigator.geolocation.clearWatch(watchID);
```

`watchPosition()`retorna um callback sucesso e erro (como `getCurrentPosition`) e um objeto `positionObjects`, que pode ter três propriedades:

* `enableHighAccuracy` – Um booleano que indica ao dispositivo que você deseja obter leituras mais precisas (este parâmetro pode ou não pode fazer a diferença, dependendo do seu hardware)
* `maximumAge` – Idade máxima (em milissegundos) da leitura (opção adequada, pois o dispositivo pode armazenar em cache leituras para poupar energia e / ou largura de banda)
* `timeout` – O tempo máximo (em milissegundos) que está preparado para permitir que o dispositivo para tentar obter uma Geo Location

Segue uma chamada para watchPosition:
```

var wpid = navigator.geolocation.watchPosition(geo_success, geo_error, {enableHighAccuracy:true, maximumAge:30000, timeout:27000});
```

Exemplo de watchPosition em uso: thedotproduct.org/posts/a-simple-example-of-navigatorgeolocationwatchposition

Imprimindo uma posição
----------------------

A localização do usuário é impressa usando o objeto Position, que tem os seguintes campos:

timestamp

Momento em que a leitura foi feita, como `DOMTimeStamp`.

coords

Objecto `nsIDOMGeoPositionCoords` indicando a localização.

address

`nsIDOMGeoPositionAddress` objeto especificando o endereço correspondente, se disponível.

Manipulação de erros
--------------------

Retornando o callback de erro, se fornecido, chamar `getCurrentPosition()` e `watchPosition()`, tem a seguinte assinatura:
```

function errorCallback(PositionError error);
```

O `PositionError` tem a seguinte estrutura de campos:

code

Um código de erro numérico dos seguintes procedimentos:

*`UNKNOWN_ERROR`* (valor numérico 0)

O processo de aquisição de localização falhou devido a um erro de qualquer outro código nesta interface.

*`PERMISSION_DENIED`* (valor numérico 1)

O processo de aquisição da localização falhou porque a origem aplicativo não tem permissão para usar a API de Geolocalização.

*`POSITION_UNAVAILABLE`* (valor numérico 2)

A posição do dispositivo não pôde ser determinada. Um ou mais provedores de localização utilizados no processo de aquisição local gerou um erro interno que falou o processo completamente.

*`TIMEOUT`* (numeric value 3)

O comprimento máximo de tempo especificado.

message

Uma mensagem de erro legível para uso em registros e depuração, mas não para exibir para o usuário.

Compatibilidade com navegadores
-------------------------------

| Navegador | Suporte Básico | Geolocation Level 2 |
| --- | --- | --- |
| Internet Explorer | IE9 RC | --- |
| Firefox (Gecko) | **3.5** (1.9.1) | --- |
| Opera | **10.60** | --- |
| Safari | Chrome | WebKit | 5 | 5 | 533 | --- |

Solicitando permissão
---------------------

Qualquer add-on hospedado em addons.mozilla.org, que faz uso de dados de geolocalização, deve solicitar antes uma permissão. A função a seguir vai solicitar a permissão de um modo semelhante ao prompt. A resposta do usuário será salva no parâmetro `pref`. A função fornecida no parâmetro de `callback` será chamado com um valor booleano que indica a resposta do usuário. Se for `true`, o add-on poderá retornar dados de geolocalização.

```js
function prompt(window, pref, message, callback) {
  let branch = Components.classes[
    "@mozilla.org/preferences-service;1"
  ].getService(Components.interfaces.nsIPrefBranch);

  if (branch.getPrefType(pref) === branch.PREF\_STRING) {
    switch (branch.getCharPref(pref)) {
      case "always":
        return callback(true);
      case "never":
        return callback(false);
    }
  }

  let done = false;

  function remember(value, result) {
    return function () {
      done = true;
      branch.setCharPref(pref, value);
      callback(result);
    };
  }

  let self = window.PopupNotifications.show(
    window.gBrowser.selectedBrowser,
    "geolocation",
    message,
    "geo-notification-icon",
    {
      label: "Share Location",
      accessKey: "S",
      callback: function (notification) {
        done = true;
        callback(true);
      },
    },
    [
      {
        label: "Always Share",
        accessKey: "A",
        callback: remember("always", true),
      },
      {
        label: "Never Share",
        accessKey: "N",
        callback: remember("never", false),
      },
    ],
    {
      eventCallback: function (event) {
        if (event === "dismissed") {
          if (!done) callback(false);
          done = true;
          window.PopupNotifications.remove(self);
        }
      },
      persistWhileVisible: true,
    },
  );
}

prompt(
  window,
  "extensions.foo-addon.allowGeolocation",
  "Foo Add-on wants to know your location.",
  function callback(allowed) {
    alert(allowed);
  },
);
```

Veja também
-----------

* `nsIGeolocationProvider`
* `nsIDOMGeolocation`
* `nsIDOMGeoPosition`
* `nsIDOMGeoPositionCallback`
* `nsIDOMGeoPositionError`
* `nsIDOMGeoPositionErrorCallback`
* `nsIDOMGeoPositionOptions`
* `nsIDOMNavigatorGeolocation`
* Geolocation API on w3.org
* Demos about the Geolocation API


MouseEvent - APIs da Web

MouseEvent
==========

A interface **`MouseEvent`** representa eventos que ocorrem devido à interação do usuário com um dispositivo apontador (como um mouse). Eventos comuns usando esta interface incluem `click`, `dblclick` (en-US), `mouseup` (en-US), `mousedown`.

**`MouseEvent`** deriva de `UIEvent` (en-US), que por sua vez deriva de `Event`. Embora o método `MouseEvent.initMouseEvent()` (en-US) seja mantido para compatibilidade com versões anteriores, a criação de um objeto **`MouseEvent`** deve ser feita usando o construtor `MouseEvent()`.

Vários eventos mais específicos derivam de **`MouseEvent`** como: `WheelEvent` (en-US) e `DragEvent` (en-US).

Event

UIEvent

(en-US)

MouseEventConstrutor
----------

**`MouseEvent()` (en-US)**

Cria um objeto **`MouseEvent`**.

Propriedades
------------

*Essa interface também herda propriedades de seus pais, `UIEvent` (en-US) e `Event`.*

**`MouseEvent.altKey` (en-US)** Read only

Retorna `true`se a tecla

`alt`

estava pressionada quando o evento do mouse foi disparado.

`MouseEvent.button` (en-US) Read only

O número do botão que foi pressionado (se aplicável) quando o evento do mouse foi disparado.

`MouseEvent.buttons` (en-US)Read only

Os botões sendo pressionados (se houver) quando o evento do mouse foi disparado.

`MouseEvent.clientX` *Read only*

A coordenada X do ponteiro do mouse em coordenadas locais (conteúdo **DOM**).

`MouseEvent.clientY`Read only

A coordenada Y do ponteiro do mouse em coordenadas locais (conteúdo **DOM**).

`MouseEvent.ctrlKey` (en-US) Read only

Retorna `true` se a tecla

`control`

estava pressionada quando o evento do mouse foi disparado.

`MouseEvent.metaKey` (en-US) Read only

Retorna `true` se a tecla

`meta`

estava pressionada quando o evento do mouse foi disparado.

MouseEvent.movementX (en-US)Read only

A coordenada X do ponteiro do mouse em relação à posição do último evento `mousemove` (en-US) .

`MouseEvent.movementY` (en-US) Read only

A coordenada Y do ponteiro do mouse em relação à posição do último evento mousemove (en-US).

`MouseEvent.offsetX` (en-US) Read only

A coordenada X do ponteiro do mouse em relação à posição da borda de preenchimento do nó de destino.

`MouseEvent.offsetY` (en-US) Read only

A coordenada Y do ponteiro do mouse em relação à posição da borda de preenchimento do nó de destino.

`MouseEvent.pageX` (en-US) Read only

A coordenada X do ponteiro do mouse em relação a todo o documento.

`MouseEvent.pageY` (en-US) Read only

A coordenada Y do ponteiro do mouse em relação a todo o documento.

`MouseEvent.region` (en-US) Read only

Retorna o id da região afetada pelo evento. Se nenhuma região atingida for afetada, **`null`** será retornado.

`MouseEvent.relatedTarget` (en-US)Read only

O destino secundário do evento, se houver.

MouseEvent.screenX (en-US)Read only

A coordenada X do ponteiro do mouse em coordenadas globais (tela).

`MouseEvent.screenY` (en-US) Read only

A coordenada Y do ponteiro do mouse em coordenadas globais (tela).

MouseEvent.shiftKey (en-US) Read only

Retorna `true` se a tecla

`shift`

estava pressionada quando o evento do mouse foi disparado.

MouseEvent.which (en-US) Read only

O botão sendo pressionado quando o evento do mouse foi disparado.

`MouseEvent.mozPressure` Read only

A quantidade de pressão aplicada a um dispositivo de toque ou tablet ao gerar o evento; este valor varia entre `0.0` (pressão mínima) e `1.0` (pressão máxima).

`MouseEvent.mozInputSource` (en-US) Read only

O tipo de dispositivo que gerou o evento (uma das constantes `MOZ_SOURCE_*` listadas abaixo). Isso permite, por exemplo, determinar se um evento de mouse foi gerado por um mouse real ou por um evento de toque (o que pode afetar o grau de precisão com que você interpreta as coordenadas associadas ao evento).

`MouseEvent.webkitForce` (en-US) Read only

A quantidade de pressão aplicada ao clicar

MouseEvent.xRead only

Alias para `MouseEvent.clientX`.

`MouseEvent.y` Read only

Alias para MouseEvent.clientY

Constantes
----------

`MouseEvent.WEBKIT_FORCE_AT_MOUSE_DOWN` (en-US) Read only

Força mínima necessária para um clique normal.

`MouseEvent.WEBKIT_FORCE_AT_FORCE_MOUSE_DOWN` (en-US) Read only

Força mínima necessária para um clique de força

Método
------

*Essa interface também herda métodos de seus pais, `UIEvent` (en-US) e `Event`.*

`MouseEvent.getModifierState()` (en-US)

Retorna o estado tual da tecla modificadora especificada. Consulte `KeyboardEvent.getModifierState` (en-US)`()` (en-US) para obter detalhes.

`MouseEvent.initMouseEvent()` (en-US)

Inicializa o valor de um **`MouseEvent`** criado. Se o evento já foi despachado, este método não faz nada.

Exemplo
-------

Este exemplo demonstra a simulação de um clique (que está gerando programaticamente um evento de clique) em uma caixa de seleção usando métodos **DOM**.

```js
function simulateClick() {
  var evt = new MouseEvent("click", {
    bubbles: true,
    cancelable: true,
    view: window,
  });
  var cb = document.getElementById("checkbox"); //element to click on
  var canceled = !cb.dispatchEvent(evt);
  if (canceled) {
    // A handler called preventDefault
    alert("canceled");
  } else {
    // None of the handlers called preventDefault
    alert("not canceled");
  }
}
document.getElementById("button").addEventListener("click", simulateClick);
```

```html
<p>
  <label><input type="checkbox" id="checkbox" /> Checked</label>
</p>
<p><button id="button">Click me</button></p>
```

Clique no botão para ver como funciona a amostra:

Especificações
--------------

| Specification |
| --- |
| UI Events # interface-mouseevent |
| CSSOM View Module # extensions-to-the-mouseevent-interface |
| Pointer Lock 2.0 # extensions-to-the-mouseevent-interface |

Compatibilidade com navegadores
-------------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Veja também
-----------

 Seu pai direto, `UIEvent` (en-US).
 `PointerEvent` (en-US): Para eventos de ponteiro avançados, incluindo multitoque


XMLHttpRequest - APIs da Web

XMLHttpRequest
==============

`XMLHttpRequest` é um objeto que fornece funcionalidade ao cliente para transferir dados entre um cliente e um servidor. Ele fornece uma maneira fácil de recuperar dados de um URL sem ter que fazer uma atualização de página inteira. Isso permite que uma página da Web atualize apenas uma parte do conteúdo sem interromper o que o usuário esteja fazendo. XMLHttpRequest é usado constantemente na programação de AJAX.

`XMLHttpRequest` foi originalmente projetado pela Microsoft e adotado pela Mozilla, Apple e Google. Está sendo padronizado pela WHATWG. Apesar do nome, XMLHttpRequest pode ser usado para recuperar qualquer tipo de dados, e não apenas XML, suportando também, protocolos diferentes de HTTP (incluindo file e ftp ).

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

var myRequest = new XMLHttpRequest();
```

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

Métodos
-------

| `XMLHttpRequest(JSObject objParameters);` |
| --- |
| `void abort();` |
| `DOMString getAllResponseHeaders();` |
| `DOMString? getResponseHeader(DOMString header);` |
| `void open(DOMString method, DOMString url, optional boolean async, optional DOMString? user, optional DOMString? password);` |
| `void overrideMimeType(DOMString mime);` |
| `void send();` `void send(ArrayBuffer data);` `void send(Blob data);` `void send(Document data);` `void send(DOMString? data);` `void send(FormData data);` |
| `void setRequestHeader(DOMString header, DOMString value);` |
| Métodos não-padrão |
| `[noscript] void init(in nsIPrincipal principal, in nsIScriptContext scriptContext, in nsPIDOMWindow ownerWindow);` |
| `[noscript] void openRequest(in AUTF8String method, in AUTF8String url, in boolean async, in AString user, in AString password);` |
| `void sendAsBinary(in DOMString body);` |

Propriedades
------------

| Atributo | Tipo | Descrição |
| --- | --- | --- |
| `onreadystatechange` | `Function?` |
 A função de objeto JavaScript que é chamado sempre que o atributo
 readyState sofre alteração. A função de callback é chamada a partir da
 thread existente na interface de usuário.

**Aviso:** Este não deve ser usado com chamadas síncronas
 e não deve ser utilizado a partir do código nativo.
  |
| `readyState` | `retorna o cabeçalho da requisição.` |

|  |  |  |
| --- | --- | --- |
| Valor | Estado | Descrição |
| `0` | `UNSENT` | `open() não foi chamado ainda.` |
| `1` | `OPENED` | `send() não foi chamado ainda.` |
| `2` | `HEADERS_RECEIVED` | `send() foi chamado, e cabeçalhos e status estão
disponíveis.` |
| `3` | `LOADING` | Download; responseText contém dados parciais. |
| `4` | `DONE` | A operação está concluída. |

 |
| `response` | ArrayBuffer, Document,Blob, DOMString |
 Retorna um objeto JavaScript de tipo
 `ArrayBuffer`, `Blob` ou
 `Document`, de acordo com o que estiver contido
 no `responseType.` Retorna
 `null` se a request não esteja completa ou não obteve
 sucesso.
  |
| `responseText` Somente leitura  | `DOMString` |
 A resposta à *request*, em formato texto, retorna null se a
 solicitação não teve êxito ou que ainda não foi enviada.
  |
| `responseType` | `XMLHttpRequestResponseType` | Pode ser configurado para alterar o tipo de resposta.

|  |  |
| --- | --- |
| Valor | Tipo de dados de `resposta` de propriedade |
| `""` (string vazia) | String (este é o padrão) |
| `"arraybuffer"` | `ArrayBuffer` |
| `"blob"` | `Blob` |
| `"document"` | `Document` |
| `"json"` |
 Objeto JavaScript, analisado a partir de uma seqüência de
 caracteres JSON retornado pelo servidor.
  |
| `"text"` | String |
| `"moz-blob"` |
 Usado pelo Firefox para permitir recuperar dados parciais do
 tipo `Blob`,de eventos de progresso. Isso
 permite que o manipulador de eventos de progresso iniciar o
 processamento de dados enquanto ele ainda está sendo recebido.
  |
| `"moz-chunked-text"` |
 Semelhante ao "text" , mas o *streaming* ainda está
 fluindo. Isto significa que o valor na response , só está
 disponível durante a expedição do "progress" do evento e
 contém apenas os dados recebidos desde a última "progress" do
 evento.

 Quando response é acessado durante um evento "progress", este
 contém uma string com os dados. Caso contrário, retorna null .

Este modo atualmente só funciona no Firefox. |
| `"moz-chunked-arraybuffer"` |
 Semelhante ao `"arraybuffer"`, mas está fluindo.
 Isto significa que o valor na response , só está disponível
 durante a expedição do "progress" do evento e contém apenas os
 dados recebidos desde a última "progress" do evento.

 Quando response é acessado durante um "progress" evento que
 contém uma seqüência com os dados. Caso contrário, retorna
 null .

Este modo atualmente só funciona no Firefox.
. |

**Nota:** Começando com 11,0 Gecko (Firefox 11.0 / 11.0
 Thunderbird / SeaMonkey 2.8), bem como WebKit construir 528, esses
 navegadores não permitem que você use o atributo responseType ao
 executar solicitações síncronas. Tentativas de fazer isso geram uma
 exceção do tipo NS\_ERROR\_DOM\_INVALID\_ACCESS\_ERR. Esta mudança foi
 proposta para padronização junto à W3C.
  |
| `responseXML` Somente leitura  | `Document?` |
 A resposta ao pedido como um DOM
 `Document`
 objeto, ou null se o pedido não foi bem sucedida, ainda não foi
 enviado, ou não pode ser analisado como XML ou HTML. A resposta é
 analisado como se fosse um `text/html` stream. Quando o
 responseType está definido para "document" e que a solicitação tenha
 sido feita de forma assíncrona, a resposta é analisado como se fosse
 um `text/html` stream.

**Nota:** Se o servidor não se aplica o text/xml
 cabeçalho Content-Type, você pode usar overrideMimeType() para forçar
 XMLHttpRequest para analisá-lo como XML de qualquer maneira.
  |
| `status` Somente leitura  | `unsigned short` |
 O status de resposta da requisição. Este é o retorno do codigo da
 requisição HTTP (por exemplo, status é 200 qual a solicitação for
 bem-sucedida).
  |
| `statusText` Somente leitura  | `DOMString` |
 A cadeia de resposta retornado pelo servidor HTTP. Ao contrário do
 status , o que inclui todo o texto da mensagem de resposta (" 200 OK ",
 por exemplo).
  |
| `timeout` | `unsigned long` |
O número de milissegundos de um pedido pode tomar antes de ser
 automaticamente encerrada. Um valor de 0 (que é o padrão) significa
 que não há tempo limite.

**Nota:** Você não pode usar um tempo limite para
 solicitações síncronas com uma janela proprietária.
  |
| `upload` | `XMLHttpRequestUpload` |
 O processo de upload pode ser rastreado através da ação de retorno de um
 evento para upload.
  |
| `withCredentials` | `boolean` |
 Indica se ou não de cross-site Access-Control solicitações devem ser
 feitas usando credenciais, como cookies ou cabeçalhos de autorização.
 O padrão é false .

**Nota:** Esta não afeta as solicitações no mesmo local.

**Nota:** Começando com 11,0 Gecko (Firefox 11.0 / 11.0
 Thunderbird / SeaMonkey 2.8), Gecko não permite que você use os
 atributos withCredentials ao realizar solicitações síncronas. Ao
 tentar fazer isso o sistema gera uma exceção do tipo
 NS\_ERROR\_DOM\_INVALID\_ACCESS\_ERR.
  |

### Propriedades não-padrão

| Attribute | Type | Description |
| --- | --- | --- |
| `channel` Somente leitura  | `nsIChannel` |
 O canal utilizado pelo objecto aquando da execução do pedido. Esta é
 null se o canal não foi criado ainda. No caso de um pedido de múltiplas
 partes, isto é o canal inicial, não as diferentes partes do pedido de
 várias partes.
 **Requer privilégios elevados para o acesso.** |
| `mozAnon` Somente leitura  | `boolean` |
 Se for verdadeiro (true) o pedido será enviado sem cabeçalhos de
 cookies e autenticação.
  |
| `mozSystem` Somente leitura  | `boolean` |
 Se for verdadeiro (true) , a política de mesma origem não será
 aplicada sobre o pedido.
  |
| `mozBackgroundRequest` | `boolean` |
 Indica se o objeto representa uma solicitação de serviço de fundo. Se
 true , nenhum grupo carga está associada com o pedido, e diálogos de
 segurança estão impedidos de ser mostrado para o usuário.
 **Requer privilégios elevados para o acesso.**

 Nos casos em que uma caixa de diálogo de segurança (como a
 autenticação ou uma notificação certificado ruim) normalmente seriam
 mostrados, o pedido simplesmente falhar em seu lugar.

**Nota:** Esta propriedade deve ser definida antes de
 chamar open().
  |
| `mozResponseArrayBuffer`
Somente leitura  | `ArrayBuffer` |
 A resposta ao pedido, como uma matriz de JavaScript digitado. Esta é
 NULL se o pedido não foi bem-sucedida, ou se não foi enviada ainda.
  |
| `multipart` | `boolean` |
**Este Gecko somente recurso foi removido no Firefox / Gecko
22.**
 Por favor Utilize
 Server-Sent Events (en-US),
 Web Sockets
 ou `responseText` de eventos de progresso em seu lugar.

 Indica se ou não a resposta está prevista para ser uma corrente de,
 possivelmente, vários documentos XML. Se definido como true , o tipo
 de conteúdo da resposta inicial deve ser multipart/x-mixed-replace ou
 ocorrerá um erro. Todos os pedidos devem ser assíncrona.

 Isso permite o suporte para servidor push; para cada documento XML que
 está escrito a este pedido, um novo documento XML DOM é criado eo
 onload manipulador é chamado entre os documentos.

**Nota:** Quando este estiver definido, o onload
 manipulador e outros manipuladores de eventos não são repostas após a
 primeira XmlDocument é carregado, eo onload manipulador é chamado após
 cada parte da resposta é recebida.
  |

Construtor
----------

### XMLHttpRequest()

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

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

XMLHttpRequest (
  JSObject objParameters
);
```

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

`objParameters`

Há dois sinalizadores que você pode definir:

`mozAnon`

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

`mozSystem`

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

Métodos
-------

### abort()

Aborta o pedido, se já foi enviada.

### getAllResponseHeaders()
```

DOMString getAllResponseHeaders();
```

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

### getResponseHeader()
```

DOMString? getResponseHeader(DOMString header);
```

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

### open()

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

**Nota:** Chamar esse método uma solicitação já está ativo (aquele para o qual open() ou openRequest() já foi chamado) é o equivalente de chamar abort().
```

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

###### Parameters

`method`

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

`url`

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

`async`

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

`user`

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

`password`

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

### overrideMimeType()

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

void overrideMimeType(DOMString mimetype);
```

### send()

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

**Nota:** Qualquer ouvintes de eventos que pretende definir tem de ser definida antes de chamar send().
```

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

###### Notas

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

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

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

### setRequestHeader()

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

void setRequestHeader(
   DOMString header,
   DOMString value
);
```

###### Parametros

`header`

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

`value`

O valor definido como o corpo do cabeçalho.

### Métodos não-padrão

#### init()

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

**Aviso:** **Nota:** Este método não deve ser chamado a partir do JavaScript.
```

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

##### Parametros

`principal`

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

`scriptContext`

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

`ownerWindow`

A janela associada com o pedido; pode ser `null`.

#### openRequest()

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

#### sendAsBinary()

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

void sendAsBinary(
   in DOMString body
);
```

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

##### Parametros

`body`

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

##### `sendAsBinary()` polyfill

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

```js
/\*\
|\*|
|\*| :: 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); \*/
  };
}
```

**Nota:** É possível construir este polyfill colocar dois tipos de dados como argumento para send() : um `ArrayBuffer` (en-US) (ui8Data.buffer - o código comentado) ou um ArrayBufferView ( ui8Data , que é uma typed array of 8-bit unsigned integers (en-US) – descomentada código). No entanto, no Google Chrome, quando você tenta enviar uma ArrayBuffer , a seguinte mensagem de aviso aparecerá: ArrayBuffer is deprecated in XMLHttpRequest.send(). Use ArrayBufferView instead. ArrayBuffer is deprecated in XMLHttpRequest.send(). Use ArrayBufferView instead.

Notas
-----

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

#### Eventos

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

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

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

Especificações
--------------

| Specification |
| --- |
| XMLHttpRequest Standard # interface-xmlhttprequest |

Compatibilidade com navegadores
-------------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Veja também
-----------

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


RTCDataChannel - APIs da Web

RTCDataChannel
==============

**Experimental:** **Esta é uma tecnologia experimental (en-US)**
Verifique a tabela de compatibilidade entre Navegadores cuidadosamente antes de usar essa funcionalidade em produção.

A interface RTCDataChannel representa um canal de rede que pode ser usado para transferências bidirecionais de dados arbitrários de ponto a ponto. Todo canal de dados está associado a `RTCPeerConnection` (en-US), e cada conexão de pares pode ter até um máximo teórico de 65,534 canais de dados (o limite real pode variar de navegador para navegador).

Para criar um canal de dados e pedir a um ponto remoto para se juntar a você, chame os metodos `RTCPeerConnection` (en-US)'s `createDataChannel()` (en-US). O interlocutor que está sendo convidado a trocar dados recebe um evento `datachannel` (que possui o tipo `RTCDataChannelEvent` (en-US)) para informá-lo de que o canal de dados foi adicionado à conexão.

Exemplo
-------

```js
var pc = new RTCPeerConnection();
var dc = pc.createDataChannel("my channel");

dc.onmessage = function (event) {
  console.log("received: " + event.data);
};

dc.onopen = function () {
  console.log("datachannel open");
};

dc.onclose = function () {
  console.log("datachannel close");
};
```

Especificações
--------------

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # rtcdatachannel |

Compatibilidade com navegadores
-------------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Veja também
-----------

* WebRTC (en-US)


Background Fetch API - APIs da Web

Background Fetch API
====================

Limited availability
--------------------

This feature is not Baseline because it does not work in some of the most widely-used browsers.

* Learn more
* See full compatibility
* Report feedback
**Experimental:** **Esta é uma tecnologia experimental (en-US)**
Verifique a tabela de compatibilidade entre Navegadores cuidadosamente antes de usar essa funcionalidade em produção.

A **Background Fetch API** fornece um método para gerenciar downloads que podem demandar um tempo significativo como filmes, arquivos de áudio e software.

Conceitos e uso
---------------

Quando uma aplicação web exige que o usuário faça downloads de arquivos grandes, geralmente cria-se um problema pois o usuário precisa ficar conectado o tempo todo para que o download termine. Se o usuário perde a conexão, fecha a tab ou sai da página o download para.

A `Background Synchronization API` (en-US) fornece uma maneira para os service workers adiarem o processamento até que um usuário esteja conectado; De toda forma, essa API não pode ser usada para tarefas que podem demorar, como fazer o download de um arquivo grande. A Background sync exige que o service worker esteja ativo até que o fetch seja completado, e para preservar bateria ou para prevenir que tasks indesejadas aconteçam em background o browser irá em algum momento parar a execução da tarefa.

A Background Fetch API resolve esse problema. Ela cria uma maneira do desenvolverdor web pedir ao browser que o mesmo faça chamadas em background, por exemplo quando o usuário clica em um botão para fazer o download de um arquivo de vídeo. O browser irá fazer o download de uma maneira visível ao usuário, mostrando o progresso do download e expondo ao usuário uma maneira de cancelar o mesmo. Quando o download termina, o browser irá abrir o service worker e nesse momento a aplicação pode fazer algo com o resultado se necessário.

A Background Fetch API permitirá que a chamada aconteça mesmo se o usuário inicie o processo estando desconectado. Uma vez que o usuário se conecta novamente o download irá iniciar. Se o usuário volta a ficar desconectado, o processo irá pausar até que a conexão volte.

Interfaces
----------

`BackgroundFetchManager` (en-US)

Um map onde as chaves são background fetch IDS e os valores são `BackgroundFetchRegistration` (en-US) objetos.

`BackgroundFetchRegistration` (en-US)

Representa a Background Fetch.

`BackgroundFetchRecord` (en-US)

Representa uma fetch request e responde isolada.

`BackgroundFetchEvent` (en-US)

O tipo de evento passo para `onbackgroundfetchabort` e `onbackgroundfetchclick`.

`BackgroundFetchUpdateUIEvent` (en-US)

O tipo de evento passado para `onbackgroundfetchsuccess` e `onbackgroundfetchfail`.

Exemplos
--------

Antes de usar Background Fetch, verifique o suporte do navegador.

```js
if (!("BackgroundFetchManager" in self)) {
  // executar um fallback para o download.
}
```

 Para usar a Background Fetch é necessário que um service worker esteja registrado. Então podemos chamar
 `backgroundFetch.fetch()` para executar o fetch. Essa chamada retorna uma promise que resolve com uma `BackgroundFetchRegistration` (en-US).

A background fetch pode baixar vários arquivos. No nosso exemplo buscamos um MP3 e um JPEG. Isso permite que um pacote de arquivos que o usuário vê como um item (por exemplo, um podcast e uma arte) sejam baixados juntos.

```js
navigator.serviceWorker.ready.then(async (swReg) => {
  const bgFetch = await swReg.backgroundFetch.fetch(
    "my-fetch",
    ["/ep-5.mp3", "ep-5-artwork.jpg"],
    {
      title: "Episódio 5: Coisas interessantes.",
      icons: [
        {
          sizes: "300x300",
          src: "/ep-5-icon.png",
          type: "image/png",
        },
      ],
      downloadTotal: 60 \* 1024 \* 1024,
    },
  );
});
```

Você pode ver uma aplicação demo que implementa a Background fetch aqui.

Especificações
--------------

| Specification |
| --- |
| Background Fetch  |

Compatibilidade com navegadores
-------------------------------

### api.BackgroundFetchManager

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

### api.BackgroundFetchRegistration

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

### api.BackgroundFetchRecord

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Veja também
-----------

* Introdução a Background Fetch
* Background Fetch - HTTP 203


MessageChannel - APIs da Web

MessageChannel
==============

A interface **`MessageChannel`** da API Channel Messaging (en-US) nos permite criar um novo canal de mensagem e enviar os dados através de suas duas propriedades `MessagePort` (en-US).

**Note:** This feature is available in Web Workers

Propriedades
------------

`MessageChannel.port1` (en-US) Somente leitura

Retorna port1 do canal.

`MessageChannel.port2` (en-US) Somente leitura

Retorna port2 do canal.

Construtor
----------

`MessageChannel()` (en-US)

Retorna um novo objeto `MessageChannel` com dois novos objetos `MessagePort` (en-US).

Exemplo
-------

No seguinte bloco de codigo, você pode ver um novo canal sendo criado usando o construtor `MessageChannel()` (en-US). Quando o `<iframe>` tiver carregado, nos passamos o `MessageChannel.port2` (en-US) para o `<iframe>` usando `MessagePort.postMessage` juntamente com uma mensagem. O manipulador `handleMessage` então reponde à mensagem que foi enviada de volta do `<iframe>` (using `MessagePort.onmessage` (en-US)), colocando-o em um parágrafo.

```js
var channel = new MessageChannel();
var para = document.querySelector("p");

var ifr = document.querySelector("iframe");
var otherWindow = ifr.contentWindow;

ifr.addEventListener("load", iframeLoaded, false);

function iframeLoaded() {
  otherWindow.postMessage("Hello from the main page!", "\*", [channel.port2]);
}

channel.port1.onmessage = handleMessage;
function handleMessage(e) {
  para.innerHTML = e.data;
}
```

Para um exemplo completo, veja nosso channel messaging basic demo no Github (rode online também ).

Especificações
--------------

| Specification |
| --- |
| HTML Standard # message-channels |

Compatibilidade com navegadores
-------------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Veja também
-----------

* Using channel messaging (en-US)


URLSearchParams - APIs da Web

URLSearchParams
===============

A interface **`URLSearchParams`** define métodos utilitários para trabalhar com os parâmetros de uma URL.

Um objeto que implementa `URLSearchParams` pode ser usado diretamente em uma estrutura `for...of` para iterar sobre pares chave/valor na mesma ordem em que elas aparecem nos parâmetros, por exemplo as linhas a seguir são equivalentes:

```js
for (const [key, value] of mySearchParams) {
}
for (const [key, value] of mySearchParams.entries()) {
}
```

**Note:** This feature is available in Web Workers

Construtor
----------

`URLSearchParams()` (en-US)

Retorna uma instância do objeto `URLSearchParams`.

Métodos
-------

`URLSearchParams.append()` (en-US)

Adiciona o par chave/valor especificado como um novo parâmetro de busca.

`URLSearchParams.delete()` (en-US)

Exclui o parâmetro de pesquisa fornecido e seu valor associado da lista de todos os parâmetros de pesquisa.

`URLSearchParams.entries()` (en-US)

Retorna um `iterator` permitindo a iteração através de todos os pares de chave/valor contidos neste objeto na mesma ordem em que aparecem na string de consulta.

`URLSearchParams.forEach()` (en-US)

Permite a iteração através de todos os valores contidos neste objeto por meio de uma função de retorno de chamada.

`URLSearchParams.get()`

Retorna o primeiro valor associado ao parâmetro de pesquisa fornecido.

`URLSearchParams.getAll()` (en-US)

Retorna todos os valores associados a um determinado parâmetro de pesquisa.

`URLSearchParams.has()` (en-US)

Retorna um valor booleano indicando se tal parâmetro existe.

`URLSearchParams.keys()` (en-US)

Retorna um `iterator` permitindo a iteração através de todas as chaves dos pares chave/valor contidos neste objeto.

`URLSearchParams.set()` (en-US)

Define o valor associado a um determinado parâmetro de pesquisa para o valor fornecido. Se houver vários valores, os demais serão excluídos.

`URLSearchParams.sort()` (en-US)

Ordena todos os pares de chave/valor, se houver, por suas chaves.

`URLSearchParams.toString()` (en-US)

Retorna uma string contendo uma string de consulta adequada para uso em uma URL.

`URLSearchParams.values()`

Retorna um `iterator` permitindo a iteração através de todos os valores dos pares chave/valor contidos neste objeto.

Exemplos
--------

```js
const paramsString = "q=URLUtils.searchParams&topic=api";
const searchParams = new URLSearchParams(paramsString);

// Iterando os parâmetros de pesquisa
for (const p of searchParams) {
  console.log(p);
}

console.log(searchParams.has("topic")); // true
console.log(searchParams.get("topic") === "api"); // true
console.log(searchParams.getAll("topic")); // ["api"]
console.log(searchParams.get("foo") === null); // true
console.log(searchParams.append("topic", "webdev"));
console.log(searchParams.toString()); // "q=URLUtils.searchParams&topic=api&topic=webdev"
console.log(searchParams.set("topic", "More webdev"));
console.log(searchParams.toString()); // "q=URLUtils.searchParams&topic=More+webdev"
console.log(searchParams.delete("topic"));
console.log(searchParams.toString()); // "q=URLUtils.searchParams"
```

```js
// Os parâmetros de pesquisa também podem ser objetos
const paramsObj = { foo: "bar", baz: "bar" };
const searchParams = new URLSearchParams(paramsObj);

console.log(searchParams.toString()); // "foo=bar&baz=bar"
console.log(searchParams.has("foo")); // true
console.log(searchParams.get("foo")); // "bar"
```

### Parâmetros de pesquisa duplicados

```js
const paramStr = "foo=bar&foo=baz";
const searchParams = new URLSearchParams(paramStr);

console.log(searchParams.toString()); // "foo=bar&foo=baz"
console.log(searchParams.has("foo")); // true
console.log(searchParams.get("foo")); // bar, somente o primeiro valor
console.log(searchParams.getAll("foo")); // ["bar", "baz"]
```

### Sem análise de URL

O construtor `URLSearchParams` *não* analisa URLs completas. No entanto, ele retirará um `?` inicial inicial de uma string, se presente.

```js
const paramsString1 = "http://example.com/search?query=%40";
const searchParams1 = new URLSearchParams(paramsString1);

console.log(searchParams1.has("query")); // false
console.log(searchParams1.has("http://example.com/search?query")); // true

console.log(searchParams1.get("query")); // null
console.log(searchParams1.get("http://example.com/search?query")); // "@" (equivalente a decodeURIComponent('%40'))

const paramsString2 = "?query=value";
const searchParams2 = new URLSearchParams(paramsString2);
console.log(searchParams2.has("query")); // true

const url = new URL("http://example.com/search?query=%40");
const searchParams3 = new URLSearchParams(url.search);
console.log(searchParams3.has("query")); // true
```

### Preservando os sinais de adição

O construtor `URLSearchParams` interpreta sinais de adição (`+`) como espaços, o que pode causar problemas.

```js
const rawData = "\x13à\x17@\x1F\x80";
const base64Data = btoa(rawData); // 'E+AXQB+A'

const searchParams = new URLSearchParams(`bin=${base64Data}`); // 'bin=E+AXQB+A'
const binQuery = searchParams.get("bin"); // 'E AXQB A', '+' são substituídos por espaços

console.log(atob(binQuery) === rawData); // false
```

Você pode evitar isso codificando os dados com o `encodeURIComponent()`.

```js
const rawData = "\x13à\x17@\x1F\x80";
const base64Data = btoa(rawData); // 'E+AXQB+A'
const encodedBase64Data = encodeURIComponent(base64Data); // 'E%2BAXQB%2BA'

const searchParams = new URLSearchParams(`bin=${encodedBase64Data}`); // 'bin=E%2BAXQB%2BA'
const binQuery = searchParams.get("bin"); // 'E+AXQB+A'

console.log(atob(binQuery) === rawData); // true
```

### Valor vazio vs. nenhum valor

`URLSearchParams` não distingue entre parâmetros com nada após o `=` e um parâmetro que não possui um `=`.

```js
const emptyVal = new URLSearchParams("foo=&bar=baz");
console.log(emptyVal.get("foo")); // retorna ''
const noEquals = new URLSearchParams("foo&bar=baz");
console.log(noEquals.get("foo")); // também retorna ''
console.log(noEquals.toString()); // 'foo=&bar=baz'
```

Especificações
--------------

| Specification |
| --- |
| URL Standard # urlsearchparams |

Compatibilidade com navegadores
-------------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Veja também
-----------

* Polyfill de `URLSearchParams` no `core-js`
* A interface `URL`.
* Google Developers: Manipulação de URL fácil com URLSearchParams


CSS Object Model - APIs da Web

CSS Object Model
================

O CSS Object Model é um conjunto de APIs que permite manipular o CSS através do JavaScript. Isto depende do DOM e da HTML APIs. Com isto é permitido a leitura e a modificação dos estilos CSS dinamicamente.

Referências
-----------

* `AnimationEvent`
* `CaretPosition` (en-US)
* `CSS`
* `CSSCharsetRule`
* `CSSConditionRule` (en-US)
* `CSSCounterStyleRule` (en-US)
* `CSSFontFaceRule` (en-US)
* `CSSFontFeatureValuesMap`
* `CSSFontFeatureValuesRule` (en-US)
* `CSSGroupingRule` (en-US)
* `CSSImportRule` (en-US)
* `CSSKeyframeRule` (en-US)
* `CSSKeyframesRule` (en-US)
* `CSSMarginRule`
* `CSSMediaRule` (en-US)
* `CSSNamespaceRule` (en-US)
* `CSSPageRule` (en-US)
* `CSSRule` (en-US)
* `CSSRuleList` (en-US)
* `CSSStylesheet` (en-US)
* `CSSStyleDeclaration` (en-US)
* `CSSSupportsRule` (en-US)
* `CSSVariablesMap`
* `CSSViewportRule`
* `ElementCSSInlineStyle` (en-US)
* `GeometryUtils`
* `GetStyleUtils`
* `LinkStyle` (en-US)
* `MediaList` (en-US)
* `MediaQueryList` (en-US)
* `PseudoElement`
* `Screen` (en-US)
* `Stylesheet` (en-US)
* `StylesheetList` (en-US)
* `TransitionEvent` (en-US)

Outras interfaces podem ser usadas com CSSOM:

`Document`, `Window`, `Element`, `HTMLElement` (en-US), `HTMLImageElement` (en-US), `Range` (en-US), `MouseEvent`, and `SVGElement` (en-US).

Tutoriais
---------

* Determinando dimensões de elementos (en-US) (É necessário algumas atualizações, já que foi feito com DHTML/Ajax).
* Gerenciando as orientações da tela (en-US)
Especificações
--------------

| Specification |
| --- |
| CSS Object Model (CSSOM)  |
| CSSOM View Module  |
| CSS Typed OM Level 1  |

Notas de compatibilidade do navegador
-------------------------------------

Todos esses recursos foram adicionados pouco a pouco ao logo dos anos para os diferentes navegadores: Foi um processo bastante complexo que não podem ser sintetizados em uma simples tabela. Por favor, pesquise por uma interface específica e sua disponibilidade.


SpeechGrammar - APIs da Web

SpeechGrammar
=============

**Experimental:** **Esta é uma tecnologia experimental (en-US)**
Verifique a tabela de compatibilidade entre Navegadores cuidadosamente antes de usar essa funcionalidade em produção.

A interface **`SpeechGrammar`** da Web Speech API (en-US) representa um conjunto de palavras ou padrões de palavras, os quais, nós queremos que o serviço de reconhecimento reconheça.

A gramática é definida usando JSpeech Grammar Format (**JSGF**.) Outros formatos podem ser suportados no futuro.

Construtor
----------

`SpeechGrammar.SpeechGrammar()` (en-US)

Cria um novo objeto `SpeechGrammar`.

Propriedades
------------

`SpeechGrammar.src` (en-US)

Define e retorna a string contendo a gramática contida na instância do objeto `SpeechGrammar`.

`SpeechGrammar.weight` (en-US) Optional

Define e retorna o peso do objeto `SpeechGrammar`.

Exemplos
--------

```js
var grammar =
  "#JSGF V1.0; grammar colors; public <color> = aqua | azure | beige | bisque | black | blue | brown | chocolate | coral | crimson | cyan | fuchsia | ghostwhite | gold | goldenrod | gray | green | indigo | ivory | khaki | lavender | lime | linen | magenta | maroon | moccasin | navy | olive | orange | orchid | peru | pink | plum | purple | red | salmon | sienna | silver | snow | tan | teal | thistle | tomato | turquoise | violet | white | yellow ;";
var recognition = new SpeechRecognition();
var speechRecognitionList = new SpeechGrammarList();
speechRecognitionList.addFromString(grammar, 1);
recognition.grammars = speechRecognitionList;

console.log(speechRecognitionList[0].src); // deveria retornar o mesmo conteúdo da variável grammar
console.log(speechRecognitionList[0].weight); // deveria retornar 1 - o mesmo peso definido na linha 4.
```

Especificações
--------------

| Specification |
| --- |
| Web Speech API # speechreco-speechgrammar |

Compatibilidade com navegadores
-------------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Veja também
-----------

* Web Speech API (en-US)


ValidityState - APIs da Web

ValidityState
=============

Baseline 2023
-------------

Newly availableSince March 2023, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

* Learn more
* See full compatibility
* Report feedback

 A interface **`ValidityState`** representa os estados de validação que um elemento
 pode conter de acordo com as propriedades de validação abaixo. Juntas, elas podem explicar porque um elemento é inválido (caso seja) ao ser validado.

Propriedades
------------

Para cada uma das propriedades Booleanas abaixo, caso retorne **`true`**, isso indica a razão específica porque a validação falhou, exceto no caso da propriedade *valid*, que retorna **`true`** no caso do elemento ser completamente válido e **`false`** caso contrário.

`ValidityState.badInput` (en-US) Somente leitura

É um `Boolean` informando se o usuário inseriu um valor que o navegador é incapaz de converter.

`ValidityState.customError` Somente leitura

É um `Boolean` informando se o elemento possui uma mensagem de validação definida por `setCustomValidity()` para um valor não vázio.

`ValidityState.patternMismatch` (en-US) Somente leitura

É um `Boolean` informando se o valor não combina com o padrão (`pattern`) especificado.

`ValidityState.rangeOverflow` (en-US) Somente leitura

É um `Boolean` informando se o valor é maior do que o máximo especificado pelo atributo `max`.

`ValidityState.rangeUnderflow` (en-US) Somente leitura

É um `Boolean` informando se o valor é menor do que o mínimo especificado pelo atributo `min`.

`ValidityState.stepMismatch` (en-US) Somente leitura

É um `Boolean` informando se o valor não segue a regra definida pelo atributo `step`.

`ValidityState.tooLong` (en-US) Somente leitura

É um `Boolean` informando se o valor ultrapassa o especificado pelo atributo `maxlength` para `HTMLInputElement` ou `HTMLTextAreaElement` (en-US). ***OBS:** Isso nunca será `true` em navegadores como o Firefox, pois a inserção de valores não é permitida ao alcançar o valor definido em `maxlength`.*

`ValidityState.tooShort` (en-US) Somente leitura

É um `Boolean` informando se o valor não corresponde ao especificado no atributo `minlength` para `HTMLInputElement` ou `HTMLTextAreaElement` (en-US).

`ValidityState.typeMismatch` (en-US) Somente leitura

É um `Boolean` informando se o valor não corresponde ao tipo de entrada definida. (Um exemplo é quando `type` é `email` ou `url`).

`ValidityState.valid` Somente leitura

É um `Boolean` informando se o elemento é completamente válido.

`ValidityState.valueMissing` (en-US) Somente leitura

É um `Boolean` informando que o elemento tem o atributo `required`, mas não tem `value`.

Especificações
--------------

| Specification |
| --- |
| HTML Standard # the-constraint-validation-api:validitystate-3 |

Compatibilidade com navegadores
-------------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Veja também
-----------

* Constraint validation (en-US)
* Forms: Data form validation (en-US)


Manipulando o histórico do navegador - APIs da Web

Manipulando o histórico do navegador
====================================

O objeto DOM `window` fornece acesso ao histórico do navegador através do objeto `history`. Ele expõe métodos e propriedades úteis que permitem que você se mova para trás e para frente através do histórico de navegação do usuário, bem como — iniciando com o HTML5 — manipular o conteúdo da pilha de históricos.

Navegando através do histórico
------------------------------

Mover para trás e para a frente através do histórico do usuário é feito usando os métodos `back()`, `forward()` e `go()`.

### Movendo para frente e para trás

Para mover para trás no histórico, apenas faça:

```js
window.history.back();
```

Isso funcionará exatamente como se o usuário clicasse no botão Voltar na barra de ferramentas do navegador.

Da mesma forma, você pode avançar (como se o usuário clicasse no botão Avançar), assim:

```js
window.history.forward();
```

### Movendo para um ponto específico no histórico

Você pode usar o método `go()` para carregar uma página específica do histórico. Cada página é identificada por sua posição relativa à página atual (sendo a página atual o indíce 0).

Para retornar uma página (equivalente ao método `back()`):

```js
window.history.go(-1);
```

Para avançar uma página (equivalente ao método `forward()`):

```js
window.history.go(1);
```

O número de páginas do histórico pode ser determinado pela propriedade *length*:

```js
const numberOfEntries = window.history.length;
```

>
> \*\*Nota:\*\*O Internet Explorer suporta URLs como argumento para o método `go()`; isso não é um comportamento padrão e não é suportado pelo Gecko.
>
>
>

Adicionando e modificando entradas
----------------------------------

O HTML5 introduziu os métodos history.pushState() (en-US) e history.replaceState(), que permitem adicionar e modificar entradas no histórico, respectivamente. Estes métodos funcionam em conjunto com o evento `window.onpopstate` (en-US).

Usar `history.pushState()` modifica a referência que é utilizada no cabeçalho HTTP para objetos `XMLHttpRequest` criados após a utilização do método. A referência será a URL do documento cuja janela é o `this` no momento de criação do objeto `XMLHttpRequest`.

### Exemplo do método pushState()

Suponha que `http://mozilla.org/foo.html` executa o seguinte JavaScript:

```js
const stateObj = { foo: "bar" };
history.pushState(stateObj, "page 2", "bar.html");
```

Isto fará com que a barra URL mostre `http://mozilla.org/bar.html`, porém não fará com que o navegador carregue `bar.html` ou verifique se `bar.html` existe.

Agora suponha que o usuário navegue para `http://google.com` e logo em seguida clique no botão Voltar. Nesse momento, a barra de URL mostrará `http://mozilla.org/bar.html`, e se você ler o `history.state` você receberá o `stateObj`. O evento `popstate` não será disparado pois a página foi recarregada. A página carregada será `bar.html`.

Se clicarmos no botão Voltar novamente, a URL modificará para `http://mozilla.org/foo.html`, e o documento receberá um evento `popstate`, dessa vez com objeto de estado sendo nulo. Nesse momento, o documento também não altera seu conteúdo em relação ao passo anterior, porém o documento pode atualizar seu conteúdo manualmente após o recebimento do evento `popstate`.

### O método pushState()

`pushState()` recebe três parâmetros: um objeto de estado, um título (que atualmente é ignorado) e (opcionalmente) uma URL. Vamos examinar cada um dos argumentos com mais detalhes:

* **objeto de estado** — O objeto de estado é um objeto JavaScript que é associado com uma nova entrada no histórico criado por `pushState()`. Sempre que o usuário navegar para o novo estado um evento `popstate` é disparado e a propriedade `state` do evento contém uma cópia do objeto de estado da entrada no histórico.
* O objeto de estado pode ser qualquer coisa que possa ser serializada. O Firefox salva o objeto de estado no disco do usuário para que possa ser restaurado após um reinício do navegador. É imposto um limite de 640k caracteres na representação serializada do objeto de estado. Caso um objeto de estado serializado maior que este valor seja passado como argumento para `pushState()`, o método irá ativar uma exceção. Caso você precise de mais espaço do que 640k, é recomendada a utilização do `sessionStorage` e/ou `localStorage`.
* **título** — Atualmente o Firefox ignora este parâmetro. Passar uma string vazia é suficiente contra futuras mudanças no método. Alternativamente, você pode passar um título curto para o estado.
* **URL** — A URL da nova entrada no histórico é passada por este parâmetro. Note que o navegador não tentará carregar essa URL após uma chamada do método `pushState()`, porém pode tentar carregar a URL mais tarde, por exemplo depois que o usuário reinicie o navegador. A nova URL não precisa ser absoluta; caso seja relativa, é resolvida em relação a atual URL. A nova URL precisar ser da mesma origem que a URL atual; caso contrário, `pushState()` ativará uma exceção. Este parâmetro é opcional; caso seja especificado, é utilizado como a atual URL do documento.

>
> \*\*Nota:\*\*No Gecko 2.0 até Gecko 5.0, o objeto passado é serializado utilizando JSON. A partir do Gecko 6.0, o objeto é serializado usando o algorítmo de clonagem estruturada. Isso permite que uma variedade maior de objetos possam ser serializados.
>
>
>

De certa forma, chamar o método `pushState()` é similar a executar `window.location = "#foo"`, no sentido de que ambos criarão e ativarão uma nova entrada no histórico associado com o documento atual. Porém `pushState()` tem algumas vantagens:

* A nova URL pode ser qualquer URL na mesma origem da atual. Em contrapartida, modificar o valor de `window.location` o mantém no mesmo `document` somente se apenas a hash é modificada.
* Você não precisa mudar a URL caso não queira. Em contrapartida, executar `window.location = "#foo"` só cria uma nova entrada no histórico se a atual hash não for `#foo`.
* Você pode associar dados arbitrários com a nova entrada do histórico. Com a solução baseada em hash, você precisa codificar todos os dados relevantes em uma string curta.
* Se `title` for utilizado pelos navegadores, esse dado pode ser utilizado (independente do hash).

Note que `pushState()` nunca causa a ativação de um evento `hashchange`, mesmo se a nova URL diferir somente na hash,

Em um documento XUL é criado o elemento XUL especificado.

Em outros documentos, é criado um elemento com um namespace `null` de URI.

### O método replaceState()

`history.replaceState()` opera exatamente igual à `history.pushState()` com exceção de modificar a atual entrada no histórico ao invés de criar uma nova. Note que isso não impede a criação de uma nova entrada no histórico global do navegador.

`replaceState()` é particularmente útil quando você quer atualizar o objeto de estado ou a URL da atual entrada do histórico como resposta a alguma ação do usuário.

>
> \*\*Nota:\*\*Em Gecko 2.0 até Gecko 5.0, o objeto passado é serializado utilizando JSON. Começando do Gecko 6.0, o objeto é serializado usando o algorítmo de clonagem estruturada. Isso permite que uma variedade maior de objetos possam ser serializados.
>
>
>

### Exemplo do método replaceState()

Suponha que `http://mozilla.org/foo.html` execute o seguinte JavaScript:

```js
const stateObj = { foo: "bar" };
history.pushState(stateObj, "page 2", "bar.html");
```

A explicação destas duas linhas acima pode ser encontrada na seção "Exemplo do método pushState()". Suponha, então, que `http://mozilla.org/bar.html` execute o seguinte JavaScript:

```js
history.replaceState(stateObj, "page 3", "bar2.html");
```

Isso fará com que a barra de URL do navegador exiba `http://mozilla.org/bar2.html`, mas não fará com que o navegador carregue `bar2.html` ou cheque se `bar2.html` existe.

Suponha agora que o usuário navegue até `http://www.microsoft.com` e, em seguida, clique no botão voltar. Neste momento, a barra de URL mostrará `http://mozilla.org/bar2.html`. Caso o usuário clique novamente no botão voltar, a barra de URL mostrará `http://mozilla.org/foo.html` e ignorará completamente `bar.html`.

### O evento popstate

O evento `popstate` é disparado sempre que a entrada do histórico ativo é alterada. Se a entrada do histórico ativa foi criada por uma chamada `pushState` ou afetada por uma chamada `replaceState`, a propriedade `state` do evento `popstate` contém uma cópia do objeto de estado da entrada do histórico.

Veja `window.onpopstate` (en-US) para exemplo de utilização.

### Lendo o estado atual

Quando sua página é carregada, ela pode ter um objeto de estado não nulo. Isso pode acontecer, por exemplo, se a página definir um objeto de estado (usando `pushState()` ou `replaceState()`) e, em seguida, o usuário reiniciar seu navegador. Quando sua página é recarregada, ela receberá um evento `onload`, mas nenhum evento `popstate`. No entanto, se você ler a propriedade `history.state`, receberá o objeto de estado que teria obtido se um `popstate` tivesse sido disparado.

Você pode ler o estado da entrada do histórico atual sem esperar por um evento `popstate` usando a propriedade `history.state` como o exemplo abaixo:

```js
var currentState = history.state;
```

Exemplos
--------

Para um exemplo completo de um web site AJAX, veja: Exemplo de navegação Ajax (en-US).

Especificações
--------------

| Specification |
| --- |
| HTML Standard # the-history-interface |

Compatibilidade com navegadores
-------------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


FileList - APIs da Web

FileList
========

Um objeto desse tipo é retornado pela propriedade `files` do elemento HTML `<input>`; isso permite acessar a lista de arquivos selecionados com o elemento `<input type="file">`. Também é usado para uma lista de arquivos soltos no conteúdo web usando a API drag and drop; consulte o objeto `DataTransfer` (en-US) para detalhes de seu uso.

**Nota:** Antes do Gecko 1.9.2, o elemento input suportava apenas um arquivo selecionado por vez, ou seja, o array FileList conteria apenas um arquivo. A partir do Gecko 1.9.2, se o atributo multiple do elemento for definido, FileList pode conter múltiplos arquivos.

Utilizando a lista de arquivos
------------------------------

Todo elemento `<input>` possui um array `files` que permite o acesso aos seus arquivos. Por exemplo, se o HTML inclui o seguinte elemento:
```

<input id="fileItem" type="file">
```

O código a seguir acessa o primeiro elemento da lista de arquivos como um objeto `File` (en-US):

```js
var file = document.getElementById("fileItem").files[0];
```

Visão geral dos métodos
-----------------------

| `File item(index);` |
| --- |

Propriedades
------------

| Atributo | Tipo | Descrição |
| --- | --- | --- |
| `length` | `integer` | Valor somente-leitura que indica o número de arquivos na lista. |

Métodos
-------

### item()

Retorna um objeto `File` (en-US) representando o arquivo no índice especificado na lista.
```

 File item(
   index
 );
```

###### Parâmetros

`index`

O índice (baseado em zero) do arquivo a ser recuperado da lista.

###### Valor de retorno

O objeto `File` (en-US) representando o arquivo requisitado.

Exemplo
-------

Este exemplo itera por todos os arquivos selecionados pelo usuário em um elemento `input`:

```js
// fileInput é um elemento HTML input: <input type="file" id="myfileinput" multiple>
var fileInput = document.getElementById("myfileinput");

// files é um objeto FileList (similar ao NodeList)
var files = fileInput.files;
var file;

// percorre os arquivos
for (var i = 0; i < files.length; i++) {
  // obtém o item
  file = files.item(i);
  // ou
  file = files[i];

  alert(file.name);
}
```

A seguir, um exemplo completo.

```html
<!doctype html>
<html>
  <head> </head>

  <body>
    <!--multiple é definido para que múltiplos arquivos possam ser selecionados-->

    <input id="myfiles" multiple type="file" />
  </body>

  <script>
 var puxarArquivos = function () {
 var fileInput = document.querySelector("#myfiles");
 var files = fileInput.files;

 for (var i = 0; i < files.length; i++) {
 var file = files[i];
 alert(file.name);
 }
 };

 // seta o 'onchange' do elemento input para chamar a função puxarArquivos
 document.querySelector("#myfiles").onchange = puxarArquivos;
 </script>
</html>
```

Especificações
--------------

| Specification |
| --- |
| File API # filelist-section |
| HTML Standard # dom-input-files-dev |

Compatibilidade com navegadores
-------------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


Arrastar e soltar - APIs da Web

Arrastar e soltar
=================

As interfaces de Drag and Drop (arrastar e soltar) habilitam aplicações a usar funcionalidades de arrastar e soltar através do navegador. Por exemplo, com essas funcionalidades, o usuário pode selecionar elementos arrastáveis (*draggable*) com o mouse, arrastar elementos até um elemento soltável (*droppable*), e soltar o elemento ao soltar o botão do mouse. Uma representação translúcida de elementos arrastáveis (*draggable)* seguem o ponteiro do mouse durante a operação de arrastar (drag).

Para web sites, extensões e aplicações XUL, você pode customizar os tipos de elementos que podem se tornar arrastáveis (draggable) e o tipo de retorno que o elemento arrastável produz, assim como os elementos soltáveis (droppable).

**NT:** Para manter a tradução mais precisa e coesa, a partir daqui iremos manter os termos *drag* e *drop* e seus variantes conforme texto original. Sendo portanto mantidos também os termos *draggable* e *droppable*.

Este documento é uma visão geral do drag and drop no HTML. Ele inclui uma descrição de suas interfaces, funcionalidades básicas de como permitir a adesão de funcionalidades arrastar e soltar em uma aplicação e um sumário da interoperabilidade entre interfaces.

Eventos Drag
------------

O drag and drop em HTML usa o `modelo de eventos DOM` e os *`eventos drag` (en-US)* são hereditários dos `eventos do mouse`. Uma operação típica de drag começa quando o usuário seleciona um elemento arrastável com o mouse, move o mouse até um elemento soltável (droppable) e solta o mouse. Durante as operações, diversos tipos de evento são acionados e alguns podem até ser acionados multiplas vezes (como por exemplo os tipos de evento `drag (en-US)` e `dragover (en-US)`.

Todos os tipos de evento drag (en-US) são associados a um manipulador global de eventos (en-US). Cada tipo de evento drag e cada atributo drag global tem um documento de referência que o descreve. A tabela a seguir descreve brevemente os tipos de evento e um link de referência para seu documento.

| Event | On Event Handler | Description |
| --- | --- | --- |
| `drag (en-US)` | `ondrag` (en-US) | Acionado quando um elemento ou seleção de texto está sendo arrastado. |
| `dragend (en-US)` | `ondragend` (en-US) | Acionado quando uma operação de arrastar está terminando (por eexmplo, ao soltar o botão do mouse ou pressionar a tecla esc). (Veja Terminando um evento Drag (en-US).) |
| `dragenter (en-US)` | `ondragenter` (en-US) | Acionado quando um elemento arrastável ou seleção de texto entra em um ponto de soltura (drop target). (Veja Determinando Drop Targets (en-US).) |
| `dragexit` | `ondragexit` (en-US) | Acionado quando um elemento não é mais o ponto de seleção imediata da operação drag. |
| `dragleave (en-US)` | `ondragleave` (en-US) | Acionado quando um elemento arrastável ou seleção de texto abandona um ponto de soltura (drop target) válido. |
| `dragover (en-US)` | `ondragover` (en-US) | Acionado quando um elemento ou seleção de texto está sendo arrastado sobre um ponto de soltura válido (a cada aproximadamente 100 milisegundos). |
| `dragstart (en-US)` | `ondragstart` (en-US) | Acionado quando o usuário começa a arrastar um elemento válido ou seleção de texto. (Veja Começando uma Operação Drag (en-US).) |
| `drop (en-US)` | `ondrop` (en-US) | Acionado quando um elemento ou seleção de texto é solta em um ponto d soltura (drop target) válido. (Veja Realizando um Drop (en-US).) |

Note que eventos `dragstart` e `dragend` não são acionados ao arrastar um arquivo vindo do sistema operacional para o navegador.

Interfaces
----------

A interface HTML drag and drop é composta pelos eventos `DragEvent` (en-US), `DataTransfer`, `DataTransferItem` (en-US) e `DataTransferItemList` (en-US).

A interface `DragEvent` (en-US) consiste de um construtor e uma propriedade, a propriedade `dataTransfer` (en-US) que é um objeto `DataTransfer`. Os objetos `DataTransfer` incluem estados do evento drag como o tipo de drag sendo feito (por exemplo `copy` ou `move`), os dados do do evento drag (um ou mais itens) e o tipo de cada *item drag* (um MIME type). Objetos `DataTransfer` também contém métodos para adicionar itens aos dados do drag e remover um item. As interfaces `DragEvent` (en-US) e `DataTransfer` devem as únicas necessárias para adicionar capacidades de drag and drop para uma aplicação. Entretanto, note que o Firefox provê suporte para apenas algumas Gecko-specific extensions ao objeto `DataTransfer`, apesar de entretanto essas extensões funcionarem apenas no Firefox.

Cada objeto `DataTransfer` contém uma propriedade `items` (en-US) que é uma `lista` (en-US) dos objetos `DataTransferItem` (en-US). Cada objeto `DataTransferItem` (en-US) representa um único *drag item* e cada item tem uma propriedade `kind (tipo)` (en-US) que é o *tipo(kind)* de data (seja ela `string` ou `file`) e uma propriedade `type (tipo)` (en-US) que é o tipo de dado do item (ou seja, MIME type). O objeto `DataTransferItem` (en-US) também contém métodos para conseguir dados do item arrastável.

O objeto `DataTransferItemList` (en-US) é uma lista de objetos `DataTransferItem` (en-US). A lista de objetos contém métodos para: adicionar um item para uma lista, remover um item de uma lista e limpar a lista com todos os itens.

A diferença chave entre das interfaces `DataTransfer` e `DataTransferItem` (en-US) é que a primeira usa o método síncrono `getData()` (en-US) para acessar os dados de um item arrastável, e a segunda usa o método assíncrono `getAsString()` (en-US) para acessá-lo.

Note: as interfaces `DragEvent` (en-US) e a `DataTransfer` são vastamente interoperáveis com navegadores desktop. Entretanto, as interfaces `DataTransferItem` (en-US) e `DataTransferItemList` (en-US) tem suporte limitado entre navegadores. Veja Interoperabildade para mais informações.

### Interfaces específicas para o Gecko

A Mozilla e o Firefox suportam algumas funcionalidades fora dos padrões do modelo drag and drop. Elas são *cfunções convenientes* para facilitar o arraste múltiplo de elementos e a manipulação de dados que não são strings (como arquivos). Para mais informações, veja Dragging and Dropping Multiple Items. Para mais informações, veja a página de referência `DataTransfer` para todas as propriedades específicas para o Gecko e Métodos específicos para o Gecko.

O básico
--------

Esta seção dispõe de um resumo das etapas básicas para adicionar a funcionalidade drag and drop à uma aplicação. Cada seção inclui uma descrição da etapa, um breve exemplo em código, e links para informações adicionais.

### Identificando o que é arrastável *(draggable)*

Para fazer um elemento se tornar arrastável, é necessária a adição de um atributo `draggable` além da adição do manipulador de eventos global `ondragstart` (en-US), conforme descrito no exemplo a seguir

```js
function dragstart\_handler(ev) {
  console.log("dragStart");
  // Adiciona o id do elemento em questão ao objeto de transferência de dados (dataTransfer)
  ev.dataTransfer.setData("text/plain", ev.target.id);
}
```

```html
<body>
  <p id="p1" draggable="true" ondragstart="dragstart\_handler(event);">
    Este elemento é arrastável.
  </p>
</body>
```

Veja a referência do atributo draggable (en-US) e o Guia de operações drag (en-US) para mais informações.

### Defina os dados do drag

A aplicação é livre para incluir qualquer quantidade de dados do item em uma operação drag. Cada dado de um item é uma `string` de um tipo particular, tipicamente um MIME type como por exemplo `text/html`.

Cada `evento drag` (en-US) tem uma propriedade `dataTransfer` (en-US) que *segura* os dados do evento. Essa propridade (que é um objeto `DataTransfer`) também tem um método para *gerenciar* os dados do arraste (drag). O método `setData()` (en-US) é usado para adicionar um item aos dados do arraste, como demonstrado no exemplo a seguir.

```js
function dragstart\_handler(ev) {
  // Adiciona os dados do arraste (drag)
  ev.dataTransfer.setData("text/plain", ev.target.id);
  ev.dataTransfer.setData("text/html", "<p>Parágrafo de exemplo</p>");
  ev.dataTransfer.setData("text/uri-list", "http://developer.mozilla.org");
}
```

Para uma lista de tipos de dados mais comuns utilizados pelo drag and drop (como texto, HTML, links, e files), veja Tipos recomendados de Drag Types (en-US) e para mais informações sobre os dados do arraste (drag data), veja Drag Data (en-US).

### Defina uma imagem de arraste (drag image)

Por padrão, o navegador provê uma imagem que aparece por trás do ponteiro do mouse durante uma operação de arraste. Entretanto, uma aplicação pode definir uma imagem customizada utilizando o método `setDragImage()` (en-US) como demonstrado no exemplo a seguir.

```js
function dragstart\_handler(ev) {
  // Cria uma imagem e então a utiliza como a "drag image".
  // NOTA: mude "example.gif" como uma imagem existente, caso contrário
  // ela não será criada e a imagem padrão será utilizada como padrão.
  var img = new Image();
  img.src = "example.gif";
  ev.dataTransfer.setDragImage(img, 10, 10);
}
```

Para aprender mais sobre arrastar imagens de retorno, veja Definindo a imagem de retorno do arraste (Drag) (en-US).

### Defina o *efeito* do arraste (*Drag effect*)

A propriedade `dropEffect` (en-US) é usada para controlar o retorno (geralmente visual) que é dado ao usuário durante uma operação drag and drop. Ela afeta qual cursor o navegador irá mostrar enquanto o arraste é realizado. Por exemplo, quando o usuário passa sobre (famoso *hover*) o ponto de soltura (drop target), o cursor do navegador pode indicar o tipo de operação que irá acontecer.

Três efeitos podem ser definidos:

`copy` indica que os dados sendo arrastados podem ser copiados da localização atual para a localização de destino (localização do *drop*).

`move` indica que os dados sendo arrastados irá ser movido.

`link` indica que alguma forma de relação ou conexão será criada entre a localização de origem (source) e de destino (drop).

Durante a operação de arraste, os efeitos do arraste (drag) podem ser modificados para determinar que certos efeitos são permitidos em determinadas localizações. Se permitido, uma soltura (drop) pode ocorrer naquela localização.

O exemplo a seguir mostra como utilizar essa propriedade.

```js
function dragstart\_handler(ev) {
  // Determina o efeito de arraste para copy
  ev.dataTransfer.dropEffect = "copy";
}
```

Veja Efeitos do Arraste (Drag Effects) (en-US) para mais detalhes.

### Defina uma zona de soltura *(drop zone)*

Por padrão, o navegador previne tudo que possa acontecer ao soltar alguma coisa em um elemento HTML. Para mudar esse comportamento de forma que um elemento se torne uma zona de soltura (d*rop zone)* ou que seja soltável *(droppable)*, o elemento precisa ter ambos os atributos `ondragover` (en-US) e `ondrop` (en-US). O exemplo a seguir mostra como utilizar esses atributos e inclui manipuladores básicos de evento para cada um.

```js
function dragover\_handler(ev) {
  ev.preventDefault();
  // Define o dropEffect para ser do tipo move
  ev.dataTransfer.dropEffect = "move";
}
function drop\_handler(ev) {
  ev.preventDefault();
  // Pega o id do alvo e adiciona o elemento que foi movido para o DOM do alvo
  var data = ev.dataTransfer.getData("text");
  ev.target.appendChild(document.getElementById(data));
}
<body>
  <div
    id="target"
    ondrop="drop\_handler(event);"
    ondragover="dragover\_handler(event);">
    Zona de Soltura (Drop Zone)
  </div>
</body>;
```

Note que cada manipulador chama `preventDefault()` para previnir o processamento adicional de eventos (como eventos touch ou eventos pointer).

Para mais informações, veja Especificando pontos de soltura (Drop Targets) (en-US).

### Manipulando o *efeito* de soltura (drop)

O manipulador do evento `drop (en-US)` é livre para processar os dados do arraste (drag) de maneira específica em uma aplicação. Tipicamente, uma aplicação usaria o método `getData()` (en-US) para reter os itens arrastados e processá-los de acordo. A semântica da aplicação pode ser diferente dependendo do valor do `dropEffect` (en-US) e/ou o estado da chave que o modifica.

O exemplo a seguir mostra o manipulador de soltura (drop handler) pegando o id do elemento de origem atráves dos dados de drag (drag data) e então usando o id para mover o elemento de sua origem para o elemento de soltura (drop element).

```js
function dragstart\_handler(ev) {
  // Adiciona o id do elemento alvo para o objeto de transferência de dados
  ev.dataTransfer.setData("text/plain", ev.target.id);
  ev.dropEffect = "move";
}
function dragover\_handler(ev) {
  ev.preventDefault();
  // Define o dropEffect para ser do tipo move
  ev.dataTransfer.dropEffect = "move";
}
function drop\_handler(ev) {
  ev.preventDefault();
  // Pega o id do alvo e adiciona o elemento que foi movido para o DOM do alvo
  var data = ev.dataTransfer.getData("text");
  ev.target.appendChild(document.getElementById(data));
}
<body>
  <p id="p1" draggable="true" ondragstart="dragstart\_handler(event);">
    Este elemento é arrastável.
  </p>
  <div
    id="target"
    ondrop="drop\_handler(event);"
    ondragover="dragover\_handler(event);">
    Zona de Soltura (Drop Zone)
  </div>
</body>;
```

Para mais informações, veja Realizando uma soltura (Drop) (en-US).

### Fim da soltura (Drag end)

No início da operação de arraste (drag), o evento `dragend (en-US)` é acionado no elemento de origem (*source)* - o elemento que foi o alvo do início do arraste (drag start). Este evento é acionado sempre quando o arraste é completado ou cancelado. O manipulador de eventos `dragend (en-US)` pode verificar o valor da propriedade `dropEffect` (en-US) para determinar se a operação de arraste foi bem sucedida ou não.

Para mais informações sobre manipular o final de uma operação de arraste, veja Finalizando um arraste (Drag) (en-US).

Interoperabilidade
------------------

Como podem ser visto no DataTransferItem interface's Browser Compatibility table (en-US), drag-and-drop a interoperabilidade é relativamente ampla emtre ps brpwsers desktop (exceto as interfaces `DataTransferItem` (en-US) e `DataTransferItemList` (en-US) que tem o menor suport). Estes dados tambem indica que o suporte ao drag and drop entre browser mobile é muito menor.

Exemplos e demonstrações
------------------------

* Copiando e movendo elementos com a interface `DataTransfer`
* Copiando e movendo elementos com a interface `DataTransferListItem`
* Arrastando e soltando arquivos; Apenas para o Firefox: http://jsfiddle.net/9C2EF/
* Arrastando e soltando arquivos; Todos os navegadores: https://jsbin.com/hiqasek/
Veja também
-----------

* Operações de Arraste (en-US)
* Arrastando e Soltando múltiplos elementos
* Tipos re arraste (Drag Types) recomendados (en-US)
* HTML5 Living Standard: Drag and Drop
* Dados de unteroperabilidade Drag and Drop de acordo com o CanIUse


WindowTimers.clearTimeout() - APIs da Web

WindowTimers.clearTimeout()
===========================

Sumário
-------

O método **`clearTimeout()`** do escopo `WindowOrWorkerGlobalScope` cancela um *timeout* previamente estabelecido pela função `setTimeout()` (en-US).

Síntaxe
-------
```

escopo.clearTimeout(timeoutID)
```

### Parâmetros

`timeoutID`

O ID do *timeout* que você deseja cancelar. Esse ID é o retorno da função `setTimeout()`.

É interessante ressaltar que os conjuntso de *IDs* usados pelos métodos `setTimeout()` (en-US) e `setInterval()` são compartilhados, o que significa que `clearTimeout()` e `clearInterval()` (en-US) podem ser tecnicamente utilizados de forma intercambiável. No entanto, para obter-se maior clareza, isso deve ser evitado.

Exemplo
-------

Execute o script abaixo em uma página web e clique na página uma vez. Você verá uma mensagem aparecer um segundo depois. Se você continuar clicando na página várias vezes nesse intervalo de tempo, a mensagem aparecerá uma única vez.

```js
var alarme = {
  relembrar: function (aMessage) {
    alert(aMessage);
    delete this.timeoutID;
  },

  setup: function () {
    if (typeof this.timeoutID === "number") {
      this.cancelar();
    }

    this.timeoutID = window.setTimeout(
      function (msg) {
        this.relembrar(msg);
      }.bind(this),
      1000,
      "Wake up!",
    );
  },

  cancelar: function () {
    window.clearTimeout(this.timeoutID);
  },
};
window.onclick = function () {
  alarme.setup();
};
```

Notas
-----

Passar um *ID* inválido para `clearTimeout` não causa nenhum efeito (não lança nenhuma exceção).

Especificações
--------------

| Specification |
| --- |
| HTML Standard # dom-cleartimeout-dev |

Compatibilidade
---------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Veja também
-----------

* `WindowOrWorkerGlobalScope.setTimeout()` (en-US)
* `WindowOrWorkerGlobalScope.setInterval()`
* `WindowOrWorkerGlobalScope.clearInterval()` (en-US)
* `Window.requestAnimationFrame()`
* *Daemons* management


API do Service Worker - APIs da Web

API do Service Worker
=====================

Essencialmente, um *service worker* se comporta como um servidor *proxy* situado entre uma aplicação web, o navegador e a rede (quando esta estiver disponível). Eles servem, dentre outras coisas, para possibilitar a criação de experiências *offline* eficientes, interceptar requisições de rede – agindo adequadamente de acordo com o *status* atual da conexão – e atualizar os *assets* que residem no servidor. Service workers também permitem o acesso às APIs de *push notification* e *background sync*.

Service worker - Conceitos e uso
--------------------------------

Um *service worker* é um tipo especial de *worker* baseado em eventos, o qual é registrado para um determinado *path* e origem. Na prática, ele é um arquivo JavaScript que pode controlar as páginas do site ao qual ele está associado, interceptando e modificando requisições e a navegação em si. Ele também faz *cache* dos recursos trafegados de maneira bastante granular, visando oferecer controle total sobre como a sua aplicação se comporta em determinadas situações (o exemplo mais óbvio, naturalmente, é quando não há conexão de rede disponível).

Assim como outros tipos de *worker*, um *service worker* é executado em um contexto isolado. Dessa forma, não tem acesso ao DOM e roda em uma thread completamente separada, sendo incapaz de realizar operações blocantes. Service workers foram projetados para ser totalmente assíncronos; como consequência disso, não permitem o acesso a APIs como XHR síncrono e localStorage.

Por questões de segurança, *service workers* funcionam apenas em sites servidos via HTTPS. A possibilidade de modificar requisições em um domínio desprotegido contra ataques do tipo man-in-the-middle (en-US) seria desastrosa. No Firefox, é vetado o acesso à API de *service workers* para sites abertos no Modo de navegação privativa.

**Nota:** Os service workers superaram tentativas anteriores de resolver problemas semelhantes, como o AppCache. Há uma explicação simples para eles terem sido bem-sucedidos: Service workers **não** tentam adivinhar o que você está tentando fazer e, muito menos, deixam de funcionar caso não tenham adivinhado corretamente. Pelo contrário, você tem o controle milimétrico de tudo.

**Nota:** Service workers fazem uso intenso de promessas, uma vez que eles têm de esperar por respostas assíncronas para, após retornadas, poderem executar a ação apropriada (de sucesso ou erro). A arquitetura de promessas é ideal para esse tipo de cenário.

### Registrando

O registro inicial de um *service worker* é feito através do método `ServiceWorkerContainer.register()`. Se bem-sucedido, seu *service worker* será descarregado no cliente e então ocorrerá a tentativa de instalação/ativação para as URLs acessadas pelo usuário sob a origem registrada ou, caso deseje, apenas dentro de um subconjunto limitado por você.

### Download, instalação e ativação

Nesse estágio, seu service worker seguirá o seguinte ciclo de vida:

1. Download
2. Instalação
3. Ativação

Quando o usuário acessa pela primeira vez um site ou página controlado por um service worker, ele é descarregado imediatamente.

Após isso, serão feitos novos downloads em intervalos de aproximadamente 24 horas. O download **pode** ocorrer mais frequentemente, mas ele **precisa** ser feito a cada 24 horas para prevenir que scripts ruins sejam um problema por períodos muito extensos.

A tentativa de instalação é feita sempre que o arquivo descarregado é identificado como novo – seja por diferir dos *service workers* pré-existentes (é feita uma comparação binária nessa etapa) ou por ser o primeiro descoberto para a página ou site em questão.

Na primeira vez que um *service worker* é disponibilizado, é feita a tentativa de instalação. Se bem-sucedida, ele é ativado.

Se, por outro lado, já existe um *service worker* pré-instalado para uma página ou site e for disponibilizada uma nova versão, ela será descarregada, mas não imediatamente ativada. Isso é chamado de ***worker* em espera**. Só será efetuada a ativação da versão atualizada quando não houver mais páginas utilizando a anterior. Após isso, ele passa a ser o ***worker* ativo**. Caso necessário, é possível pular a etapa de espera com o método `ServiceWorkerGlobalScope.skipWaiting()` (en-US). Em seguida, o novo worker ativo pode reivindicar as páginas existentes usando `Clients.claim()` (en-US).

Você pode adicionar um *listener* para o evento `InstallEvent` (en-US). Uma ação padrão, quando esse evento é disparado, é preparar o seu *service worker* para ser utilizado (por exemplo: criado um cache usando a API de storage nativa e armazenando nela os *assets* que você quer que permaneçam disponíveis caso a aplicação fique *offline*).

Há também o evento `activate`. O momento em que ele é disparado é geralmente o ideal para limpar caches antigos e outras coisas associadas com a versão anterior do seu *service worker*.

Seu service worker pode responder a requisições usando o `FetchEvent` (en-US). Você pode manipular a resposta a essas requisições da maneira que quiser, através do método `FetchEvent.respondWith` (en-US).

>
> \*\*Nota:\*\*Como `oninstall` e `onactivate` podem demorar a serem concluídos, a especificação de *service workers* disponibiliza um método waitUntil (en-US). Ele recebe como parâmetro uma promessa, notificando o navegador que há trabalho em andamento até que aquela promessa seja resolvida. O navegador, portanto, não deverá encerrar o service worker durante esse período de espera.
>
>
>

Para um tutorial completo, mostrando como construir seu primeiro exemplo do zero, leia Usando Service Workers (en-US).

Outras ideias de usos possíveis
-------------------------------

* Sincronização de dados em *background*
* Responder a requisições de recursos a partir de outras origens
* Receber de forma centralizada atualizações para dados de cálculo mais custoso, como geolocalização ou giroscópio, de forma a permitir que múltiplas páginas façam uso de um único conjunto de dados.
* No lado do cliente, fazer compilação e gerenciamento de dependências para CoffeeScript, LESS, módulos CommonJS/AMD, entre outros.
* *Hooks* para serviços em *background*.
* Templates customizados com base em certos padrões de URL.
* Melhorias de performance como, por exemplo, fazer o pré-carregamento de recursos que o usuário provavelmente irá precisar a curto prazo, como as próximas fotos de um álbum.

No futuro, service workers serão capazes de fazer várias outras coisas úteis para a plataforma web, deixando-a mais próxima de *apps* nativos em.

É interessante mencionar que outras especificações podem e irão passar a usar o contexto de service workers, por exemplo:

* Sincronização em background: Iniciar um service worker mesmo quando não há usuários no site, de forma que o cache possa ser atualizado;
* Reagir a mensagens push: Iniciar um service worker para enviar uma mensagem aos usuários dizendo que há conteúdo novo disponível;
* Reagir a uma data/hora específica;
* Entrar em uma geo-fence.
Interfaces
----------

`Cache`

Representa o armazenamento para os pares de objeto `Request` e `Response`, os quais são cacheados como parte do ciclo de vida do `ServiceWorker` (en-US).

`CacheStorage` (en-US)

Representa o armazenamento para objetos `Cache`. Ele disponibiliza um diretório-mestre com todos os caches nomeados que um `ServiceWorker` (en-US) pode acessar, mantendo o mapeamento de nomes para os objetos `Cache` correspondentes.

`Client` (en-US)

Representa o escopo do cliente de um *service worker*. Um cliente pode ser um documento no contexto de um navegador ou um `SharedWorker` (en-US), o qual é controlado por um *worker* ativo.

`Clients` (en-US)

Representa o container para uma lista de objetos `Client` (en-US). É a principal forma de acessar os clientes na origem atual para o *service worker* ativo.

`ExtendableEvent` (en-US)

Estende a vida dos eventos `install` e `activate` disparados no `ServiceWorkerGlobalScope` (en-US), como parte do ciclo de vida do *service worker*. Isso garante que qualquer evento funcional (como o `FetchEvent` (en-US)) não seja despachado para o `ServiceWorker` (en-US) até que ele conclua as ações em andamento, como por exemplo: atualizar esquemas de banco de dados, apagar caches defasados, etc.

`ExtendableMessageEvent` (en-US)

O objeto de evento do `message`, o qual é disparado em um *service worker* (quando uma mensagem de canal é recebida no `ServiceWorkerGlobalScope` (en-US) a partir de outro contexto) — estende o tempo de vida desses eventos.

`FetchEvent` (en-US)

O parâmetro recebido no *handler* `ServiceWorkerGlobalScope.onfetch`. O `FetchEvent` representa uma ação de descarregamento que é despachada no `ServiceWorkerGlobalScope` (en-US) de um `ServiceWorker` (en-US). Ele contém informações sobre a requisição e a resposta resultante, além de disponibilizar o método `FetchEvent.respondWith()` (en-US), o qual nos permite devolver uma resposta customizada para a página que está sendo controlada.

`InstallEvent` (en-US)

O parâmetro recebido no *handler* `oninstall`. A interface `InstallEvent` representa uma ação de instalação que é despachada no `ServiceWorkerGlobalScope` (en-US) de um `ServiceWorker` (en-US). Como deriva do `ExtendableEvent` (en-US), ele assegura que eventos funcionais, como o `FetchEvent` (en-US), não sejam despachados durante a instalação.

`NavigationPreloadManager` (en-US)

Disponibiliza métodos para gerenciar o pré-carregamento de recursos com um *service worker.*

`Navigator.serviceWorker` (en-US)

Retornar um objeto `ServiceWorkerContainer` (en-US), o qual permite accesso ao registro, remoção, atualização e comunicação com os objetos `ServiceWorker` (en-US) para o documento associado.

`NotificationEvent` (en-US)

O parâmetro recebido no *handler* `onnotificationclick`. A interface `NotificationEvent` representa um evento de *click* em uma notificação que é despachado no `ServiceWorkerGlobalScope` (en-US) de um `ServiceWorker` (en-US).

`ServiceWorker` (en-US)

Representa um *service worker*. Diferentes contextos de navegação (ex: páginas, *workers*, etc.) podem ser associados com o mesmo objeto `ServiceWorker`.

`ServiceWorkerContainer` (en-US)

Disponibiliza um objeto representando o service worker como uma unidade global no ecossistema de rede, incluindo métodos para registrar, desregistrar e atualizar *service workers*, além de poder acessar o status de cada *worker* e seus registros.

`ServiceWorkerGlobalScope` (en-US)

Representa o contexto de execução global de um *service worker*.

`ServiceWorkerMessageEvent` (en-US)
Deprecated

Representa uma mensagem enviada a um `ServiceWorkerGlobalScope` (en-US). **Vale ressaltar que essa interface está defasada em navegadores modernos. As mensagens de *service worker* agora usam a interface `MessageEvent` (en-US) para manter consistência com outras funcionalidades de messageria da web.**

`ServiceWorkerRegistration` (en-US)

Representa o registro de um *service worker*.

`ServiceWorkerState` (en-US)
Experimental

Associado com o estado do `ServiceWorker` (en-US).

`SyncEvent` (en-US)
Non-standard

A interface SyncEvent representa uma ação de sincronização que é despachada no `ServiceWorkerGlobalScope` (en-US) de um ServiceWorker.

`SyncManager` (en-US)
Non-standard

Disponibiliza uma interface para registrar e listar registros de sincronização.

`WindowClient` (en-US)

Representa o escopo de um cliente de *service worker* que é um documento em um contexto de navegador, o qual é controlado por um *worker* ativo. Esse é um tipo especial de objeto `Client` (en-US), como alguns métodos e propriedades adicionais disponíveis.

Especificações
--------------

| Specification |
| --- |
| Service Workers  |

Compatibilidade com navegadores
-------------------------------

{{Compat}}Veja também
-----------

* ServiceWorker Cookbook
* Using Service Workers (en-US)
* Service workers basic code example
* Is ServiceWorker ready?
* Promises
* Using web workers (en-US)
* Best Practices for using the VARY header