From f586f7ac9c00c1adae2487220d91dc2ef293e5b8 Mon Sep 17 00:00:00 2001 From: julieng Date: Thu, 15 Sep 2022 08:04:32 +0200 Subject: [PATCH 1/2] move *.html to *.md --- files/pt-br/web/web_components/{index.html => index.md} | 0 .../web_components/using_custom_elements/{index.html => index.md} | 0 2 files changed, 0 insertions(+), 0 deletions(-) rename files/pt-br/web/web_components/{index.html => index.md} (100%) rename files/pt-br/web/web_components/using_custom_elements/{index.html => index.md} (100%) diff --git a/files/pt-br/web/web_components/index.html b/files/pt-br/web/web_components/index.md similarity index 100% rename from files/pt-br/web/web_components/index.html rename to files/pt-br/web/web_components/index.md diff --git a/files/pt-br/web/web_components/using_custom_elements/index.html b/files/pt-br/web/web_components/using_custom_elements/index.md similarity index 100% rename from files/pt-br/web/web_components/using_custom_elements/index.html rename to files/pt-br/web/web_components/using_custom_elements/index.md From 7072369d78ee967548082b9a4c1d95c4258116d7 Mon Sep 17 00:00:00 2001 From: julieng Date: Thu, 15 Sep 2022 08:04:37 +0200 Subject: [PATCH 2/2] convert content to md --- files/pt-br/web/web_components/index.md | 367 ++++++++---------- .../using_custom_elements/index.md | 249 ++++++------ 2 files changed, 294 insertions(+), 322 deletions(-) diff --git a/files/pt-br/web/web_components/index.md b/files/pt-br/web/web_components/index.md index 4638adf570dd79..def140211492c8 100644 --- a/files/pt-br/web/web_components/index.md +++ b/files/pt-br/web/web_components/index.md @@ -3,210 +3,163 @@ title: Web Components slug: Web/Web_Components translation_of: Web/Web_Components --- -
{{DefaultAPISidebar("Web Components")}}
- -
-

Web Components é uma suíte de diferentes tecnologias que permite a criação de elementos customizados reutilizáveis — com a funcionalidade separada do resto do seu código — e que podem ser utilizados em suas aplicações web.

-
- -

Conceitos e uso

- -

Como desenvolvedores, sabemos que é uma boa ideia reutilizar o código o máximo que pudermos. Tradicionalmente, isso não tem sido fácil quando o assunto são estruturas de marcação customizadas — pense no complexo HTML (e estilo e script associados) que, às vezes, deve ser escrito para renderizar controles UI customizados e em como utilizá-los repetidas vezes pode tornar sua página uma bagunça se você não tomar cuidado.

- -

Web Components buscam resolver esses problemas — são formados por três tecnologias principais, que podem ser usadas em conjunto para criar elementos customizados versáteis, com funcionalidade encapsulada, que podem ser reutilizados onde você quiser sem preocupação com conflito de código.

- - - -

A abordagem básica para se implementar um componente web geralmente se parece com isso:

- -
    -
  1. Crie uma classe na qual você especifica a funcionalidade do seu componente web, usando a sintaxe de classe do ECMAScript 2015 (veja Classes para mais informações).
    2. -
  2. Registre seus elemento customizado através do método {{domxref("CustomElementRegistry.define()")}}, passando o nome do elemento a ser definido, a classe ou função na qual sua funcionalidade foi especificada, e opcionalmente, de qual elemento ele herda suas propriedades.
    3. -
  3. Se necessário, incorpore um shadow DOM ao elemento customizado usando o método {{domxref("Element.attachShadow()")}}. Adicione elementos filhos, listeners, etc., ao shadow DOM usando métodos normais de DOM.
    4. -
  4. Se necessário, defina um template HTML usando {{htmlelement("template")}} e {{htmlelement("slot")}}. Novamente, use os métodos normais de DOM methods para clonar o template e inclui-la ao shadow DOM.
    5. -
  5. Use seu elemento customizado onde você preferir em sua página, da mesma forma que usaria qualquer outro elemento HTML.
    6. -
- -

Tutoriais

- -
-
Usando elementos customizados
-
Um guia que mostra como usar os recursos de elementos customizados para criar componentes web simples, além de como analisar o ciclo de vida das funções de retorno e outros recursos mais avançados.
-
Usando shadow DOM
-
Um guia que analisa os fundamentos do shadow DOM, mostrando como incorporá-lo a um elemento, adicioná-lo à árvore do shadow DOM, estilizá-lo, etc.
-
Usando templates e slots
-
Um guia que mostra como definir uma estrutura HTML reutilzável através dos elementos {{htmlelement("template")}} e {{htmlelement("slot")}}, e como utilizar essa estrutura dentro de elementos web.
-
- -

Referência

- -

Elementos customizados

- -
-
{{domxref("CustomElementRegistry")}}
-
Contém funcionalidade relacionada a elementos personalizados, principalmente o método {{domxref("CustomElementRegistry.define()")}} usado para registrar novos elementos personalizados, para que possam ser usados ​​em seu documento.
-
{{domxref("Window.customElements")}}
-
Retorna uma referência ao objeto CustomElementRegistry.
-
Callbacks do ciclo de vida
-
Funções callback especiais definidas dentro da definição de classe de elemento customizado, afetando seu comportamento: -
    -
  • connectedCallback: Invocada quando um elemento customizado é adicionao ao DOM do documento.
    • -
  • disconnectedCallback: Invocada quando o elemento customizado é desconectado do DOM do documento.
    • -
  • adoptedCallback: Invocada quando o elemento customizado é movido para um novo documento.
    • -
  • attributeChangedCallback: Invocada quando um dos atributos de um elemento customizado é adicionado, removido ou alterado.
    • -
-
-
Extensões para criação de elementos built-in customizados
-
-
    -
  • O atributo HTML global {{htmlattrxref("is")}}: Permite especificar que um elemento HTML padrão deve se comportar como um elemento built-in customizado registrado.
    • -
  • A opção "is" do método {{domxref("Document.createElement()")}}: Permite criar uma instância de um elemento HTML standard que se comporta como um determinado elemento built-in customizado registrado.
    • -
-
-
CSS pseudo-classes
-
Pseudo-classes relacionadas especificamente a elementos customizados: -
    -
  • {{cssxref(":defined")}}: Corresponde a qualquer elemento que está definido, incluindo elementos built-in e elementos customizados que foram definidos com CustomElementRegistry.define()).
    • -
  • {{cssxref(":host")}}: Seleciona o host fantasma do shadow DOM contendo o CSS utilizado internamente.
    • -
  • {{cssxref(":host()")}}: Seleciona o host fantasma do shadow DOM contendo o CSS utilizado internamente (permitindo selecionar um elemento customizado de dentro de seu shadow DOM) — mas somente se o seletor que foi passado via parâmetro da função corresponder ao host fantasma.
    • -
  • {{cssxref(":host-context()")}}: Seleciona o host fantasma do shadow DOM contendo o CSS utilizado internamente (permitindo selecionar um elemento customizado de dentro de seu shadow DOM) — mas somente se o seletor que foi passado via parâmetro da função corresponder ao(s) ancestral(ais) do host fantasma relativo à posição que ele toma dentro da hierarquida do DOM.
    • -
-
-
CSS pseudo-elementos
-
Pseudo-elementos relacionados especificamente a elementos customizados: -
    -
  • {{cssxref("::part")}}: Representa qualquer elemento dentro de uma shadow tree que tenha um atributo {{HTMLAttrxRef("part")}} correspondente.
    • -
-
-
- -

Shadow DOM

- -
-
{{domxref("ShadowRoot")}}
-
Representa o nó raíz de uma sub-árvore DOM fantasma.
-
{{domxref("DocumentOrShadowRoot")}}
-
Um mixin que define funcionalidades que ficam disponíveis através do documento e das raízes fantasma.
-
Extensões {{domxref("Element")}}
-
Extensões à interface Element relacionado ao shadow DOM: -
    -
  • O método {{domxref("Element.attachShadow()")}} vincula uma árvore DOM fantasma ao elemento especificado.
    • -
  • A propriedade {{domxref("Element.shadowRoot")}} retorna a árvore fantasma raíz vinculada ao elemento especificado, ou null se não existir nenhuma árvore fantasma vinculada.
    • -
-
-
Adições relevantes {{domxref("Node")}}
-
Adicionais à interface Node pertinentes ao shadow DOM: -
    -
  • O método {{domxref("Node.getRootNode()")}} retorna a raíz do objeto contexto, que opcionalmente inclui a "raíz fantasma" (shadow root) se a mesma estiver dispinível.
    • -
  • A propriedade {{domxref("Node.isConnected")}} retorna um boolean indicando se o Nó está ou não conectado (direta ou indiretamente) ao objeto contexto, ex. o objeto {{domxref("Document")}} no caso de um DOM normal, ou o {{domxref("ShadowRoot")}} no caso de um DOM fantasma (shadow DOM).
    • -
-
-
Extensões {{domxref("Event")}}
-
Extensões para a interface de Event relacionado a shadow DOM: -
    -
  • {{domxref("Event.composed")}}: Retorna um {{jsxref("Boolean")}} que indica
    - se o evento irá se propagar através dos limites do shadow DOM para dentro do DOM padrão (true), ou não (false).
    • -
  • {{domxref("Event.composedPath")}}: Retorna o caminho do evento (objetos nos quais os listeners serão invocados). Não inclui nós na shadow tree se a shadow root foi criada com {{domxref("ShadowRoot.mode")}} closed (fechado).
    • -
-
-
- -

Templates HTML

- -
-
{{htmlelement("template")}}
-
Contém um fragmento HTML que não é renderizado quando um documento que o contém é inicialmente carregado, mas pode ser exibido em tempo de execução usando JavaScript, geralmente utilizado como base de estruturas de elementos customizados. A interface DOM associada é {{domxref("HTMLTemplateElement")}}.
-
{{htmlelement("slot")}}
-
Um placeholder dentro de um web component que você pode preencher com seu texto de marcação, permitindo criar árvores DOM separadas e apresentar delas juntas. A interface DOM associada é a {{domxref("HTMLSlotElement")}}.
-
O atributo HTML global slot
-
Atribui um slot em uma árvore shadow DOM a um elemento.
-
{{domxref("Slotable")}}
-
Um mixin implementado por ambos os nós {{domxref("Element")}} e{{domxref("Text")}} definindo funcionalidades que permitem tornar-se conteúdo de um elemento {{htmlelement("slot")}}. O mixin define um atributo, {{domxref("Slotable.assignedSlot")}}, o qual retorna uma referência do slot em que o nó está sendo inserido.
-
- -
-
Extensões {{domxref("Element")}}
-
Extensões para a interface de Element relacionado a slots: -
    -
  • {{domxref("Element.slot")}}: Retorna o nome do slot do shadow DOM associado ao elemento.
    • -
-
-
Pseudo-elementos CSS
-
Pseudo-elementos relacionados especificamente a slots: -
    -
  • {{cssxref("::slotted")}}: Corresponde a qualquer conteúdo inserido naquele slot.
    • -
-
-
O evento {{event("slotchange")}}
-
Disparado em uma instância {{domxref("HTMLSlotElement")}} (elemento {{htmlelement("slot")}}) quando há mudança no nó(s) contido naquele slot.
-
- -

Exemplos

- -

Estamos construindo alguns exemplos em nosso repo do GitHub web-components-examples.
- Mais exemplos serão adicionados com o passar do tempo.

- -

Especificações

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
EspecificaçãoStatusComentário
{{SpecName("HTML WHATWG","scripting.html#the-template-element","<template> element")}}{{Spec2("HTML WHATWG")}}Definição de {{HTMLElement("template")}}.
{{SpecName("HTML WHATWG","custom-elements.html#custom-elements","custom elements")}}{{Spec2("HTML WHATWG")}}Definição de Elementos HTML Customizados.
{{SpecName("DOM WHATWG","#shadow-trees","shadow trees")}}{{Spec2("DOM WHATWG")}}Definição de Shadow DOM.
{{SpecName("HTML Imports", "", "")}}{{Spec2("HTML Imports")}}Definição inicial de HTML Imports.
{{SpecName("Shadow DOM", "", "")}}{{Spec2("Shadow DOM")}}Definição inicial de Shadow DOM.
- -

Compatibilidade com navegadores

- -

Em geral:

- - - -

Para obter informações detalhadas sobre o suporte de funções específicas nos navegadores, você deve consultar as páginas de referência listadas abaixo.

- -

Veja também

- - +{{DefaultAPISidebar("Web Components")}} + +Web Components é uma suíte de diferentes tecnologias que permite a criação de elementos customizados reutilizáveis — com a funcionalidade separada do resto do seu código — e que podem ser utilizados em suas aplicações web. + +## Conceitos e uso + +Como desenvolvedores, sabemos que é uma boa ideia reutilizar o código o máximo que pudermos. Tradicionalmente, isso não tem sido fácil quando o assunto são estruturas de marcação customizadas — pense no complexo HTML (e estilo e script associados) que, às vezes, deve ser escrito para renderizar controles UI customizados e em como utilizá-los repetidas vezes pode tornar sua página uma bagunça se você não tomar cuidado. + +Web Components buscam resolver esses problemas — são formados por três tecnologias principais, que podem ser usadas em conjunto para criar elementos customizados versáteis, com funcionalidade encapsulada, que podem ser reutilizados onde você quiser sem preocupação com conflito de código. + +- **Elementos customizados**: Um conjunto de APIs JavaScript que permite definir elementos customizados e seus respectivos comportamentos, podendo ser utilizados de diferentes formas na interface da aplicação. +- **Shadow DOM**: Um conjunto de APIs JavaScript para incorporar uma árvore DOM "fantasma" encapsulada a um elemento — que é renderizada separadamente do DOM do documento principal — e controlar a funcionalidade associada. Nesse caso, você pode manter os recursos de um elemento privados, fazendo com que seu comportamento e estilo possam ser escritos sem medo de causar conflito com outras partes do documento. +- **Templates HTML**: Os elementos {{HTMLElement("template")}} e {{HTMLElement("slot")}} permitem que você escreva templates de marcação que não são exibidas na página. Elas podem então ser reutilizadas várias vezes como modelo de estrutura de um elemento customizado. + +A abordagem básica para se implementar um componente web geralmente se parece com isso: + +1. Crie uma classe na qual você especifica a funcionalidade do seu componente web, usando a sintaxe de classe do ECMAScript 2015 (veja [Classes](/pt-BR/docs/Web/JavaScript/Reference/Classes) para mais informações). +2. Registre seus elemento customizado através do método {{domxref("CustomElementRegistry.define()")}}, passando o nome do elemento a ser definido, a classe ou função na qual sua funcionalidade foi especificada, e opcionalmente, de qual elemento ele herda suas propriedades. +3. Se necessário, incorpore um shadow DOM ao elemento customizado usando o método {{domxref("Element.attachShadow()")}}. Adicione elementos filhos, listeners, etc., ao shadow DOM usando métodos normais de DOM. +4. Se necessário, defina um template HTML usando {{htmlelement("template")}} e {{htmlelement("slot")}}. Novamente, use os métodos normais de DOM methods para clonar o template e inclui-la ao shadow DOM. +5. Use seu elemento customizado onde você preferir em sua página, da mesma forma que usaria qualquer outro elemento HTML. + +## Tutoriais + +- [Usando elementos customizados](/pt-BR/docs/Web/Web_Components/Usando_custom_elements) + - : Um guia que mostra como usar os recursos de elementos customizados para criar componentes web simples, além de como analisar o ciclo de vida das funções de retorno e outros recursos mais avançados. +- [Usando shadow DOM](/pt-BR/docs/Web/Web_Components/Using_shadow_DOM) + - : Um guia que analisa os fundamentos do shadow DOM, mostrando como incorporá-lo a um elemento, adicioná-lo à árvore do shadow DOM, estilizá-lo, etc. +- [Usando templates e slots](/pt-BR/docs/Web/Web_Components/Using_templates_and_slots) + - : Um guia que mostra como definir uma estrutura HTML reutilzável através dos elementos {{htmlelement("template")}} e {{htmlelement("slot")}}, e como utilizar essa estrutura dentro de elementos web. + +## Referência + +### Elementos customizados + +- {{domxref("CustomElementRegistry")}} + - : Contém funcionalidade relacionada a elementos personalizados, principalmente o método {{domxref("CustomElementRegistry.define()")}} usado para registrar novos elementos personalizados, para que possam ser usados ​​em seu documento. +- {{domxref("Window.customElements")}} + - : Retorna uma referência ao objeto `CustomElementRegistry`. +- [Callbacks do ciclo de vida](/pt-BR/docs/Web/Web_Components/Using_custom_elements#Using_the_lifecycle_callbacks) + + - : Funções callback especiais definidas dentro da definição de classe de elemento customizado, afetando seu comportamento: + + - `connectedCallback`: Invocada quando um elemento customizado é adicionao ao DOM do documento. + - `disconnectedCallback`: Invocada quando o elemento customizado é desconectado do DOM do documento. + - `adoptedCallback`: Invocada quando o elemento customizado é movido para um novo documento. + - `attributeChangedCallback`: Invocada quando um dos atributos de um elemento customizado é adicionado, removido ou alterado. + +- Extensões para criação de elementos built-in customizados + + - : + + - O atributo HTML global {{htmlattrxref("is")}}: Permite especificar que um elemento HTML padrão deve se comportar como um elemento built-in customizado registrado. + - A opção "is" do método {{domxref("Document.createElement()")}}: Permite criar uma instância de um elemento HTML standard que se comporta como um determinado elemento built-in customizado registrado. + +- CSS pseudo-classes + + - : Pseudo-classes relacionadas especificamente a elementos customizados: + + - {{cssxref(":defined")}}: Corresponde a qualquer elemento que está definido, incluindo elementos built-in e elementos customizados que foram definidos com `CustomElementRegistry.define()`). + - {{cssxref(":host")}}: Seleciona o host fantasma do [shadow DOM](/pt-BR/docs/Web/Web_Components/Using_shadow_DOM) contendo o CSS utilizado internamente. + - {{cssxref(":host()")}}: Seleciona o host fantasma do [shadow DOM](/pt-BR/docs/Web/Web_Components/Using_shadow_DOM) contendo o CSS utilizado internamente (permitindo selecionar um elemento customizado de dentro de seu shadow DOM) — mas somente se o seletor que foi passado via parâmetro da função corresponder ao host fantasma. + - {{cssxref(":host-context()")}}: Seleciona o host fantasma do [shadow DOM](/pt-BR/docs/Web/Web_Components/Using_shadow_DOM) contendo o CSS utilizado internamente (permitindo selecionar um elemento customizado de dentro de seu shadow DOM) — mas somente se o seletor que foi passado via parâmetro da função corresponder ao(s) ancestral(ais) do host fantasma relativo à posição que ele toma dentro da hierarquida do DOM. + +- CSS pseudo-elementos + + - : Pseudo-elementos relacionados especificamente a elementos customizados: + + - {{cssxref("::part")}}: Representa qualquer elemento dentro de uma [shadow tree](/pt-BR/docs/Web/Web_Components/Using_shadow_DOM) que tenha um atributo {{HTMLAttrxRef("part")}} correspondente. + +### Shadow DOM + +- {{domxref("ShadowRoot")}} + - : Representa o nó raíz de uma sub-árvore DOM fantasma. +- {{domxref("DocumentOrShadowRoot")}} + - : Um mixin que define funcionalidades que ficam disponíveis através do documento e das raízes fantasma. +- Extensões {{domxref("Element")}} + + - : Extensões à interface `Element` relacionado ao shadow DOM: + + - O método {{domxref("Element.attachShadow()")}} vincula uma árvore DOM fantasma ao elemento especificado. + - A propriedade {{domxref("Element.shadowRoot")}} retorna a árvore fantasma raíz vinculada ao elemento especificado, ou `null` se não existir nenhuma árvore fantasma vinculada. + +- Adições relevantes {{domxref("Node")}} + + - : Adicionais à interface `Node` pertinentes ao shadow DOM: + + - O método {{domxref("Node.getRootNode()")}} retorna a raíz do objeto contexto, que opcionalmente inclui a "raíz fantasma" (shadow root) se a mesma estiver dispinível. + - A propriedade {{domxref("Node.isConnected")}} retorna um boolean indicando se o Nó está ou não conectado (direta ou indiretamente) ao objeto contexto, ex. o objeto {{domxref("Document")}} no caso de um DOM normal, ou o {{domxref("ShadowRoot")}} no caso de um DOM fantasma (shadow DOM). + +- Extensões {{domxref("Event")}} + + - : Extensões para a interface de `Event` relacionado a shadow DOM: + + - {{domxref("Event.composed")}}: Retorna um {{jsxref("Boolean")}} que indica + se o evento irá se propagar através dos limites do shadow DOM para dentro do DOM padrão (`true`), ou não (`false`). + - {{domxref("Event.composedPath")}}: Retorna o caminho do evento (objetos nos quais os listeners serão invocados). Não inclui nós na shadow tree se a shadow root foi criada com {{domxref("ShadowRoot.mode")}} closed (fechado). + +### Templates HTML + +- {{htmlelement("template")}} + - : Contém um fragmento HTML que não é renderizado quando um documento que o contém é inicialmente carregado, mas pode ser exibido em tempo de execução usando JavaScript, geralmente utilizado como base de estruturas de elementos customizados. A interface DOM associada é {{domxref("HTMLTemplateElement")}}. +- {{htmlelement("slot")}} + - : Um placeholder dentro de um web component que você pode preencher com seu texto de marcação, permitindo criar árvores DOM separadas e apresentar delas juntas. A interface DOM associada é a {{domxref("HTMLSlotElement")}}. +- `O atributo HTML global slot` + - : Atribui um slot em uma árvore shadow DOM a um elemento. +- {{domxref("Slotable")}} + - : Um mixin implementado por ambos os nós {{domxref("Element")}} e{{domxref("Text")}} definindo funcionalidades que permitem tornar-se conteúdo de um elemento {{htmlelement("slot")}}. O mixin define um atributo, {{domxref("Slotable.assignedSlot")}}, o qual retorna uma referência do slot em que o nó está sendo inserido. + + + +- Extensões {{domxref("Element")}} + + - : Extensões para a interface de `Element` relacionado a slots: + + - {{domxref("Element.slot")}}: Retorna o nome do slot do shadow DOM associado ao elemento. + +- Pseudo-elementos CSS + + - : Pseudo-elementos relacionados especificamente a slots: + + - {{cssxref("::slotted")}}: Corresponde a qualquer conteúdo inserido naquele slot. + +- O evento {{event("slotchange")}} + - : Disparado em uma instância {{domxref("HTMLSlotElement")}} (elemento {{htmlelement("slot")}}) quando há mudança no nó(s) contido naquele slot. + +## Exemplos + +Estamos construindo alguns exemplos em nosso repo do GitHub [web-components-examples](https://github.com/mdn/web-components-examples). +Mais exemplos serão adicionados com o passar do tempo. + +## Especificações + +| Especificação | Status | Comentário | +| ---------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------- | +| {{SpecName("HTML WHATWG","scripting.html#the-template-element","<template> element")}} | {{Spec2("HTML WHATWG")}} | Definição de {{HTMLElement("template")}}. | +| {{SpecName("HTML WHATWG","custom-elements.html#custom-elements","custom elements")}} | {{Spec2("HTML WHATWG")}} | Definição de [Elementos HTML Customizados](/pt-BR/docs/Web/Web_Components/Using_custom_elements). | +| {{SpecName("DOM WHATWG","#shadow-trees","shadow trees")}} | {{Spec2("DOM WHATWG")}} | Definição de [Shadow DOM](/pt-BR/docs/Web/Web_Components/Using_shadow_DOM). | +| {{SpecName("HTML Imports", "", "")}} | {{Spec2("HTML Imports")}} | Definição inicial de [HTML Imports](/pt-BR/docs/Web/Web_Components/HTML_Imports). | +| {{SpecName("Shadow DOM", "", "")}} | {{Spec2("Shadow DOM")}} | Definição inicial de [Shadow DOM](/pt-BR/docs/Web/Web_Components/Using_shadow_DOM). | + +## Compatibilidade com navegadores + +Em geral: + +- Web components são suportados por padrão pelo Firefox (versão 63), Chrome, e Opera. +- Safari suporta muitas das funcionalidades de web component, porém menos do que os navegadores citados acima. +- Edge está trabalhando na implementação. + +Para obter informações detalhadas sobre o suporte de funções específicas nos navegadores, você deve consultar as páginas de referência listadas abaixo. + +## Veja também + +- [webcomponents.org](https://www.webcomponents.org/) — site apresentando exemplos de web components, tutoriais e outras informações. +- [FAST](https://fast.design/) é uma biblioteca de web component construída pela Microsoft que oferece vários pacotes para potencializar dependendo das necessidades do seu projeto. [Fast Element](https://github.com/microsoft/fast/tree/master/packages/web-components/fast-element) é um meio fácil de criar Web Components de alto desempenho, com eficiência de memória e em conformidade com os padrões. [Fast Foundation](https://github.com/microsoft/fast/tree/master/packages/web-components/fast-foundation) é uma biblioteca de classes, modelos e outros utilitários de Web Components criados em elementos rápidos destinados a serem compostos em Web Components registrados. +- [Hybrids](https://github.com/hybridsjs/hybrids) — Biblioteca web components de código aberto, que favorece objetos simples e funções puras em vez de `class` e this sintaxe. Ele fornece uma API simples e funcional para a criação de elementos personalizados. +- [Polymer](https://www.polymer-project.org/) — Framework de web components do Google - um conjunto de polyfills, melhorias e exemplos. Atualmente, a maneira mais fácil de usar os web components em vários navegadores. +- [Snuggsi](https://github.com/devpunks/snuggsi#readme) — Web Components fáceis com \~1kB _Incluindo polyfill_ — Tudo que você precisa é um navegador e um conhecimento básico de HTML, CSS e classes JavaScript para ser produtivo. +- [Slim.js](https://github.com/slimjs/slim.js) — Biblioteca web components de código aberto - uma biblioteca de alto desempenho para criação rápida e fácil de componentes; extensível e plugável e compatível com cross-framework. +- [Stencil](https://stenciljs.com/) — Conjunto de ferramentas para a construção de sistemas de design reutilizáveis e escalonáveis em web components. diff --git a/files/pt-br/web/web_components/using_custom_elements/index.md b/files/pt-br/web/web_components/using_custom_elements/index.md index 30f43d4c1ce016..65d4d6b36e03b1 100644 --- a/files/pt-br/web/web_components/using_custom_elements/index.md +++ b/files/pt-br/web/web_components/using_custom_elements/index.md @@ -12,35 +12,34 @@ tags: translation_of: Web/Web_Components/Using_custom_elements original_slug: Web/Web_Components/Usando_custom_elements --- -
{{DefaultAPISidebar("Web Components")}}
+{{DefaultAPISidebar("Web Components")}} -

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.

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

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

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

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

+O controlador de custom elements em um documento da web é o objeto {{domxref("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 {{domxref("CustomElementRegistry.define()")}}. Isso leva como argumentos:

+Para registar um custom element na página, use o método {{domxref("CustomElementRegistry.define()")}}. Isso leva como argumentos: - +- Um {{domxref("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](https://html.spec.whatwg.org/#valid-custom-element-name) (kebab-case); não podem ser palavras isoladas. +- Um objeto de [classe](/pt-BR/docs/Web/JavaScript/Reference/Classes) 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:

+Então, por exemplo, podemos definir um custom element [word-count](https://mdn.github.io/web-components-examples/word-count-web-component/) `(contagem-palavras)` assim: -
customElements.define('word-count', WordCount, { extends: 'p' });
+```js +customElements.define('word-count', WordCount, { extends: 'p' }); +``` -

O elemento é chamado de word-count, seu objeto de classe é WordCount, e estende o elemento {{htmlelement("p")}}.

+O elemento é chamado de `word-count`, seu objeto de classe é `WordCount`, e estende o elemento {{htmlelement("p")}}. -

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

+O objeto de classe de um custom element é escrito usando a sintaxe de classe ES 2015. Por exemplo, `WordCount` é estruturado assim:: -
class WordCount extends HTMLParagraphElement {
+```js
+class WordCount extends HTMLParagraphElement {
   constructor() {
     // Sempre chame super primeiro no construtor
     super();
@@ -49,30 +48,30 @@ original_slug: Web/Web_Components/Usando_custom_elements
 
     ...
   }
-}
+} +``` -

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.

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

+Você aprenderá mais sobre eles na seção [Using the lifecycle callbacks](#using_the_lifecycle_callbacks) abaixo. -

Existem dois tipos de custom elements:

+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 ``, 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 {{htmlattrxref("is")}} (ou propriedade). Por exemplo `

`, ou `document.createElement("p", { is: "word-count" })`. -

Trabalhando com alguns exemplos simples

+## 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.

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

Custom elements autônomos

+### 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.

+Vamos dar uma olhada em um exemplo de um custom element autônomo — [``](https://github.com/mdn/web-components-examples/tree/master/popup-info-box-web-component) (veja um [exemplo ao vivo](https://mdn.github.io/web-components-examples/popup-info-box-web-component/)). 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 {{domxref("HTMLElement")}}.

+Para começar, o arquivo JavaScript define uma classe chamada `PopUpInfo`, que estende a classe genérica {{domxref("HTMLElement")}}. -
class PopUpInfo extends HTMLElement {
+```js
+class PopUpInfo extends HTMLElement {
   constructor() {
     // Sempre chame super primeiro no construtor
     super();
@@ -81,13 +80,15 @@ original_slug: Web/Web_Components/Usando_custom_elements
 
     ...
   }
-}
+} +``` -

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.

+O trecho de código anterior contém a definição do [`constructor()`](/en-US/docs/Web/JavaScript/Reference/Classes/constructor) da classe, que sempre começa chamando [`super()`](/en-US/docs/Web/JavaScript/Reference/Operators/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.

+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. -
// Create a shadow root
+```js
+// Create a shadow root
 this.attachShadow({mode: 'open'}); // sets and returns 'this.shadowRoot'
 
 // Create (nested) span elements
@@ -112,48 +113,52 @@ style.textContent = '.wrapper {' +
 
 // 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: -

Por fim, registramos nosso custom element no CustomElementRegistry usando o métododefine() 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); +``` -
customElements.define('popup-info', PopUpInfo);
+Agora está disponível para uso em nossa página. Em nosso HTML, nós o usamos assim: -

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

- -
<popup-info img="img/alt.png" data-text="Your card validation code (CVC)
+```html
+
+  back of your card.">
+```
 
-

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

-

+> **Nota:** Você pode ver o [código-fonte JavaScript completo](https://github.com/mdn/web-components-examples/blob/master/popup-info-box-web-component/main.js) aqui.
 
-
Estilos internos vs. externos

+### Estilos internos vs. externos
 
-
No exemplo acima, aplicamos o estilo ao Shadow DOM usando um elemento {{htmlelement("style")}}, mas é perfeitamente possível fazer isso referenciando uma folha de estilo externa de um elemento {{htmlelement("link")}} em vez disso.

+No exemplo acima, aplicamos o estilo ao Shadow DOM usando um elemento {{htmlelement("style")}}, mas é perfeitamente possível fazer isso referenciando uma folha de estilo externa de um elemento {{htmlelement("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):

+Por exemplo, dê uma olhada neste código de nosso exemplo [popup-info-box-external-stylesheet](https://mdn.github.io/web-components-examples/popup-info-box-external-stylesheet/) (veja o [código-fonte](https://github.com/mdn/web-components-examples/blob/master/popup-info-box-external-stylesheet/main.js)):
 
-
// Aplicar estilos externos ao shadow dom
+```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);

+shadow.appendChild(linkElem);
+```
 
-
Observe que os elementos {{htmlelement("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.

+Observe que os elementos {{htmlelement("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 {{htmlelement("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.

+Muitos navegadores modernos implementam uma otimização para tags {{htmlelement("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

+### 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.

+Agora vamos dar uma olhada em outro exemplo de custom element integrado — [expanding-list](https://github.com/mdn/web-components-examples/tree/master/expanding-list-web-component) ([ver ao vivo também](https://mdn.github.io/web-components-examples/expanding-list-web-component/)). 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:

+Em primeiro lugar, definimos a classe do nosso elemento, da mesma maneira que antes:
 
-
class ExpandingList extends HTMLUListElement {
+```js
+class ExpandingList extends HTMLUListElement {
   constructor() {
     // Sempre chame super primeiro no construtor
     super();
@@ -162,60 +167,64 @@ shadow.appendChild(linkElem);

 
     ...
   }
-}
+} +``` -

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 {{domxref("HTMLUListElement")}}, e não {{domxref("HTMLElement")}}. Portanto, ele tem todas as características de um elemento {{htmlelement("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.

+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 {{domxref("HTMLUListElement")}}, e não {{domxref("HTMLElement")}}. Portanto, ele tem todas as características de um elemento {{htmlelement("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:

+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: -
customElements.define('expanding-list', ExpandingList, { extends: "ul" });
+```js +customElements.define('expanding-list', ExpandingList, { extends: "ul" }); +``` -

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

+Usar o elemento integrado em um documento da web também parece um pouco diferente: -
<ul is="expanding-list">
+```html
+
    
 
   ...
 
-</ul>
+ +``` + +Você usa um elemento `
    ` normalmente, mas especifica o nome do elemento personalizado dentro do atributo `is`. -

    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](https://github.com/mdn/web-components-examples/blob/master/expanding-list-web-component/main.js) aqui. -
    -

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

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

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

    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. -
      -
    • 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 {{domxref("Node.isConnected")}} para ter certeza. -
      -

      Nota: connectedCallback pode ser chamado assim que seu elemento não estiver mais conectado, use {{domxref("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
      • -
    +- `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:

    +Vejamos um exemplo em uso. O código abaixo é retirado do exemplo [life-cycle-callbacks](https://github.com/mdn/web-components-examples/tree/master/life-cycle-callbacks) ([ver rodando ao vivo](https://mdn.github.io/web-components-examples/life-cycle-callbacks/)). Este é um exemplo trivial que simplesmente gera um quadrado colorido de tamanho fixo na página. O custom element tem a seguinte aparência: -
    <custom-square l="100" c="red"></custom-square>
    +```html + +``` -

    O construtor da classe é realmente simples - aqui anexamos um shadow DOM ao elemento e, em seguida, anexamos os elementos vazios {{htmlelement("div")}} e {{htmlelement("style")}} ao shadow root:

    +O construtor da classe é realmente simples - aqui anexamos um shadow DOM ao elemento e, em seguida, anexamos os elementos vazios {{htmlelement("div")}} e {{htmlelement("style")}} ao shadow root: -
    const shadow = this.attachShadow({mode: 'open'});
+```js
+const shadow = this.attachShadow({mode: 'open'});
 
 const div = document.createElement('div');
 const style = document.createElement('style');
 shadow.appendChild(style);
-shadow.appendChild(div);
    +shadow.appendChild(div); +``` -

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

    +A função chave neste exemplo é `updateStyle()` — isso pega um elemento, pega seu shadow root, encontra seu elemento `