Esta tradução está incompleta. Por favor, ajude a traduzir este artigo.

Web Components são 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 <template> e <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 ou uma função na qual você especifica a funcionalidade de seu componente web. Se optar por usar classe, utilize a sintaxe definida pelo ECMAScript 2015 (veja Classes para mais informações). 
  2. Registre seus elemento customizado através do método 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 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 <template> e <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
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 <template> e <slot>, e como utilizar essa estrutura dentro de elementos web.

Referência

Elementos customizados

CustomElementRegistry
Contains functionality related to custom elements, most notably the CustomElementRegistry.define() method used to register new custom elements so they can then be used in your document.
Window.customElements
Returns a reference to the CustomElementRegistry object.
Life cycle callbacks
Special callback functions defined inside the custom element's class definition, which affect its behavior:
  • connectedCallback: Invoked when the custom element is first connected to the document's DOM.
  • disconnectedCallback: Invoked when the custom element is disconnected from the document's DOM.
  • adoptedCallback: Invoked when the custom element is moved to a new document.
  • attributeChangedCallback: Invoked when one of the custom element's attributes is added, removed, or changed.
Extensions for creating custom built-in elements
  • The is global HTML attribute: Allows you to specify that a standard HTML element should behave like a registered custom built-in element.
  • The "is" option of the Document.createElement() method: Allows you to create an instance of a standard HTML element that behaves like a given registered custom built-in element.
CSS pseudo-classes
Pseudo-classes relating specifically to custom elements:
  • :defined: Matches any element that is defined, including built in elements and custom elements defined with CustomElementRegistry.define()).
  • :host: Selects the shadow host of the shadow DOM containing the CSS it is used inside.
  • :host(): Selects the shadow host of the shadow DOM 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.
  • :host-context(): Selects the shadow host of the shadow DOM 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.

Shadow DOM

ShadowRoot
Represents the root node of a shadow DOM subtree.
DocumentOrShadowRoot
A mixin defining features that are available across document and shadow roots.
Element extensions
Extensions to the Element interface related to shadow DOM:
  • The Element.attachShadow() method attaches a shadow DOM tree to the specified element.
  • The Element.shadowRoot property returns the shadow root attached to the specified element, or null if there is no shadow root attached.
Relevant Node additions
Additions to the Node interface relevant to shadow DOM:
  • The Node.getRootNode() method returns the context object's root, which optionally includes the shadow root if it is available.
  • The Node.isConnected property returns a boolean indicating whether or not the Node is connected (directly or indirectly) to the context object, e.g. the Document object in the case of the normal DOM, or the ShadowRoot in the case of a shadow DOM.
Event extensions
Extensions to the Event interface related to shadow DOM:
  • Event.composed: Returns a Boolean which indicates whether the event will propagate across the shadow DOM boundary into the standard DOM (true), or not  (false).
  • 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 ShadowRoot.mode closed.

Templates HTML

<template>
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 HTMLTemplateElement.
<slot>
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 HTMLSlotElement.
The slot global HTML attribute
Assigns a slot in a shadow DOM shadow tree to an element.
Slotable
A mixin implemented by both Element and Text nodes, defining features that allow them to become the contents of an <slot> element. The mixin defines one attribute, Slotable.assignedSlot, which returns a reference to the slot the node is inserted in.
Element extensions
Extensions to the Element interface related to slots:
  • Element.slot: Returns the name of the shadow DOM slot attached to the element.
CSS pseudo-elements
Pseudo-elements relating specifically to slots:
  • ::slotted: Matches any content that is inserted into a slot.
The slotchange event
Fired on an HTMLSlotElement instance (<slot> element) when the node(s) contained in that slot change.

Exemplos

We are building up a number of examples in our web-components-examples GitHub repo. More will be added as time goes on.

Especificações

Specification Status Comment
HTML Living Standard
The definition of '<template> element' in that specification.
Padrão em tempo real The definition of <template>.
HTML Living Standard
The definition of 'custom elements' in that specification.
Padrão em tempo real The definition of HTML Custom Elements.
DOM
The definition of 'shadow trees' in that specification.
Padrão em tempo real The definition of Shadow DOM.
HTML Imports Rascunho atual Initial HTML Imports definition.
Shadow DOM Obsoleto Initial Shadow DOM definition.

Compatibilidade entre navegadores

In general:

  • Web components are supported by default in Firefox (version 63), Chrome, and Opera.
  • Safari supports a number of web component features, but less than the above browsers.
  • Edge is working on an implementation.

For detailed browser support of specific features, you'll have to consult the reference pages listed above.

Veja também

  • webcomponents.org — site featuring web components examples, tutorials, and other information.
  • Hybrids — Open source web components library, which favors plain objects and pure functions over class and this syntax. It provides a simple and functional API for creating custom elements.
  • Polymer — Google's web components framework — a set of polyfills, enhancements, and examples. Currently the easiest way to use web components cross-browser.
  • Snuggsi.es — Easy Web Components in ~1kB Including polyfill — All you need is a browser and basic understanding of HTML, CSS, and JavaScript classes to be productive.
  • Slim.js — Open source web components library — a high-performant library for rapid and easy component authoring; extensible and pluggable and cross-framework compatible.
  • Smart.js — Web Components library with simple API for creating cross-browser custom elements. 

Etiquetas do documento e colaboradores

Colaboradores desta página: luan0ap, cristiano-soares
Última atualização por: luan0ap,