Shadow DOM 301

Conceitos avançados e APIs do DOM

Eric Bidelman

Aviso: este artigo descreve uma versão antiga do Shadow DOM (v0). Se você tiver interesse em usar o Shadow DOM, confira nosso novo artigo, "Shadow DOM v1: self-contained web components". Ela abrange tudo da especificação mais recente do Shadow DOM v1, fornecida no Chrome 53, Safari 10 e Firefox 63.

Este artigo aborda outras coisas incríveis que você pode fazer com o Shadow DOM. Ele se baseia nos conceitos discutidos no Shadow DOM 101 e no Shadow DOM 201.

Observação : no Chrome, ative a opção "Ativar recursos experimentais da plataforma da Web" em about:flags para testar tudo o que foi abordado neste artigo.

Como usar várias raízes paralelas

Se você está organizando uma festa, fica poluído quando todos estão amontoados na mesma sala. e quer distribuir grupos de pessoas em várias salas. Os elementos que hospedam o Shadow DOM também podem fazer isso, ou seja, eles podem hospedar mais de uma raiz shadow por vez.

Vejamos o que acontece ao tentar anexar várias raízes paralelas a um host:

<div id="example1">Light DOM</div>
<script>
  var container = document.querySelector('#example1');
  var root1 = container.createShadowRoot();
  var root2 = container.createShadowRoot();
  root1.innerHTML = '<div>Root 1 FTW</div>';
  root2.innerHTML = '<div>Root 2 FTW</div>';
</script>

Observação : no DevTools, ative a opção "Show Shadow DOM" para poder inspecionar ShadowRoots.

O que é renderizado é a "Root 2 FTW", apesar de já haver uma árvore paralela anexada. Isso ocorre porque vence a última árvore shadow adicionada ao host. É uma pilha LIFO, tanto para a renderização quanto para a renderização. Examinar o DevTools para verificar esse comportamento.

Observação : as árvores sombra adicionadas a um host são empilhadas na ordem em que são adicionadas, começando pela mais recente. O último adicionado é aquele que é renderizado.

Observação : a árvore adicionada mais recentemente é chamada de árvore mais jovem. As árvores anteriores são chamadas de árvores mais antigas. Neste exemplo, root2 é a árvore mais nova e root1 é a mais antiga.

Por que adianta usar várias sombras se apenas a última é convidada para a parte de renderização? Insira pontos de inserção de sombra.

Pontos de inserção de sombra

Os "pontos de inserção de sombra" (<shadow>) são semelhantes aos pontos de inserção normais (<content>) porque são marcadores de posição. No entanto, em vez de serem marcadores de conteúdo do host, eles são hosts para outras árvores paralelas. É o Shadow DOM Inception!

Como você provavelmente pode imaginar, as coisas ficam mais complicadas à medida que você detalhar o buraco do coelho. Por esse motivo, a especificação é muito clara sobre o que acontece quando vários elementos <shadow> estão em jogo:

Observação : se houver vários pontos de inserção <shadow> em uma árvore paralela, somente o primeiro vai ser reconhecido. O restante é ignorado.

Voltando ao nosso exemplo original, a primeira sombra root1 foi deixada da lista de convites. Ao adicionar um ponto de inserção <shadow>, ele volta:

<div id="example2">Light DOM</div>
<script>
var container = document.querySelector('#example2');
var root1 = container.createShadowRoot();
var root2 = container.createShadowRoot();
root1.innerHTML = '<div>Root 1 FTW</div><content></content>';
**root2.innerHTML = '<div>Root 2 FTW</div><shadow></shadow>';**
</script>

Há algumas coisas interessantes sobre esse exemplo:

1. "Root 2 FTW" ainda é renderizada acima de "Root 1 FTW". Isso ocorre devido ao local em que colocamos o ponto de inserção <shadow>. Se quiser inverter, mova o ponto de inserção: root2.innerHTML = '<shadow></shadow><div>Root 2 FTW</div>';.
2. Agora há um ponto de inserção <content> na raiz1. Isso faz o nó de texto "Light DOM" acompanhar a renderização.

O que é renderizado em <shadow>?

Às vezes, é útil saber qual árvore paralela antiga está sendo renderizada em uma <shadow>. É possível conseguir uma referência a essa árvore usando .olderShadowRoot:

**root2.olderShadowRoot** === root1 //true

Como obter a raiz paralela de um host

Se um elemento hospedar o Shadow DOM, será possível acessar a raiz paralela mais recente usando .shadowRoot:

var root = host.createShadowRoot();
console.log(host.shadowRoot === root); // true
console.log(document.body.shadowRoot); // null

Se você estiver preocupado com as pessoas passando por suas sombras, redefina .shadowRoot para ser nulo:

Object.defineProperty(host, 'shadowRoot', {
  get: function() { return null; },
  set: function(value) { }
});

Parece um truque, mas funciona. No fim, é importante lembrar que, embora seja incrivelmente fantástico, o Shadow DOM não foi projetado para ser um recurso de segurança. Não dependa disso para isolar o conteúdo completamente.

Como criar o Shadow DOM em JS

Se você preferir criar o DOM em JS, HTMLContentElement e HTMLShadowElement têm interfaces para isso.

<div id="example3">
  <span>Light DOM</span>
</div>
<script>
var container = document.querySelector('#example3');
var root1 = container.createShadowRoot();
var root2 = container.createShadowRoot();

var div = document.createElement('div');
div.textContent = 'Root 1 FTW';
root1.appendChild(div);

 // HTMLContentElement
var content = document.createElement('content');
content.select = 'span'; // selects any spans the host node contains
root1.appendChild(content);

var div = document.createElement('div');
div.textContent = 'Root 2 FTW';
root2.appendChild(div);

// HTMLShadowElement
var shadow = document.createElement('shadow');
root2.appendChild(shadow);
</script>

Este exemplo é quase idêntico ao da seção anterior. A única diferença é que agora estou usando select para extrair o <span> recém-adicionado.

Como trabalhar com pontos de inserção

Os nós selecionados fora do elemento host e "distribuídos" na árvore paralela são chamados de... tambor... nós distribuídos! Eles têm permissão para cruzar o limite da sombra quando os pontos de inserção os convidam a entrar.

O que é conceitualmente bizarro sobre os pontos de inserção é que eles não movem fisicamente o DOM. Os nós do host permanecem intactos. Os pontos de inserção apenas reprojetam nós do host na árvore paralela. É uma coisa de apresentação/renderização: "Mova esses nós para cá" "Renderize esses nós neste local".

Observação : não é possível transferir o DOM para um <content>.

Exemplo:

<div><h2>Light DOM</h2></div>
<script>
var root = document.querySelector('div').createShadowRoot();
root.innerHTML = '<content select="h2"></content>';

var h2 = document.querySelector('h2');
console.log(root.querySelector('content[select="h2"] h2')); // null;
console.log(root.querySelector('content').contains(h2)); // false
</script>

Isso é o suficiente para O h2 não é filho do shadow DOM. Isso leva a outra informação importante:

Observação : os pontos de inserção são muito eficientes. Pense nelas como uma forma de criar uma "API declarativa" para o Shadow DOM. Um elemento host pode incluir todas as marcações existentes, mas ele não terá sentido a menos que seja convidado para o Shadow DOM com um ponto de inserção.

Element.getDistributedNodes()

Não é possível passar para <content>, mas a API .getDistributedNodes() permite consultar os nós distribuídos em um ponto de inserção:

<div id="example4">
  <h2>Eric</h2>
  <h2>Bidelman</h2>
  <div>Digital Jedi</div>
  <h4>footer text</h4>
</div>

<template id="sdom">
  <header>
    <content select="h2"></content>
  </header>
  <section>
    <content select="div"></content>
  </section>
  <footer>
    <content select="h4:first-of-type"></content>
  </footer>
</template>

<script>
var container = document.querySelector('#example4');

var root = container.createShadowRoot();

var t = document.querySelector('#sdom');
var clone = document.importNode(t.content, true);
root.appendChild(clone);

var html = [];
[].forEach.call(root.querySelectorAll('content'), function(el) {
  html.push(el.outerHTML + ': ');
  var nodes = el.getDistributedNodes();
  [].forEach.call(nodes, function(node) {
    html.push(node.outerHTML);
  });
  html.push('\n');
});
</script>

Element.getDestinationInsertionPoints()

Assim como em .getDistributedNodes(), é possível verificar em quais pontos de inserção um nó é distribuído chamando .getDestinationInsertionPoints():

<div id="host">
  <h2>Light DOM
</div>

<script>
  var container = document.querySelector('div');

  var root1 = container.createShadowRoot();
  var root2 = container.createShadowRoot();
  root1.innerHTML = '<content select="h2"></content>';
  root2.innerHTML = '<shadow></shadow>';

  var h2 = document.querySelector('#host h2');
  var insertionPoints = h2.getDestinationInsertionPoints();
  [].forEach.call(insertionPoints, function(contentEl) {
    console.log(contentEl);
  });
</script>

Ferramenta: Visualizador do Shadow DOM

Entender a magia negra do Shadow DOM é difícil. Lembro-me de tentar envolver minha cabeça em torno dele pela primeira vez.

Para ajudar na visualização de como a renderização do Shadow DOM funciona, criei uma ferramenta com o d3.js. As duas caixas de marcação no lado esquerdo são editáveis. Você pode colar sua própria marcação e testar como as coisas funcionam e os pontos de inserção fazem o swizzling dos nós do host na árvore paralela.

Iniciar o Visualizador do Shadow DOM

Faça um teste e depois me conte o que achou.

Modelo de evento

Alguns eventos cruzam o limite das sombras e outros não. Nos casos em que os eventos cruzam o limite, o destino do evento é ajustado para manter o encapsulamento oferecido pelo limite superior da raiz paralela. Ou seja, os eventos são segmentados novamente para parecer que vieram do elemento host, e não de elementos internos para o Shadow DOM.

Observação : acesse event.path para conferir o caminho do evento ajustado.

Ação do jogo 1

• Este é interessante. Você verá um mouseout do elemento host (<div data-host>) para o nó azul. Mesmo sendo um nó distribuído, ele ainda está no host, não no ShadowDOM. Mover o mouse para baixo para amarelo novamente causa uma mouseout no nó azul.

Jogar ação 2

• Há um mouseout que aparece no host (no final). Normalmente, os eventos mouseout são acionados para todos os blocos amarelos. No entanto, nesse caso, esses elementos são internos ao Shadow DOM e o evento não passa pelo limite superior.

Jogar ação 3

• Quando você clica na entrada, o focusin não aparece na entrada, mas no próprio nó do host. Ele foi atacado de novo!

Eventos que são sempre interrompidos

Os eventos a seguir nunca cruzam o limite das sombras:

• cancel
• error
• select
• alterar
• autoinfligida
• redefinir
• resize
• scroll
• selectstart

Conclusão

Espero que você concorde que o Shadow DOM é incrivelmente eficiente. Pela primeira vez, temos o encapsulamento adequado, sem a bagagem extra de <iframe>s ou outras técnicas mais antigas.

O Shadow DOM é certamente ainda mais complexo, mas vale a pena adicioná-lo à plataforma da Web. Passe algum tempo com ele. Aprenda. Faça perguntas.

Para saber mais, consulte o artigo de introdução Shadow DOM 101 de Dominic e o artigo Shadow DOM 201: CSS e estilo.