1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
|
---
title: Web Components
slug: Web/Web_Components
translation_of: Web/Web_Components
---
<div>{{DefaultAPISidebar("Web Components")}}</div>
<div class="summary">
<p>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.</p>
</div>
<h2 id="Conceitos_e_uso">Conceitos e uso</h2>
<p>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.</p>
<p>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.</p>
<ul>
<li><strong>Elementos customizados</strong>: 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.</li>
<li><strong>Shadow DOM</strong>: 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.</li>
<li><strong>Templates HTML</strong>: 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.</li>
</ul>
<p>A abordagem básica para se implementar um componente web geralmente se parece com isso:</p>
<ol>
<li>Crie uma classe na qual você especifica a funcionalidade do seu componente web, usando a sintaxe de classe do ECMAScript 2015 (veja <a href="/en-US/docs/Web/JavaScript/Reference/Classes">Classes</a> para mais informações). </li>
<li>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.</li>
<li>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.</li>
<li>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.</li>
<li>Use seu elemento customizado onde você preferir em sua página, da mesma forma que usaria qualquer outro elemento HTML.</li>
</ol>
<h2 id="Tutoriais">Tutoriais</h2>
<dl>
<dt><a href="/pt-BR/docs/Web/Web_Components/Usando_custom_elements">Usando elementos customizados</a></dt>
<dd>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.</dd>
<dt><a href="/en-US/docs/Web/Web_Components/Using_shadow_DOM">Usando shadow DOM</a></dt>
<dd>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.</dd>
<dt><a href="/en-US/docs/Web/Web_Components/Using_templates_and_slots">Usando templates e slots</a></dt>
<dd>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.</dd>
</dl>
<h2 id="Referência">Referência</h2>
<h3 id="Elementos_customizados">Elementos customizados</h3>
<dl>
<dt>{{domxref("CustomElementRegistry")}}</dt>
<dd>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.</dd>
<dt>{{domxref("Window.customElements")}}</dt>
<dd>Retorna uma referência ao objeto <code>CustomElementRegistry</code>.</dd>
<dt><a href="/en-US/docs/Web/Web_Components/Using_custom_elements#Using_the_lifecycle_callbacks">Callbacks do ciclo de vida</a></dt>
<dd>Funções callback especiais definidas dentro da definição de classe de elemento customizado, afetando seu comportamento:
<ul>
<li><code>connectedCallback</code>: Invocada quando um elemento customizado é adicionao ao DOM do documento.</li>
<li><code>disconnectedCallback</code>: Invocada quando o elemento customizado é desconectado do DOM do documento.</li>
<li><code>adoptedCallback</code>: Invocada quando o elemento customizado é movido para um novo documento.</li>
<li><code>attributeChangedCallback</code>: Invocada quando um dos atributos de um elemento customizado é adicionado, removido ou alterado.</li>
</ul>
</dd>
<dd>
<ul>
</ul>
</dd>
</dl>
<dl>
<dt>Extensões para criação de elementos built-in customizados</dt>
<dd>
<ul>
<li>O atributo HTML global {{htmlattrxref("is")}}: Permite especificar que um elemento HTML padrão deve se comportar como um elemento built-in customizado registrado.</li>
<li>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.</li>
</ul>
</dd>
<dt>CSS pseudo-classes</dt>
<dd>Pseudo-classes relacionadas especificamente a elementos customizados:
<ul>
<li>{{cssxref(":defined")}}: Corresponde a qualquer elemento que está definido, incluindo elementos built-in e elementos customizados que foram definidos com <code>CustomElementRegistry.define()</code>).</li>
<li>{{cssxref(":host")}}: Seleciona o host fantasma do <a href="/en-US/docs/Web/Web_Components/Using_shadow_DOM">shadow DOM</a> contendo o CSS utilizado internamente.</li>
<li>{{cssxref(":host()")}}: Seleciona o host fantasma do <a href="/en-US/docs/Web/Web_Components/Using_shadow_DOM">shadow DOM</a> 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.</li>
<li>{{cssxref(":host-context()")}}: Seleciona o host fantasma do <a href="/en-US/docs/Web/Web_Components/Using_shadow_DOM">shadow DOM</a> 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.</li>
</ul>
</dd>
<dt>CSS pseudo-elementos</dt>
<dd>Pseudo-elementos relacionados especificamente a elementos customizados:
<ul>
<li>{{cssxref("::part")}}: Representa qualquer elemento dentro de uma <a href="/en-US/docs/Web/Web_Components/Using_shadow_DOM">shadow tree</a> que tenha um atributo {{HTMLAttrxRef("part")}} correspondente.</li>
</ul>
</dd>
</dl>
<h3 id="Shadow_DOM">Shadow DOM</h3>
<dl>
<dt>{{domxref("ShadowRoot")}}</dt>
<dd>Representa o nó raíz de uma sub-árvore DOM fantasma.</dd>
<dt>{{domxref("DocumentOrShadowRoot")}}</dt>
<dd>Um mixin que define funcionalidades que ficam disponíveis através do documento e das raízes fantasma.</dd>
<dt>Extensões {{domxref("Element")}}</dt>
<dd>Extensões à interface <code>Element</code> relacionado ao shadow DOM:
<ul>
<li>O método {{domxref("Element.attachShadow()")}} vincula uma árvore DOM fantasma ao elemento especificado.</li>
<li>A propriedade {{domxref("Element.shadowRoot")}} retorna a árvore fantasma raíz vinculada ao elemento especificado, ou <code>null</code> se não existir nenhuma árvore fantasma vinculada.</li>
</ul>
</dd>
<dt>Adições relevantes {{domxref("Node")}}</dt>
<dd>Adicionais à interface <code>Node</code> pertinentes ao shadow DOM:
<ul>
<li>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.</li>
<li>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).</li>
</ul>
</dd>
<dt>Extensões {{domxref("Event")}} </dt>
<dd>Extensões para a interface de <code>Event</code> relacionado a shadow DOM:
<ul>
<li>{{domxref("Event.composed")}}: Retorna um {{jsxref("Boolean")}} que indica<br>
se o evento irá se propagar através dos limites do shadow DOM para dentro do DOM padrão (<code>true</code>), ou não (<code>false</code>).</li>
<li>{{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).</li>
</ul>
</dd>
</dl>
<h3 id="Templates_HTML">Templates HTML</h3>
<dl>
<dt>{{htmlelement("template")}}</dt>
<dd>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")}}.</dd>
<dt>{{htmlelement("slot")}}</dt>
<dd>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")}}.</dd>
<dt><code>O atributo HTML global <a href="/en-US/docs/Web/HTML/Global_attributes/slot">slot</a></code></dt>
<dd>Atribui um slot em uma árvore shadow DOM a um elemento.</dd>
<dt>{{domxref("Slotable")}}</dt>
<dd>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.</dd>
</dl>
<dl>
<dt>Extensões {{domxref("Element")}}</dt>
<dd>Extensões para a interface de <code>Element</code> relacionado a slots:
<ul>
<li>{{domxref("Element.slot")}}: Retorna o nome do slot do shadow DOM associado ao elemento.</li>
</ul>
</dd>
<dt>Pseudo-elementos CSS</dt>
<dd>Pseudo-elementos relacionados especificamente a slots:
<ul>
<li>{{cssxref("::slotted")}}: Corresponde a qualquer conteúdo inserido naquele slot.</li>
</ul>
</dd>
<dt>O evento {{event("slotchange")}}</dt>
<dd>Disparado em uma instância {{domxref("HTMLSlotElement")}} (elemento {{htmlelement("slot")}}) quando há mudança no nó(s) contido naquele slot.</dd>
</dl>
<h2 id="Exemplos">Exemplos</h2>
<p>Estamos construindo alguns exemplos em nosso repo do GitHub <a href="https://github.com/mdn/web-components-examples">web-components-examples</a>.<br>
Mais exemplos serão adicionados com o passar do tempo.</p>
<h2 id="Especificações">Especificações</h2>
<table class="standard-table">
<tbody>
<tr>
<th scope="col">Especificação</th>
<th scope="col">Status</th>
<th scope="col">Comentário</th>
</tr>
<tr>
<td>{{SpecName("HTML WHATWG","scripting.html#the-template-element","<template> element")}}</td>
<td>{{Spec2("HTML WHATWG")}}</td>
<td>Definição de {{HTMLElement("template")}}.</td>
</tr>
<tr>
<td>{{SpecName("HTML WHATWG","custom-elements.html#custom-elements","custom elements")}}</td>
<td>{{Spec2("HTML WHATWG")}}</td>
<td>Definição de <a href="/en-US/docs/Web/Web_Components/Using_custom_elements">Elementos HTML Customizados</a>.</td>
</tr>
<tr>
<td>{{SpecName("DOM WHATWG","#shadow-trees","shadow trees")}}</td>
<td>{{Spec2("DOM WHATWG")}}</td>
<td>Definição de <a href="/en-US/docs/Web/Web_Components/Using_shadow_DOM">Shadow DOM</a>.</td>
</tr>
<tr>
<td>{{SpecName("HTML Imports", "", "")}}</td>
<td>{{Spec2("HTML Imports")}}</td>
<td>Definição inicial de <a href="/en-US/docs/Web/Web_Components/HTML_Imports">HTML Imports</a>.</td>
</tr>
<tr>
<td>{{SpecName("Shadow DOM", "", "")}}</td>
<td>{{Spec2("Shadow DOM")}}</td>
<td>Definição inicial de <a href="/en-US/docs/Web/Web_Components/Using_shadow_DOM">Shadow DOM</a>.</td>
</tr>
</tbody>
</table>
<h2 id="Browser_compatibility">Compatibilidade com navegadores</h2>
<p>Em geral:</p>
<ul>
<li>Web components são suportados por padrão pelo Firefox (versão 63), Chrome, e Opera.</li>
<li>Safari suporta muitas das funcionalidades de web component, porém menos do que os navegadores citados acima.</li>
<li>Edge está trabalhando na implementação.</li>
</ul>
<p>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.</p>
<h2 id="Veja_também">Veja também</h2>
<ul>
<li><a href="https://www.webcomponents.org/">webcomponents.org</a> — site apresentando exemplos de web components, tutoriais e outras informações.</li>
<li><a href="https://fast.design/" rel="noopener">FAST</a> é uma biblioteca de web component construída pela Microsoft que oferece vários pacotes para potencializar dependendo das necessidades do seu projeto. <a href="https://github.com/microsoft/fast/tree/master/packages/web-components/fast-element" rel="noopener">Fast Element</a> é um meio fácil de criar Web Components de alto desempenho, com eficiência de memória e em conformidade com os padrões. <a href="https://github.com/microsoft/fast/tree/master/packages/web-components/fast-foundation" rel="noopener">Fast Foundation</a> é 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.</li>
<li><a href="https://github.com/hybridsjs/hybrids">Hybrids</a> — Biblioteca web components de código aberto, que favorece objetos simples e funções puras em vez de <code>class</code> e <font face="consolas, Liberation Mono, courier, monospace"><span>this</span></font> sintaxe. Ele fornece uma API simples e funcional para a criação de elementos personalizados.</li>
<li><a href="https://www.polymer-project.org/">Polymer</a> — 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.</li>
<li><a href="https://github.com/devpunks/snuggsi#readme">Snuggsi</a> — Web Components fáceis com ~1kB <em>Incluindo polyfill</em> — Tudo que você precisa é um navegador e um conhecimento básico de HTML, CSS e classes JavaScript para ser produtivo.</li>
<li><a href="https://github.com/slimjs/slim.js">Slim.js</a> — 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.</li>
<li><a href="https://stenciljs.com/">Stencil</a> — Conjunto de ferramentas para a construção de sistemas de design reutilizáveis e escalonáveis em web components.</li>
</ul>
<div id="gtx-trans" style="position: absolute; left: 155px; top: 1512px;">
<div class="gtx-trans-icon"></div>
</div>
|
