Sloty a kompozice stínového DOMu

Mnoho druhů komponent, například záložky, menu, obrázkové galerie a podobně, potřebuje vykreslit obsah.

StejnÄ› jako zabudovaná prohlížečová značka <select> očekává položky <option>, naÅ¡e <vlastni-zalozky> mohou očekávat, že do nich bude pÅ™edán skutečný obsah záložek. A <vlastni-menu> může očekávat položky menu.

Kód, který využívá <vlastni-menu>, může vypadat následovnÄ›:

<vlastni-menu>
  <title>Nabídka sladkostí</title>
  <item>Lízátko</item>
  <item>Ovocný toast</item>
  <item>Košíčky</item>
</vlastni-menu>

…Pak by je naše komponenta měla správně vykreslit jako pěkné menu se zadaným titulkem a položkami, zpracovávat události menu a tak dále.

Jak to implementovat?

Můžeme se pokusit analyzovat obsah elementu a dynamicky zkopírovat a přeskládat DOM uzly. To je možné, ale když budeme přesunovat elementy do stínového DOMu, nebudou se v nich aplikovat CSS styly z dokumentu, takže můžeme ztratit vizuální stylizaci. Navíc to vyžaduje napsat nějaký ten kód.

NaÅ¡tÄ›stí to nemusíme dÄ›lat. Stínový DOM podporuje elementy <slot>, které se automaticky naplní obsahem ze svÄ›tlého DOMu.

Pojmenované sloty

Na jednoduchém příkladu se podívejme, jak sloty fungují.

Zde stínový DOM značky <karta-uzivatele> poskytuje dva sloty, naplňované ze svÄ›tlého DOMu:

<script>
customElements.define('karta-uzivatele', class extends HTMLElement {
  connectedCallback() {
    this.attachShadow({mode: 'open'});
    this.shadowRoot.innerHTML = `
      <div>Jméno:
        <slot name="uživatel"></slot>
      </div>
      <div>Datum narození:
        <slot name="narození"></slot>
      </div>
    `;
  }
});
</script>

<karta-uzivatele>
  <span slot="uživatel">Jan Novák</span>
  <span slot="narození">01.01.2001</span>
</karta-uzivatele>

Ve stínovém DOMu <slot name="X"> definuje „bod vložení“, místo, kam budou vykresleny elementy obsahující slot="X".

Prohlížeč pak provede „kompozici“: vezme elementy ze světlého DOMu a vykreslí je do odpovídajících slotů stínového DOMu. Na konci budeme mít přesně to, co jsme chtěli – komponentu, která může být vyplněna daty.

Zde je struktura DOMu po provedení skriptu, nebereme-li v úvahu kompozici:

<karta-uzivatele>
  #shadow-root
    <div>Jméno:
      <slot name="uživatel"></slot>
    </div>
    <div>Datum narození:
      <slot name="narození"></slot>
    </div>
  <span slot="uživatel">Jan Novák</span>
  <span slot="narození">01.01.2001</span>
</karta-uzivatele>

VytvoÅ™ili jsme stínový DOM, takže je zde pod #shadow-root. Nyní element obsahuje svÄ›tlý i stínový DOM.

Pro účely vykreslení prohlížeč pro každou značku <slot name="..."> ve stínovém DOMu vyhledá slot="..." se stejným názvem ve svÄ›tlém DOMu. Tyto elementy jsou vykresleny do slotů:

Výsledek se nazývá „zploštělý“ (flattened) DOM:

<karta-uzivatele>
  #shadow-root
    <div>Jméno:
      <slot name="uživatel">
        <!-- do slotu je vložen element se slotem -->
        <span slot="uživatel">Jan Novák</span>
      </slot>
    </div>
    <div>Datum narození:
      <slot name="narození">
        <span slot="narození">01.01.2001</span>
      </slot>
    </div>
</karta-uzivatele>

…Zploštělý DOM však existuje výhradně pro účely vykreslování a zpracování událostí. Je svým způsobem „virtuální“. Je to způsob, jak se vše zobrazuje. Ale ve skutečnosti nejsou uzly v dokumentu přesunuty!

To si můžeme snadno zkontrolovat, jestliže spustíme querySelectorAll: uzly budou stále na svých místech.

// uzly <span> světlého DOMu jsou stále na stejných místech, pod `<karta-uzivatele>`
alert( document.querySelectorAll('karta-uzivatele span').length ); // 2

Zploštělý DOM je tedy odvozen ze stínového DOMu vložením slotů. Prohlížeč jej vykreslí a použije pro zdědění stylů a propagaci událostí (více o tom později). JavaScript však stále vidí dokument tak, „jak je“, před zploštěním.

<karta-uzivatele>
  <span slot="uživatel">Jan Novák</span>
  <div>
    <!-- nesprávný slot, musí být přímým dítětem elementu karta-uzivatele -->
    <span slot="narození">01.01.2001</span>
  </div>
</karta-uzivatele>

Pokud je ve světlém DOMu více elementů se stejným názvem slotu, budou vloženy do slotu jeden po druhém.

Například tohle:

<karta-uzivatele>
  <span slot="uživatel">Jan</span>
  <span slot="uživatel">Novák</span>
</karta-uzivatele>

vydá následující zploÅ¡tÄ›lý DOM se dvÄ›ma elementy ve <slot name="uživatel">:

<karta-uzivatele>
  #shadow-root
    <div>Jméno:
      <slot name="uživatel">
        <span slot="uživatel">Jan</span>
        <span slot="uživatel">Novák</span>
      </slot>
    </div>
    <div>Datum narození:
      <slot name="narození"></slot>
    </div>
</karta-uzivatele>

Záložní obsah slotu

Pokud vložíme nÄ›co do značky <slot>, stane se to záložním, „standardním“ obsahem. Prohlížeč to zobrazí, jestliže svÄ›tlý DOM nebude obsahovat odpovídající náplň.

Například v tomto kousku stínového DOMu se zobrazí Anonym, jestliže ve svÄ›tlém DOMu nebude žádný slot="uživatel".

<div>Jméno:
  <slot name="uživatel">Anonym</slot>
</div>

Standardní slot: první nepojmenovaný

První <slot> ve stínovém DOMu, který nemá žádný název, je „standardní“ slot. Získá vÅ¡echny uzly ze svÄ›tlého DOMu, které nejsou vloženy do jiného slotu.

PÅ™idejme například do naÅ¡eho elementu <karta-uzivatele> standardní slot, který zobrazí vÅ¡echny informace o uživateli, které nebyly vloženy do slotů:

<script>
customElements.define('karta-uzivatele', class extends HTMLElement {
  connectedCallback() {
    this.attachShadow({mode: 'open'});
    this.shadowRoot.innerHTML = `
    <div>Jméno:
      <slot name="uživatel"></slot>
    </div>
    <div>Datum narození:
      <slot name="narození"></slot>
    </div>
    <fieldset>
      <legend>Další informace</legend>
      <slot></slot>
    </fieldset>
    `;
  }
});
</script>

<karta-uzivatele>
  <div>Rád plavu.</div>
  <span slot="uživatel">Jan Novák</span>
  <span slot="narození">01.01.2001</span>
  <div>...A taky hraji volejbal!</div>
</karta-uzivatele>

Veškerý obsah světlého DOMu, který nebyl vložen do slotů, se dostane do sady polí „Další informace“.

Elementy se do slotu vkládají jeden za druhým, takže oba nevložené kousky informace budou společně ve standardním slotu.

Zploštělý DOM vypadá následovně:

<karta-uzivatele>
  #shadow-root
    <div>Name:
      <slot name="uživatel">
        <span slot="uživatel">Jan Novák</span>
      </slot>
    </div>
    <div>Datum narození:
      <slot name="narození">
        <span slot="narození">01.01.2001</span>
      </slot>
    </div>
    <fieldset>
      <legend>Další informace</legend>
      <slot>
        <div>Rád plavu.</div>
        <div>...A taky hraji volejbal!</div>
      </slot>
    </fieldset>
</karta-uzivatele>

Příklad menu

Nyní se vraÅ¥me k <vlastni-menu>, zmínÄ›nému na začátku kapitoly.

K předání elementů můžeme použít sloty.

Zde je kód pro <vlastni-menu>:

<vlastni-menu>
  <span slot="titulek">Nabídka sladkostí</span>
  <li slot="položka">Lízátko</li>
  <li slot="položka">Ovocný toast</li>
  <li slot="položka">Košíčky</li>
</vlastni-menu>

Šablona stínového DOMu s příslušnými sloty:

<template id="Å¡ablona">
  <style> /* styly menu */ </style>
  <div class="menu">
    <slot name="titulek"></slot>
    <ul><slot name="položka"></slot></ul>
  </div>
</template>

1. <span slot="titulek"> bude vložen do <slot name="titulek">.
2. V elementu <vlastni-menu> je mnoho položek <li slot="položka">, ale v Å¡ablonÄ› je jen jedna <slot name="položka">. VÅ¡echny tyto elementy <li slot="položka"> se tedy vloží do <slot name="položka"> jeden po druhém, čímž vytvoří seznam.

Zploštělý DOM bude vypadat takto:

<vlastni-menu>
  #shadow-root
    <style> /* styly menu */ </style>
    <div class="menu">
      <slot name="titulek">
        <span slot="titulek">Nabídka sladkostí</span>
      </slot>
      <ul>
        <slot name="položka">
          <li slot="položka">Lízátko</li>
          <li slot="položka">Ovocný toast</li>
          <li slot="položka">Košíčky</li>
        </slot>
      </ul>
    </div>
</vlastni-menu>

Můžeme si vÅ¡imnout, že v platném DOMu <li> musí být přímým dítÄ›tem <ul>, ale tohle je zploÅ¡tÄ›lý DOM, který popisuje, jak budou komponenty vykresleny, takže takové vÄ›ci se tady běžnÄ› stávají.

PotÅ™ebujeme už jen pÅ™idat handler click k otevÅ™ení a zavÅ™ení seznamu a <vlastni-menu> je hotové:

customElements.define('vlastni-menu', class extends HTMLElement {
  connectedCallback() {
    this.attachShadow({mode: 'open'});

    // šablona je šablona stínového DOMu (výše)
    this.shadowRoot.append( Å¡ablona.content.cloneNode(true) );

    // nemůžeme vybírat uzly světlého DOMu, takže budeme zpracovávat kliknutí na slot
    this.shadowRoot.querySelector('slot[name="titulek"]').onclick = () => {
      // otevře/zavře menu
      this.shadowRoot.querySelector('.menu').classList.toggle('closed');
    };
  }
});

Zde je celá ukázka:

Samozřejmě do ní můžeme přidávat další funkcionalitu: události, metody a podobně.

Aktualizace slotů

Co když vnější kód chce dynamicky přidávat a odstraňovat položky menu?

Prohlížeč sleduje sloty a aktualizuje vykreslení, pokud jsou přidány nebo odstraněny elementy do slotů.

Navíc, protože uzly světlého DOMu se nekopírují, ale jen vykreslují do slotů, změny uvnitř nich budou okamžitě viditelné.

Pro aktualizaci vykreslování tedy nemusíme dÄ›lat nic. Jestliže vÅ¡ak kód komponenty chce vÄ›dÄ›t o zmÄ›nách slotů, má k dispozici událost slotchange.

Například zde je po 1 sekundě dynamicky vložena položka menu a po 2 sekundách se změní titulek:

<vlastni-menu id="menu">
  <span slot="titulek">Nabídka sladkostí</span>
</vlastni-menu>

<script>
customElements.define('vlastni-menu', class extends HTMLElement {
  connectedCallback() {
    this.attachShadow({mode: 'open'});
    this.shadowRoot.innerHTML = `<div class="menu">
      <slot name="titulek"></slot>
      <ul><slot name="položka"></slot></ul>
    </div>`;

    // shadowRoot nemůže mít handlery událostí, použijeme tedy první dítě
    this.shadowRoot.firstElementChild.addEventListener('slotchange',
      e => alert("slotchange: " + e.target.name)
    );
  }
});

setTimeout(() => {
  menu.insertAdjacentHTML('beforeEnd', '<li slot="položka">Lízátko</li>')
}, 1000);

setTimeout(() => {
  menu.querySelector('[slot="titulek"]').innerHTML = "Nové menu";
}, 2000);
</script>

Vykreslování menu se pokaždé aktualizuje bez našeho zásahu.

Nastanou tady dvÄ› události slotchange:

1. Při inicializaci:

   slotchange: titulek se spustí okamžitÄ›, když se slot="titulek" ze svÄ›tlého DOMu vloží do přísluÅ¡ného slotu.

2. Po 1 sekundÄ›:

   slotchange: položka se spustí, když je pÅ™idána nová <li slot="položka">.

Prosíme vÅ¡imnÄ›te si, že po 2 sekundách, když se zmÄ›ní obsah slot="titulek", událost slotchange nenastane. Je to proto, že pÅ™i tom nedojde ke zmÄ›nÄ› slotu. Modifikujeme obsah elementu vloženého do slotu, to je nÄ›co jiného.

Kdybychom chtěli v JavaScriptu sledovat vnitřní modifikace světlého DOMu, je to rovněž možné pomocí obecnějšího mechanismu: MutationObserver.

API pro sloty

Na závěr uveďme metody JavaScriptu pro práci se sloty.

Jak jsme již vidÄ›li, JavaScript se dívá na „skutečný“, nezploÅ¡tÄ›lý DOM. Pokud vÅ¡ak stínový strom má {mode: 'open'}, můžeme zjistit, které elementy jsou pÅ™iÅ™azeny do slotu, a naopak, najít slot podle elementu uvnitÅ™ nÄ›j:

• uzel.assignedSlot – vrátí element <slot>, do nÄ›hož je pÅ™iÅ™azen uzel.
• slot.assignedNodes({flatten: true/false}) – DOM uzly, pÅ™iÅ™azené do slotu. Volba flatten je standardnÄ› false. Pokud je výslovnÄ› nastavena na true, metoda se podívá hloubÄ›ji do zploÅ¡tÄ›lého DOMu, v případÄ› vnoÅ™ených komponent vrátí vnoÅ™ené sloty a není-li žádný uzel pÅ™iÅ™azen, vrátí záložní obsah.
• slot.assignedElements({flatten: true/false}) – DOM elementy pÅ™iÅ™azené do slotu (totéž jako pÅ™edchozí metoda, ale jen elementové uzly).

Tyto metody jsou užitečné, když chceme obsah vložený do slotů nejen zobrazovat, ale i zpracovávat v JavaScriptu.

Například jestliže komponenta <vlastni-menu> chce vÄ›dÄ›t, co zobrazuje, může sledovat slotchange a získat položky ze slot.assignedElements:

<vlastni-menu id="menu">
  <span slot="titulek">Nabídka sladkostí</span>
  <li slot="položka">Lízátko</li>
  <li slot="položka">Ovocný toast</li>
</vlastni-menu>

<script>
customElements.define('vlastni-menu', class extends HTMLElement {
  položky = []

  connectedCallback() {
    this.attachShadow({mode: 'open'});
    this.shadowRoot.innerHTML = `<div class="menu">
      <slot name="titulek"></slot>
      <ul><slot name="položka"></slot></ul>
    </div>`;

    // spustí se, když se obsah slotu změní
    this.shadowRoot.firstElementChild.addEventListener('slotchange', e => {
      let slot = e.target;
      if (slot.name == 'položka') {
        this.položky = slot.assignedElements().map(elem => elem.textContent);
        alert("Položky: " + this.položky);
      }
    });
  }
});

// aktualizujeme položky po 1 sekundě
setTimeout(() => {
  menu.insertAdjacentHTML('beforeEnd', '<li slot="položka">Košíčky</li>')
}, 1000);
</script>

Shrnutí

Když element obsahuje stínový DOM, jeho světlý DOM se zpravidla nezobrazí. Sloty umožňují zobrazit elementy ze světlého DOMu na stanovených místech stínového DOMu.

Sloty se dělí do dvou druhů:

• Pojmenované sloty: <slot name="X">...</slot> – obdrží dÄ›ti ze svÄ›tlého DOMu obsahující slot="X".
• Standardní slot: první <slot> bez názvu (další nepojmenované sloty jsou ignorovány) – obdrží dÄ›ti ze svÄ›tlého DOMu nevložené do jiných slotů.
• Pokud pro stejný slot existuje více elementů, budou vloženy jeden za druhým.
• Obsah elementu <slot> se používá jako záloha. Zobrazí se, jestliže pro tento slot nejsou ve svÄ›tlém DOMu žádné dÄ›ti.

Proces vykreslování elementů uvnitř jejich slotů se nazývá „kompozice“. Výsledek se nazývá „zploštělý DOM“.

Kompozice ve skutečnosti nepřesunuje uzly, z pohledu JavaScriptu je DOM stále stejný.

JavaScript může přistupovat ke slotům pomocí těchto metod:

• slot.assignedNodes/Elements() – vrací uzly/elementy uvnitÅ™ slot.
• node.assignedSlot – opačná vlastnost, vrací slot podle uzlu.

Jestliže chceme vědět, co zobrazujeme, můžeme sledovat obsah slotu pomocí:

• událost slotchange – spustí se poprvé, kdy je slot naplnÄ›n, a pÅ™i vÅ¡ech operacích pÅ™idání, odstranÄ›ní a nahrazení elementu ve slotu, ale ne jeho dÄ›tí. Tento slot je v událost.target.
• MutationObserver pro vstup hloubÄ›ji do obsahu slotu a sledování zmÄ›n uvnitÅ™ nÄ›j.

Když teď víme, jak zobrazovat elementy ze světlého DOMu ve stínovém DOMu, podívejme se, jak jim správně nastavit styly. Základní pravidlo zní, že styly stínových elementů se nastavují uvnitř a styly světlých vně, ale existují významné výjimky.

Podrobnosti probereme v příští kapitole.