Modelo, slot e sombra

O benefício dos componentes da Web é a reutilização: você pode criar um widget de interface uma vez e reutilizá-lo várias vezes. Embora você precise de JavaScript para criar componentes da Web, não é necessário ter uma biblioteca JavaScript. O HTML e as APIs associadas oferecem tudo o que você precisa.

O padrão de componente da Web é composto por três partes: modelos HTML, elementos personalizados e o Shadow DOM. Quando combinados, é possível criar elementos personalizados, independentes (encapsulados) e reutilizáveis que podem ser integrados totalmente a aplicativos, assim como os outros elementos HTML que já abordamos.

Nesta seção, vamos criar o elemento <star-rating>, um componente da Web que permite aos usuários avaliar uma experiência em uma escala de uma a cinco estrelas. Ao nomear um elemento personalizado, recomendamos usar apenas letras minúsculas. Inclua traços, pois isso ajuda a distinguir entre elementos normais e personalizados.

Discutimos o uso dos elementos <template> e <slot>, do atributo slot e do JavaScript para criar um modelo com um Shadow DOM encapsulado. Reutilizamos o elemento definido, personalizando uma seção de texto, como você faria com qualquer elemento ou componente da Web. Também discutimos brevemente o uso de CSS dentro e fora do elemento personalizado.

O elemento <template>

O elemento <template> é usado para declarar fragmentos de HTML a serem clonados e inseridos no DOM com JavaScript. O conteúdo do elemento não é renderizado por padrão. Em vez disso, eles são instanciados usando JavaScript.

<template id="star-rating-template">
  <form>
    <fieldset>
      <legend>Rate your experience:</legend>
      <rating>
        <input type="radio" name="rating" value="1" aria-label="1 star" required />
        <input type="radio" name="rating" value="2" aria-label="2 stars" />
        <input type="radio" name="rating" value="3" aria-label="3 stars" />
        <input type="radio" name="rating" value="4" aria-label="4 stars" />
        <input type="radio" name="rating" value="5" aria-label="5 stars" />
      </rating>
    </fieldset>
    <button type="reset">Reset</button>
    <button type="submit">Submit</button>
  </form>
</template>

Como o conteúdo de um elemento <template> não é gravado na tela, o <form> e o conteúdo dele não são renderizados. A saída do CodePen a seguir parece vazia. Abra a guia HTML para ver a marcação <template>.

Neste exemplo, o <form> não é filho de um <template> no DOM. Em vez disso, o conteúdo dos elementos <template> são filhos de um DocumentFragment retornado pela propriedade HTMLTemplateElement.content. Para que ele fique visível, é preciso usar o JavaScript para capturar o conteúdo e anexá-lo ao DOM.

Esse JavaScript não criou um elemento personalizado. Em vez disso, esse exemplo anexou o conteúdo de <template> ao <body>. O conteúdo se tornou parte do DOM visível e estilizável.

O CodePen como aparece no DOM.

Exigir JavaScript para implementar um modelo para apenas uma classificação por estrelas não é muito útil, mas criar um componente da Web para um widget de classificação por estrelas personalizável e usado repetidamente é útil.

O elemento <slot>

Incluímos um slot para incluir uma legenda personalizada por ocorrência. O HTML fornece um elemento <slot> como um marcador de posição dentro de um <template> que, se receber um nome, cria um "slot nomeado". Um slot nomeado pode ser usado para personalizar o conteúdo em um componente da Web. O elemento <slot> permite controlar onde os filhos de um elemento personalizado devem ser inseridos na árvore de sombra.

No modelo, mude <legend> para <slot>:

<template id="star-rating-template">
  <form>
    <fieldset>
      <slot name="star-rating-legend">
        <legend>Rate your experience:</legend>
      </slot>

O atributo name é usado para atribuir slots a outros elementos se o elemento tiver um atributo slot com um valor que corresponda ao nome de um slot nomeado. Se o elemento personalizado não tiver uma correspondência para um slot, o conteúdo do <slot> será renderizado. Por isso, incluímos um <legend> com conteúdo genérico que pode ser renderizado quando alguém adiciona <star-rating></star-rating>, sem conteúdo, no HTML.

<star-rating>
  <legend slot="star-rating-legend">Blendan Smooth</legend>
</star-rating>
<star-rating>
  <legend slot="star-rating-legend">Hoover Sukhdeep</legend>
</star-rating>
<star-rating>
  <legend slot="star-rating-legend">Toasty McToastface</legend>
  <p>Is this text visible?</p>
</star-rating>

O atributo slot é um atributo global usado para substituir o conteúdo do <slot> em um <template>. No nosso elemento personalizado, o elemento com o atributo slot é um <legend>. Não precisa ser assim. No nosso modelo, <slot name="star-rating-legend"> é substituído por <anyElement slot="star-rating-legend">, em que <anyElement> pode ser qualquer elemento, até mesmo outro elemento personalizado.

Elementos indefinidos

No nosso <template>, usamos um elemento <rating>. Este não é um elemento personalizado. Na verdade, é um elemento desconhecido. Os navegadores não falham quando não reconhecem um elemento. Os elementos HTML não reconhecidos são tratados pelo navegador como elementos inline anônimos que podem ser estilizados com CSS. Assim como <span>, os elementos <rating> e <star-rating> não têm estilos ou semântica aplicados pelo user agent.

Neste CodePen, o <template> e o conteúdo não são renderizados. O <template> é um elemento conhecido que contém conteúdo que não deve ser renderizado. O elemento <star-rating> ainda não foi definido. Até que um elemento seja definido, o navegador o exibe como todos os elementos não reconhecidos. Por enquanto, o <star-rating> não reconhecido é tratado como um elemento inline anônimo. Portanto, o conteúdo, incluindo as legendas e o <p> no terceiro <star-rating>, é exibido como se estivesse em um <span>.

Vamos definir nosso elemento para converter esse elemento não reconhecido em um elemento personalizado.

Elementos personalizados

O JavaScript é necessário para definir elementos personalizados. Quando definido, o conteúdo do elemento <star-rating> é substituído por uma raiz de sombra que contém todo o conteúdo do modelo associado a ele. Os elementos <slot> do modelo são substituídos pelo conteúdo do elemento no <star-rating> com o valor do atributo slot correspondente ao valor do nome do <slot>, se houver. Caso contrário, o conteúdo dos slots do modelo será exibido.

O conteúdo em um elemento personalizado que não está associado a um slot (o <p>Is this text visible?</p> no nosso terceiro <star-rating>) não é incluído na raiz de sombra e, portanto, não é exibido.

Definimos o elemento personalizado chamado star-rating estendendo o HTMLElement:

customElements.define('star-rating',
  class extends HTMLElement {
    constructor() {
      super(); // Always call super first in constructor
      const starRating = document.getElementById('star-rating-template').content;
      const shadowRoot = this.attachShadow({
        mode: 'open'
      });
      shadowRoot.appendChild(starRating.cloneNode(true));
    }
  });

Agora que o elemento está definido, sempre que o navegador encontrar um elemento <star-rating>, ele será renderizado conforme definido pelo elemento com o #star-rating-template, que é nosso modelo. O navegador anexa uma árvore do shadow DOM ao nó, adicionando um clone do conteúdo do modelo ao final desse shadow DOM.

const shadowRoot = this.attachShadow({mode: 'open'});
shadowRoot.appendChild(starRating.cloneNode(true));

Se você analisar as ferramentas para desenvolvedores, vai notar que o <form> do <template> faz parte da raiz de sombra de cada elemento personalizado. Um clone do conteúdo de <template> aparece em cada elemento personalizado nas ferramentas para desenvolvedores e fica visível no navegador, mas o conteúdo do elemento personalizado em si não é renderizado na tela.

Captura de tela do DevTools mostrando o conteúdo do modelo clonado em cada elemento personalizado.

No exemplo de <template>, anexamos o conteúdo do modelo ao corpo do documento, adicionando o conteúdo ao DOM normal. Na definição de customElements, usamos o mesmo appendChild(), mas o conteúdo do modelo clonado foi anexado a um DOM paralelo encapsulado.

Você percebeu que as estrelas voltaram a ser botões de opção sem estilo? Como faz parte de um DOM paralelo, e não do DOM padrão, o estilo na guia CSS do CodePen não se aplica. Os estilos CSS dessa guia têm como escopo o documento, não o shadow DOM, então os estilos não são aplicados. Precisamos criar estilos encapsulados para estilizar o conteúdo encapsulado do Shadow DOM.

Shadow DOM

O Shadow DOM define o escopo dos estilos CSS para cada árvore de sombra, isolando-a do restante do documento. Isso significa que o CSS externo não se aplica ao componente, e os estilos do componente não têm efeito no restante do documento, a menos que sejam direcionados intencionalmente.

Como anexamos o conteúdo a um shadow DOM, podemos incluir um elemento <style> que fornece CSS encapsulado ao elemento personalizado.

Como isso é limitado ao elemento personalizado, não precisamos nos preocupar com o vazamento de estilos para o restante do documento. Podemos reduzir substancialmente a especificidade dos seletores. Por exemplo, como as únicas entradas usadas no elemento personalizado são botões de opção, podemos usar input em vez de input[type="radio"] como seletor.

 <template id="star-rating-template">
  <style>
    rating {
      display: inline-flex;
    }
    input {
      appearance: none;
      margin: 0;
      box-shadow: none;
    }
    input::after {
      content: '\2605'; /* solid star */
      font-size: 32px;
    }
    rating:hover input:invalid::after,
    rating:focus-within input:invalid::after {
      color: #888;
    }
    input:invalid::after,
      rating:hover input:hover ~ input:invalid::after,
      input:focus ~ input:invalid::after  {
      color: #ddd;
    }
    input:valid {
      color: orange;
    }
    input:checked ~ input:not(:checked)::after {
      color: #ccc;
      content: '\2606'; /* hollow star */
    }
  </style>
  <form>
    <fieldset>
      <slot name="star-rating-legend">
        <legend>Rate your experience:</legend>
      </slot>
      <rating>
        <input type="radio" name="rating" value="1" aria-label="1 star" required/>
        <input type="radio" name="rating" value="2" aria-label="2 stars"/>
        <input type="radio" name="rating" value="3" aria-label="3 stars"/>
        <input type="radio" name="rating" value="4" aria-label="4 stars"/>
        <input type="radio" name="rating" value="5" aria-label="5 stars"/>
      </rating>
    </fieldset>
    <button type="reset">Reset</button>
    <button type="submit">Submit</button>
  </form>
</template>

Embora os componentes da Web sejam encapsulados com marcação <template> e os estilos CSS tenham como escopo o shadow DOM e fiquem ocultos de tudo fora dos componentes, o conteúdo do slot renderizado, a parte <anyElement slot="star-rating-legend"> do <star-rating>, não é encapsulado.

Estilo fora do escopo atual

É possível, mas não simples, estilizar o documento de dentro de um shadow DOM e estilizar o conteúdo de um shadow DOM usando os estilos globais. O limite de sombra, onde o DOM paralelo termina e o DOM regular começa, pode ser atravessado, mas apenas de forma muito intencional.

A árvore de sombra é a árvore do DOM dentro do shadow DOM. A raiz de sombra é o nó raiz da árvore de sombra.

A pseudoclasse :host seleciona o <star-rating>, o elemento host de sombra. O host de sombra é o nó do DOM ao qual o shadow DOM está anexado. Para segmentar apenas versões específicas do host, use :host(). Isso seleciona apenas os elementos de host de sombra que correspondem ao parâmetro transmitido, como um seletor de classe ou atributo. Para selecionar todos os elementos personalizados, use star-rating { /* styles */ } no CSS global ou :host(:not(#nonExistantId)) nos estilos de modelo. Em termos de especificidade, o CSS global vence.

O pseudoelemento ::slotted() cruza o limite do shadow DOM de dentro dele. Ele seleciona um elemento com slot se ele corresponder ao seletor. No nosso exemplo, ::slotted(legend) corresponde às nossas três legendas.

Para segmentar um DOM de sombra do CSS no escopo global, o modelo precisa ser editado. O atributo part pode ser adicionado a qualquer elemento que você queira estilizar. Em seguida, use o pseudoelemento ::part() para corresponder elementos em uma árvore de sombra que correspondem ao parâmetro transmitido. O elemento âncora ou de origem do pseudoelemento é o host ou o nome do elemento personalizado, neste caso, star-rating. O parâmetro é o valor do atributo part.

Se a marcação do modelo começasse assim:

<template id="star-rating-template">
  <form part="formPart">
    <fieldset part="fieldsetPart">

Podemos segmentar <form> e <fieldset> com:

star-rating::part(formPart) { /* styles */ }
star-rating::part(fieldsetPart) { /* styles */ }

Os nomes de partes funcionam de maneira semelhante às classes: um elemento pode ter vários nomes de partes separados por espaços, e vários elementos podem ter o mesmo nome de parte.

O Google tem uma lista de verificação fantástica para criar elementos personalizados. Também pode ser interessante saber mais sobre DOMs paralelos declarativos.

Teste seu conhecimento

Teste seus conhecimentos sobre modelo, slot e sombra.

Por padrão, os estilos de fora do shadow DOM estilizam os elementos internos.

Verdadeiro
Tente de novo.
Falso
Correto.

Qual resposta é uma descrição correta do elemento <template>?

Um elemento genérico usado para exibir qualquer conteúdo na sua página.
Tente de novo.
Um elemento marcador de posição.
Tente de novo.
Um elemento usado para declarar fragmentos de HTML que não serão renderizados por padrão.
Correto.