WebRTC API - APIs da Web

WebRTC API
==========

**WebRTC** (Web Real-Time Communications) é uma tecnologia que permite aplicativos e sites da Web a capturarem e opcionalmente transmitirem mídia de áudio e/ou vídeo, assim como trocar informação arbitrária entre navegadores sem a necessidade de um intermediador. O conjunto de padrões que abrangem WebRTC possibilita o compartilhamento de informação e a realização de teleconferência peer-to-peer, dispensando a instalação de *plug-ins* ou quaisquer softwares de terceiros.

WebRTC consiste em diversas APIs e protocolos interrelacionados que trabalham juntos. A documentação que você encontrará aqui o ajudará a entender os fundamentos de WebRTC, como configurar e usar, tanto informação, quanto conexões de mídia e mais.

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

WebRTC serve à diversas propostas; junto com a Media Capture and Streams API (en-US), eles fornecem poder multimídia para a Web, incluindo suporte para áudio e vídeo conferência, troca de arquivos, compartilhamento de tela, gerenciamento de identidade e interface com sistemas telefônicos legados, incluindo suporte para envio de sinais DTMF (en-US) (touch-tone dialing). As conexões entre pares podem ser feitas sem a necessidade de drivers ou plug-ins especiais e, muitas vezes, sem servidores intermediários.

As conexões entre dois pares são representadas pela interface `RTCPeerConnection` (en-US). Uma vez que uma conexão foi estabelecida e aberta usando `RTCPeerConnection`, *streams* de mídia (`MediaStream` (en-US)s) e/ou canais de dados (`RTCDataChannel`s) podem ser adicionados à conexão.

Dados de mídia podem consistir em qualquer número de *tracks*(faixas) de dados de mídia; *tracks*, que são representados por objetos baseados na interface `MediaStreamTrack` (en-US) , que podem conter um número dentre tipos de dados de mídia, incluíndo áudio, vídeo e texto (como legendas ou até mesmo nomes de capítulos). A maioria das transmissões consiste de ao menos uma faixa de áudio e comumente também uma faixa de vídeo, e podem ser usadas para enviar e receber ambas as mídias ao vivo ou dados salvos de mídia (como um filme transmitido).

Você também pode usar a conexão entre dois *peers* para trocar dados arbitrários binários usando a interface `RTCDataChannel`. Isto pode ser usado para informação de *back-channel* (canal de volta), troca de *metadata*, pacotes de *status* de games, transferência de arquivos, ou até mesmo como um canal primário para transferir dados.

### Interoperabilidade

O WebRTC é geralmente bem suportado em navegadores modernos, mas algumas incompatibilidades permanecem. A biblioteca adapter.js é um calço para isolar aplicativos dessas incompatibilidades.

Referência WebRTC
-----------------

WebRTC provê interfaces que trabalham em conjunto para realizar uma variedade de tarefas, nós dividimos as interfaces na listagem abaixo por categoria. Por favor, atente-se a sidebar para uma listagem em ordem alfabética.

### Configuração e gerenciamento e conexão

Essas interfaces, dicionários e tipos são usados para configurar, abrir e gerenciar conexões WebRTC. Estão inclusas as interfaces que representam conexões de mídia de mesmo nível, canais de dados e interfaces usadas ao trocar informações sobre as capacidades de cada par para selecionar a melhor configuração possível para uma conexão de mídia bidirecional.

#### Interfaces

`RTCPeerConnection` (en-US)

Representa uma conexão WebRTC entre o computador local e um ponto remoto. Ele é usado para lidar com o streaming eficiente de dados entre os dois pares.

`RTCDataChannel`

Representa um canal de dados bidirecional entre dois pares de uma conexão.

`RTCDataChannelEvent` (en-US)

Representa eventos que ocorrem ao anexar um `RTCDataChannel` a um `RTCPeerConnection` (en-US). O único evento enviado com esta interface é `datachannel` (en-US).

`RTCSessionDescription` (en-US)

Representa os parâmetros de uma sessão. Cada `RTCSessionDescription` consiste em uma descrição `type` (en-US) indicando qual parte do processo de negociação de oferta/resposta ela descreve e do descritor SDP da sessão.

`RTCStatsReport` (en-US)

Fornece estatísticas detalhadas de informações para uma conexão ou para uma *track* individual na conexão; o relatório pode ser obtido chamando `RTCPeerConnection.getStats()` (en-US). Detalhes sobre o uso de estatísticas WebRTC podem ser encontrados em WebRTC Statistics API.

`RTCIceCandidate` (en-US)

Representa um servidor *Interactive Connectivity Establishment* (Estabelecimento de Conectividade Interativa) candidato (ICE (en-US)) para estabelecer um `RTCPeerConnection` (en-US).

`RTCIceTransport`

Representa informações sobre um transporte ICE (en-US).

`RTCPeerConnectionIceEvent` (en-US)

Representa eventos que ocorrem em relação aos candidatos ICE com o destino, geralmente um `RTCPeerConnection` (en-US). Apenas um evento é deste tipo: `icecandidate` (en-US).

`RTCRtpSender` (en-US)

Gerencia a codificação e a transmissão de dados para um `MediaStreamTrack` (en-US) em um `RTCPeerConnection` (en-US).

`RTCRtpReceiver` (en-US)

Gerencia a recepção e decodificação de dados para um `MediaStreamTrack` (en-US) em um `RTCPeerConnection` (en-US).

`RTCTrackEvent` (en-US)

A interface usada para representar um evento `track` (en-US), que indica que um objeto `RTCRtpReceiver` (en-US) foi adicionado ao `RTCPeerConnection` (en-US), indicando que um novo `MediaStreamTrack` (en-US) de entrada foi criado e adicionado ao `RTCPeerConnection`.

`RTCSctpTransport` (en-US)

Fornece informações que descrevem um transporte de *Stream Control Transmission Protocol ou **SCTP (en-US)*** (Protocolo de Transmissão de Controle de Fluxo) e também fornece uma maneira de acessar a segurança da *Datagram Transport Layer Security ou **DTLS (en-US)*** (Camada de Transporte de Datagrama Subjacente) através do qual os pacotes SCTP para todos os canais de dados de uma `RTCPeerConnection` (en-US) são enviados e recebidos.

#### Dicionários

`RTCIceServer` (en-US)

Define como se conectar a um único servidor ICE (en-US) (como um servidor STUN (en-US) ou TURN (en-US)).

`RTCRtpContributingSource` (en-US)

Contém informações sobre uma determinada *fonte de contribuição (CSRC)*, incluindo a hora mais recente em que um pacote para o qual a fonte contribuiu foi reproduzido.

#### Eventos

`bufferedamountlow` (en-US)

A quantidade de dados atualmente armazenados em buffer pelo canal de dados — conforme indicado por sua propriedade `bufferedAmount` (en-US) — diminuiu para ficar igual ou inferior ao tamanho mínimo de dados em buffer do canal, conforme especificado por `bufferedAmountLowThreshold` (en-US).

`close` (en-US)

O canal de dados concluiu o processo de fechamento e agora está no estado 'fechado'. Seu transporte de dados subjacente está completamente fechado neste ponto. Você pode ser notificado *antes* do fechamento, observando o evento `closing`.

`closing` (en-US)

O `RTCDataChannel` fez a transição para o estado `closing`, indicando que será fechado em breve. Você pode detectar a conclusão do processo de fechamento observando o evento `close`.

`connectionstatechange` (en-US)

O estado da conexão foi alterado, pode ser acessada em `connectionState`.

`datachannel` (en-US)

Um novo `RTCDataChannel` está disponível após o peer remoto abrir um novo canal de dados. O tipo deste evento é `RTCDataChannelEvent` (en-US).

`error` (en-US)

Um `RTCErrorEvent` (en-US) indicando que ocorreu um erro no canal de dados.

`error` (en-US)

Um `RTCErrorEvent` (en-US) indicando que ocorreu um erro no `RTCDtlsTransport` (en-US). Este erro será `dtls-failure` ou `fingerprint-failure`.

`gatheringstatechange` (en-US)

O estado de coleta do `RTCIceTransport` mudou.

`icecandidate` (en-US)

Um `RTCPeerConnectionIceEvent` (en-US) que é enviado sempre que o dispositivo local identifica um novo candidato ICE que precisa ser adicionado ao par local chamando `setLocalDescription()` (en-US).

`icecandidateerror` (en-US)

Um `RTCPeerConnectionIceErrorEvent` (en-US) indicando que ocorreu um erro durante a coleta de candidatos ICE.

`iceconnectionstatechange` (en-US)

Enviado para um `RTCPeerConnection` (en-US) quando o estado de sua conexão ICE - encontrado na propriedade `iceconnectionstate` (en-US) - muda.

`icegatheringstatechange` (en-US)

Enviado para um `RTCPeerConnection` (en-US) quando seu estado de coleta de ICE - encontrado na propriedade `icegatheringstate` (en-US) - muda.

`message` (en-US)

Uma mensagem foi recebida no canal de dados. O evento é do tipo `MessageEvent` (en-US).

`negotiationneeded` (en-US)

Informa ao `RTCPeerConnection` que ele precisa realizar negociação de sessão chamando `createOffer()` (en-US) seguido por `setLocalDescription()` (en-US).

`open` (en-US)

O transporte de dados subjacente para o `RTCDataChannel` foi aberto ou reaberto com sucesso.

`selectedcandidatepairchange` (en-US)

O par atualmente selecionado de candidatos ICE foi alterado para o `RTCIceTransport` no qual o evento é disparado.

`track` (en-US)

O evento `track`, do tipo `RTCTrackevent` (en-US) é enviado para um `RTCPeerConnection` (en-US) quando uma nova trilha é adicionada à conexão após a negociação bem-sucedida da mídia transmissão.

`signalingstatechange` (en-US)

Enviado para a conexão de mesmo nível quando seu `signalingstate` (en-US) foi alterado. Isso acontece como resultado de uma chamada para `setLocalDescription()` (en-US) ou `setRemoteDescription()` (en-US).

`statechange`

O estado do `RTCDtlsTransport` mudou.

`statechange` (en-US)

O estado do `RTCIceTransport` mudou.

`statechange` (en-US)

O estado do `RTCSctpTransport` mudou.

#### Tipos

`RTCSctpTransport.state` (en-US)

Indica o estado de uma instância `RTCSctpTransport` (en-US).

### Identidade e segurança

A API WebRTC inclui várias interfaces para gerenciar segurança e identidade.

`RTCIdentityProvider`

Permite que um agente de usuário possa solicitar que uma declaração de identidade seja gerada ou validada.

`RTCIdentityAssertion` (en-US)

Representa a identidade de um ponto remoto da conexão atual. Se nenhum par ainda foi definido e verificado, esta interface retorna `null`. Uma vez definido, não pode ser alterado.

`RTCIdentityProviderRegistrar`

Registra um provedor de identidade (idP).

`RTCCertificate`

Representa um certificado que um `RTCPeerConnection` (en-US) usa para autenticar.

### Telefonia

Essas interfaces e eventos estão relacionadas à interatividade com redes telefônicas públicas comutadas (PTSNs) Elas são primariamente usadas para enviar sons de discagem por tom - ou pacotes que representam esses tons - pela rede para um par remoto.

#### Interfaces

`RTCDTMFSender` (en-US)

Gerencia a codificação e a transmissão da sinalização de multifrequência de tom duplo (DTMF (en-US)) para um `RTCPeerConnection` (en-US).

`RTCDTMFToneChangeEvent` (en-US)

Usado pelo evento `tonechange` (en-US) para indicar que um tom DTMF começou ou terminou. Este evento não propaga "bolhas" (exceto onde indicado de outra forma) e não é cancelável (exceto onde indicado de outra forma).

#### Eventos

`tonechange` (en-US)

Um novo tom DTMF (en-US) começou a tocar na conexão, ou o último tom no `toneBuffer` (en-US) do `RTCDTMFSender` foi enviado e o buffer agora está vazio. O tipo do evento é `RTCDTMFToneChangeEvent` (en-US).

Guias
-----

Introdução aos protocolos WebRTC

Este artigo apresenta os protocolos sobre os quais a API WebRTC é construída.

Conectividade WebRTC (en-US)

Um guia de como as conexões WebRTC funcionam e como os vários protocolos e interfaces podem ser usados juntos para criar aplicativos de comunicação poderosos.

Vida útil de uma sessão WebRTC (en-US)

WebRTC permite criar comunicação *peer-to-peer* de dados arbitrários, áudio ou vídeo — ou qualquer combinação deles — em um aplicativo de navegador. Neste artigo, veremos o tempo de vida de uma sessão WebRTC, desde o estabelecimento da conexão até o fechamento da conexão quando ela não for mais necessária.

Estabelecendo uma conexão: O padrão de negociação perfeito (en-US)

**Negociação perfeita** é um padrão de design recomendado para o seu processo de sinalização, que fornece transparência na negociação enquanto permite que ambos os lados sejam o *`offerer`* (ofertante) ou o *`answerer`* (respondente), sem necessidade de muito código para diferenciar os dois.

Sinalização e chamada de vídeo bidirecional (en-US)

Um tutorial e exemplo que transforma um sistema de chat baseado em WebSocket criado para um exemplo anterior e adiciona suporte para abertura de chamadas de vídeo entre os participantes. A conexão WebSocket do servidor de bate-papo é usada para sinalização WebRTC.

Codecs usados pelo WebRTC (en-US)

Um guia para os codecs que o WebRTC exige que os navegadores suportem, bem como os opcionais suportados por vários navegadores populares. Está incluído um guia para ajudá-lo a escolher os melhores codecs para suas necessidades.

Usando canais de dados WebRTC (en-US)

Este guia aborda como você pode usar uma conexão de mesmo nível e um `RTCDataChannel` associado para trocar dados arbitrários entre dois pares.

Usando DTMF com WebRTC (en-US)

O suporte do WebRTC para interagir com gateways que se conectam a sistemas telefônicos antigos inclui suporte para enviar tons DTMF usando a interface `RTCDTMFSender` (en-US). Este guia mostra como fazer isso.

Tutoriais
---------

Melhorando a compatibilidade usando o adaptador WebRTC.js (en-US)

A organização WebRTC fornece no GitHub o adaptador WebRTC para solucionar problemas de compatibilidade em implementações WebRTC de diferentes navegadores. O adaptador é um shim JavaScript que permite que seu código seja escrito de acordo com a especificação para que "simplesmente funcione" em todos os navegadores com suporte a WebRTC.

Uma simples amostra de RTCDataChannel

A interface `RTCDataChannel` é um recurso que permite abrir um canal entre dois pares através do qual você pode enviar e receber dados arbitrários. A API é intencionalmente semelhante à API WebSocket, para que o mesmo modelo de programação possa ser usado para cada uma.

Construindo um telefone conectado à Internet com Peer.js (en-US)

Este tutorial é um guia passo a passo sobre como construir um telefone usando Peer.js

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

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers  |
| Media Capture and Streams  |
| Media Capture from DOM Elements  |

### Protocolos adequados para WebRTC

* Negociação de protocolo de camada de aplicativo para comunicações em tempo real na Web (en-US)
* Requisitos de processamento e codec de áudio WebRTC (en-US)
* Canais de dados RTCWeb (en-US)
* Protocolo de Canal de Dados RTCWeb (en-US)
* Comunicação Web em Tempo Real (WebRTC): Transporte de Mídia e Uso de RTP (en-US)
* Arquitetura de segurança WebRTC (en-US)
* Transportes para RTCWEB (en-US)
### Protocolos de suporte relacionados

* Estabelecimento de Conectividade Interativa (ICE): Um Protocolo para Tradutor de Endereço de Rede (NAT) Traversal para Protocolo de Oferta/Resposta (en-US)
* Utilitários de travessia de sessão para NAT (STUN) (en-US)
* Esquema de URI para o protocolo Session Traversal Utilities for NAT (STUN) (en-US)
* Traversal Using Relays around NAT (TURN) Uniform Resource Identifiers (en-US)
* Um modelo de oferta/resposta com protocolo de descrição de sessão (SDP) (en-US)
* Session Traversal Utilities for NAT (STUN) Extension for Third Party Authorization (en-US)
Veja também
-----------

* `MediaDevices`
* `MediaStreamEvent` (en-US)
* `MediaStreamTrack` (en-US)
* `MessageEvent` (en-US)
* `MediaStream` (en-US)
* API de captura de mídia e fluxos (en-US)
* Firefox multistream e renegociação para Jitsi Videobridge (en-US)
* Peering através do WebRTC Fog com SocketPeer (en-US)
* Inside the Party Bus: Construindo um aplicativo da Web com vários fluxos de vídeo ao vivo + gráficos interativos (en-US)
* Tecnologias de mídia da Web (en-US)
* API de estatísticas WebRTC


NodeList - APIs da Web

NodeList
========

Objetos **`NodeList`** são coleções de nodos semelhantes aos objetos retornados pelos métodos `Node.childNodes` e `document.querySelectorAll()`.

**Nota:** Apesar de `NodeList` não ser um `Array`, é possível ser iterada usando o método `forEach()`. Muitos navegadores antigos ainda não implementaram este método.

Em alguns casos, `NodeList` é uma *coleção viva*, ou seja, toda alteração feita no DOM reflete nos elementos da coleção. Por exemplo, `Node.childNodes` é uma coleção viva:

```js
var parent = document.getElementById("parent");
var child_nodes = parent.childNodes;
console.log(child_nodes.length); // let's assume "2"
parent.appendChild(document.createElement("div"));
console.log(child_nodes.length); // should output "3"
```

Já em outros casos `NodeList` é um *coleção estática*, significando que toda alteração subsequente ao DOM não afeta o conteúdo da coleção. `document.querySelectorAll()` é um exemplo de método que retorna uma `NodeList` estática.

É aconselhável lembrar dessa distinção quando for escolher como iterar sobre os itens de uma `NodeList`, e como você faz o *cache* do tamanho dessa lista.

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

`NodeList.length` (en-US)

A quantidade de nodos na `NodeList`.

Métodos
-------

`NodeList.item()` (en-US)

Retorna um item da lista pelo índice, ou `null` se o índice for inválido; pode ser usado como uma alternativa a `nodeList[idx]` (que retorna `undefined` quando `idx` é inválido).

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

Retorna um `iterador` que permite passar por todos os pares chave/valor contidos no objeto.

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

Executa uma função recebida uma vez para cada elemento no `NodeList`.

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

Retorna um `iterador` que permite passar por todas as chaves dos pares chave/valor contidos no objeto.

`NodeList.values()` (en-US)

Retorna um `iterador` que permite passar por todos os valores dos pares chave/valor contidos no objeto.

Exemplo
-------

É possivel iterar sobre os items de um `NodeList` usando:

```js
for (var i = 0; i < myNodeList.length; ++i) {
  var item = myNodeList[i]; // Calling myNodeList.item(i) isn't necessary in JavaScript
}
```

Não caia na tentação de usar for...in ou for each...in para enumerar os items de uma lista, já que também serão enumeradas as propriedades `length` e `item` da `NodeList`, o que causará erros se o seu script assumir que processará apenas objetos `element`. Não esquecendo que `for..in` **não** garante a iteração nas propriedades de forma ordenada.

`for...of` (en-US) iterará sobre os objetos da `NodeList` de maneira correta:

```js
var list = document.querySelectorAll("input[type=checkbox]");
for (var item of list) {
  item.checked = true;
}
```

Navegadores modernos suportam métodos de iteração, `forEach()` (en-US), bem como `entries()` (en-US), `values()` (en-US), e `keys()` (en-US)

Há também um jeito compatível com o Internet Explorer de usar `Array.prototype.forEach` para iteração.

```js
var list = document.querySelectorAll("input[type=checkbox]");
Array.prototype.forEach.call(list, function (item) {
  item.checked = true;
});
```

NodeList prototype
------------------

Você também pode adicionar protótipos para `NodeList`:

```js
var elements = document.querySelectorAll(".suggestions");

NodeList.prototype.addEventListener = function (event, func) {
  this.forEach(function (content, item) {
    content.addEventListener(event, func);
  });
};

function log() {
  console.log(this, " was clicked");
}

elements.addEventListener("click", log);
//or
elements.addEventListener("click", function () {
  console.log(this, " awas clicked");
});
// output from both will be element was clicked the element would be HTML Element
```

Para mais informações sobre forEach veja `Array.prototype.forEach`.

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

| Specification |
| --- |
| DOM Standard # interface-nodelist |

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

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


Seleção - APIs da Web

Seleção
=======

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

Um objeto **`Selection`** representa um intervalo do texto selecionado pelo usuário ou a posição atual do cursor. Para obter o objeto Selection para inspecionar ou modificar, use `Window.getSelection()`.

O usuário pode fazer a seleção da esquerda para a direita (na orientação do documento) ou da direita para a esquerta (orientação inversa do documento). O atributo **anchor (âncora)** é onde o usuário iniciou a seleção e o atributo **focus (foco)** é onde o usuário terminou a seleção. Se você fizer a seleção utilizando um mouse no desktop, o *anchor* é definido onde você pressionou o botão do mouse e o *focus* é definido onde você soltou o botão do mouse. *Anchor* e *focus* não devem ser confundidos com a posição inicial e final da seleção, pois o *anchor* pode ser definido antes do *focus* ou vice versa, dependendo da direção em que você fez sua seleção.

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

`Selection.anchorNode` (en-US)Somente leitura

Retorna o `Node` onde a seleção começou.

`Selection.anchorOffset` (en-US)Somente leitura

Retorna um número representando o deslocamento do anchor dentro do elemento Se o elemento for do tipo text node, o número retornado será o número de caracteres no elemento que precedem o anchor (clique inicial da seleção). Se o elemento for do tipo element (qualquer tag html que não seja text node), o número retornado será o número de nós filhos do elemento que precedem o anchor.

`Selection.focusNode` (en-US)Somente leitura

Retorna o `Node` onde a seleção termina.

`Selection.focusOffset` (en-US)Somente leitura

Retorna um número representando o deslocamento do focus dentro do elemento Se o elemento for do tipo text node, o número retornado será o número de caracteres no elemento que precedem o focus (posição onde o mouse foi solto). Se o elemento for do tipo element (qualquer tag html que não seja text node), o número retornado será o número de nós filhos do elemento que precedem o focus.

`Selection.isCollapsed` (en-US)Somente leitura

Retorna um valor booleano indicando se o início e o final da seleção são a mesma posição, ou seja, começou e terminou no mesmo lugar.

`Selection.rangeCount` (en-US)Somente leitura

Retorna no número de intervalos da seleção.

`Selection.type` (en-US)Somente leitura

Retorna um `DOMString` descrevento o tipo da seleção atual.

Métodos
-------

`Selection.addRange()` (en-US)

Um objeto `Range` (en-US) que será adicionado na seleção.

`Selection.collapse()` (en-US)

Colapsa a seleção atual em um único ponto.

`Selection.collapseToEnd()` (en-US)

Colapsa a seleção para o final do último intervalo na seleção.

`Selection.collapseToStart()` (en-US)

Colapsa a seleção para o início do primeiro intervalo na seleção.

`Selection.containsNode()` (en-US)

Indica se um certo nó é parte da seleção.

`Selection.deleteFromDocument()` (en-US)

Apaga o conteúdo da seleção do documento.

`Selection.empty()` (en-US)

Remove todos os intervalos da seleção. Este é um apelido para `removeAllRanges()` — Veja `Selection.removeAllRanges()` (en-US) para mais detalhes.

`Selection.extend()` (en-US)

Move o focus (final da seleção) para um ponto específico.

`Selection.getRangeAt()` (en-US)

Retorna um objeto `Range` (en-US) represetando um dos intervalos atualmente selecionados.

`Selection.modify()` (en-US)
Non-standard

Altera a seleção atual.

`Selection.removeRange()` (en-US)

Remove um intervalo da seleção.

`Selection.removeAllRanges()` (en-US)

Remove todos os intervalos da seleção.

`Selection.selectAllChildren()` (en-US)

Adiciona todos os filhos do nó especificado para a seleção.

`Selection.setBaseAndExtent()` (en-US)

Define que a seleção será um intervalo incluindo todos ou partes dos dois nós DOM especificados, e qualquer conteúdo entre esses nós.

`Selection.setPosition()` (en-US)

Colapsa a seleção atual para um único ponto. Este é um apelido para `collapse()` — Veja `Selection.collapse()` (en-US) para mais detalhes.

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

Retorna uma string atualmente representada pelo objeto selection, i.e. o texto atualmente selecionado.

Notas
-----

### Representação da seleção em formato de String

Chamando a função `Selection.toString()` (en-US) retorna o texto selecionado, e.g.:

```js
var selObj = window.getSelection();
window.alert(selObj);
```

Perceba que usando um objeto selection como argumento de `window.alert` executará o metodo `toString` automaticamente.

### Multiplos intervalos em uma seleção

 Um objeto selection representa os `intervalos` (en-US) que o usuário selecionou.
 Normalmente é apenas um intervalo, acessado da seguinte forma:

```js
var selObj = window.getSelection();
var range = selObj.getRangeAt(0);
```

* `selObj` é um objeto selection
* `range` é um objeto `Range` (en-US)

Como consta nas Especificações da API de seleção, a API foi inicialmente criada pela Netscape e usados multiplos intervalos, por instância, para permitir ao usuário selecionar uma coluna de uma `<table>`. Outros navegadores como Gecko não implementaram multiplos intervalos, e a especificação exige que a seleção sempre tenha um único intervalo.

### Seleção e foco de input

Seleção e foco de input (indicado por `Document.activeElement`) tem uma relação complexa, que depende do navegador. Para um código compatível com vários navegadores, o melhor é manter os códigos separados.

O Safari e o Chrome (ao contrário do Firefox) historicamente foca no elemento contendo a seleção quando a seleção é modificada programaticamente, mas isto pode mudar no futuro (veja W3C bug 14383 e WebKit bug 38696).

### Comportamento da API de Seleção em termos de edição e alterações de foco do host

A API de Seleção tem um comportamento comum (i.e. compartilhado entre navegadores) que define como o comportamento do foco muda para **elemento editável**, após alguns desses métodos serem executados.

Os comportamentos são que um elemento editado recebe o foco se anteriormente a seleção estiver fora dele, então um método da API de seleção é executado e causa uma nova seleção que será feita em um único intervalo dentro do elemento sendo editado. O foco então é movido para o final do elemento.

**Nota:** Os métodos da API de seleção, move o foco apenas para o elemento sendo editado, não para outro elemento que pode receber o foco (e.g. `<a>`).

O comportamento acima é aplicado para as seleções feitas usando os seguintes métodos:

* `Selection.collapse()` (en-US)
* `Selection.collapseToStart()` (en-US)
* `Selection.collapseToEnd()` (en-US)
* `Selection.extend()` (en-US)
* `Selection.selectAllChildren()` (en-US)
* `Selection.addRange()` (en-US)
* `Selection.setBaseAndExtent()` (en-US)

e quando o intervalo é modificado usando os seguintes métodos:

* `Range.setStart()` (en-US)
* `Range.setEnd()` (en-US)
* `Range.setStartBefore()` (en-US)
* `Range.setStartAfter()` (en-US)
* `Range.setEndBefore()` (en-US)
* `Range.setEndAfter()` (en-US)
* `Range.collapse()` (en-US)
* `Range.selectNode()` (en-US)
* `Range.selectNodeContents()` (en-US)
### Glossário

Outras palavras chaves usadas nesta seção.

anchor

O anchor de uma seleção é o ponto inicial da seleção. Quando a seleção é feita com um mouse, é onde o botão do mouse é inicialmente pressionado. Quando o usuário altera a seleção usando o mouse ou teclado, o anchor não move.

Elemento editável

Um elemento editável — i.e. um elemento HTML com o atributo `contenteditable` definido, ou o HTML filho de um documento estiver com o `designMode` habilitado.

foco de uma seleção

O foco da seleção é o ponto final da seleção. Quando feita a seleção com um mouse, o focus é onde o botão do mouse foi solto. Quando o usuário muda a seleção usando o mouse ou teclado, o focus é o final da seleção que move. **Nota:** Não é o mesmo que o elemento selecionado do documento, como retornado em `document.activeElement`.

intervalo

Um intervalo é uma parte contínua do documento. Um intervalo pode conter nós inteiros ou partes de nós, como uma parte de um text node. Um usuário normalmente irá selecionar um único intervalo por vez, mas é possível que o usuário selecione multiplos intervalos (e.g. usando a tecla Control). Um intervalo pode ser obtido de uma seleção como um objeto `range` (en-US). Um objeto de intervalo pode ser criado no DOM e programaticamente adicionada ou removida de uma seleção.

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

| Specification |
| --- |
| Selection API # selection-interface |

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

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

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

* `Window.getSelection`, `Document.getSelection`, `Range` (en-US)
* Selection-related events: `selectionchange` and `selectstart`
* HTML inputs provide simpler helper APIs for working with selection (see `HTMLInputElement.setSelectionRange()`)
* `Document.activeElement`, `HTMLElement.focus()` (en-US), and `HTMLElement.blur()` (en-US)


Storage - APIs da Web

Storage
=======

A interface de Armazenamento da Web Storage API fornece acesso ao armazenamento de sessão ou armazenamento local para um domínio específico, permitindo que você, por exemplo, adicione, modifique ou exclua itens de dados armazenados.

Se você quiser manipular o armazenamento de sessão para um domínio, você chama o método `Window.sessionStorage`; Se você quiser manipular o armazenamento local para um domínio, você chama `Window.localStorage`.

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

`Storage.length` Somente leitura

Retorna um número inteiro que representa o número de itens de dados armazenados no objeto Storage.

Métodos
-------

`Storage.key()`

Quando passado um número n, este método retornará o nome da n-ésima chave no armazenamento..

`Storage.getItem()`

Quando passado um nome de chave, retornará o valor dessa chave.

`Storage.setItem()`

Quando passado um nome de chave e valor, irá adicionar essa chave para o armazenamento, ou atualizar o valor dessa chave, se já existir.

`Storage.removeItem()`

Quando passado um nome de chave, irá remover essa chave do armazenamento.

`Storage.clear()`

Quando chamado, irá esvaziar todas as chaves fora do armazenamento.

Exemplos
--------

Aqui acessamos um objeto Storage chamando localStorage. Primeiro testamos se o armazenamento local contém itens de dados usando! localStorage.getItem ('bgcolor'). Se isso acontecer, executaremos uma função chamada setStyles () que agarra os itens de dados usando `localStorage.getItem()` E usa esses valores para atualizar estilos de página. Se não, executamos outra função, populateStorage (), que usa `localStorage.setItem()` Para definir os valores do item, em seguida, executa setStyles ().

```js
if (!localStorage.getItem("bgcolor")) {
  populateStorage();
} else {
  setStyles();
}

function populateStorage() {
  localStorage.setItem("bgcolor", document.getElementById("bgcolor").value);
  localStorage.setItem("font", document.getElementById("font").value);
  localStorage.setItem("image", document.getElementById("image").value);

  setStyles();
}

function setStyles() {
  var currentColor = localStorage.getItem("bgcolor");
  var currentFont = localStorage.getItem("font");
  var currentImage = localStorage.getItem("image");

  document.getElementById("bgcolor").value = currentColor;
  document.getElementById("font").value = currentFont;
  document.getElementById("image").value = currentImage;

  htmlElem.style.backgroundColor = "#" + currentColor;
  pElem.style.fontFamily = currentFont;
  imgElem.setAttribute("src", currentImage);
}
```

**Nota:** Para ver isso funcionando como um exemplo completo de trabalho, consulte nossa Demonstração de armazenamento na Web.

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

| Specification |
| --- |
| HTML Standard # storage |

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

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

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

Using the Web Storage API


SpeechSynthesis - APIs da Web

SpeechSynthesis
===============

**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 **`SpeechSynthesis`** da Web Speech API (en-US) é a interface controladora para o serviço de fala; este pode ser usado para obter informações sobre as vozes sintetizadas disponíveis no dispositivo, reproduzir e pausar uma elocução, além de outros comandos.

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

*`SpeechSynthesis` também herda propriedades da sua interface pai, `EventTarget`.*

`SpeechSynthesis.paused` (en-US) Somente leitura

Um `Boolean` (en-US) que retorna `true` se o objeto `SpeechSynthesis` está em estado de pausa.

`SpeechSynthesis.pending` (en-US) Somente leitura

Um `Boolean` (en-US) que retorna `true` se a fila de elocuções contém falas que ainda não foram reproduzidas.

`SpeechSynthesis.speaking` (en-US) Somente leitura

Um `Boolean` (en-US) que retorna `true` se uma elocução está sendo reproduzida atualmente — mesmo que `SpeechSynthesis` esteja em estado de pausa.

### Tratamento de eventos

`SpeechSynthesis.onvoiceschanged` (en-US)

Disparado quando a lista de objetos `SpeechSynthesisVoice` (en-US) que pode ser retornada pelo método `SpeechSynthesis.getVoices()` (en-US) mudou.

Métodos
-------

*`SpeechSynthesis` também herda métodos da sua interface pai, `EventTarget`.*

`SpeechSynthesis.cancel()` (en-US)

Remove todas as elocuções da fila para reprodução.

`SpeechSynthesis.getVoices()` (en-US)

Retorna uma lista de objetos `SpeechSynthesisVoice` (en-US) representando todas as vozes disponíveis no dispositivo atuall

`SpeechSynthesis.pause()` (en-US)

Deixa o objeto `SpeechSynthesis` em estado de pausa.

`SpeechSynthesis.resume()` (en-US)

Retira o estado de pausa do objeto `SpeechSynthesis`: retoma a reprodução se ele estiver pausado.

`SpeechSynthesis.speak()` (en-US)

Adiciona uma `utterance` (en-US) à fila de reprodução; ela será reproduzida assim que todas as elocuções enfileiradas anteriormente tenham sido reproduzidas.

Exemplos
--------

Na nossa demonstração básica Speech synthesiser demo, nós primeiro pegamos uma referência para o controlador SpeechSynthesis usando `window.speechSynthesis`. Após definir algumas variáveis necessárias, nós obtemos uma lista de vozes disponíveis usando o método `SpeechSynthesis.getVoices()` (en-US) usando-as para popular um menu de seleção de forma que o usuário possa escolher a voz que desejar.

Dentro do tratamento `inputForm.onsubmit`, nós impedimos a submissão do formulário com preventDefault(), instanciamos uma `SpeechSynthesisUtterance` (en-US) contendo o texto presente no `<input>`, atribuímos a voz da elocução para a voz selecionada no elemento `<select>`, e iniciamos a reprodução da elocução através do método `SpeechSynthesis.speak()` (en-US).

```js
var synth = window.speechSynthesis;

var inputForm = document.querySelector("form");
var inputTxt = document.querySelector(".txt");
var voiceSelect = document.querySelector("select");

var pitch = document.querySelector("#pitch");
var pitchValue = document.querySelector(".pitch-value");
var rate = document.querySelector("#rate");
var rateValue = document.querySelector(".rate-value");

var voices = [];

function populateVoiceList() {
  voices = synth.getVoices();

  for (i = 0; i < voices.length; i++) {
    var option = document.createElement("option");
    option.textContent = voices[i].name + " (" + voices[i].lang + ")";

    if (voices[i].default) {
      option.textContent += " -- DEFAULT";
    }

    option.setAttribute("data-lang", voices[i].lang);
    option.setAttribute("data-name", voices[i].name);
    voiceSelect.appendChild(option);
  }
}

populateVoiceList();
if (speechSynthesis.onvoiceschanged !== undefined) {
  speechSynthesis.onvoiceschanged = populateVoiceList;
}

inputForm.onsubmit = function (event) {
  event.preventDefault();

  var utterThis = new SpeechSynthesisUtterance(inputTxt.value);
  var selectedOption = voiceSelect.selectedOptions[0].getAttribute("data-name");
  for (i = 0; i < voices.length; i++) {
    if (voices[i].name === selectedOption) {
      utterThis.voice = voices[i];
    }
  }
  utterThis.pitch = pitch.value;
  utterThis.rate = rate.value;
  synth.speak(utterThis);

  inputTxt.blur();
};
```

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

| Specification |
| --- |
| Web Speech API # tts-section |

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)


Animation - APIs da Web

Animation
=========

Baseline 2022
-------------

Newly availableSince September 2022, 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
**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 **`Animation`** da Web Animations API (en-US) representa um único player de animação e fornece controles e uma linha do tempo (timeline) para um nó de animação ou recurso.

Construtor
----------

`Animation()` (en-US)

Cria uma nova instância do objeto `Animation`.

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

`Animation.currentTime`

O valor do tempo atual da animação, em milissegundos, esteja ela executando ou pausada. Se a animação não tem uma `timeline` (en-US), está inativa ou ainda não foi executada, este valor é `null`.

`Animation.effect` (en-US)

Obtém e define o `KeyframeEffect` (en-US) associado a essa animação.

`Animation.finished` (en-US) Somente leitura

Retorna a `Primise` de finalização atual para essa animação.

`Animation.id` (en-US)

Obtém e define a `String` usada para identificar a animação.

`Animation.oncancel` (en-US)

Obtém e define o manipulador para o evento `cancel`.

`Animation.onfinish` (en-US)

Obtém e define o manipulador para o evento `finish`.

`Animation.playState` Somente leitura

Retorna um valor enumerado descrevendo o estado de execução de uma animação.

`Animation.playbackRate` (en-US)

Obtém ou define a taxa de execução da animação.

`Animation.ready` (en-US) Somente leitura

Retorna a promessa atual para quando essa animação estiver pronta.

`Animation.startTime` (en-US)

Obtém ou define o tempo agendado quando a execução de uma animação deve começar.

`Animation.timeline` (en-US)

Obtém ou define a `timeline` (en-US) associada a essa animação.

Métodos
-------

`Animation.cancel()`

Limpa todos os `keyframeEffects` (en-US) causados por essa animação e aborta sua execução.

`Animation.finish()` (en-US)

Vai até um dos extremos dessa animação, dependendo se ela está executando ou retornando.

`Animation.pause()` (en-US)

Suspende a execução de uma animação.

`Animation.play()` (en-US)

Inicia ou continua a execução de uma animação ou a recomeça se ela tiver terminado anteriormente.

`Animation.reverse()` (en-US)

Move a animação ao contrário, parando no início da animação.

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

| Specification |
| --- |
| Web Animations # the-animation-interface |

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

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


Exemplo Avançado - APIs da Web

Exemplo Avançado
================

Exemplo Avançado
----------------

O exemplo avançado apresentará vários tipos de divs baseado em seu conteúdo. O exemplo permite tipificar o conteúdo muitas vezes, alternando entre tipos ascendente ou descendente. O JavaScript apenas carrega o arquivo .xsl a primeira vez, e prepara a variável `xslloaded` verdadeira (true) assim que o arquivo tiver terminado de carregar. Usando o método `getParameter` no obejto `XSLTProcessor`, o código pode decidir pelo tipo ascendente ou descendente. Se o parâmetro estiver vazio o padrão é ascendente (primeira vezes que o tipo aparece, como não há valor para isto no aarquivo XSLT). O valor do tipo é colocado usando `setParameter`.

The XSLT file has a parameter called `myOrder` that JavaScript sets to change the sorting method. The `xsl:sort` element's order attribute can access the value of the parameter using `$myOrder`. However, the value needs to be an XPATH expression and not a string, so `{$myOrder}` is used. Using {} evaluates the content as an XPath expression.

Once the transformation is complete, the result is appened to the document, as shown in this example.

**Figure 7 : Sorting based on div contentview example.**

```js
// XHTML Fragment:

<div id="example">
  <div>1</div>
  <div>2</div>
  <div>3</div>
  <div>4</div>
  <div>5</div>
  <div>6</div>
  <div>7</div>
  <div>8</div>
  <div>9</div>
  <div>10</div>
</div>

// JavaScript

var xslRef;
var xslloaded = false;
var xsltProcessor = new XSLTProcessor();
var myDOM;

var xmlRef = document.implementation.createDocument("", "", null);

function sort() {
  if (!xslloaded){
    p = new XMLHttpRequest();
    p.open("GET", "example2.xsl", false);
    p.send(null);

    xslRef = p.responseXML;
    xsltProcessor.importStylesheet(xslRef);
    xslloaded = true;
  }

  // create a new XML document in memory
  xmlRef = document.implementation.createDocument("", "", null);

  // we want to move a part of the DOM from an HTML document to an XML document.
  // importNode is used to clone the nodes we want to process via XSLT - true makes it do a deep clone
  var myNode = document.getElementById("example");
  var clonedNode = xmlRef.importNode(myNode, true);

  // after cloning, we append
  xmlRef.appendChild(clonedNode);

  // set the sorting parameter in the XSL file
  var sortVal = xsltProcessor.getParameter(null, "myOrder");

  if (sortVal == "" || sortVal == "descending")
    xsltProcessor.setParameter(null, "myOrder", "ascending");
  else
    xsltProcessor.setParameter(null, "myOrder", "descending");

  // initiate the transformation
  var fragment = xsltProcessor.transformToFragment(xmlRef, document);

  // clear the contents
  document.getElementById("example").innerHTML = "";

  myDOM = fragment;
  // add the new content from the transformation
  document.getElementById("example").appendChild(fragment)
}

// XSL Stylesheet:

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0" xmlns="https://www.w3.org/1999/xhtml" xmlns:html="https://www.w3.org/1999/xhtml" xmlns:xsl="https://www.w3.org/1999/XSL/Transform">
  <xsl:output method="html" indent="yes" />

  <xsl:param name="myOrder" />

  <xsl:template match="/">

    <xsl:apply-templates select="/div//div">
      <xsl:sort select="." data-type="number" order="{$myOrder}" />
    </xsl:apply-templates>
  </xsl:template>

  <xsl:template match="div">
    <xsl:copy-of select="." />
  </xsl:template>
</xsl:stylesheet>
```


Adicionando conteúdo 2D a um contexto WebGL - APIs da Web

Adicionando conteúdo 2D a um contexto WebGL
===========================================

* « Previous
* Next » (en-US)

Uma vez que você tenha criado um contexto WebGL com sucesso, você pode iniciar a renderizar nele. O mais simples que podemos fazer é desenhar um objeto 2D não texturizado. Então vamos começar por aí, construindo o código necessário para se desenhar um quadrado.

Desenhando a cena
-----------------

A coisa mais importante para se entender antes de começarmos é que, mesmo que estejamos só renderizando um objeto bidimensional nesse exemplo, nós ainda estamos desenhamos em um espaço 3d. Portanto, ainda precisamos estabelecer os shaders que irão criar a cor para a nossa cena simples, assim como desenhar o objeto. Eles irão estabelecer como o quadrado irá aparecer na tela.

### Inicializando os shaders

Shaders são especificados ao usar a Linguagem de Shading OpenGL ES. Com o intuito de tornar mais fácil para manter e atualizar nosso conteúdo, nós podemos escrever nosso código que carrega os shaders para buscá-los no documento HTML, ao invés de termos de criar tudo em JavaScript. Vamos dar uma olhada na nossa rotina `initShaders()`, que cuida dessa tarefa:

```js
function initShaders() {
  var fragmentShader = getShader(gl, "shader-fs");
  var vertexShader = getShader(gl, "shader-vs");

  // Cria o progrma shader

  shaderProgram = gl.createProgram();
  gl.attachShader(shaderProgram, vertexShader);
  gl.attachShader(shaderProgram, fragmentShader);
  gl.linkProgram(shaderProgram);

  // Se falhar ao criar o progrma shader, alerta

  if (!gl.getProgramParameter(shaderProgram, gl.LINK\_STATUS)) {
    alert("Não foi possível inicializar o programa shader.");
  }

  gl.useProgram(shaderProgram);

  vertexPositionAttribute = gl.getAttribLocation(
    shaderProgram,
    "aVertexPosition",
  );
  gl.enableVertexAttribArray(vertexPositionAttribute);
}
```

Dois programas estão sendo inicializados por essa rotina; o primeiro, fragment shader, é carregado a partir do elemento HTML com o id "shader-fs". O segundo, vertex shader, é carregado pelo elemento HTML com o id "shader-vs". Nós vamos analisar a função getShader() no próximo tutorial; Essa rotina, na verdade, lida com a parte de puxar os programas shader da DOM.

Então nós criamos o programa shader chamando do objeto WebGL a função createProgram(), anexamos dois shaders nele e fazemos o link com o programa shader. Depois de fazer isso, o parametro LINK\_STATUS do objeto g1 é checado para ter certeza de que o link foi criado com sucesso; Se sim, nós ativamos o novo programa shader.

### Carregando os shaders da DOM

`A rotina getShader()` busca um programa shader com o nome específico do DOM, retornando o programa shader compilado para o requisitante, ou null se ele não pode ser carregado ou compilado.

```js
function getShader(gl, id) {
  var shaderScript, theSource, currentChild, shader;

  shaderScript = document.getElementById(id);

  if (!shaderScript) {
    return null;
  }

  theSource = "";
  currentChild = shaderScript.firstChild;

  while(currentChild) {
    if (currentChild.nodeType == currentChild.TEXT\_NODE) {
      theSource += currentChild.textContent;
    }

    currentChild = currentChild.nextSibling;
  }
```

Uma vez que o elemento com o ID específico é encontrado, seu texto é lido na variável theSource.

```js
if (shaderScript.type == "x-shader/x-fragment") {
  shader = gl.createShader(gl.FRAGMENT\_SHADER);
} else if (shaderScript.type == "x-shader/x-vertex") {
  shader = gl.createShader(gl.VERTEX\_SHADER);
} else {
  // Tipo de shader desconhecido
  return null;
}
```

Uma vez que o código para o shader tenha sido lido, nós observamos o tipo MIME do objeto shader para determinar se é um sombreamento de vértice (MIME type "x-shader/x-vertex") ou um fragmento de shader (MIME type "x-shader/x-fragment"), em seguinda crie um tipo de shader apropriado para a partir do código fonte recuperado.

```js
  gl.shaderSource(shader, theSource);

  // Compile o programa shader
  gl.compileShader(shader);

  // Veja se ele compila com sucesso
  if (!gl.getShaderParameter(shader, gl.COMPILE\_STATUS)) {
      alert("Um erro ocorreu ao compilar os shaders: " + gl.getShaderInfoLog(shader));
      return null;
  }

  return shader;
}
```

Finalmente, a fonte é passada para o shader e compilada. Se um erro ocorrer enquanto o shader estiver compilando, nós mostraremos um alerta e retornaremos null; Caso contrário, o shader recém compilado é retornado para o requisitante.

### Os shaders

Agora, nós precisamos adicionar os programas shaders ao HTML para descrever nosso documento. Os detalhes sobre como os shaders trabalham estão além do escopo deste artigo, assim como a sintaxe da linguagem do shader.

#### Fragmentos shader

Cada pixel é um poligono chamado de fragmento (fragment) na linguagem GL. O trabalho do fragmento de shader é estabelecer a cor de cada pixel. Ness caso, nós estamos apenas definindo a cor branca para cada pixel.

g1\_FragColor é um construtor de variável GL que é utilizado para a cor do fragmento. Altere seu valor para definir a cor do pixel, como mostrado abaixo.

```html
<script id="shader-fs" type="x-shader/x-fragment">
 void main(void) {
 gl\_FragColor = vec4(1.0, 1.0, 1.0, 1.0);
 }
</script>
```

#### Vértice do shader

A vértice (vertex) do shader define a posição e a forma de cada vértice.

```html
<script id="shader-vs" type="x-shader/x-vertex">
 attribute vec3 aVertexPosition;

 uniform mat4 uMVMatrix;
 uniform mat4 uPMatrix;

 void main(void) {
 gl\_Position = uPMatrix \* uMVMatrix \* vec4(aVertexPosition, 1.0);
 }
</script>
```

Criando um objeto
-----------------

Before we can render our square, we need to create the buffer that contains its vertices. We'll do that using a function we call `initBuffers()`; as we explore more advanced WebGL concepts, this routine will be augmented to create more — and more complex — 3D objects.

```js
var horizAspect = 480.0 / 640.0;

function initBuffers() {
  squareVerticesBuffer = gl.createBuffer();
  gl.bindBuffer(gl.ARRAY\_BUFFER, squareVerticesBuffer);

  var vertices = [
    1.0, 1.0, 0.0, -1.0, 1.0, 0.0, 1.0, -1.0, 0.0, -1.0, -1.0, 0.0,
  ];

  gl.bufferData(gl.ARRAY\_BUFFER, new Float32Array(vertices), gl.STATIC\_DRAW);
}
```

This routine is pretty simplistic given the basic nature of the scene in this example. It starts by calling the `gl` object's `createBuffer()` method to obtain a buffer into which we'll store the vertices. This is then bound to the context by calling the `bindBuffer()` method.

Once that's done, we create a JavaScript array containing the coordinates for each vertex of the square. This is then converted into an array of WebGL floats and passed into the `gl` object's `bufferData()` method to establish the vertices for the object.

Desenhando a cena
-----------------

Once the shaders are established and the object constructed, we can actually render the scene. Since we're not animating anything in this example, our `drawScene()` function is very simple. It uses a few utility routines we'll cover shortly.

```js
function drawScene() {
  gl.clear(gl.COLOR\_BUFFER\_BIT | gl.DEPTH\_BUFFER\_BIT);

  perspectiveMatrix = makePerspective(45, 640.0 / 480.0, 0.1, 100.0);

  loadIdentity();
  mvTranslate([-0.0, 0.0, -6.0]);

  gl.bindBuffer(gl.ARRAY\_BUFFER, squareVerticesBuffer);
  gl.vertexAttribPointer(vertexPositionAttribute, 3, gl.FLOAT, false, 0, 0);
  setMatrixUniforms();
  gl.drawArrays(gl.TRIANGLE\_STRIP, 0, 4);
}
```

The first step is to clear the context to our background color; then we establish the camera's perspective. We set a field of view of 45°, with a width to height ratio of 640/480 (the dimensions of our canvas). We also specify that we only want objects between 0.1 and 100 units from the camera to be rendered.

Then we establish the position of the square by loading the identity position and translating away from the camera by 6 units. After that, we bind the square's vertex buffer to the context, configure it, and draw the object by calling the `drawArrays()` method.

View the complete code | Open this demo on a new page

Operações úteis da Matrix
-------------------------

Matrix operations are complicated enough. Nobody really wants to write all the code needed to handle them on their own. Fortunately, there's Sylvester, a very handy library for handling vector and matrix operations from JavaScript.

The `glUtils.js` file used by this demo is used by a number of WebGL demos floating around on the Web. Nobody seems entirely clear on where it came from, but it does simplify the use of Sylvester even further by adding methods for building special types of matrices, as well as outputting HTML for displaying them.

In addition, this demo defines a few helpful routines to interface with these libraries for specific tasks. What exactly they do is beyond the scope of this demo, but there are plenty of good references on matrices available online; see the See also section for a list of a few.

```js
function loadIdentity() {
  mvMatrix = Matrix.I(4);
}

function multMatrix(m) {
  mvMatrix = mvMatrix.x(m);
}

function mvTranslate(v) {
  multMatrix(Matrix.Translation($V([v[0], v[1], v[2]])).ensure4x4());
}

function setMatrixUniforms() {
  var pUniform = gl.getUniformLocation(shaderProgram, "uPMatrix");
  gl.uniformMatrix4fv(
    pUniform,
    false,
    new Float32Array(perspectiveMatrix.flatten()),
  );

  var mvUniform = gl.getUniformLocation(shaderProgram, "uMVMatrix");
  gl.uniformMatrix4fv(mvUniform, false, new Float32Array(mvMatrix.flatten()));
}
```

Ver Também
----------

* Matrices on Wolfram MathWorld
* Matriz na Wikipedia
* « Previous
* Next » (en-US)


Começando com WebGL - APIs da Web

Começando com WebGL
===================

* Next »

WebGL permite que o contéudo web use uma API baseada em OpenGL ES 2.0 para realizar renderização 3D em um `canvas` HTML em browsers que o suportam sem o uso de plugins. Programas WebGL consistem em um código de controle escrito em JavaScript e códigos de efeitos especiais (shader code) que é executado na Unidade Gráfica de Processamento (GPU) de um computador. Elementos WebGL podem ser utilizados junto com outros elementos HTML e com outras partes da página ou do fundo.

Esse artigo vai introduzir o básico sobre o uso do WebGL. Acredita-se que você já possui entendimento da matemática que envolve os gráficos 3D, e que este artigo não tem a pretensão de tentar ensinar-lhe OpenGL em si.

Os exemplos de código deste tutorial também podem ser encontrados no Exemplos de WebGL no repositório do GitHub.

Preparando-se para renderizar em 3D
-----------------------------------

A primeira coisa que você precisa para para renderização do WebGL, é a inicialização do canvas. O fragmento HTML abaixo declara um canvas em que nosso exemplo será desenhado.

```html
<body>
  <canvas id="glCanvas" width="640" height="480"></canvas>
</body>
```

### Preparando o contexto WebGL

A função `main()` em nosso código JavaScript é chamada quando nosso script é carregado. O objetivo é configurar o contexto do WebGL e começar a renderizar o conteúdo.

```js
main();

//
// começa aqui
//
function main() {
  const canvas = document.querySelector("#glCanvas");
  // Inicializa o contexto GL
  const gl = canvas.getContext("webgl");

  // Só continua se o WebGL estiver disponível e funcionando
  if (!gl) {
    alert(
      "Incapaz de inicializar o WebGL.Seu navegador ou sua máquina não suporta.",
    );
    return;
  }

  // Define a cor para preto totalmente opaca (sem transparência)
  gl.clearColor(0.0, 0.0, 0.0, 1.0);
  // Limpa o buffer de cores com uma cor específica
  gl.clear(gl.COLOR\_BUFFER\_BIT);
}
```

A primeira coisa que nós fazemos aqui é obter a referência para o canvas, atribuindo-a para a variável chamada `canvas`.

Uma vez que nós temos o canvas, nós tentamos obter um WebGLRenderingContext (en-US) para ele chamando o getContext e passando a string `"webgl"`. Se o browser não suportar o webgl `getContext` vai retornar `null` nesse caso nós mostraremos uma mensagem para o usuário e sair.

Se o contexto for inicializado com sucesso, a variável `gl` é nossa referência para ele. Nesse caso, nós altermos a cor para preto, e o contexto para aquela cor (redesenhando o canvas com a cor de fundo).

Nesse ponto, você tem código suficiente para o contexto WebGL ser inicializado com sucesso, e você deve visualizar uma grande caixa preta vazia, pronta e esperando para receber conteúdo.

Veja o código completo | Abra a demo em uma nova página

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

* Uma introdução ao WebGL: Escrito por Luz Caballero, publicado por dev.opera.com. Esse artigo direciona sobre o que o WebGL é, explicando como o WebGL funciona (incluindo o conceito de pipeline de renderização), e introduz algumas bibliotecas do WebGL.
* Fundamentos do WebGL
* Uma introdução para o OpenGL moderno: Uma séroe de bons artigos sobre OpenGL escrita por Joe Groff, provendo uma introdução clara para o OpenGL a partir de sua história até os importantes conceitos de pipeline de gráficos, e também inclui alguns exemplos demonstrativos sobre como o OpenGL funciona. Se você não tem ideia do que seja OpenGL, esse é um bom lugar para começar.
* Next »


Coordinates.altitude - APIs da Web

Coordinates.altitude
====================

**Secure context:** This feature is available only in secure contexts (en-US) (HTTPS), in some or all supporting browsers.

A propriedade **`Coordinates.altitude`** somente-leitura é uma representação do tipo double da altitude em metros, relativo ao nível do mar. O valor é nulo se a implementação não pode fornecer este dado.

Sintaxe
-------
```

alt = coordinates.altitude
```

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

| Specification |
| --- |
| Geolocation API # altitude-and-altitudeaccuracy-attributes |

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

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

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

* Using geolocation (en-US)
* The `Coordinates` interface it belongs to.


Document.bgColor - APIs da Web

Document.bgColor
================

**Deprecated:** This feature is no longer recommended. Though some browsers might still support it, it may have already been removed from the relevant web standards, may be in the process of being dropped, or may only be kept for compatibility purposes. Avoid using it, and update existing code if possible; see the compatibility table at the bottom of this page to guide your decision. Be aware that this feature may cease to work at any time.

A propriedade obsoleta `bgColor` obtém ou atribue a cor de fundo do documento atual.

Sintaxe
-------
```

color = document.bgColor
document.bgColor = color
```

### Parâmetros

* `color` é uma sequência de caracteres representando a cor como uma palavra (p. ex. "red") ou um valor hexadecimal (p. ex. "`#ff0000`").
Exemplo
-------
```

document.bgColor = "darkblue";
```

Notas
-----

O valor padrão para esta propriedade no Firefox é branco (`#ffffff` em hexadecimal).

`document.bgColor` está obsoleto no DOM Level 2 HTML. A alternativa recomendada é fazer uso do atributo CSS `background-color` que pode ser acessado através do DOM com `document.body.style.backgroundColor`. Uma outra alternativa é o `document.body.bgColor`, apesar dessa também estar obsoleta no HTML 4.01 em funcão da alternativa do CSS.


DOMContentLoaded - APIs da Web

DOMContentLoaded
================

O evento `DOMContentLoaded` é acionado quando todo o HTML foi completamente carregado e analisado, sem aguardar pelo CSS, imagens, e subframes para encerrar o carregamento. Um evento muito diferente - `load` (en-US) - deve ser usado apenas para detectar uma página completamente carregada. É um engano comum as pessoas usarem `load` (en-US) quando `DOMContentLoaded` seria muito mais apropriado.

**Nota:** Javascript Síncrono pausa a análise do DOM.

Acelerando
----------

Se você quer que o DOM seja analisado o mais rápido possível após uma requisição do usuário, você deve usar recursos do javascript assíncrono e otimizar o carregamento de folhas de estilo pois, caso contrário, a página será carregada mais lentamente pois muitos itens serão carregados paralelamente, atrasando a visualização da página.

Informações gerais
------------------

Especificação

HTML5

Interface

Event

Propaga

Sim

Cancelável

Sim (embora especificado como evento simples não-cancelável)

Alvo

Document

Ação Default

Nenhuma.

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

| Property | Type | Description |
| --- | --- | --- |
| `target` Somente leitura  | `EventTarget` | Alvo do evento (O topo do DOM). |
| `type` Somente leitura  | `DOMString` | Tipo de evento |
| `bubbles` Somente leitura  | `Boolean` | O evento é por padrão bubbles ou não. |
| `cancelable` Somente leitura  | `Boolean` | O evento pode ser cancelado ou não. |

Exemplo
-------

### Básico

```html
<script>
 document.addEventListener("DOMContentLoaded", function (event) {
 console.log("DOM completamente carregado e analisado");
 });
</script>
```

### Forçando o atraso do DOMContentLoaded

```html
<script>
 document.addEventListener("DOMContentLoaded", function (event) {
 console.log("DOM completamente carregado e analisado");
 });

 for (var i = 0; i < 1000000000; i++) {} // este script síncrono irá o atrasar carregamento do DOM. Então o evento DOMContentLoaded irá ser ativado mais tarde.
</script>
```

### Verificando se o carregamento está completo

`DOMContentLoaded` pode disparar antes do seu script ser carregado, então é importante validar antes de adicionar um listener.
```

function doSomething() {
  console.info("DOM carregado");
}

if (document.readyState === "loading") {  // Ainda carregando
  document.addEventListener("DOMContentLoaded", doSomething);
} else {  // `DOMContentLoaded` foi disparado
  doSomething();
}
```

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

| Specification |
| --- |
| HTML Standard # stop-parsing |

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

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

Eventos Relacionados
--------------------

* `DOMContentLoaded (en-US)`
* `readystatechange (en-US)`
* `load (en-US)`
* `beforeunload (en-US)`
* `unload (en-US)`


document.getElementById() - APIs da Web

document.getElementById()
=========================

Sumário
-------

Retorna a referência do elemento através do seu ID.

Sintaxe
-------
```

var elemento = document.getElementById(id);
```

onde

* `elemento` é uma referência a um objeto `Element`, ou null se um elemento com o ID especificado não estiver contido neste documento.
* `id` é uma string que diferência maiúsculas e minúsculas representando o ID único do elemento sendo procurado.
Exemplo
-------

```html
<!doctype html>
<html>
  <head>
    <title>Exemplo getElementById</title>
    <script>
 function mudarCor(novaCor) {
 var elemento = document.getElementById("para1");
 elemento.style.color = novaCor;
 }
 </script>
  </head>
  <body>
    <p id="para1">Algum texto de exemplo</p>
    <button onclick="mudarCor('blue');">Azul</button>
    <button onclick="mudarCor('red');">Vermelho</button>
  </body>
</html>
```

Notas
-----

Os novatos devem notar que a caixa de 'Id' no nome deste método *deve* estar correta para o código da função - 'getElementByID *não funciona*, por mais natural que possa parecer.

Se não existe um elemento com o id fornecido, esta função retorna `null`. Note que o parâmetro ID diferência maiúsculas e minúsculas. Assim document.getElementById("Main") retornará `null` ao invés do elemento `<div id="main">`, devido a "M" e "m" serem diferentes para o objetivo deste método.

**Elementos que não estão no documento** não são procurados por `getElementById`. Quando criar um elemento e atribuir um ID ao mesmo, você deve inserir o elemento na árvore do documento com `insertBefore` (en-US) ou método similar antes que você possa acessá-lo com `getElementById`:

```js
var elemento = document.createElement("div");
elemento.id = "testqq";
var el = document.getElementById("testqq"); // el será null!
```

**Documentos não-HTML.** A implementação do DOM deve ter informações que diz quais atributos são do tipo ID. Atributos com o nome "id" não são do tipo ID a menos que assim sejam definidos nos documentos DTD. O atributo `id` é definido para ser um tipo ID em casos comuns de XHTML, XUL, e outros. Implementações que não reconhecem se os atributos são do tipo ID, ou não são esperados retornam `null`.

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

| Specification |
| --- |
| DOM Standard # ref-for-dom-nonelementparentnode-getelementbyid② |

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

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

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

* referências de document (en-US) para outros métodos e propriedades podem ser usados para obter referências para elementos no documento.
* xml:id - tem um método utilitário que permite que obtenha 'xml:id' em documentos XML


Document.implementation - APIs da Web

Document.implementation
=======================

Sumário
-------

Retorna um objeto `DOMImplementation` (en-US) associado ao documento atual.

Sintaxe
-------
```

DOMImpObj = document.implementation;
```

Exemplo
-------

```js
var modName = "HTML";
var modVer = "2.0";
var conformTest = document.implementation.hasFeature(modName, modVer);

alert("DOM " + modName + " " + modVer + " supported?: " + conformTest);

// alerts with: "DOM HTML 2.0 supported?: true" if DOM Level 2 HTML module is supported.
```

Uma lista dos nomes de módulos (ex., Core, HTML, XML, etc) está disponível na DOM Level 2 Conformance Section

Notas
-----

A Recomendação do W3C DOM Level 1 apenas especifica o método `hasFeature`, que é o único meio de verificar se o módulo DOM é suportado pelo navegador (veja exemplo acima e What does your user agent claim to support?). Quando disponível, outros métodos `DOMImplementation` proverão serviços para controlar coisas fora deste único documento. Por exemplo, a interface `DOMImplementation` inclui um método `createDocumentType` com o qual DTD's podem ser criados para um ou mais documentos gerenciados pela implementação.

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

| Specification |
| --- |
| DOM Standard # ref-for-dom-document-implementation① |

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

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


Document.scripts - APIs da Web

Document.scripts
================

Retorna uma lista dos elementos `<script>` no documento. O objeto retornado é um `HTMLCollection`.

Sintaxe
-------
```

var scriptList = document.scripts;
```

O `scriptList retornado é um` `HTMLCollection`. Você pode usar isso apenas como um array para obter todos os elementos da lista.

Exemplo
-------

Este exemplo é para ver se a página contém elementos `<script>`.

```js
var scripts = document.scripts;

if (scripts.length) {
  alert("This page has scripts!");
}
```

Especificação
-------------

| Specification |
| --- |
| HTML Standard # dom-document-scripts-dev |

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

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


Document.characterSet - APIs da Web

Document.characterSet
=====================

A propriedade somente leitura Document.characterSet retorna a character encoding(codificação de caracteres) do documento com o qual ele é renderizado atualmente. (Uma codificação de caracteres é um conjunto de caracteres e como interpretar bytes nesses caracteres.)

**Nota:** Um "character set"(conjunto de caracteres) e "character encoding"(codificação de caracteres) estão relacionados, mas diferentes. Apesar do nome dessa propriedade, ela retorna a codificação.

Usuários podem sobrepor a codificação especificada pelo desenvolvedor dentro do cabeçalho Content-Type (tipo de conteúdo) ou embutida como <meta charset = "utf-8">, como no menu `Exibir → Codificacao de Texto` . Essa substituição é fornecida para corrigir codificações especificadas pelo desenvolvedor incorretas que resultam em texto ilegivel.

**Nota:** As propriedades `document.charset` e `document.inputEncoding` são aliases legados para `document.characterSet`. Não use mais eles.

Sintaxe
-------
```

var string = document.characterSet;
```

Exemplos
--------

```html
<button onclick="console.log(document.characterSet);">
  Registro de Codificacao de Caracteres
</button>
<!-- mostra a codificacao de caracteres do documento no console do desevolvedor, como "ISO-8859-1" ou "UTF-8" -->
```

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

| Specification |
| --- |
| DOM Standard # ref-for-dom-document-characterset① |

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

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


Document.alinkColor - APIs da Web

Document.alinkColor
===================

**Deprecated:** This feature is no longer recommended. Though some browsers might still support it, it may have already been removed from the relevant web standards, may be in the process of being dropped, or may only be kept for compatibility purposes. Avoid using it, and update existing code if possible; see the compatibility table at the bottom of this page to guide your decision. Be aware that this feature may cease to work at any time.

Retorna ou define a cor de um link ativo no corpo do documento. Um link está ativo durante o tempo entre os eventos `mousedown` e `mouseup`.

Sintaxe
-------
```

var color = document.alinkColor;
document.alinkColor = color;
```

color é uma string que contém o nome da cor (e.g., `blue`, `darkblue`, etc.) ou o valor hexadecimal da cor (e.g., `#0000FF`)

Notas
-----

O valor padrão para esta propriedade no Mozilla Firefox é vermelho (`#ee0000` em hexadecimal).

`document.alinkColor` está obsoleto em DOM Level 2 HTML. Uma alternativa é o seletor de CSS `:active`.

Outra alternativa é `document.body.aLink`, embora tenha sido depreciado no HTML 4.01 a favor da alternativa CSS.

Gecko suporta ambos `alinkColor`/`:active` e `:focus`. Suporte para Internet Explorer 6 e 7 `alinkColor`/`:active` apenas para HTML anchor (<a>) links e o comportamento é o mesmo que `:focus` sob Gecko. Não há suporte para `:focus` no IE.

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

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


Document.getElementsByClassName() - APIs da Web

Document.getElementsByClassName()
=================================

Retorna um vetor de objetos com todos os elementos filhos que possuem o nome da classe dada. Quando invocado no objeto *document*, o documento é examinado por completo, incluindo o nó raiz. Você também pode invocar `getElementsByClassName()` em qualquer elemento; isso retornaria somente elementos que são descendentes do nó raiz especificado com o nome da classe.

Sintaxe
-------
```

var elementos = document.getElementsByClassName(nomes); // ou:
var elementos = rootElement.getElementsByClassName(nomes);
```

* *elementos* é uma lista viva do `HTMLCollection` de elementos encontrados.
* *nomes* é um texto que representa uma lista dos nomes das classes que são separados por espaço em branco.
* getElementsByClassName pode ser invocado por qualquer elemento, não somente pelo nó raiz *document.* O elemento no qual ele é chamado será usado como a raiz para a busca\*.\*
Exemplos
--------

Retorna todos os elementos que possuem a classe 'teste'

```js
document.getElementsByClassName("teste");
```

Retorna todos os elementos que possuem as classes 'vermelho' e 'teste'

```js
document.getElementsByClassName("vermelho teste");
```

Retorna todos os elementos que possuem a classe 'teste' dentro do elemento que possui o ID 'principal'

```js
document.getElementById("principal").getElementsByClassName("teste");
```

Nós podemos também usar os métodos do Array.prototype em qualquer dos elementos `HTMLCollection` passando o *HTMLCollection* como valor deste método. Aqui podemos encontrar todos os elementos do tipo *div* que possuem a classe 'teste':

```js
var elementosTeste = document.getElementsByClassName("teste");
var divsTeste = Array.prototype.filter.call(
  elementosTeste,
  function (elementoTeste) {
    return elementoTeste.nodeName === "DIV";
  },
);
```

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

| Specification |
| --- |
| DOM Standard # ref-for-dom-document-getelementsbyclassname① |

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

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

Especificação
-------------

* W3C: getElementsByClassName


Document.compatMode - APIs da Web

Document.compatMode
===================

Indica se o documento está renderizado no Quirks mode ou no modo dos Padrões.

Sintaxe
-------
```

modo = document.compatMode
```

Valores
-------

* `"BackCompat"` se o documento está em **quirks mode**;
* `"CSS1Compat"` se o documento está no modo "não-*quirks*" (também conhecido como "**full standards mode**") ou "*limited-quirks*" (também conhecido como "**almost standards mode**").

`modo`

É um valor enumerado que pode ser:

**Nota:** Nota: todos estes modos agora são definidos em padrões, então os antigos nomes "standards" e "almost standards" são sem sentido, e portanto não são mais usados nos padrões.

Exemplo
-------
```

if (document.compatMode == "BackCompat") {
  // in Quirks mode
}
```

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

* DOM: Document.compatMode


Document.elementFromPoint() - APIs da Web

Document.elementFromPoint()
===========================

O método **`elementFromPoint()`** da interface `Document` retorna o elemento de maior nível nas coordenadas especificadas.

Se o elemento no ponto especificado pertencer à outro documento (por exemplo, um subdocumento em um iframe), será retornado o pai do subdocumento (o próprio iframe). Se o elemento em determinado ponto for anônimo ou for um conteudo gerado por XBL, como por exemplo barras de scroll de caixas de texto, então será retornado o primeiro elemento pai, não-anônimo (por exemplo, a própria caixa de texto).

Se o ponto especificado estiver fora dos limites visíveis do documento ou tiver uma coordenada negativa, o resultado é `null`.

Se você precisa encontrar uma posição específica dentro do elemento, use `Document.caretPositionFromPoint()` (en-US).

**Nota:** Chamados por documentos XUL devem esperar até o evento `onload` ser acionado antes de chamar este método.

Sintaxe
-------
```

var element = document.elementFromPoint(x, y);
```

### Parâmetros

x

Uma posição horizontal dentro do viewport atual.

y

Uma position vertical dentro do viewport atual.

### Valor retornado

O objeto de nível mais alto `Element` dentro das coordenadas declaradas.

Exemplo
-------

```html
<!doctype html>
<html lang="en">
  <head>
    <title>exemplo de elementFromPoint</title>

    <script>
 function changeColor(newColor) {
 elem = document.elementFromPoint(2, 2);
 elem.style.color = newColor;
 }
 </script>
  </head>

  <body>
    <p id="para1">Algum texto aqui</p>
    <button onclick="changeColor('blue');">azul</button>
    <button onclick="changeColor('red');">vermelho</button>
  </body>
</html>
```

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

| Specification |
| --- |
| CSSOM View Module # dom-document-elementfrompoint |

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

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


Document.referrer - APIs da Web

Document.referrer
=================

Retorna o URI da página que continha o *link* para a página atual.

Sintaxe
-------
```

string = document.referrer;
```

Notas
-----

O valor retornado será uma *string* vazia se o usuário tiver chegado na página diretamente (digitando o endereço no navegador ou como um item "Favorito"). Como essa propriedade retorna apenas uma *string*, ela não dá acesso DOM à página que fez a referência.

Especificação
-------------

* DOM Level 2: referrer


Document.URL - APIs da Web

Document.URL
============

A propriedade **`URL`** (usada apenas para leitura) da Interface `Document` retorna a URL atual do navegador como um texto (string).

Síntaxe
-------

```js
var url_atual = document.URL;
```

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

| Specification |
| --- |
| DOM Standard # ref-for-dom-document-url① |

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

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


Document.documentURI - APIs da Web

Document.documentURI
====================

A propiedade **`documentURI`** da interface `Document` retorna uma string com a localização de um documento.Na definição original DOM3 **`documentURI`** é um atributo de leitura/escrita.No padrão mais recente DOM4 é somente de leitura.Sintaxe
-------
```

var string = document.documentURI;
```

Notas
-----

Os Documentos HTML tem uma propriedade `document.URL` que retorna o mesmo valor (localização do documento).

A diferençã é que **`document.URL`** só pode ser usado em documentos HTML, enquanto **`documentURI`** está disponivel para todos os documentos web.

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

| Specification |
| --- |
| DOM Standard # ref-for-dom-document-documenturi① |

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

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


Document.getElementsByName() - APIs da Web

Document.getElementsByName()
============================

O método\*\*`getElementsByName()`\*\* do objeto `Document` retorna uma coleção de elementos `NodeList` com um dado `name` (en-US) no documento.

Sintaxe
-------
```

var elementos = document.getElementsByName(nome);
```

* *elementos* é uma coleção ativa de `NodeList`, significando que ele atualiza automaticamente com os novos elementos com o mesmo `nome` que são adicionados/removidos do documento.
* *nome* é um valor do atributo `nome` dos elemento(s).
Exemplo
-------

```html
<!doctype html>
<html lang="en">
  <title>Exemplo: usando document.getElementsByName</title>

  <input type="hidden" name="up" />
  <input type="hidden" name="down" />

  <script>
 var up\_nomes = document.getElementsByName("up");
 console.log(up\_nomes[0].tagName); // exibindo o campo "INPUT"
 </script>
</html>
```

Notas
-----

O atributo `name` (en-US) pode somente ser aplicado nos documentos (X)HTML.

A coleção retornada `NodeList` contém *todos* os elementos com o respectivo `nome`, tal como `<meta>`, `<object>` (en-US), e até os elementos o qual não suporta o atributo `nome` para todos.

**Aviso:** O método **getElementsByName** trabalha diferentemente em IE10 e anteriores. Além de que, `getElementsByName()` também retorna elementos que tem um atributo `id` com o valor especificado. Seja cuidadoso para não usar a mesma string como ambos `nome` e `id`.

**Aviso:** O método **getElementsByName** trabalha diferentemente no IE. Portanto, `getElementsByName()` não retorna todos os elementos no qual não pode ter um atributo `nome` (tal como `<span>`).

**Aviso:** Ambos IE e Edge retorna um `HTMLCollection`, e não um `NodeList`

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

| Specification |
| --- |
| HTML Standard # dom-document-getelementsbyname-dev |

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

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

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

* `document.getElementById()` para retornar uma referência para um elemento por um único `id`
* `document.getElementsByTagName()` (en-US) para retornar referências para elementos com o mesmo nome tag
* `document.querySelector()` para retornar referências para elementos via seletores CSS como `'div.myclass'`


Document.createElementNS() - APIs da Web

Document.createElementNS()
==========================

Creates an element with the specified namespace URI and qualified name.

Cria um elemento com Namespace URI e nome qualificado, como especificado.

Syntax
------
```

element = document.createElementNS(namespaceURI, qualifiedName);
```

* `element` é o element (en-US) criado.
* `namespaceURI` é uma string que especifica o namespace URI para associar com o elemento. A propriedade namespaceURI (en-US) do elemento criado é inicializada com os valores de `namespaceURI`. (Consulte seção abaixo para "Namespace URI's válidos")
* `qualifiedName` é uma string que especifica o tipo de elemento a ser criado. A propriedade nodeName (en-US) do elemento criado é inicializada com o valor de `qualifiedName`
Namespace URI's válidos
-----------------------

* HTML - Use `https://www.w3.org/1999/xhtml`
* SVG - Use `https://www.w3.org/2000/svg`
* XBL - Use `http://www.mozilla.org/xbl`
* XUL - Use `http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul`
Exemplo
-------

Isso cria um novo elemento <div> no namespace XHTML e anexa ele ao elemento vbox. Embora isso não seja um documento XUL extremamente útil, pode demonstrar o uso de elementos de dois namespaces diferentes em apenas um documento:

```xml
<?xml version="1.0"?>
<page xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"
 xmlns:html="https://www.w3.org/1999/xhtml"
 title="||Working with elements||"
 onload="init()">

<script type="text/javascript"><![CDATA[
 var container;
 var newdiv;
 var txtnode;

 function init(){
 container = document.getElementById("ContainerBox");
 newdiv = document.createElementNS("https://www.w3.org/1999/xhtml","div");
 txtnode = document.createTextNode("Este é o texto construído dinâmicamente com createElementNS e createTextNode então é inserido no documento usando appendChild.");
 newdiv.appendChild(txtnode);
 container.appendChild(newdiv);
 }

]]></script>

 <vbox id='ContainerBox' flex='1'>
  <html:div>
   O script desta página irá colocar conteúdo dinâmico abaixo:
  </html:div>
 </vbox>

</page>
```

Notas
-----

O exemplo dado anteriormente usa script inline que não é recomendado em documentos XHTML. Este exemplo particular é atualmente um documento XUL com XHTML incorporado, contudo, a recomendação ainda se aplica. scripts Inline não causam nenhum problema neste pequeno exemplo, contudo, para qualquer trabalho sério você precisa ler sobre Uso correto de CSS e JavaScript en documentos XHTML.

Para criar um elemento sem especificar seu namespace URI, use o método createElement.

Especificação
-------------

* DOM 2 Core: createElementNS
* Namespaces em XML
Veja também
-----------

* `document.createElement()`
* `document.createTextNode()` (en-US)
* `Element.namespaceURI` (en-US)
* Namespaces in XML


Document.close() - APIs da Web

Document.close()
================

O metodo `document.close()` termina a gravação em um documento, aberto com document.open().

Sintaxe
-------
```

document.close();
```

Exemplo
-------
```

// abre um documento e escreve nele.
// escreve o conteúdo no documento.
// fecha o documento.
document.open();
document.write("<p>O primeiro e unico conteúdo.</p>");
document.close();
```

Especificação
-------------

DOM Level 2 HTML: `close()` Method


Document.head - APIs da Web

Document.head
=============

Retorna o elemento `<head>` do documento atual. Se existir mais de um elemento `<head>`, apenas o primeiro será devolvido.

Sintaxe
-------
```

var objRef = document.head;
```

Exemplo
-------

```js
// No HTML: <head id="my-document-head">
var aHead = document.head;

alert(aHead.id); // "my-document-head";

alert(document.head === document.querySelector("head")); // true
```

Notas
-----

`document.head` suporta apenas leitura. Qualquer tentativa de atribuir um valor a essa propriedade irá falhar silenciosamente ou irá, usando o modo ECMAScript Strict (en-US) de um browser Gecko, disparar um `TypeError`.

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

| Specification |
| --- |
| HTML Standard # dom-document-head-dev |

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

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

Veja Também
-----------

* `document.body`


Document.createElement() - APIs da Web

Document.createElement()
========================

Em um documento HTML, o método **`Document.createElement()`** cria o elemento HTML especificado ou um `HTMLUnknownElement` (en-US) se o nome do elemento dado não for conhecido.

Em um documento XUL, o elemento XUL especificado é criado.

Em outros documentos, ele cria um elemento com um *namespace* URI `null`.

Sintaxe
-------
```

var elemento = document.createElement(nomeDaTag);
```

* `elemento` é o objeto `Element` criado.
* `nomeDaTag` é uma *string* que especifica o tipo do elemento a ser criado. O `nodeName` (en-US) do elemento criado é inicializado com o valor da `nomeDaTag`. Não use nomes qualificados (como "html:a") com este método.
Exemplo
-------

Este código cria uma nova `<div>` e a insere antes do elemento com ID "`div1`".

### HTML

```html
<!doctype html>
<html>
  <head>
    <title>||Trabalhando com elementos||</title>
  </head>
  <body>
    <div id="div1">O texto acima foi criado dinamicamente.</div>
  </body>
</html>
```

### JavaScript

```js
document.body.onload = adcElemento;

function adcElemento() {
  // cria um novo elemento div
  // e dá à ele conteúdo
  var divNova = document.createElement("div");
  var conteudoNovo = document.createTextNode("Olá, cumprimentos!");
  divNova.appendChild(conteudoNovo); //adiciona o nó de texto à nova div criada

  // adiciona o novo elemento criado e seu conteúdo ao DOM
  var divAtual = document.getElementById("div1");
  document.body.insertBefore(divNova, divAtual);
}
```

Notas
-----

* Quando chamada em um objeto de documento marcado como um documento HTML, `createElement()` torna seu argumento caixa-baixa antes de criá-lo.
* Para criar um elemento com um nome qualificado e *namespace URI*, use `document.createElementNS()`.
* Antes do Gecko 2.0 você podia incluir os símbolos de menor que e maior que em volta da `tagName` no modo *quirks*; a partir do Gecko 2.0, a função comporta-se da mesma forma em ambos os modos *quirks* e estrito.
* A partir do Gecko 19.0, `createElement(null)` funciona como `createElement("null")`. Note que o Opera torna `null` uma *string*, mas ambos Chrome e Internet Explorer lançarão erros.
* A partir do Gecko 22.0 `createElement()` não mais usa a interface `HTMLSpanElement` quando o argumento é "bgsounds", "multicol", or "image". Ao invés disso, `HTMLUnknownElement` é usado para "bgsound", "multicol" e `HTMLElement` (en-US) `HTMLElement` é usado para "image".
* A implementação Gecko de `createElement` não se conforma à especificação DOM para documentos XUL e XHTML: `localName` e `namespaceURI` não estão definidos para `null` no elemento criado. Veja Firefox bug 280692 para detalhes.
Especificações
--------------

* DOM 2 Core: createElement
* HTML5: APIs in HTML documents


Document.designMode - APIs da Web

Document.designMode
===================

Sumário
-------

`document.designMode` controla se o documento todo é editável. Valores validos são `"on"` e `"off"`. De acordo com a especificação, esta propriedade é por padrão `"off"`. Firefox segue este padrão. Nas versões anteriores do Chrome e IE o padrão é `"inherit"`. No IE6-10, o valor é capitalizado.

Sintaxe
-------

```js
var mode = document.designMode;
document.designMode = "on";
document.designMode = "off";
```

Exemplo
-------

Cria um documento `<iframe>` editável:
```

iframe_node.contentDocument.designMode = "on";
```

Especificação
-------------

| Specification |
| --- |
| HTML Standard # dom-document-designmode-dev |

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

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

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

* Rich-Text Editing in Mozilla
* `HTMLElement.contentEditable`
* designMode property on MSDN


readystatechange - APIs da Web

readystatechange
================

O evento `readystatechange` é ativado quando o atributo `readyState` de um documento é alterado.

Informações gerais
------------------

Especificação

HTML5

Interface

Event

Propaga

Não

Cancelável

Não

Alvo

Document

Ação Padrão

Nenhuma.

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

| Property | Type | Description |
| --- | --- | --- |
| `target` Somente leitura  | `EventTarget` | The event target (the topmost target in the DOM tree). |
| `type` Somente leitura  | `DOMString` | The type of event. |
| `bubbles` Somente leitura  | `Boolean` | Whether the event normally bubbles or not. |
| `cancelable` Somente leitura  | `Boolean` | Whether the event is cancellable or not. |

Exemplo
-------

```js
// alternativa ao DOMContentLoaded
document.onreadystatechange = function () {
  if (document.readyState == "interactive") {
    initApplication();
  }
};
```

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

Este evento tem sido suportado pelo Internet Explorer há várias versões, e pode ser usada como uma alternativa para o evento `DOMContentLoaded` (en-US) (veja a seção cross-browser fallback).

Eventos Relacionados
--------------------

* `DOMContentLoaded (en-US)`
* `readystatechange (en-US)`
* `load (en-US)`
* `beforeunload (en-US)`
* `unload (en-US)`


Document.contentType - APIs da Web

Document.contentType
====================

**`Document.contentType`** é uma propriedade somente de leitura, que retorna o tipo MIME do documento que esta sendo rendenrizado.Isso pode vir de cabeçalhos HTPP ou de outras fontes de informações MIME, e pode se afetado por conversões realizadas pelo navegador ou pelas extenções.

**Nota:** Esta proiedade não é afetada pelos elementos `<meta>`.

Sintaxe
-------
```

contentType = document.contentType;
```

### Value

`contentType` é uma propriedade somente de leitura.

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

| Specification |
| --- |
| DOM Standard # ref-for-dom-document-contenttype① |

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

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


Document.hasFocus() - APIs da Web

Document.hasFocus()
===================

O método **`Document.hasFocus()`** retorna um valor `Boolean` que indica se o documento ou qualquer elemento dentro do documento está com o foco ativo. Este método pode ser usado para determinar se o elemento ativo em um documento tem foco.

**Nota:** Quando se está visualizando um documento, um elemento com focus é sempre o ativo no mesmo, mas um elemento ativo não necessariamente tem o foco. Por exemplo, um elemento ativo com uma janela (popup) que não é a principal não tem foco.

Sintaxe
-------
```

focused = document.hasFocus();
```

### Valor retornado

`false` se o elemento ativo no documento não tem foco; `true` se o elemento ativo no documento tem foco.

Exemplo
-------

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>TEST</title>
    <style>
 #message {
 font-weight: bold;
 }
 </style>
    <script>
 setInterval( checkPageFocus, 200 );

 function checkPageFocus() {
 var info = document.getElementById("message");

 if ( document.hasFocus() ) {
 info.innerHTML = "O documento tem o foco.";
 } else {
 info.innerHTML = "O documento não tem o foco.";
 }
 }

 function openWindow() {
 window.open (
 "http://developer.mozilla.org/",
 "mozdev",
 "width=640,
 height=300,
 left=150,
 top=260"
 );
 }
 </script>
  </head>
  <body>
    <h1>Exemplo do JavaScript hasFocus</h1>
    <div id="message">Esperando por ação do usuário</div>
    <div><button onclick="openWindow()">Abre uma nova janela</button></div>
  </body>
</html>
```

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

| Specification |
| --- |
| HTML Standard # dom-document-hasfocus-dev |

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

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

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

* Usando a API de Page Visibility (en-US)


Document.images - APIs da Web

Document.images
===============

Summary
-------

`document.images` retorna uma coleção de imagens (en-US) do documento HTML.

Sintaxe
-------
```

var htmlCollection = document.images;
```

Exemplo
-------

```js
var ilist = document.images;

for (var i = 0; i < ilist.length; i++) {
  if (ilist[i].src == "banner.gif") {
    // found the banner
  }
}
```

Notas
-----

`document.images.length` – propriedade, retorna o número de imagens na página.

`document.images` é parte do DOM HTML, e só trabalho com documentos HTML.

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

| Specification |
| --- |
| HTML Standard # dom-document-images-dev |

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

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


Document.activeElement - APIs da Web

Document.activeElement
======================

Retorna o `elemento` atualmente em foco, ou seja, o elemento que receberá os eventos do teclado caso o usuário digite algo. Esse atributo é somente-leitura.

Geralmente retorna um `<input>` ou `<textarea>`, caso esteja com uma seleção de texto ativa. Caso esteja, pode obter mais informações sobre a seleção utilizando as propriedades `selectionStart` e `selectionEnd`. Caso o elemento em foco seja um `<select>`(menu) ou `<input>` do tipo `button`, `checkbox` ou `radio`.

**Nota:** No Mac, elementos que nao sejam campos de texto geralmente não recebem foco.

Normalmente o usuário pode navegar entre os elementos que pode receber foco na página com o uso da tecla `tab` e ativar estes elementos com a tecla `espaço` (apertar um botão ou selecionar uma opção).

Não confunda foco com uma seleção de texto no documento, que consiste em sua maioria de nódos de texto estáticos. Veja `window.getSelection()`.

Quando não há nada selecionado, o `activeElement` da página é o `<body>` ou `null`.

**Nota:** Este atributo é parte da seção "Em desenvolvimento" da especificação do HTML 5.

Sintaxe
-------
```

var curElement = document.activeElement;
```

Exemplo
-------

```html
<!doctype html>
<html>
  <head>
    <script type="text/javascript" charset="utf-8">
 function init() {
 function onMouseUp(e) {
 console.log(e);
 var outputElement = document.getElementById("output-element");
 var outputText = document.getElementById("output-text");
 var selectedTextArea = document.activeElement;
 var selection = selectedTextArea.value.substring(
 selectedTextArea.selectionStart,
 selectedTextArea.selectionEnd,
 );
 outputElement.innerHTML = selectedTextArea.id;
 outputText.innerHTML = selection;
 }

 document
 .getElementById("ta-example-one")
 .addEventListener("mouseup", onMouseUp, false);
 document
 .getElementById("ta-example-two")
 .addEventListener("mouseup", onMouseUp, false);
 }
 </script>
  </head>
  <body onload="init()">
    <div>Select some text from one of the Textareas below:</div>
    <form id="frm-example" action="#" accept-charset="utf-8">
      <textarea name="ta-example-one" id="ta-example-one" rows="8" cols="40">
This is Textarea Example One:
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec tincidunt, lorem a porttitor molestie, odio nibh iaculis libero, et accumsan nunc orci eu dui.
</textarea
 >
      <textarea name="ta-example-two" id="ta-example-two" rows="8" cols="40">
This is Textarea Example Two:
Fusce ullamcorper, nisl ac porttitor adipiscing, urna orci egestas libero, ut accumsan orci lacus laoreet diam. Morbi sed euismod diam.
</textarea
 >
    </form>
    Active Element Id: <span id="output-element"></span><br />
    Selected Text: <span id="output-text"></span>
  </body>
</html>
```

View on JSFiddle

Notas
-----

Originalmente apresentada como extensão DOM proprietária no Internet Explorer 4, esta propriedade também é suportada no Opera e Safari (versão 4 ou maior)

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

| Specification |
| --- |
| HTML Standard # dom-documentorshadowroot-activeelement-dev |

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

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

Eventos relacionados
--------------------

* `focus (en-US)`
* `blur (en-US)`
* `focusin (en-US)`
* `focusout (en-US)`


Document.querySelector() - APIs da Web

Document.querySelector()
========================

Sumário
-------

Retorna o primeiro elemento dentro do documento (usando ordenação em profundidade, pré-ordenada e transversal dos nós do documento) que corresponde ao grupo especificado de seletores.

Sintaxe
-------
```

element = document.querySelector(selectors);
```

Onde:

* `element` é um objeto `Element`.
* `selectors` é uma string que contém um ou mais seletores CSS separados por vírgulas.
Exemplo
-------

Neste exemplo, o primeiro elemento no documento com a classe "`myclass`" é retornado:

```js
var el = document.querySelector(".myclass");
```

Notas
-----

Retorna `null` se nenhum resultado for encontrado; caso contrário, retorna o primeiro elemento correspondente.

Se o seletor utilizado for um `ID` e este `ID` foi erroneamente utilizado várias vezes no documento, ele retorna somente o primeiro elemento correspondente.

Gera uma exceção `SYNTAX_ERR` se o grupo de seletores utilizado for inválido.

`querySelector()` foi introduzido com a API de seletores.

Compatibilidade dos navegadores
-------------------------------

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

Especificação
-------------

* Selectors API
Veja também
-----------

* `document.querySelectorAll()`
* `element.querySelector()`
* `element.querySelectorAll()`
* Code snippets for querySelector


Document.body - APIs da Web

Document.body
=============

Retorna o elemento `<body>` ou o `<frameset>` (en-US) do documento atual, ou `null` se nenhum destes elementos existir.

Sintaxe
-------
```

var objRef = document.body;
document.body = objRef;
```

Exemplo
-------

```js
// No HTML: <body id="oldBodyElement"></body>
alert(document.body.id); // "oldBodyElement"

var aNewBodyElement = document.createElement("body");

aNewBodyElement.id = "newBodyElement";
document.body = aNewBodyElement;
alert(document.body.id); // "newBodyElement"
```

Notas
-----

`document.body` é o elemento que envolve o conteúdo do documento. Em documentos com conteúdo no `<body>`, retorna o elemento `<body>`, e em documentos que usam frameset, retorna o elemento `<frameset>` mais periférico.

Apesar do `body` ser configurável, definir um novo `body` em um documento irá remover todos os elementos contidos no elemento `<body>` existente.

Especificação
-------------

* DOM Level 2 HTML: HTMLDocument.body
* HTML5: DOM Tree Accessors
Veja Também
-----------

* `document.head`