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
224
225
226
|
---
title: Componentes da Web
slug: Web/Componentes_Web
tags:
- Artigo da Web
- Componentes
- Componentes da Web
- Desenvolvimento da Web
- Importações HTML
- JavaScript
- Landing
- Modelo
- Resumo
- Sinopse
- elementos personalizados
- shadow dom
- slot
translation_of: Web/Web_Components
---
<div>{{DefaultAPISidebar("Componentes Web")}}</div>
<div></div>
<div class="summary">
<p>Componentes Web é uma suite de diferentes tecnologias que permite a criação de elementos reutilizáveis — com a sua funcionalidade encapsulada longe do restante código — E utilizá-las nas suas aplicações web.</p>
</div>
<h2 id="Conceitos_e_utilização">Conceitos e utilização</h2>
<p>Como programadores, todos sabemos que é boa ideia reutilizar código tanto como possível. Tradicionalmente, esta ideia não tem sido tão fácil para estruturas de marcação — pense no complexo HTML (e seus estilos e scripts associados) em que por vezes é necessário escrever controlos personalizados de UI e usá-los múltiplas vezes pode tornar a página numa desordem se não tiver cuidado</p>
<p>Componentes Web visa resolver tais problemas — consiste em três grandes tecnologias, que usadas em conjunto, permitem criar elementos versáteis com funcionalidade encapsulada e que podem ser reutilizados onde se queira sem medo de colisões de código.</p>
<ul>
<li><strong>Custom elements</strong>: A set of JavaScript APIs that allow you to define custom elements and their behaviour, which can then be used as desired in your user interface.</li>
<li><strong>Shadow DOM</strong>: A set of JavaScript APIs for attaching an encapsulated "shadow" DOM tree to an element — which is rendered separately from the main document DOM — and controlling associated functionality. In this way, you can keep an element's features private, so they can be scripted and styled without the fear of collision with other parts of the document.</li>
<li><strong>HTML templates</strong>: The {{HTMLElement("template")}} and {{HTMLElement("slot")}} elements enable you to write markup templates that are not displayed in the rendered page. These can then be reused multiple times as the basis of a custom element's structure.</li>
</ul>
<p>The basic approach for implementing a web component generally looks something like this:</p>
<ol>
<li>Create a class or a function in which you specify your web component functionality. If using a class, use the ECMAScript 2015 class syntax (see <a href="/en-US/docs/Web/JavaScript/Reference/Classes">Classes</a> for more information). </li>
<li>Register your new custom element using the {{domxref("CustomElementRegistry.define()")}} method, passing it the element name to be defined, the class or function in which its functionality is specified, and optionally, what element it inherits from.</li>
<li>If required, attach a shadow DOM to the custom element using {{domxref("Element.attachShadow()")}} method. Add child elements, event listeners, etc., to the shadow DOM using regular DOM methods.</li>
<li>If required, define an HTML template using {{htmlelement("template")}} and {{htmlelement("slot")}}. Again use regular DOM methods to clone the template and attach it to your shadow DOM.</li>
<li>Use your custom element wherever you like on your page, just like you would any regular HTML element.</li>
</ol>
<h2 id="Tutoriais">Tutoriais</h2>
<dl>
<dt><a href="/en-US/docs/Web/Web_Components/Using_custom_elements">Using custom elements</a></dt>
<dd>A guide showing how to use the features of custom elements to create simple web components, as well as looking into lifecycle callbacks and some other more advanced features.</dd>
<dt><a href="/en-US/docs/Web/Web_Components/Using_shadow_DOM">Using shadow DOM</a></dt>
<dd>A guide that looks at shadow DOM fundamentals, showing how to attach a shadow DOM to an element, add to the shadow DOM tree, style it, and more.</dd>
<dt><a href="/en-US/docs/Web/Web_Components/Using_templates_and_slots">Using templates and slots</a></dt>
<dd>A guide showing how to define a reusable HTML structure using {{htmlelement("template")}} and {{htmlelement("slot")}} elements, and then use that structure inside your web components.</dd>
</dl>
<h2 id="Referência">Referência</h2>
<h3 id="Elementos_de_Custom">Elementos de <em>Custom</em></h3>
<dl>
<dt>{{domxref("CustomElementRegistry")}}</dt>
<dd>Contains functionality related to custom elements, most notably the {{domxref("CustomElementRegistry.define()")}} method used to register new custom elements so they can then be used in your document.</dd>
<dt>{{domxref("Window.customElements")}}</dt>
<dd>Returns a reference to the <code>CustomElementRegistry</code> object.</dd>
<dt><a href="/en-US/docs/Web/Web_Components/Using_custom_elements#Using_the_lifecycle_callbacks">Life cycle callbacks</a></dt>
<dd>Special callback functions defined inside the custom element's class definition, which affect its behavior:
<ul>
<li><code>connectedCallback</code>: Invoked when the custom element is first connected to the document's DOM.</li>
<li><code>disconnectedCallback</code>: Invoked when the custom element is disconnected from the document's DOM.</li>
<li><code>adoptedCallback</code>: Invoked when the custom element is moved to a new document.</li>
<li><code>attributeChangedCallback</code>: Invoked when one of the custom element's attributes is added, removed, or changed.</li>
</ul>
</dd>
<dd>
<ul>
</ul>
</dd>
</dl>
<dl>
<dt>Extensions for creating custom built-in elements</dt>
<dd>
<ul>
<li>The {{htmlattrxref("is")}} global HTML attribute: Allows you to specify that a standard HTML element should behave like a registered custom built-in element.</li>
<li>The "is" option of the {{domxref("Document.createElement()")}} method: Allows you to create an instance of a standard HTML element that behaves like a given registered custom built-in element.</li>
</ul>
</dd>
<dt>CSS pseudo-classes</dt>
<dd>Pseudo-classes relating specifically to custom elements:
<ul>
<li>{{cssxref(":defined")}}: Matches any element that is defined, including built in elements and custom elements defined with <code>CustomElementRegistry.define()</code>).</li>
<li>{{cssxref(":host")}}: Selects the shadow host of the <a href="/en-US/docs/Web/Web_Components/Using_shadow_DOM">shadow DOM</a> containing the CSS it is used inside.</li>
<li>{{cssxref(":host()")}}: Selects the shadow host of the <a href="/en-US/docs/Web/Web_Components/Using_shadow_DOM">shadow DOM</a> containing the CSS it is used inside (so you can select a custom element from inside its shadow DOM) — but only if the selector given as the function's parameter matches the shadow host.</li>
<li>{{cssxref(":host-context()")}}: Selects the shadow host of the <a href="/en-US/docs/Web/Web_Components/Using_shadow_DOM">shadow DOM</a> containing the CSS it is used inside (so you can select a custom element from inside its shadow DOM) — but only if the selector given as the function's parameter matches the shadow host's ancestor(s) in the place it sits inside the DOM hierarchy.</li>
</ul>
</dd>
</dl>
<h3 id="Shadow_DOM">Shadow DOM</h3>
<dl>
<dt>{{domxref("ShadowRoot")}}</dt>
<dd>Represents the root node of a shadow DOM subtree.</dd>
<dt>{{domxref("DocumentOrShadowRoot")}}</dt>
<dd>A mixin defining features that are available across document and shadow roots.</dd>
<dt>{{domxref("Element")}} extensions</dt>
<dd>Extensions to the <code>Element</code> interface related to shadow DOM:
<ul>
<li>The {{domxref("Element.attachShadow()")}} method attaches a shadow DOM tree to the specified element.</li>
<li>The {{domxref("Element.shadowRoot")}} property returns the shadow root attached to the specified element, or <code>null</code> if there is no shadow root attached.</li>
</ul>
</dd>
<dt>Relevant {{domxref("Node")}} additions</dt>
<dd>Additions to the <code>Node</code> interface relevant to shadow DOM:
<ul>
<li>The {{domxref("Node.getRootNode()")}} method returns the context object's root, which optionally includes the shadow root if it is available.</li>
<li>The {{domxref("Node.isConnected")}} property returns a boolean indicating whether or not the Node is connected (directly or indirectly) to the context object, e.g. the {{domxref("Document")}} object in the case of the normal DOM, or the {{domxref("ShadowRoot")}} in the case of a shadow DOM.</li>
</ul>
</dd>
<dt>{{domxref("Event")}} extensions</dt>
<dd>Extensions to the <code>Event</code> interface related to shadow DOM:
<ul>
<li>{{domxref("Event.composed")}}: Returns a {{jsxref("Boolean")}} which indicates whether the event will propagate across the shadow DOM boundary into the standard DOM (<code>true</code>), or not (<code>false</code>).</li>
<li>{{domxref("Event.composedPath")}}: Returns the event’s path (objects on which listeners will be invoked). This does not include nodes in shadow trees if the shadow root was created with {{domxref("ShadowRoot.mode")}} closed.</li>
</ul>
</dd>
</dl>
<h3 id="Modelos_de_HTML">Modelos de HTML</h3>
<dl>
<dt>{{htmlelement("template")}}</dt>
<dd>Contains an HTML fragment that is not rendered when a containing document is initially loaded, but can be displayed at runtime using JavaScript, mainly used as the basis of custom element structures. The associated DOM interface is {{domxref("HTMLTemplateElement")}}.</dd>
<dt>{{htmlelement("slot")}}</dt>
<dd>A placeholder inside a web component that you can fill with your own markup, which lets you create separate DOM trees and present them together. The associated DOM interface is {{domxref("HTMLSlotElement")}}.</dd>
<dt>The <code><a href="/en-US/docs/Web/HTML/Global_attributes/slot">slot</a></code> global HTML attribute</dt>
<dd>Assigns a slot in a shadow DOM shadow tree to an element.</dd>
<dt>{{domxref("Slotable")}}</dt>
<dd>A mixin implemented by both {{domxref("Element")}} and {{domxref("Text")}} nodes, defining features that allow them to become the contents of an {{htmlelement("slot")}} element. The mixin defines one attribute, {{domxref("Slotable.assignedSlot")}}, which returns a reference to the slot the node is inserted in.</dd>
</dl>
<dl>
<dt>{{domxref("Element")}} extensions</dt>
<dd>Extensions to the <code>Element</code> interface related to slots:
<ul>
<li>{{domxref("Element.slot")}}: Returns the name of the shadow DOM slot attached to the element.</li>
</ul>
</dd>
<dt>CSS pseudo-elements</dt>
<dd>Pseudo-elements relating specifically to slots:
<ul>
<li>{{cssxref("::slotted")}}: Matches any content that is inserted into a slot.</li>
</ul>
</dd>
<dt>The {{event("slotchange")}} event</dt>
<dd>Fired on an {{domxref("HTMLSlotElement")}} instance ({{htmlelement("slot")}} element) when the node(s) contained in that slot change.</dd>
</dl>
<h2 id="Exemplos">Exemplos</h2>
<p>We are building up a number of examples in our <a href="https://github.com/mdn/web-components-examples">web-components-examples</a> GitHub repo. More will be added as time goes on.</p>
<h2 id="Especificações">Especificações</h2>
<table class="standard-table">
<tbody>
<tr>
<th scope="col">Especificação</th>
<th scope="col">Estado</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>The definition of {{HTMLElement("template")}}.</td>
</tr>
<tr>
<td>{{SpecName("HTML WHATWG","custom-elements.html#custom-elements","custom elements")}}</td>
<td>{{Spec2("HTML WHATWG")}}</td>
<td>The definition of <a href="/en-US/docs/Web/Web_Components/Using_custom_elements">HTML Custom Elements</a>.</td>
</tr>
<tr>
<td>{{SpecName("DOM WHATWG","#shadow-trees","shadow trees")}}</td>
<td>{{Spec2("DOM WHATWG")}}</td>
<td>The definition of <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>Initial <a href="/en-US/docs/Web/Web_Components/HTML_Imports">HTML Imports</a> definition.</td>
</tr>
<tr>
<td>{{SpecName("Shadow DOM", "", "")}}</td>
<td>{{Spec2("Shadow DOM")}}</td>
<td>Initial <a href="/en-US/docs/Web/Web_Components/Using_shadow_DOM">Shadow DOM</a> definition.</td>
</tr>
</tbody>
</table>
<h2 id="Compatibilidade_de_navegador">Compatibilidade de navegador</h2>
<p>In general:</p>
<ul>
<li>Web components are supported by default in Firefox (version 63), Chrome, and Opera.</li>
<li>Safari supports a number of web component features, but less than the above browsers.</li>
<li>Edge is working on an implementation.</li>
</ul>
<p>For detailed browser support of specific features, you'll have to consult the reference pages listed above.</p>
<h2 id="Consulte_também">Consulte também</h2>
<ul>
<li><a href="https://www.webcomponents.org/">webcomponents.org</a> — site featuring web components examples, tutorials, and other information.</li>
<li><a href="https://github.com/hybridsjs/hybrids">Hybrids</a> — Open source web components library, which favors plain objects and pure functions over <code>class</code> and <font face="consolas, Liberation Mono, courier, monospace"><span style="background-color: rgba(220, 220, 220, 0.5);">this</span></font> syntax. It provides a simple and functional API for creating custom elements.</li>
<li><a href="https://www.polymer-project.org/">Polymer</a> — Google's web components framework — a set of polyfills, enhancements, and examples. Currently the easiest way to use web components cross-browser.</li>
<li><a href="https://github.com/devpunks/snuggsi#readme">Snuggsi.es</a> — Easy Web Components in ~1kB <em>Including polyfill</em> — All you need is a browser and basic understanding of HTML, CSS, and JavaScript classes to be productive.</li>
<li><a href="https://github.com/slimjs/slim.js">Slim.js</a> — Open source web components library — a high-performant library for rapid and easy component authoring; extensible and pluggable and cross-framework compatible.</li>
<li><a href="https://www.htmlelements.com/">Smart.js</a> — Web Components library with simple API for creating cross-browser custom elements. </li>
</ul>
|
