Document.write() - APIs da Web

Document.write()
================

O método **`Document.write()`** grava uma sequência de caracteres em um documento aberto por `document.open()` (en-US).

**Nota:** à medida que `document.write` grava no **fluxo** de documentos, chamando `document.write` em um documento fechado (carregado) invoca automaticamente `document.open`, que limpará o documento (en-US).

Sintaxe
-------

```js
document.write(markup);
```

### Parametros

*markup*

Uma string contendo o texto a ser gravado no documento.

### Exemplo

```html
<html>
  <head>
    <title>Escreva exemplo</title>

    <script>
 function newContent() {
 document.open();
 document.write("<h1>Sair com o velho - entrar com o novo!</h1>");
 document.close();
 }
 </script>
  </head>

  <body onload="newContent();">
    <p>Algum conteúdo do documento original.</p>
  </body>
</html>
```

Notas
-----

Escrevendo em um documento que já foi carregado sem chamar `document.open()` (en-US) automaticamente vai chamar `document.open`. Ao términno da escrita, é recomendável chamar `document.close()` para dizer ao navegador para encerrar o carregamento da página. O texto que você escreve é analisado no modelo de estrutura do documento. No exemplo acima, o elemento `h1` se torna um nó (node) no documento.

Se chamar `document.write()` incorporada em uma tag HTML `<script>` embutida, então `document.open()` não será chamada. Por exemplo:

```html
<script>
 document.write("<h1>Título principal</h1>");
</script>
```

**Nota:** `document.write` e `document.writeln` não funcionam em documentos XHTML (você receberá o erro "Operation is not supported" [`NS_ERROR_DOM_NOT_SUPPORTED_ERR`] no console de erros). Isso acontece ao abrir um arquivo local com a extensão .xhtml ou em qualquer documento exibido com um MIME type `application/xhtml+xml` MIME type (en-US). Mais informações disponíveis em W3C XHTML FAQ.

**Nota:** `document.write` em deferred ou asynchronous scripts será ignorado, e você receberá uma mensagem como "A call to `document.write()` from an asynchronously-loaded external script was ignored" no console de erros.

**Nota:** Somente no Edge, chamando `document.write` mais de uma vez em `<iframe>` causa o erro "SCRIPT70: Permission denied".

**Nota:** A partir de 55, Chrome não executará elementos `<script>` injetados via `document.write()` caso haja falta de cache HTTP para usuários em uma conexão 2G. Há uma lista de condições que precisam ser atendidas para que isso seja verdade.

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

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

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

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

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

* `element.innerHTML`
* `document.createElement()`


Document.importNode() - APIs da Web

Document.importNode()
=====================

Cria uma cópia de um nó a partir de um documento externo para ser inserido no document atual.

Sintaxe
-------
```

var node = document.importNode(externalNode, deep);
```

`node`

`O novo nó que será importado no documento. A propriedade parentNode do novo nó é null, desde que ele não foi inserido na árvores do documento.`

`externalNode`

`O nó de outro documento para ser importado.`

`deep`

`Um boolean, indicando se os nós filhos, do nó a ser importado, devem ser importados também.`

**Nota:** In the DOM4 specification (as implemented in Gecko 13.0), `deep` is an optional argument. If omitted, the method acts as if the value of `deep` was **`true`**, defaulting to using deep cloning as the default behavior. To create a shallow clone, `deep` must be set to `false`.

This behavior has been changed in the latest spec, and if omitted, the method will act as if the value of `deep` was **`false`**. Though It's still optional, you should always provide the `deep` argument both for backward and forward compatibility. With Gecko 28.0, the console warned developers not to omit the argument. Starting with Gecko 29.0), a shallow clone is defaulted instead of a deep clone.

Exemplo
-------

```js
var iframe = document.getElementsByTagName("iframe")[0];
var oldNode = iframe.contentWindow.document.getElementById("myNode");
var newNode = document.importNode(oldNode, true);
document.getElementById("container").appendChild(newNode);
```

Notas
-----

O nó original não é removido do documento de origem. O nó importado é um clone do original.

Nodes from external documents should be cloned using `document.importNode()` (or adopted using `document.adoptNode()` (en-US)) before they can be inserted into the current document. For more on the `Node.ownerDocument` (en-US) issues, see the W3C DOM FAQ.

Firefox doesn't currently enforce this rule (it did for a while during the development of Firefox 3, but too many sites break when this rule is enforced). We encourage Web developers to fix their code to follow this rule for improved future compatibility.

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

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

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

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

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

* `document.adoptNode()` (en-US)


Document.doctype - APIs da Web

Document.doctype
================

Retorna a declaração do tipo de documento(Document Type Declaration (DTD)) associado ao documento atual. O objeto retornado implementa a interface `DocumentType` (en-US). Use `DOMImplementation.createDocumentType()` (en-US) para criar um `DocumentType`.

Sintaxe
-------
```

doctype = document.doctype;
```

* `doctype` é uma proriedade somente de leitura.
Exemplo
-------

```js
var doctypeObj = document.doctype;

console.log(
  "doctypeObj.name: " +
    doctypeObj.name +
    "\n" +
    "doctypeObj.internalSubset: " +
    doctypeObj.internalSubset +
    "\n" +
    "doctypeObj.publicId: " +
    doctypeObj.publicId +
    "\n" +
    "doctypeObj.systemId: " +
    doctypeObj.systemId,
);
```

Notas
-----

A propriedade retornará `null` se não houvernehum DTD associado ao documento atual.

O nível 2 do DOM não suporta a edição da declaração do tipo de documento.

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

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

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

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


Document.defaultView - APIs da Web

Document.defaultView
====================

Sumário
-------

Em navegadores, retorna o objeto window (en-US) associado ao documento ou `null` se não houver.

Sintaxe
-------
```

var win = document.defaultView;
```

Esta propriedade é de somente-leitura.

Notas
-----

De acordo com o quirksmode, `defaultView` não é suportado no IE até o IE 9.

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

* HTML5: defaultView
* DOM Level 2 Views: defaultView
* DOM Level 3 Views (Apenas desenvolvido para o Working Group Note e não implementado)


Document.fullscreen - APIs da Web

Document.fullscreen
===================

**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 de somente leitura da interface **`fullscreen`** retorna se o documento correspondente está mostrando conteúdo em modo de tela cheia (full-screen).

Apesar dessa propriedade ser de somente leitura, ela não será executa se for modificada (mesmo em modo estrito); o setter não é um operador e não será modificado.

**Nota:** Desde que esta propriedade foi descontinuada, você pode determinar se o modo full-screen está ativo no documento checando se `Document.fullscreenElement` (en-US) não é `null`.

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

var isFullScreen = document.fullscreen;
```

### Valor

Um valor booleano é `true` se o documento está mostrando um elemento no modo full-screen; se não, o valor é `false`.

Exemplo
-------

Esta simples função retorna se o modo full-sreen está ativo, usando a obsoleta propriedade **`fullscreen`**.

```js
function isDocumentInFullScreenMode() {
  return document.fullscreen;
}
```

Neste próximo exemplo, de outra maneira, usa a propriedade atual `fullscreenElement` para determinar a mesma coisa:

```js
function isDocumentInFullScreenMode() {
  return document.fullscreenElement !== null;
}
```

Se `fullscreenElement` não é `null`, retorna `true`, indicando se modo full-screen está sendo usado.

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

| Specification |
| --- |
| Fullscreen API Standard # dom-document-fullscreen |

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

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

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

* Fullscreen API (en-US)
* Guide to the Fullscreen API (en-US)
* `Document.fullscreenEnabled` (en-US)


Document() - APIs da Web

Document()
==========

**Non-standard:** This feature is non-standard and is not on a standards track. Do not use it on production sites facing the Web: it will not work for every user. There may also be large incompatibilities between implementations and the behavior may change in the future.

O construtor **`Document`** cria um novo objeto `Document`, o qual trata de uma página carregada no navegador servindo como porta de entrada para o conteúdo da página.

Sintaxe
-------
```

var document = new Document()
```

### Parâmetros

Nenhum.

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

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

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

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


Document.readyState - APIs da Web

Document.readyState
===================

Sumário
-------

Retorna "*loading*" enquanto `document` está carregando, "*interactive*" quando foi carregado porém seus sub-recursos (como imagens, por exemplo) ainda não, e "*complete*" quando foi totalmente carregado.

O evento `readystatechange` é acionado no objeto `document` quando esse valor é alterado.

Sintaxe
-------
```

var string = document.readyState;
```

### Valores

O `readyState` de um documento pode ser um dos seguintes:

`loading`

O `document` ainda está carregando.

`interactive`

O documento terminou de ser carregado e o documento foi analisado, mas sub-recursos, como imagens, folhas de estilo e quadros, ainda estão sendo carregados.

`complete`

O documento e todos os sub-recursos terminaram de carregar. O estado indica que o `load (en-US)` evento está prestes a disparar.

Exemplos
--------

### Diferentes estados de readyState
```

switch (document.readyState) {
  case "loading":
    // O documento esta carregando
    break;
  case "interactive":
    // O documento acabou de carregar. Nós podemos acessar os elementos do DOM.
    // mas sub-recursos, como imagens, folhas de estilo e quadros, ainda estão sendo carregados.
    var span = document.createElement("span");
    span.textContent = "A <span> element.";
    document.body.appendChild(span);
    break;
  case "complete":
    // A pagina carregou por completo.
    console.log("The first CSS rule is: " + document.styleSheets[0].cssRules[0].cssText);
    break;
}
```

### readystatechange como uma alternativa para DOMContentLoaded evento
```

// alternativa para DOMContentLoaded evento
document.onreadystatechange = function () {
  if (document.readyState === 'interactive') {
    initApplication();
  }
}
```

### readystatechange como uma alternativa para load evento
```

// ternativa para load evento
document.onreadystatechange = function () {
  if (document.readyState === 'complete') {
    initApplication();
  }
}
```

### readystatechange como ouvinte de evento para inserir ou modificar o DOM antes de DOMContentLoaded
```

document.addEventListener('readystatechange', event => {
  if (event.target.readyState === 'interactive') {
    initLoader();
  }
  else if (event.target.readyState === 'complete') {
    initApp();
  }
});
```

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

* http://www.whatwg.org/specs/web-apps/current-work/multipage/dom.html#current-document-readiness
Veja também
-----------

* document.onreadystatechange


Document.anchors - APIs da Web

Document.anchors
================

**HTML5:** 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.

`anchors` retorna uma lista de todas as âncoras no documento.

Sintaxe
-------
```

nodeList = document.anchors;
```

Exemplo
-------

```js
if (document.anchors.length >= 5) {
  dump("dump found too many anchors");
  window.location = "http://www.google.com";
}
```

O código a seguir é um exemplo que popula automaticamente um índice de conteúdo com cada âncora encontrada na página:

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Test</title>
    <script>
 function init() {
 var toc = document.getElementById("toc");
 var i, li, newAnchor;
 for (i = 0; i < document.anchors.length; i++) {
 li = document.createElement("li");
 newAnchor = document.createElement("a");
 newAnchor.href = "#" + document.anchors[i].name;
 newAnchor.innerHTML = document.anchors[i].text;
 li.appendChild(newAnchor);
 toc.appendChild(li);
 }
 }
 </script>
  </head>
  <body onload="init()">
    <h1>Title</h1>
    <h2><a name="contents">Contents</a></h2>
    <ul id="toc"></ul>

    <h2><a name="plants">Plants</a></h2>
    <ol>
      <li>Apples</li>
      <li>Oranges</li>
      <li>Pears</li>
    </ol>

    <h2><a name="veggies">Veggies</a></h2>
    <ol>
      <li>Carrots</li>
      <li>Celery</li>
      <li>Beats</li>
    </ol>
  </body>
</html>
```

View on JSFiddle

Notas
-----

Por motivos de compatibilidade, o conjunto de âncoras retornadas por `anchors` contém apenas as âncoras criadas com o atributo `name`, não incluindo as âncoras criadas com o atributo `id`.

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

| Specification |
| --- |
| HTML Standard # dom-document-anchors |


Document.querySelectorAll() - APIs da Web

Document.querySelectorAll()
===========================

Introdução
----------

Retorna uma lista de elementos presentes no documento (usando ordenação em profundidade, pré-ordenada e transversal dos nós do documento) que coincidam com o grupo de seletores especificado. O objeto retornado é uma `NodeList`.

Sintaxe
-------
```

elementList = document.querySelectorAll(selectors);
```

onde

* `elementList` é uma `NodeList` não-viva (alterações no DOM não refletem na lista) de objetos `Element`.
* `selectors` é uma *string* contendo um ou mais seletores CSS separados por vírgulas.

A NodeList retornada irá conter todos os elementos do documento que coincidam com os seletores especificados. Se a string `selectors` conter um CSS `PseudoElements`, o retorno será uma NodeList vazia.

Exemplo
-------

Esse exemplo retorna uma lista de todos os elementos `div` presentes no `document` que contenham as classes "`note`" ou "`alert`":

```js
var matches = document.querySelectorAll("div.note, div.alert");
```

Notas
-----

Retorna uma `NodeList` não-viva (alterações no DOM não refletem na lista) de todos os elementos que coincidam com os seletores informados.

Lança uma exceção `SYNTAX_ERR` se o grupo especificado de seletores for inválido.

`querySelectorAll()` foi introduzida na WebApps API.

Navegadores baseados em *WebKit* têm um *bug*: quando a string `seletores` contém um pseudo-elemento CSS (en-US), a `NodeList` retornada não esta vazia, neste caso ela contém o elemento `<html>`.

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

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

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

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

* `Element.querySelectorAll`
* `Document.querySelector`
* `Element.querySelector`
* `Exemplos de código com querySelector`


Document.getSelection() - APIs da Web

Document.getSelection()
=======================

Esse método funciona de forma idêntica ao método `Window.getSelection()`; Ele retorna um objeto `Selection` representando o texto atualmente selecionado no documento.


NodeFilter - APIs da Web

NodeFilter
==========

Uma interface **`NodeFilter`** representa um objeto usado para filtrar os nós (elementos), em uma iteração `NodeIterator` (en-US) ou `TreeWalker` (en-US). Essas interfaces não conhecem nada sobre o DOM ou sobre como percorrer ou atravessar, elementos; elas apenas sabem como avaliar se um único nó atende aos requisitos do filtro fornecido ou não.

**Nota:** O navegador não fornece nenhum objeto que implemente essa interface. É esperado que o desenvolvedor escreva tal objeto, utilizando o método `acceptNode()` conforme as suas necessidades, podendo mesclar com objetos do tipo `TreeWalker` (en-US) ou `NodeIterator` (en-US) em sua implementação..

Properties
----------

*Essa interface não implementa, nem herda, nenhuma propriedade.*

Methods
-------

*Essa interface não herda nenhum método.*

`NodeFilter.acceptNode()` (en-US)

Returns an `unsigned short` that will be used to tell if a given `Node` must be accepted or not by the `NodeIterator` (en-US) or `TreeWalker` (en-US) iteration algorithm. This method is expected to be written by the user of a `NodeFilter`. Possible return values are:

| Constant | Description |
| --- | --- |
| `FILTER_ACCEPT` | Value returned by the `NodeFilter.acceptNode()` (en-US) method when a node should be accepted. |
| `FILTER_REJECT` | Value to be returned by the `NodeFilter.acceptNode()` (en-US) method when a node should be rejected. For `TreeWalker` (en-US), child nodes are also rejected. For `NodeIterator` (en-US), this flag is synonymous with FILTER\_SKIP. |
| `FILTER_SKIP` | Value to be returned by `NodeFilter.acceptNode()` (en-US) for nodes to be skipped by the `NodeIterator` (en-US) or `TreeWalker` (en-US) object. The children of skipped nodes are still considered. This is treated as "skip this node but not its children". |

Example
-------

```js
var nodeIterator = document.createNodeIterator(
  // Node to use as root
  document.getElementById("someId"),

  // Only consider nodes that are text nodes (nodeType 3)
  NodeFilter.SHOW\_TEXT,

  // Object containing the function to use for the acceptNode method
  // of the NodeFilter
  {
    acceptNode: function (node) {
      // Logic to determine whether to accept, reject or skip node
      // In this case, only accept nodes that have content
      // other than whitespace
      if (!/^\s\*$/.test(node.data)) {
        return NodeFilter.FILTER\_ACCEPT;
      }
    },
  },
  false,
);

// Show the content of every non-empty text node that is a child of root
var node;

while ((node = nodeIterator.nextNode())) {
  alert(node.data);
}
```

Specifications
--------------

| Specification |
| --- |
| DOM Standard # dom-document-createnodeiterator |

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

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

See also
--------

* Related interfaces: `TreeWalker` (en-US), `NodeIterator` (en-US).


Document.location - APIs da Web

Document.location
=================

A propriedade, de apenas leitura, **`Document.location`** retorna um objeto `Location`, que contém informações sobre a URL do documento e provém métodos para mudar a URL e carregar outra URL.

Embora `Document.location` seja um objeto `Location de apenas leitura`, você pode atribuir um `DOMString` para ele. Isso significa que você pode trabalhar com document.location, na maioria dos casos, como se fosse uma string: `document.location = 'http://www.example.com'` é um sinônimo de `document.location.href = 'http://www.example.com'`.

Para recuperar somente a URL como uma string, a propriedade de apenas leitura `document.URL` pode ser utilizada.

Se o documento atual não estiver no contexto de navegação, o valor retornado será `null`.

Sintaxe
-------
```

locationObj = document.location
document.location = 'http://www.mozilla.org' // Equivalente a document.location.href = 'http://www.mozilla.org'
```

Exemplo
-------

```js
dump(document.location);
// Imprime uma string como
// "http://www.example.com/juicybits.html" to the console
```

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

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

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

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

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

* O valor da interface de retorno, `Location`.
* Uma informação similar, mas anexada ao browsing context (en-US), `Window.location`.


Document.writeln() - APIs da Web

Document.writeln()
==================

Grava uma seqüência de texto, seguido por um caractere de nova linha a um documento.

Sintaxes
--------
```

document.writeln(line);
```

### Parâmetros

* `line`é uma string contendo uma linha de texto.
Exemplo
-------
```

document.writeln("<p>enter password:</p>");
```

Notas
-----

**document.writeln** é o mesmo que document.write mas acrescenta uma nova linha.

**Nota:** **document.writeln** (like **document.write**) does not work in XHTML documents (you'll get a "Operation is not supported" (`NS_ERROR_DOM_NOT_SUPPORTED_ERR`) error on the error console). This is the case if opening a local file with a .xhtml file extension or for any document served with an application/xhtml+xml MIME type. More information is available in the W3C XHTML FAQ.

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

writeln


Document.execCommand() - APIs da Web

Document.execCommand()
======================

Quando um documento HTML está em `designMode`, seu objeto `document` expõe um metodo **`execCommand`** para editar a região editável corrente, algo como elementos form inputs ou `contentEditable`.

A maioria dos comandos afetam apenas uma área selecionada [seleção] (negrito, itálico, etc.), enquantos outros adicionam novos elementos (adicionar um link por exemplo), ou afetam uma linha toda (identação). Quando usando `contentEditable`, o metódo `execCommand()` afeta o elemento editável ativo.

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

document.execCommand(aCommandName, aShowDefaultUI, aValueArgument)
```

### Valor de Retorno

Um `Boolean` que tem valor `false` se o comando não é válido ou está desabilitado.

**Nota:** Retorna `true` se for parte da interação do usuário. Não tente utilizar o retorno para verificar o suporte do browser antes de chamar o comando.

### Parâmetros

`aCommandName`

Uma `DOMString` especificando o nome do comando a ser executado. Veja Comandos para um lista dos possíveis comandos.

`aShowDefaultUI`

Um `Boolean` indicando se a interface padrão do usuário deve ser mostrada. Isso não é implementado no Mozilla.

`aValueArgument`

Para comandos que requerem um argumento de entrada. É uma `DOMString` provendo a informação. Por exemplo, `insertImage` requer uma URL da imagem a ser inserida. Use `null` se nenhum argumento é necessário.

### Comandos

`backColor`

Muda a cor de fundo do documento. No modo `styleWithCss`, ele afeta a cor de fundo do bloco que contém. Isso requer um valor de `<color>` passado como argumento. Observe que o Internet Explorer usa isso para definir a cor do plano de fundo do **texto**.

`bold`

Ativa / desativa negrito na seleção ou no ponto de inserção. O Internet Explorer usa a tag `<strong>` no lugar de `<b>`.

`ClearAuthenticationCache`

Limpa todas as credenciais de autenticação do cache.

`contentReadOnly`

Torna o documento de conteúdo somente leitura ou editável. Isso requer um valor booleano `true` / `false` como argumento. (Não é suportado pelo Internet Explorer.)

`copy`

Copia a seleção atual para a área de transferência. As condições para ativar esse comportamento variam de um navegador para outro e evoluíram com o tempo. Verifique a Tabela de Compatibilidade entre Browsers para determinar se você pode usar no seu caso.

`createLink`

Cria um hiperlink a partir da seleção, mas apenas se houver uma seleção. Requer uma string URI como argumento para o `href` do link. O URI deve conter pelo menos um único caractere, que pode ser um espaço em branco. (O Internet Explorer criará um link com um valor nulo.)

`cut`

Remove a seleção atual e a copia para a área de transferência. Quando esse comportamento é ativado, varia entre os navegadores e suas condições evoluíram com o tempo. Verifique a Tabela de Compatibilidade entre Browsers para mais detalhes.

`decreaseFontSize`

Adiciona a tag `<small>` (en-US) ao redor da seleção ou no ponto de inserção. (Não é suportado pelo Internet Explorer.)

`defaultParagraphSeparator`

Altera o separador de parágrafos usado quando novos parágrafos são criados em regiões de texto editáveis. Veja Diferenças na geração de marcação para mais detalhes.

`delete`

Exclui o conteúdo da seleção atual.

`enableAbsolutePositionEditor`

Habilita ou desabilita a garra que permite mover elementos absolutamente posicionados. Está desabilitado por padrão no Firefox 63 Beta / Dev Edition (Erro do Firefox 1449564)

`enableInlineTableEditing`

Ativa ou desativa os controles de inserção e exclusão de linhas / colunas da tabela. Está desabilitado por padrão no Firefox 63 Beta / Dev Edition (Erro do Firefox 1449564).

`enableObjectResizing`

Ativa ou desativa as alças de redimensionamento em imagens, tabelas e elementos absolutamente posicionados e outros objetos redimensionáveis. Está desabilitado por padrão no Firefox 63 Beta / Dev Edition (Erro do Firefox 1449564).

`fontName`

Altera o nome da fonte para a seleção ou no ponto de inserção. Isso requer uma string com o nome da fonte (como `"Arial"`) como argumento.

`fontSize`

Altera o tamanho da fonte para a seleção ou no ponto de inserção. Isso requer um número inteiro de `1`-`7` como argumento.

`foreColor`

Altera a cor da fonte para a seleção ou no ponto de inserção. Isso requer uma string de cor (hexadecimal) como argumento.

`formatBlock`

Adiciona um elemento de nível de bloco HTML ao redor da linha que contém a seleção atual, substituindo o elemento de bloco que contém a linha, se houver (no Firefox, `<blockquote>` é a exceção - envolverá qualquer elemento de bloco que contenha). Requer uma sequência de nome de tag como argumento de valor. Praticamente todos os elementos em nível de bloco podem ser usados. (Internet Explorer e Edge suportam apenas tags de cabeçalho `H1`–`H6`, `ADDRESS`, e `PRE`, que devem estar entre colchetes angulares, como `"<H1>"`.)

`forwardDelete`

Exclui o caractere depois da posição do cursor, idêntico a pressionar a tecla Delete em um teclado do Windows.

`heading`

Adiciona um elemento de cabeçalho ao redor de uma linha de seleção ou ponto de inserção. Requer uma string com o nome da tag como argumento (ex. `"H1"`, `"H6"`). (Não suportado pelo Internet Explorer e Safari.)

`hiliteColor`

Altera a cor do plano de fundo para a seleção ou no ponto de inserção. Requer uma sequência de valores de cores como argumento. `useCSS` tem de ser `true` para essa função. (Não é suportado pelo Internet Explorer.)

`increaseFontSize`

Adiciona uma tag `<big>` ao redor da seleção ou no ponto de inserção. (Não é suportado pelo Internet Explorer.)

`indent`

Recua a linha que contém o ponto de seleção ou inserção. No Firefox, se a seleção abranger várias linhas em diferentes níveis de recuo, apenas as linhas menos recuadas na seleção serão recuadas.

`insertBrOnReturn`

Controla se a tecla Enter insere um elemento `<br>`, ou divide o elemento do bloco atual em dois. (Não é suportado pelo Internet Explorer.)

`insertHorizontalRule`

Insere um elemento `<hr>` no ponto de inserção ou substitui a seleção por ele.

`insertHTML`

Insere uma string HTML no ponto de inserção (exclui a seleção). Requer uma string HTML válida como argumento. (Não é suportado pelo Internet Explorer.)

`insertImage`

Insere uma imagem no ponto de inserção (exclui a seleção). Requer uma string de URL para o `src` da imagem como argumento. Os requisitos para essa string são os mesmos que `createLink`.

`insertOrderedList`

Cria uma lista ordenada e numerada para a seleção ou no ponto de inserção.

`insertUnorderedList`

Cria uma lista não ordenada para a seleção ou no ponto de inserção.

`insertParagraph`

Insere um parágrafo ao redor da seleção ou da linha atual. (O Internet Explorer insere um parágrafo no ponto de inserção e exclui a seleção.)

`insertText`

Insere o texto fornecido no ponto de inserção (exclui a seleção).

`italic`

Ativa / desativa o itálico para a seleção ou no ponto de inserção. (O Internet Explorer usa o elemento `<em>` no lugar de `<i>`.)

`justifyCenter`

Centraliza o ponto de seleção ou inserção.

`justifyFull`

Justifica o ponto de seleção ou inserção.

`justifyLeft`

Justifica o ponto de seleção ou inserção à esquerda.

`justifyRight`

Justifica à direita a seleção ou o ponto de inserção.

`outdent`

Supera a linha que contém o ponto de seleção ou inserção.

`paste`

Cola o conteúdo da área de transferência no ponto de inserção (substitui a seleção atual). Desativado para conteúdo da web. Veja [1].

`redo`

Refaz o comando desfazer anterior.

`removeFormat`

Remove toda a formatação da seleção atual.

`selectAll`

Seleciona todo o conteúdo da região editável.

`strikeThrough`

Ativa / desativa o strikethrough(linha riscada) para a seleção ou no ponto de inserção.

`subscript`

Ativa / desativa o subscrito (en-US) para a seleção ou no ponto de inserção.

`superscript`

Ativa / desativa o superscript (en-US) para a seleção ou no ponto de inserção.

`underline`

Ativa / desativa o underline (en-US) para a seleção ou no ponto de inserção.

`undo`

Desfaz o último comando executado.

`unlink`

Remove o elemento âncora de um hiperlink selecionado.

`useCSS`
Deprecated

Alterna o uso de tags HTML ou CSS para a marcação gerada. Requer um booleano `true` / `false` como argumento.

NOTA: Este argumento é logicamente reverso (ou seja, use `false` para usar CSS, `true` para usar HTML) e não é suportado pelo Internet Explorer. Isso foi preterido em favor do `styleWithCSS`.

`styleWithCSS`

Substitui o comando `useCSS`. `true` modifica / gera atributos de `style` na marcação, `false` gera elementos de apresentação(html).

Exemplo
-------

Um exemplo de como usar a funcionalidade no CodePen.

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

| Especificação | Estado | Comentário |
| --- | --- | --- |
| execCommand |  |  |

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

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

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

* `HTMLElement.contentEditable`
* `document.designMode`
* Edição de Rich-Text com Mozilla
* Scribe: documentação sobre inconsitencias entre browsers com bugs relacionados a `document.execCommand`.


Document.documentElement - APIs da Web

Document.documentElement
========================

O **document.documentElement** retorna o `Elemento` que é o elemento raiz do `documento` (por exemplo, o elemento `<html>` para documentos HTML).

Sintaxe
-------
```

var element = document.documentElement;
```

Exemplo
-------

```js
var rootElement = document.documentElement;
var primeiroNivel = rootElement.childNodes;

// primeiroNivel é a NodeList do filho direto do elemento raíz
for (var i = 0; i < primeiroNivel.length; i++) {
  // faça algo com cada filho direto do elemento raiz
  // como primeiroNivel[i]
}
```

Notas
-----

Esta propriedade é uma conveniência somente leitura para obter o elemento raiz associado com qualquer documento.

Documentos HTML tipicamente contém somente um único nó filho, `<html>`, talvez com uma declaração DOCTYPE antes dele. Documentos XML, frequentemete contêm múltiplos nós filhos: o elemento de raiz, a declaração DOCTYPE, e as instruções de processamento.

É por isso que você deve usar `document.documentElement` em vez de `document.firstChild` para obter o elemento raiz.

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

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

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

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


Document.currentScript - APIs da Web

Document.currentScript
======================

Retorna o elemento que está sendo processado atualmente.

Sintaxe
-------
```

var curScriptElement = document.currentScript;
```

Exemplo
-------

O exemplo abaixo verifica se o script está sendo executado de forma assíncrona:

```js
if (document.currentScript.async) {
  console.log("Execução assíncrona");
} else {
  console.log("Execução síncrona");
}
```

View Live Examples

Nota
----

Se o código estiver sendo chamado como um callback ou manipulador de eventos, ele não irá referenciar o elemento; a referência ao elemento só acontece quando ele está sendo processado inicialmente.

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

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

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

* HTML5
Veja também
-----------

* `<script>`
* `element.onafterscriptexecute`
* `element.onbeforescriptexecute`


Conceitos da API Stream - APIs da Web

Conceitos da API Stream
=======================

A Streams API adiciona conjunto muito útil de ferramentas à plataforma web, provendo objetos que permitem ao JavaScript acessar via programação dados de stream recebidos pela rede e processá-los conforme desejado pelo desenvolvedor. Alguns conceitos e terminologias associadas a streams podem ser novos pra você - este artigo explicará tudo o que você precisa saber.

Readable streams
----------------

Um readable stream pode ser representado em JavaScript por um objeto `ReadableStream` (en-US) que flui de uma underlying source - é um recurso em algum lugar na rede ou outro lugar no domínio do qual deseja obter dados..

Há dois tipos de fontes subjacentes:

* **Push sources** constatemente envia dados enquanto os acessa, e você decide quando iniciar, pausar ou cancelar o acesso ao stream. Exemplos deste tipo incluem stream de vídeo e sockets TCP/Web sockets.
* **Pull sources** requer que você requisite os dados explicitamente uma conectado. Exemplos deste tipo incluem operações de acesso a arquivos via chamada Fetch ou XHR (en-US).

 O dado é lido sequencialmente em pequenos blocos de informação chamado chunks. Um chunk por ser um simples byte, ou, pode ser algo maior como um typed array de um certo tamanho.
 Um simples stream pode conter chunks de diferentes tamanhos e tipos.

 ![](/pt-BR/docs/Web/API/Streams_API/Concepts/readable_streams.png)

Os chunks alocados em um stream são ditos **enqueued** (enfileirados) — isto significa que eles estão aguardando em uma fila prontos para serem lidos. Uma **internal queue** rastreia os chunks que ainda não foram lidos (veja filas internas e estratégias de enfileiramento na sessão abaixo).

Os chunks dentro de um stream são lidos por um **reader** — este processa o dado de um chunk por vez, permitindo fazer qualquer tipo de operação que desejar .O reader com mais outro código de processamento junto é chamado **consumer**.

Há também uma construção que você usará chamada **controller** — cada reader tem um controller associado que lhe permite controlar o stream (por exemplo, cancelá-lo se desejar).

Apenas um reader pode ler um stream por vez; quando um reader é criado e inicia a leitura de um stream (um **active reader**), dizemos que ele está **atrelado** a ele. Se você deseja outro reader para iniciar a leitura de seu stream, você precisa tipicamente cancelar o primeiro reader antes de fazer qualquer coisa (embora você possa usar um stream **tee**, veja Teeing na sessão abaixo)

Observe que há dois tipos diferentes de readable streams. Assim como um readable stream convencional há um tipo chamado byte stream - este é uma versão extendida de um stream convencional para leitura de underlying byte sources (de outra forma conhecido como BYOB, ou "bring your own buffer"). Estes permitem que streams sejam lidos diretamente em um buffer fornecido pelo desenvolvedor, minimizando a cópia necessária. Tal underlying stream (e por extensão, reader e controller) seu código dependerá em primeiro lugar de como o stream foi criado (veja o `ReadableStream.ReadableStream()` (en-US) construtor de página).

**Aviso:** **Importante**: Bytes streams não estão implementados ainda em algum lugar, e foram levantadas questões sobre se os detalhes de especificação estão em condições para serem implementados. Isto pode mudar com o tempo.

Você pode fazer uso dos stream readers já implementados via mecanismos como `Response.body` (en-US) como uma requisição, ou com seus próprios streams usando o `ReadableStream.ReadableStream()` (en-US) como construtor.

Teeing
------

Embora um único reader possa ler um stream por vez, é possível dividir um stream em duas cópias idênticas, que podem então serem lidas por dois readers distintos. Isto é chamado **teeing.**

Em JavaScript, isto pode ser alcançado pelo método `ReadableStream.tee()` (en-US) — ele retorna um array contendo duas cópias idêniticas o readable stream original, o qual pode então ser lido independentemente por dois readers separados.

Você deve fazê-lo por exemplo em um ServiceWorker se deseja pegar a resposta de um servidor e disponibilizar via stream no navegador, mas, também disponibilizá-lo via cache do ServiceWorker. Uma vez que o corpo da resposta não pode ser consumido mais que uma vez, e um stream não pode ser lido por mais de um reader por vez, você precisaria de duas cópias para fazer isto.

![](/pt-BR/docs/Web/API/Streams_API/Concepts/tee.png)

Writable streams
----------------

Um **writable stream** é o destino o qual você pode escrever dados, representado em JavaScript pelo objeto `WritableStream` (en-US). Ele serve como uma camada de abstração sobre um **underlying sink** — um I/O de baixo-nivel que sincroniza quais dados brutos são escritos.

O dado é escrito para o stream via um **writer,** um chunk por vez. Um chunk pode ter uma infinidade de formas, assim como os chunk em um reader. Você pode usar qualquer código que desejar para produzir chunks prontos para escrever, mais o código associado ao **producer.**

Quando um writer é criado e inicia a escrita para um stream (um **active writer**), dizemos estar **locked** (atrelado) a este. Apenas um writer opde escrever em um writable stream por vez. Se deseja outro writer iniciar a escrita em seu stream, você deve tipicamente abortá-lo antes de anexar outro write à ele.

Uma **internal queue** mantém os chunks que foram escritos por um stream mas não foram ainda processados por underlying sink.

Há uma construção que você usará chamada controller — cada writer tem um controller associado que permite a você controlar o stream (por exemplo, abortá-lo se desejado).

![](/pt-BR/docs/Web/API/Streams_API/Concepts/writable_streams.png)

Você pode fazer uso de writable streams usando o construtor

You can make use of writable streams using the `WritableStream.WritableStream()` (en-US). Estes atualmente possuem uma disponibilidade limitada nos navegadores.

Pipe chains
-----------

A API de Streams torna possível encadear streams (ou pelo menos irá fazer quando os navegadores implementarem a funcionalidade relevante para tal) usando uma estrutura chamada **pipe chain**. Há dois métodos disponíveis na especificação para facilitá-lo:

* `ReadableStream.pipeThrough()` (en-US) — pipes de stream através do **transform stream**, que é um par compreendido do writable stream que possui dados escritos, e readable stream que então tem os dados lidos dele — ele atua como um tipo de esteira que constantemente pega a entrada de dados e os transforma em um outro estado. Efetivamente o mesmo stream é escrito para então os mesmos valores serem lidos. Um simples exemplo é um decodificador de texto, onde bytes brutos são escritos, e então strings são lidas. Você pode encontrar mais ideias úteis e exemplos na especificação — leia Transform streams para ideias e this web sockets example.
* `ReadableStream.pipeTo()` (en-US) — pipes para um writable stream que atua como um ponto final para a pipe chain.

Para iniciar um pipe chain é chamado o **original source**, e no final é chamado **ultimate sink**.

![](/pt-BR/docs/Web/API/Streams_API/Concepts/pipechain.png)

**Nota:** Esta funcionalidade não está totalmente pensada ainda, embora disponível em muitos navegadores. Até certo ponto espero que a especificação dos writers pode contribuir para algo como uma clase `TransformStream` para criar facilmente transform stream.

Backpressure
------------

Um importante conceito sobre streams é **backpressure** — é um processo pelo qual um stream simples ou uma pipe chain ajusta a velocidade de leitura/escrita. Quando um stream mais tarde na conrrente continua ocupado e não está ainda pronto para aceitar mais chunks, ele envia um sinal de volta através da corrente informar mais tarde o transform stream (ou a fonte original) para diminuir a velocidade de entrega conforme apropriado tal que você não precise terminar com um gargalo em algum lugar.

Para usar backpressure em um ReadableStream, podemos perguntar ao controller pelo tamanho do chunk desejado pelo consumer consultando o atributo `ReadableStreamDefaultController.desiredSize` (en-US) no controller. Se estiver muito baixo, nosso ReadableStream pode informar sua underlying source de dados e o backpressure junto a cadeira de stream.

Se mais tarde o consumer novamente deseja receber dados, podemos usar o método pull no stream para informar nossa underlying source para alimentar nosso stream com dados.

Internal queues and queuing strategies
--------------------------------------

Como mencionado antes, os chunks de um stream que não foram ainda processados e finalizados são mantidos por uma internal queue (fila interna).

* No caso de readable stream, esses chunks foram enfileirados mas ainda não lidos.
* No caso do writable stream, esses chunks que foram escritos mas ainda não processados pela underlying sink.

Filas internas trabalham com uma **queuing strategy**, o qual dita informar a backpressure baseado na **internal queue state.**

Em geral, a estratégia compara o tamanho dos chunks na fila com o valor chamado no **high water mark**, o qual é o total do maior valor de chunk que a fila pode gerenciar de modo realista.

O cálculo realizado é
```

high water mark - total size of chunks in queue = desired size
```

O **desired size** é o tamanho de chunks que um stream ainda pode aceitar para manter o fluxo do stream menor que o high water mark. Após o cálculo ser efetuado, a geração de chunks terá sua velocidade reduzida ou aumentada conforme apropriado para manter o fluxo do stream o mais rápido possível enquanto mantém o tamanho desejado acima de zero. Se o valor cair para zero (ou menor no caso de writable streams), significa que os chunks estão sendo gerados mais rápido que o stream pode lidar, o qual resulta em problemas.

**Nota:** O que ocorre no caso em que valor desejado for zero ou negativo não foi definido na especificação até o momento. Paciência é uma virtude.

Como um exemplo, vamos pegar um chunk de tamanho 1, e uma high water mark de 3. Isto significa que até 3 chunks podem ser enfileirados antes que a high water mark seja alcançada e o backpressure aplicado.


Storage.removeItem() - APIs da Web

Storage.removeItem()
====================

O método `removeItem()` da interface `Storage`, quando passado um nome de chave, irá remover essa chave do armazenamento.

Syntax
------
```

storage.removeItem(keyName);
```

### Parâmetros

***keyName***

A `DOMString` contendo o nome da chave que você deseja remover.

### Retorno

*Nenhum valor de retorno.*

Exemplo
-------

A função a seguir cria três itens de dados no armazenamento local, em seguida, remove o item "image".

```js
function populateStorage() {
  localStorage.setItem("bgcolor", "red");
  localStorage.setItem("font", "Helvetica");
  localStorage.setItem("image", "myCat.png");

  localStorage.removeItem("image");
}
```

**Nota:** Para ver o uso em um exemplo prático veja nosso Web Storage Demo.

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

| Specification |
| --- |
| HTML Standard # dom-storage-removeitem-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 Web Storage


Storage.key() - APIs da Web

Storage.key()
=============

O método **`key()`** da interface `Storage`, quando passado um número n, retorna o nome da n-ésima chave no dado objeto `Storage`. A ordem das chaves é definida pelo user-agent, então não deve-se confiar nela.

Syntax
------
```

var aKeyName = storage.key(index);
```

### Parâmetros

`index`

Um inteiro representando o número da chave que deseja obter. Esse é um índice que começa em zero.

### Retorno

Uma `DOMString` contendo o nome da chave. Se o index não existir, retornará `null`.

Exemplos
--------

A função a seguir itera sobre as chaves do armazenamento local:

```js
function forEachKey(callback) {
  for (var i = 0; i < localStorage.length; i++) {
    callback(localStorage.key(i));
  }
}
```

A função a seguir itera sobre as chaves do armazenamento local e obtém o valor de cada chave:

```js
for (var i = 0; i < localStorage.length; i++) {
  console.log(localStorage.getItem(localStorage.key(i)));
}
```

**Nota:** Pra ver um exemplo real, consulte nossa Demonstração de armazenamento na Web.

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

| Specification |
| --- |
| HTML Standard # dom-storage-key-dev |

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


Storage.length - APIs da Web

Storage.length
==============

A propriedade length, que é somente leitura, da interface `Storage` retorna um inteiro que representa o número de itens armazenados no objeto `Storage`.

Sintaxe
-------
```

var aLength = storage.length;
```

### Retorno

Um inteiro

Exemplo
-------

A função a seguir adiciona três itens ('bgcolor', 'font' e 'image') ao local storage do domínio atual, em seguida retorna o número de itens no storage:

```js
function populateStorage() {
  localStorage.setItem("bgcolor", "yellow");
  localStorage.setItem("font", "Helvetica");
  localStorage.setItem("image", "cats.png");

  localStorage.length; // should return 3
}
```

**Nota:** Para um exemplo do mundo real, veja nosso Web Storage Demo.

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

| Specification |
| --- |
| HTML Standard # dom-storage-length-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 Web Storage


Storage.setItem() - APIs da Web

Storage.setItem()
=================

O método `setItem()` da interface `Storage`, quando passado 'chave' e 'valor', irá adicionar esta chave ao storage, ou atualizar o valor caso a chave já exista.

Syntax
------
```

storage.setItem(keyName, keyValue);
```

### Parâmetros

*keyName*

Um `DOMString` contendo o nome da chave que você deseja criar ou alterar.

*keyValue*

Um `DOMString` contendo o valor da chave que você está criando ou atualizando.

### Retornos

*Sem retorno.*

### Exceções

`setItem()` poderá lançar uma exceção caso o storage esteja cheio. Particularmente, no Safari Mobile (desde o iOS 5) sempre irá lançar quando o usuário entrar em modo privado (Safari define a quota para 0 bytes no modo privado ao contrário de outros navegadores que permitem o armazenamento em modo privado, usando recipientes de dados separados).
 Assim os desenvolvedores devem certificar-se de **sempre tratar as possíveis exceções do `setItem()`**.

Exemplo
-------

A função abaixo irá criar três dados dentro do local storage.

```js
function populateStorage() {
  localStorage.setItem("bgcolor", "red");
  localStorage.setItem("font", "Helvetica");
  localStorage.setItem("image", "myCat.png");
}
```

**Nota:** Para ver ele sendo usado em um exemplo real, consulte nosso Web Storage Demo.

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

| Specification |
| --- |
| HTML Standard # dom-storage-setitem-dev |

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

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

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

Usando a Web Storage API


Storage.clear() - APIs da Web

Storage.clear()
===============

O método `clear()` da interface `Storage`, quando realizado uma chamada, todas as chaves do armazenamento são esvaziadas.

Syntaxe
-------

```js
storage.clear();
```

### Parametros

*Nenhum parametro..*

### Retorno

*Nenhum retorno.*

Exemplo
-------

A função abaixo cria três itens e armazenam localmente, depois remove todos utilizando a função clear().

```js
function populateStorage() {
  localStorage.setItem("bgcolor", "red");
  localStorage.setItem("font", "Helvetica");
  localStorage.setItem("image", "myCat.png");

  localStorage.clear();
}
```

**Nota:** Para visualizar um exemplo real, veja nossa seção Demonstração de Web Storage.

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

| Specification |
| --- |
| HTML Standard # dom-storage-clear-dev |

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

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

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

Utilizando a API Web Storage


localStorage.getItem() - APIs da Web

localStorage.getItem()
======================

Passar o nome da chave para o método `getItem()` da interface `Storage` retornará o seu valor.

Sintaxe
-------
```

var aValue = localStorage.getItem(keyName);
```

### Parâmetros

*`keyName`*

Um `DOMString` contendo o nome da chave cujo valor você quer obter.

### Retorno

Um `DOMString` contendo o valor da chave. Se a chave não existe, é retornado null.

Exemplo
-------

A função seguinte recupera três itens armazenados no local storage e usa-os para definir estilos customizados em uma página.

```js
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 essa funcionalidade aplicada a um exemplo real, veja nossa Web Storage Demo.

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

| Specification |
| --- |
| HTML Standard # dom-storage-getitem-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 Web Storage


URLSearchParams.get() - APIs da Web

URLSearchParams.get()
=====================

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

O métod **get()** da interface `URLSearchParams`, retorna o primeiro valor associado ao parametro de busca fornecido.

Syntax
------
```

URLSearchParams.get(name)
```

### Parâmetros

name

O nome do parâmetro à ser retornado.

### Retorno

Um `USVString` (en-US) se o parâmetro de pesquisa for encontrado; Caso contrário, **`null`**.

Exemplo
-------

Se a URL da sua página é `https://example.com/?name=Jonathan&age=18` você pode obter o parâmetro 'name' e 'age' usando:
```

let params = new URLSearchParams(document.location.search.substring(1));
let name = params.get("name"); // retorna a string "Jonathan"
let age = parseInt(params.get("age"), 10); // retorna o número 18
```

Buscar um parâmetro que não esteja presente na string de pesquisa, retornará **`null`**:
```

let address = params.get("address"); // null
```

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

| Specification |
| --- |
| URL Standard # dom-urlsearchparams-get |

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

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


URLSearchParams.values() - APIs da Web

URLSearchParams.values()
========================

O m*étodo* \*\*`URLSearchParams.values()`\*\*retorna um `iterator` que permite passar por todos os valores do objeto. Os valores são objetos `USVString` (en-US).

**Nota:** Esse método está disponível no Web Workers.

Sintaxe
-------
```

searchParams.values();
```

### Valor de retorno

Retorna um `iterator`.

Exemplo
-------

```js
// Cria um objeto URLSearchParams
var searchParams = new URLSearchParams("key1=value1&key2=value2");

// Mostra os pares de chave/valor
for (var value of searchParams.values()) {
  console.log(value);
}
```

O resultado é:
```

value1
value2
```

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

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

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

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

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

* Outras interfaces relacionadas à URL: `URL`, `URLUtils`.


RTCPeerConnection.connectionState - APIs da Web

RTCPeerConnection.connectionState
=================================

A propriedade **`connectionState`** do tipo somente leitura da interface `RTCPeerConnection` (en-US) indica o estado atual da conexão em par, devolvendo um valor em string específicado por um enum `RTCPeerConnection` (en-US).

Quando o valor da propriedade muda, o evento `connectionstatechange` é enviado para a intância `RTCPeerConnection` (en-US).

Syntax
------
```

var connectionState = RTCPeerConnection.connectionState;
```

### Value

O estado atual da conexão, como um valor do enum `RTCPeerConnectionState`.

{{page("/pt-BR/docs/Web/API/RTCPeerConnection", "RTCPeerConnectionState enum", 0, 1)}}Example
-------

```js
var pc = new RTCPeerConnection(configuration);

/\* ... \*/

var connectionState = pc.connectionState;
```

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

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # dom-peerconnection-connection-state |

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

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

See also
--------

* Lifetime of a WebRTC session (en-US)
* `RTCPeerConnection` (en-US)
* `connectionstatechange`
* WebRTC (en-US)


CustomElementRegistry.whenDefined() - APIs da Web

CustomElementRegistry.whenDefined()
===================================

 O **`whenDefined()`** é um método de `CustomElementRegistry` e a interface retorna uma `Promise` que é resolvido quando o elemento nomeado é
 definido.

Syntax
------

```js
customElements.whenDefined(name): Promise<CustomElementConstructor>;
```

### Parâmetros

name

Nome do elemento personalizado.

### Valor de retorno

 A `Promise` que será cumprida com o elemento personalizado (en-US)'s construtor quando um
 custom element (en-US) torna-se definido com o nome fornecido. (Se o custom element (en-US) já foi
 definido, a promessa devolvida será imediatamente cumprida.)

### Exceções

| Exceção | Descrição |
| --- | --- |
| `SyntaxError` | Se o nome fornecido não for um nome de elemento personalizado válido, a promessa rejeita com um `SyntaxError`. |

Exemplos
--------

 Este exemplo usa `whenDefined()` para detectar quando os elementos personalizados que compõem um menu são definidos. O menu exibe o conteúdo do espaço reservado até que o conteúdo do
 menu real esteja pronto para ser exibido.

```html
<nav id="menu-container">
  <div class="menu-placeholder">Loading...</div>
  <nav-menu>
    <menu-item>Item 1</menu-item>
    <menu-item>Item 2</menu-item>
    ...
    <menu-item>Item N</menu-item>
  </nav-menu>
</nav>
```

```js
const container = document.getElementById("menu-container");
const placeholder = container.querySelector(".menu-placeholder");
// Busca todos os filhos do menu que ainda não foram definidos.
const undefinedElements = container.querySelectorAll(":not(:defined)");

async function removePlaceholder() {
  const promises = [...undefinedElements].map((button) =>
    customElements.whenDefined(button.localName),
  );

  // Espere que todos os filhos sejam atualizados
  await Promise.all(promises);
  // em seguida, remova o espaço reservado
  container.removeChild(placeholder);
}

removePlaceholder();
```

Specifications
--------------

| Specification |
| --- |
| HTML Standard # dom-customelementregistry-whendefined-dev |

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

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


CustomElementRegistry.upgrade() - APIs da Web

CustomElementRegistry.upgrade()
===============================

 O **`upgrade()`** é um método de `CustomElementRegistry` a interface atualiza todos os shadow-containing custom elements em um `Node` da
 subárvore, mesmo antes de estarem conectados ao principal documento.

Syntax
------

```js
customElements.upgrade(root);
```

### Parâmetros

`root`

 Uma instância de `Node` com shadow-containing os elementos descendentes que serão atualizados. Se não houver elementos descendentes que possam ser atualizados, nenhum erro será
 emitido.

### Valor de retorno

Void.

Exemplos
--------

Retirado de HTML spec:

```js
const el = document.createElement("spider-man");

class SpiderMan extends HTMLElement {}
customElements.define("spider-man", SpiderMan);

console.assert(!(el instanceof SpiderMan)); // Ainda não atualizado

customElements.upgrade(el);
console.assert(el instanceof SpiderMan); // Atualizado!
```

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

| Specification |
| --- |
| HTML Standard # dom-customelementregistry-upgrade-dev |

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

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


CustomElementRegistry.define() - APIs da Web

CustomElementRegistry.define()
==============================

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

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

* Learn more
* See full compatibility
* Report feedback
O método **`define()`** da interface `CustomElementRegistry` define um novo elemento personalizado.

Dois tipos de elementos personalizados podem ser criados:

* **Elementos personalizados autônomos**: Elementos autônomos; estes herdam de HTMLElement (Elemento HTML genérico).
* **Elementos personalizados pré-construídos**: Estes elementos herdam - e estendem - elementos HTML já existentes (p.ej HTMLParagraphElement que é um elemento HTML
 `<p>`).
Sintaxe
-------
```

customElements.define(name, constructor, options);
```

### Parâmetros

name

Nome do novo item personalizado. Observe que os nomes dos elementos personalizados devem conter um hífen.

constructor

Construtor para o novo elemento personalizado

options Optional

Um objeto que controla como o elemento é definido. Atualmente, apenas uma opção é permitida:

* `extends`: String que especifica o nome do elemento pré-definido a partir do qual se estende. Usado para criar*elementos personalizados pré-construídos*.

### Valor de retorno

Void.

### Exceções

| Exceção | Descrição |
| --- | --- |
| `NotSupportedError` | El `CustomElementRegistry` já contém uma entrada com o mesmo nome ou o mesmo construtor (ou já foi definido de alguma outra forma), ou foi especificado `extends` mas o elemento do qual você está tentando estender é desconhecido. |
| `SyntaxError` | O nome fornecido não é um nome de elemento personalizado válido. |
| `TypeError` | O constructor referenciado não é um constructor |

**Nota:** Exceções são frequentemente obtidas `NotSupportedError`s quando o método `define()` está falhando, mas é realmente um problema relacionado a
 `Element.attachShadow()` (en-US).

Exemplos
--------

### Elemento personalizado autônomo

O código a seguir é retirado do nosso exemplo popup-info-box-web-component (ver ao vivo).

```js
// Crie uma classe para o elemento
class PopUpInfo extends HTMLElement {
  constructor() {
    // Sempre a primeira coisa a fazer é chamar super no construtor
    super();

    // crie um shadow root
    var shadow = this.attachShadow({ mode: "open" });

    // Crie três elementos span
    var wrapper = document.createElement("span");
    wrapper.setAttribute("class", "wrapper");

    var icon = document.createElement("span");
    icon.setAttribute("class", "icon");
    icon.setAttribute("tabindex", 0);

    var info = document.createElement("span");
    info.setAttribute("class", "info");

    // Pegue o conteúdo do atributo de texto e coloque-o no span info
    var text = this.getAttribute("text");
    info.textContent = text;

    // Pegue o conteúdo do atributo img (se existir) e coloque-o no ícone de span
    var imgUrl;
    if (this.hasAttribute("img")) {
      imgUrl = this.getAttribute("img");
    } else {
      imgUrl = "img/default.png";
    }

    // A extensão não pode ter diretamente uma imagem, mas se contiver um elemento img
    var img = document.createElement("img");
    img.src = imgUrl;
    icon.appendChild(img);

    // Crie os estilos CSS e inclua-os no shadow DOM
    var style = document.createElement("style");

    style.textContent =
      ".wrapper {" +
      "position: relative;" +
      "}" +
      ".info {" +
      "font-size: 0.8rem;" +
      "width: 200px;" +
      "display: inline-block;" +
      "border: 1px solid black;" +
      "padding: 10px;" +
      "background: white;" +
      "border-radius: 10px;" +
      "opacity: 0;" +
      "transition: 0.6s all;" +
      "position: absolute;" +
      "bottom: 20px;" +
      "left: 10px;" +
      "z-index: 3;" +
      "}" +
      "img {" +
      "width: 1.2rem" +
      "}" +
      ".icon:hover + .info, .icon:focus + .info {" +
      "opacity: 1;" +
      "}";

    // anexar os elementos criados (extensões e estilo) ao shadow DOM
    // observe que o span wrapper contém o ícone e os spans de informações

    shadow.appendChild(style);
    shadow.appendChild(wrapper);
    wrapper.appendChild(icon);
    wrapper.appendChild(info);
  }
}

// Defina um novo elemento
customElements.define("popup-info", PopUpInfo);
```

```html
<popup-info
 img="img/alt.png"
 text="O código de validação do seu cartão (CVC) é um recurso segurança extra - consiste em 3 ou 4 números no verso do seu cartão."></popup-info>
```

**Nota:** Construtores de elementos personalizados autocontidos devem estender `HTMLElement` (en-US).

### Elemento personalizado pré-construído

O código a seguir é retirado do nosso exemplo word-count-web-component (ver ao vivo).

```js
// Crie uma classe para o elemento
class WordCount extends HTMLParagraphElement {
  constructor() {
    // Sempre a primeira coisa a fazer é chamar super no construtor
    super();

    // contar palavras do pai deste elemento
    var wcParent = this.parentNode;

    // A função countWords conta palavras (mesmo que sejam separadas por amis de um espaço)
    // que existe no nó passado como parâmetro.
    // innerText está definido para objetos HTMLElement, enquanto textContent para todos os objetos Node
    // o operador || nos faz pegar pelo menos um dos dois

    function countWords(node) {
      var text = node.innerText || node.textContent;
      return text.split(/\s+/g).length;
    }

    var count = "Words: " + countWords(wcParent);

    // crie um shadow root
    var shadow = this.attachShadow({ mode: "open" });

    // Crie um nó span com o número de palavras
    var text = document.createElement("span");
    text.textContent = count;

    // Adicione ao shadow root
    shadow.appendChild(text);

    // Atualize o contador quando o conteúdo do elemento mudar
    setInterval(function () {
      var count = "Words: " + countWords(wcParent);
      text.textContent = count;
    }, 200);
  }
}

// Defina o novo elemento
customElements.define("word-count", WordCount, { extends: "p" });
```

```html
<p is="word-count"></p>
```

### Criando elemento que desativa a capacidade de utilizar attach no shadow root

 Se a classe usada para o elemento contém a propriedade estática `disabledFeatures` retornando a string "shadow" isso fará com que `Element.attachShadow()` (en-US) retorne um
 `DOMException` (en-US) `NotSupportedError`.

```js
class PopUpInfo extends HTMLElement {
  static get disabledFeatures() {
    return ["shadow"];
  }

  constructor() {
    super();

    var shadow = this.attachShadow({ mode: "open" });
    // isso fará com que um erro seja lançado quando o elemento for definido.
  }
}
```

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

| Specification |
| --- |
| HTML Standard # dom-customelementregistry-define-dev |

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

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


CustomElementRegistry.get() - APIs da Web

CustomElementRegistry.get()
===========================

O **`get()`** é um método de `CustomElementRegistry` a interface retorna um construtor para um elemento personalizado previamente definido.

Syntax
------

```js
constructor = customElements.get(name);
```

### Parâmetros

name

O nome do elemento personalizado cujo construtor você deseja retornar uma referência.

### Valor de retorno

O construtor do elemento personalizado nomeado, ou `undefined`se não há definição de elemento personalizado com esse nome.

Examples
--------

```js
customElements.define(
  "my-paragraph",
  class extends HTMLElement {
    constructor() {
      let templateContent = document.getElementById("my-paragraph").content;
      super() // returns element this scope
        .attachShadow({ mode: "open" }) // sets AND returns this.shadowRoot
        .append(templateContent.cloneNode(true));
    }
  },
);

// Retorne uma referência ao construtor my-paragraph
let ctor = customElements.get("my-paragraph");
```

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

| Specification |
| --- |
| HTML Standard # dom-customelementregistry-get-dev |

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

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


Usando custom elements - APIs da Web

Usando custom elements
======================

Um dos principais recursos do padrão de Web Components é a capacidade de criar elementos personalizados que encapsulam sua funcionalidade em uma página HTML, em vez de ter que se contentar com um lote longo e aninhado de elementos que, juntos, fornecem um recurso de página personalizada. Este artigo apresenta o uso da API de Custom Elements.

**Nota:** Custom elements são suportados por padrão no Firefox, Chrome e Edge (76). Opera e Safari até agora suportam apenas custom elements autônomos.

Visão de alto nível
-------------------

O controlador de custom elements em um documento da web é o objeto `CustomElementRegistry` — este objeto permite que você registre um custom element na página, retorne informações sobre quais custom elements estão registrados, etc..

Para registar um custom element na página, use o método `CustomElementRegistry.define()`. Isso leva como argumentos:

* Um `DOMString` que representa o nome que você está dando ao elemento. Observe que os nomes dos custom elements requerem o uso de um traço (kebab-case); não podem ser palavras isoladas.
* Um objeto de classe que define o comportamento do elemento.
* Opcionalmente, um objeto de opções contendo uma propriedade `extends`, que especifica o elemento integrado do qual seu elemento herda, se houver (relevante apenas para elementos integrados personalizados; consulte a definição abaixo).

Então, por exemplo, podemos definir um custom element word-count `(contagem-palavras)` assim:

```js
customElements.define("word-count", WordCount, { extends: "p" });
```

O elemento é chamado de `word-count`, seu objeto de classe é `WordCount`, e estende o elemento `<p>`.

O objeto de classe de um custom element é escrito usando a sintaxe de classe ES 2015. Por exemplo, `WordCount` é estruturado assim::

```js
class WordCount extends HTMLParagraphElement {
  constructor() {
    // Sempre chame super primeiro no construtor
    super();

    // Funcionalidade do elemento escrita aqui

    ...
  }
}
```

Este é apenas um exemplo simples, mas você pode fazer mais aqui. É possível definir retornos de chamada de ciclo de vida específicos dentro da classe, que são executados em pontos específicos do ciclo de vida do elemento. Por exemplo, `connectedCallback` é invocado cada vez que o custom element é anexado a um elemento conectado ao documento, enquanto `attributeChangedCallback` é invocado quando um dos atributos do elemento customizado é adicionado, removido ou alterado.

Você aprenderá mais sobre eles na seção Using the lifecycle callbacks abaixo.

Existem dois tipos de custom elements:

* **Autonomous custom elements** são autonômos — eles não herdam de elementos HTML padrão. Você os usa em uma página, literalmente escrevendo-os como um elemento HTML. Por exemplo `<popup-info>`, ou `document.createElement("popup-info")`.
* **Customized built-in elements** herdam de elementos HTML básicos. Para criar um deles, você deve especificar qual elemento eles estendem (como implícito nos exemplos acima), e eles são usados escrevendo o elemento básico, mas especificando o nome do elemento personalizado no atributo `is` (ou propriedade). Por exemplo `<p is="word-count">`, ou `document.createElement("p", { is: "word-count" })`.
Trabalhando com alguns exemplos simples
---------------------------------------

Neste ponto, vamos examinar mais alguns exemplos simples para mostrar como os custom elements são criados com mais detalhes.

### Custom elements autônomos

Vamos dar uma olhada em um exemplo de um custom element autônomo — `<popup-info-box>` (veja um exemplo ao vivo). Isso pega um imagem de ícone e uma sequência de texto e incorpora o ícone na página. Quando o ícone está em foco, ele exibe o texto em uma caixa pop-up de informações para fornecer mais informações no contexto.

Para começar, o arquivo JavaScript define uma classe chamada `PopUpInfo`, que estende a classe genérica `HTMLElement` (en-US).

```js
class PopUpInfo extends HTMLElement {
  constructor() {
    // Sempre chame super primeiro no construtor
    super();

    // escreva a funcionalidade do elemento aqui

    ...
  }
}
```

O trecho de código anterior contém a definição do `constructor()` da classe, que sempre começa chamando `super()` para que a cadeia de protótipo correta seja estabelecida.

Dentro do construtor, definimos toda a funcionalidade que o elemento terá quando uma instância dele for instanciada. Neste caso, anexamos uma shadow root ao custom element, usamos alguma manipulação de DOM para criar a estrutura de shadow DOM interna do elemento - que é então anexada à shadow root - e, finalmente, anexamos algum CSS à shadow root para estilizá-la.

```js
// Create a shadow root
this.attachShadow({ mode: "open" }); // sets and returns 'this.shadowRoot'

// Create (nested) span elements
const wrapper = document.createElement("span");
wrapper.setAttribute("class", "wrapper");
const icon = wrapper.appendChild(document.createElement("span"));
icon.setAttribute("class", "icon");
icon.setAttribute("tabindex", 0);
// Insert icon from defined attribute or default icon
const img = icon.appendChild(document.createElement("img"));
img.src = this.hasAttribute("img")
  ? this.getAttribute("img")
  : "img/default.png";

const info = wrapper.appendChild(document.createElement("span"));
info.setAttribute("class", "info");
// Take attribute content and put it inside the info span
info.textContent = this.getAttribute("data-text");

// Create some CSS to apply to the shadow dom
const style = document.createElement("style");
style.textContent =
  ".wrapper {" +
  // CSS truncated for brevity

  // attach the created elements to the shadow DOM
  this.shadowRoot.append(style, wrapper);
```

Por fim, registramos nosso custom element no `CustomElementRegistry` usando o método`define()` mencionado anteriormente — nos parâmetros especificamos o nome do elemento e, em seguida, o nome da classe que define sua funcionalidade:

```js
customElements.define("popup-info", PopUpInfo);
```

Agora está disponível para uso em nossa página. Em nosso HTML, nós o usamos assim:

```html
<popup-info
 img="img/alt.png"
 data-text="Your card validation code (CVC)
 is an extra security feature — it is the last 3 or 4 numbers on the
 back of your card."></popup-info>
```

**Nota:** Você pode ver o código-fonte JavaScript completo aqui.

### Estilos internos vs. externos

No exemplo acima, aplicamos o estilo ao Shadow DOM usando um elemento `<style>`, mas é perfeitamente possível fazer isso referenciando uma folha de estilo externa de um elemento `<link>` em vez disso.

Por exemplo, dê uma olhada neste código de nosso exemplo popup-info-box-external-stylesheet (veja o código-fonte):

```js
// Aplicar estilos externos ao shadow dom
const linkElem = document.createElement("link");
linkElem.setAttribute("rel", "stylesheet");
linkElem.setAttribute("href", "style.css");

// Anexe o elemento criado ao shadow dom
shadow.appendChild(linkElem);
```

Observe que os elementos `<link>` não bloqueiam a pintura do shadow root, portanto, pode haver um flash de conteúdo não estilizado (FOUC) enquanto a folha de estilo é carregada.

Muitos navegadores modernos implementam uma otimização para tags `<style>` clonadas de um nó comum ou que tenham texto idêntico, para permitir que compartilhem uma única folha de estilo de apoio. Com essa otimização, o desempenho dos estilos externo e interno deve ser semelhante.

### Customized built-in elements

Agora vamos dar uma olhada em outro exemplo de custom element integrado — expanding-list (ver ao vivo também). Isso transforma qualquer lista não ordenada em um menu de expansão/recolhimento.

Em primeiro lugar, definimos a classe do nosso elemento, da mesma maneira que antes:

```js
class ExpandingList extends HTMLUListElement {
  constructor() {
    // Sempre chame super primeiro no construtor
    super();

    // escreva a funcionalidade do elemento aqui

    ...
  }
}
```

Não explicaremos a funcionalidade do elemento em detalhes aqui, mas você pode descobrir como ele funciona verificando o código-fonte. A única diferença real aqui é que nosso elemento está estendendo a interface `HTMLUListElement` (en-US), e não `HTMLElement` (en-US). Portanto, ele tem todas as características de um elemento `<ul>` com a funcionalidade que definimos construída no topo, ao invés de ser um elemento autônomo. Isso é o que o torna um elemento integrado personalizado, em vez de um elemento autônomo.

Em seguida, registramos o elemento usando o método `define()` como antes, exceto que, desta vez, ele também inclui um objeto de opções que detalha de qual elemento nosso elemento personalizado herda:

```js
customElements.define("expanding-list", ExpandingList, { extends: "ul" });
```

Usar o elemento integrado em um documento da web também parece um pouco diferente:

```html
<ul is="expanding-list">
  ...
</ul>
```

Você usa um elemento `<ul>` normalmente, mas especifica o nome do elemento personalizado dentro do atributo `is`.

**Nota:** Novamente, você pode ver o código-fonte JavaScript completo aqui.

Usando os callbacks do ciclo de vida
------------------------------------

Você pode definir vários retornos de chamada diferentes dentro da definição de classe de um custom element, que disparam em diferentes pontos do ciclo de vida do elemento:

* `connectedCallback`: Chamado sempre que o custom element é anexado a um elemento conectado ao documento. Isso acontecerá sempre que o nó for movido e pode acontecer antes que o conteúdo do elemento tenha sido totalmente analisado.

**Nota:** `connectedCallback` pode ser chamado assim que seu elemento não estiver mais conectado, use `Node.isConnected` para ter certeza.
* `disconnectedCallback`: Invocado sempre que o custom element é desconectado do documento DOM.
* `adoptedCallback`: Invocado sempre que o custom element é movido para um novo documento.
* `attributeChangedCallback`: Invocado sempre que um dos atributos do custom element é adicionado, removido ou alterado. Os atributos a serem observados na mudança são especificados em um método estático `observedAttributes`

Vejamos um exemplo em uso. O código abaixo é retirado do exemplo life-cycle-callbacks (ver rodando ao vivo). Este é um exemplo trivial que simplesmente gera um quadrado colorido de tamanho fixo na página. O custom element tem a seguinte aparência:

```html
<custom-square l="100" c="red"></custom-square>
```

O construtor da classe é realmente simples - aqui anexamos um shadow DOM ao elemento e, em seguida, anexamos os elementos vazios `<div>` e `<style>` ao shadow root:

```js
const shadow = this.attachShadow({ mode: "open" });

const div = document.createElement("div");
const style = document.createElement("style");
shadow.appendChild(style);
shadow.appendChild(div);
```

A função chave neste exemplo é `updateStyle()` — isso pega um elemento, pega seu shadow root, encontra seu elemento `<style>`, e adiciona `width`, `height`, e `background-color` para o estilo.

```js
function updateStyle(elem) {
  const shadow = elem.shadowRoot;
  shadow.querySelector("style").textContent = `
 div {
 width: ${elem.getAttribute("l")}px;
 height: ${elem.getAttribute("l")}px;
 background-color: ${elem.getAttribute("c")};
 }
 `;
}
```

As atualizações reais são todas tratadas pelos retornos de chamada do ciclo de vida, que são colocados dentro da definição da classe como métodos. O `connectedCallback()` é executado sempre que o elemento é adicionado ao DOM - aqui, executamos a função `updateStyle()` para garantir que o quadrado seja estilizado conforme definido em seus atributos:

```js
connectedCallback() {
  console.log('Custom square element added to page.');
  updateStyle(this);
}
```

Os retornos de chamada `disconnectedCallback()` e `adoptedCallback()` registram mensagens simples no console para nos informar quando o elemento é removido do DOM ou movido para uma página diferente:

```js
disconnectedCallback() {
  console.log('Custom square element removed from page.');
}

adoptedCallback() {
  console.log('Custom square element moved to new page.');
}
```

O `attributeChangedCallback()` é executado sempre que um dos atributos do elemento é alterado de alguma forma. Como você pode ver por suas propriedades, é possível atuar sobre os atributos individualmente, observando seus nomes e antigos e novos valores de atributos. Neste caso, entretanto, estamos apenas executando a função `updateStyle()` novamente para garantir que o estilo do quadrado seja atualizado de acordo com os novos valores:

```js
attributeChangedCallback(name, oldValue, newValue) {
  console.log('Custom square element attributes changed.');
  updateStyle(this);
}
```

Observe que, para fazer com que o retorno de chamada `attributeChangedCallback()` seja acionado quando um atributo for alterado, você deve observar os atributos. Isso é feito especificando um método `static get observedAttributes()` dentro da classe de custom element - isso deve `retornar` um array contendo os nomes dos atributos que você deseja observar:

```js
static get observedAttributes() { return ['c', 'l']; }
```

Isso é colocado bem no topo do construtor, em nosso exemplo.

**Nota:** Encontre o código-fonte JavaScript completo aqui.

Polyfills vs. classes
---------------------

Polyfills de Custom Element podem corrigir construtores nativos, como `HTMLElement` e outros, e retornar uma instância diferente daquela recém-criada.

Se você precisar de um `constructor` e uma chamada de `super` obrigatória, lembre-se de passar argumentos opcionais e retornar o resultado de tal chamada de `super`.

```js
class CustomElement extends HTMLElement {
  constructor(...args) {
    const self = super(...args);
    // self functionality written in here
    // self.addEventListener(...)
    // return the right context
    return self;
  }
}
```

Se você não precisa realizar nenhuma operação no construtor, você pode simplesmente omiti-lo para que seu comportamento nativo (veja a seguir) seja preservado.

```js
 constructor(...args) { return super(...args); }
```

Transpiladores vs. classes
--------------------------

Observe que as classes ES2015 não podem ser transpiladas de forma confiável em Babel 6 ou TypeScript visando navegadores legados. Você pode usar o Babel 7 ou o babel-plugin-transform-builtin-classes para Babel 6, e target ES2015 em TypeScript em vez do legado..

Bibliotecas
-----------

Existem várias bibliotecas que são construídas em Web Components com o objetivo de aumentar o nível de abstração ao criar elementos personalizados. Algumas dessas bibliotecas são snuggsi ツ, X-Tag, Slim.js, LitElement, Smart, Stencil e hyperHTML-Element.


Usando eventos enviados pelo servidor - APIs da Web

Usando eventos enviados pelo servidor
=====================================

O desenvolvimento de um aplicativo da Web que usa eventos enviados pelo servidor (en-US) é simples. Você precisará de um pouco de código no servidor para transmitir eventos para o front-end, mas o código do lado do cliente funciona quase de forma idêntica a websockets em parte do tratamento eventos de entrada. Esta é uma conexão unidirecional, portanto, você não pode enviar eventos de um cliente para um servidor.

Recebendo eventos do servidor
-----------------------------

A API de eventos enviados pelo servidor está contida na interface `EventSource`; para abrir uma conexão com o servidor para começar a receber eventos dele, crie um novo objeto `EventSource` com a URL de um script que gera os eventos. Por exemplo:

```js
const evtSource = new EventSource("ssedemo.php");
```

Se o script do gerador de eventos estiver hospedado em uma origem diferente, um novo objeto `EventSource` deve ser criado com a URL e um dicionário de opções. Por exemplo, supondo que o script do cliente esteja em `example.com`:

```js
const evtSource = new EventSource("//api.example.com/ssedemo.php", {
  withCredentials: true,
});
```

Depois de instanciar a origem do evento, você pode começar a ouvir as mensagens do servidor anexando um manipulador para o evento `message` (en-US):

```js
evtSource.onmessage = (event) => {
  const newElement = document.createElement("li");
  const eventList = document.getElementById("list");

  newElement.textContent = `message: ${event.data}`;
  eventList.appendChild(newElement);
};
```

Este código escuta as mensagens recebidas (ou seja, avisos do servidor que não possuem um campo `event`) e anexa o texto da mensagem a uma lista no HTML do documento.

Você também pode escutar eventos com `addEventListener()`:

```js
evtSource.addEventListener("ping", (evento) => {
  const novoElemento = document.createElement("li");
  const eventList = document.getElementById("list");
  const time = JSON.parse(event.data).time;
  newElement.textContent = `ping em ${time}`;
  eventList.appendChild(newElement);
});
```

Este código é semelhante, exceto que será chamado automaticamente sempre que o servidor enviar uma mensagem com o campo `event` definido como "ping"; ele então analisa o JSON no campo `data` e gera essa informação.

**Aviso:** quando **não usado em HTTP/2**, o SSE sofre de uma limitação ao número máximo de conexões abertas, o que pode ser especialmente doloroso ao abrir várias guias, pois o limite é *por navegador* e é definido para um número muito baixo (6). O problema foi marcado como "Não será corrigido" no Chrome e no Firefox. Esse limite é por navegador + domínio, o que significa que você pode abrir 6 conexões SSE em todas as guias para `www.example1.com` e outras 6 conexões SSE para `www.example2.com` (por Stackoverflow). Ao usar HTTP/2, o número máximo de *streams HTTP* simultâneos é negociado entre o servidor e o cliente (o padrão é 100).

Enviando eventos do servidor
----------------------------

O script do lado do servidor que envia eventos precisa responder usando o tipo MIME `text/event-stream`. Cada notificação é enviada como um bloco de texto finalizado por um par de novas linhas. Para obter detalhes sobre o formato do fluxo de eventos, consulte Formato do fluxo de eventos.

O código PHP para o exemplo que estamos usando aqui segue:

```php
date\_default\_timezone\_set("America/New\_York");
header("Cache-Control: no-store");
header("Content-Type: text/event-stream");

$counter = rand(1, 10);
while (true) {
  // A cada segundo, envia um evento "ping".

  echo "evento: ping\n";
  $curDate = date(DATE\_ISO8601);
  echo 'data: {"time": "' . $curDate . '"}';
  echo "\n\n";

  // Envia uma mensagem simples em intervalos aleatórios.

  $counter--;

  if (!$counter) {
    echo 'data: Esta é uma mensagem no momento ' . $curDate . "\n\n";
    $counter = rand(1, 10);
  }

  ob\_end\_flush();
  flush();

  // Interrompe o loop se o cliente abortou a conexão (fechou a página)

  if (connection\_aborted()) break;

  sleep(1);
}
```

 O código acima gera um evento a cada segundo, com o tipo de evento "ping". Os dados de cada evento são um objeto JSON contendo o carimbo de data/hora ISO 8601 correspondente à hora em que o evento foi gerado. Em intervalos aleatórios, uma mensagem simples (sem tipo de evento) é enviada.
 O loop continuará funcionando independentemente do status da conexão, portanto, uma verificação é incluída
 para quebrar o loop se a conexão foi fechada (por exemplo, o cliente fecha a página).

você pode encontrar um exemplo completo que usa o código mostrado neste artigo no GitHub — veja [Simple SSE demo using PHP](https://github.com/mdn/dom-examples/tree/main /servidor-enviados-eventos).

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

Quando ocorrem problemas (como um tempo limite de rede ou problemas relacionados a controle de acesso), um evento de erro é gerado. Você pode agir sobre isso programaticamente implementando o retorno de chamada `onerror` no objeto `EventSource`:

```js
evtSource.onerror = (err) => {
  console.error("EventSource falhou:", err);
};
```

Fechando streams de eventos
---------------------------

Por padrão, se a conexão entre o cliente e o servidor for fechada, a conexão será reiniciada. A conexão é finalizada com o método `.close()`.

```js
evtSource.close();
```

Formato do fluxo de eventos
---------------------------

O fluxo de eventos é um fluxo simples de dados de texto que deve ser codificado usando UTF-8. As mensagens no fluxo de eventos são separadas por um par de caracteres de nova linha. Dois pontos como o primeiro caractere de uma linha é essencialmente um comentário e é ignorado.

**Nota:** A linha de comentário pode ser usada para evitar que as conexões atinjam o tempo limite; um servidor pode enviar um comentário periodicamente para manter a conexão ativa.

Cada mensagem consiste em uma ou mais linhas de texto listando os campos dessa mensagem. Cada campo é representado pelo nome do campo, seguido por dois pontos, seguido pelos dados de texto para o valor desse campo.

### Campos

Cada mensagem recebida tem alguma combinação dos seguintes campos, um por linha:

`event`

Uma string que identifica o tipo de evento descrito. Se isso for especificado, um evento será despachado no navegador para o ouvinte para o nome do evento especificado; o código-fonte do site deve usar `addEventListener()` para ouvir eventos nomeados. O manipulador `onmessage` é chamado se nenhum nome de evento for especificado para uma mensagem.

`data`

O campo de dados para a mensagem. Quando o `EventSource` recebe várias linhas consecutivas que começam com `data:`, ele as concatena, inserindo um caractere de nova linha entre cada uma. As novas linhas à direita são removidas.

`id`

o ID do evento para definir o último valor do ID do evento do objeto `EventSource`.

`retry`

O tempo de reconexão. Se a conexão com o servidor for perdida, o navegador aguardará o tempo especificado antes de tentar se reconectar. Deve ser um número inteiro, especificando o tempo de reconexão em milissegundos. Se um valor não inteiro for especificado, o campo será ignorado.

Todos os outros nomes de campo são ignorados.

**Nota:** se uma linha não contiver dois pontos, a linha inteira será tratada como o nome do campo com uma string de valor vazia.

### Exemplos

#### Mensagens somente de dados

No exemplo a seguir, há três mensagens enviadas. O primeiro é apenas um comentário, pois começa com dois pontos. Como mencionado anteriormente, isso pode ser útil como um mecanismo de manutenção se as mensagens não forem enviadas regularmente.

A segunda mensagem contém um campo de dados com o valor "algum texto". A terceira mensagem contém um campo de dados com o valor "outra mensagem\ncom duas linhas". Observe o caractere especial de nova linha no valor.

```bash
: este é um fluxo de teste

dados: algum texto

dados: outra mensagem
dados: com duas linhas
```

#### Eventos nomeados

Este exemplo envia eventos nomeados. Cada um tem um nome de evento especificado pelo campo `event` e um campo `data` cujo valor é uma string JSON apropriada com os dados necessários para que o cliente atue no evento. O campo `data` pode, é claro, ter qualquer string de dados; não precisa ser JSON.

```bash
evento: userconnect
data: {"username": "bobby", "time": "02:33:48"}

evento: mensagem do usuário
data: {"username": "bobby", "time": "02:34:11", "text": "Olá a todos."}

evento: userdisconnect
data: {"username": "bobby", "time": "02:34:23"}

evento: mensagem do usuário
data: {"username": "sean", "time": "02:34:36", "text": "Tchau, bobby."}
```

#### Misturando e combinando

Você não precisa usar apenas mensagens sem nome ou eventos digitados; você pode misturá-los em um único fluxo de eventos.

```bash
evento: userconnect
data: {"username": "bobby", "time": "02:33:48"}

data: Aqui está uma mensagem do sistema de algum tipo que será usada
dados: para realizar alguma tarefa.

evento: mensagem do usuário
data: {"username": "bobby", "time": "02:34:11", "text": "Olá a todos."}
```

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

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

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

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


Position.coords - APIs da Web

Position.coords
===============

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

A propriedade **`Position.coords`** é somente leitura. É um objeto de `Coordinates` que contém uma representação geográfica: a localização, que é a latitude e longitude na Terra, a altitude e a velocidade do objeto em questão. Também contempla a precisão da informação sobre estes valores.

Sintaxe
-------
```

coord = position.coords
```

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

| Specification |
| --- |
| Geolocation API # coords-attribute |

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

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

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

* Usando geolocalização (en-US)
* A interface `Position` a qual ela pertence.


Request() - APIs da Web

Request()
=========

O construtor **`Request()`** cria um novo objeto `Request`.

Sintaxe
-------
```

var myRequest = new Request(input[, init]);
```

### Parâmetros

*input*

Define o recurso que você deseja buscar. Isso pode ser:

* Um `USVString` (en-US) contendo o URL direto do recurso que você deseja buscar.
* Um objeto `Request`, criando efetivamente uma cópia. Observe as seguintes atualizações comportamentais para reter a segurança e, ao mesmo tempo, tornar o construtor menos propenso a gerar exceções:
    + Se esse objeto existir em outra origem para a chamada do construtor, o `Request.referrer` (en-US) será removido.
    + Se esse objeto tiver um `Request.mode` (en-US) de navegação, o valor do modo será convertido para a mesma origem.

*init* Optional

Um objeto de opções contendo quaisquer configurações personalizadas que você deseja aplicar à solicitação. As opções possíveis são:

* `method`: O método de request, ex: `GET`, `POST`.
* `headers`: Quaisquer cabeçalhos que você deseja adicionar à sua solicitação, contidos em um objeto `Headers` (en-US) ou em um objeto literal com valores de `ByteString` (en-US).
* `body`: Qualquer corpo que você deseja adicionar à sua solicitação: isso pode ser um `Blob`, `BufferSource`, `FormData`, `URLSearchParams`, `USVString` (en-US), ou objeto `ReadableStream` (en-US). Observe que uma solicitação usando o método GET ou HEAD não pode ter um corpo.
* `mode`: O modo que você deseja usar para a solicitação, por exemplo: `cors`, `no-cors`, `same-origin`, or `navigate`. O padrão é `cors`. No Chrome o padrão é `no-cors` antes do Chrome 47 e `same-origin` do Chrome 47 em diante.
* `credentials`: As credenciais de solicitação que você deseja usar para a solicitação: `omit`, `same-origin`, ou `include`. O padrão é `omit`. No Chrome o padrão é `same-origin` antes do Chrome 47 e `include` do Chrome 47 em diante.
* `cache`: O cache mode (en-US) que você deseja usar para a solicitação.
* `redirect`: O modo de redirecionamento para usar: `follow`, `error`, or `manual`. No Chrome o padrão é `follow` (antes do Chrome 47 foi padronizado `manual`).
* `referrer`: Um `USVString` (en-US) especificando `no-referrer`, `client`, ou uma URL. O padrão é `client`.
* `integrity`: Contém o valor de integridade do sub-recurso (en-US) da solicitação (exemplo: `sha256-BpfBw7ivV8q2jLiT13fxDYAe2tJllusRSZ273h2nFSE=`).

Erros
-----

| Tipo | Descrição |
| --- | --- |
| `TypeError` | Desde Firefox 43 (en-US), `Request()` lançará um TypeError se o URL tiver credenciais, tal como `http://user:password@example.com`. |

Exemplo
-------

Em nosso exemplo Fetch Request(veja Fetch Request live) nós criamos um novo objeto `Request` usando o construtor, em seguida, busque-o usando uma chamada `GlobalFetch.fetch` (en-US). Como estamos buscando uma imagem, executamos o `Body.blob` (en-US) na resposta para fornecer o tipo MIME adequado para que ela seja manipulada corretamente. Em seguida, criamos uma URL do objeto e a exibimos em um Elemento `<img>`.

```js
var myImage = document.querySelector("img");

var myRequest = new Request("flowers.jpg");

fetch(myRequest)
  .then(function (response) {
    return response.blob();
  })
  .then(function (response) {
    var objectURL = URL.createObjectURL(response);
    myImage.src = objectURL;
  });
```

Em nosso Fetch Request with init example (veja Fetch Request init live) nós fazemos a mesma coisa, exceto que passamos em um objeto init quando invocamos `fetch()`:

```js
var myImage = document.querySelector('img');

var myHeaders = new Headers();
myHeaders.append('Content-Type', 'image/jpeg');

var myInit = { method: 'GET',
               headers: myHeaders,
               mode: 'cors',
               cache: 'default' };

var myRequest = new Request('flowers.jpg',myInit);

fetch(myRequest).then(function(response) {
  ...
});
```

Observe que você também pode passar o objeto init para a chamada `fetch` para obter o mesmo efeito, por exemplo:

```js
fetch(myRequest,myInit).then(function(response) {
  ...
});
```

Você também pode usar um literal de objeto como `headers` em `init`.

```js
var myInit = {
  method: "GET",
  headers: {
    "Content-Type": "image/jpeg",
  },
  mode: "cors",
  cache: "default",
};

var myRequest = new Request("flowers.jpg", myInit);
```

Você também pode passar um objeto `Request` para o construtor `Request()` para criar uma cópia do Request (isso é semelhante a chamar o método `clone()` (en-US) .)

```js
var copy = new Request(myRequest);
```

**Nota:** Este último uso é provavelmente útil apenas em ServiceWorkers (en-US).

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

| Specification |
| --- |
| Fetch Standard # ref-for-dom-request① |

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

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

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

* ServiceWorker API (en-US)
* HTTP access control (CORS) (en-US)
* HTTP


MouseEvent.clientY - APIs da Web

MouseEvent.clientY
==================

A propriedade **`clientY`** da interface `MouseEvent` fornece a coordenada vertical do cliente dentro da aplicacão em que o evento ocorreu (ao contrário da coordenada que pertence a página).

Por exemplo, clicando no topo da área do cliente sempre resultará num evento de mouse com um valor `0` de `clientY`, independente se a página está "escrollada" verticalmente.

Sintaxe
-------
```

var y = instanciaDeEventoDoMouse.clientY
```

### Valor de retorno

O valor retornado por essa propriedade é um valor flutuante double como foi redefinida pelo "CSSOM View Module". Originalmente esta propriedade era definida como um inteiro `long`. Veja a seção de compatibilidade de browsers para mais detalhes.

Exemplo
-------

Este exemplo mostra as coordenadas do mouse quando você ativar o evento `mousemove (en-US)`.

### HTML

```html
<p>Mova seu mouse para ver sua posicão.</p>
<p id="screen-log"></p>
```

### JavaScript

```js
let screenLog = document.querySelector("#screen-log");
document.addEventListener("mousemove", logKey);

function logKey(e) {
  screenLog.innerText = `
 Screen X/Y: ${e.screenX}, ${e.screenY}
 Client X/Y: ${e.clientX}, ${e.clientY}`;
}
```

### Resultado

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

| Specification |
| --- |
| UI Events # dom-mouseevent-clienty |

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

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

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

* `MouseEvent`
* `clientX`
* `screenX` (en-US) / `screenY` (en-US)