Halaman ini diterjemahkan oleh Cloud Translation API.

DOM Bayangan Deklaratif

Cara baru untuk mengimplementasikan dan menggunakan Shadow DOM secara langsung di HTML.

Jason Miller

Mason Freed

Shadow DOM deklaratif adalah fitur platform web standar, yang telah didukung di Chrome versi 90. Perhatikan bahwa spesifikasi untuk fitur ini berubah pada tahun 2023 (termasuk penggantian nama shadowroot menjadi shadowrootmode), dan versi standar terbaru dari semua bagian fitur yang hadir di Chrome versi 124.

Shadow DOM adalah salah satu dari tiga standar Komponen Web, yang dilengkapi dengan template HTML dan Elemen Kustom. Shadow DOM menyediakan cara untuk mencakup gaya CSS ke subhierarki DOM tertentu dan mengisolasi subpohon tersebut dari bagian lain dokumen. Elemen <slot> memberi kita cara untuk mengontrol tempat turunan Custom Element harus disisipkan dalam Shadow Tree-nya. Kombinasi fitur-fitur ini memungkinkan sistem untuk membuat komponen mandiri dan dapat digunakan kembali yang terintegrasi secara lancar ke aplikasi yang ada seperti elemen HTML bawaan.

Sampai sekarang, satu-satunya cara untuk menggunakan Shadow DOM adalah dengan membangun akar bayangan menggunakan JavaScript:

const host = document.getElementById('host');
const shadowRoot = host.attachShadow({mode: 'open'});
shadowRoot.innerHTML = '<h1>Hello Shadow DOM</h1>';

API imperatif seperti ini berfungsi dengan baik untuk rendering sisi klien: modul JavaScript yang sama yang menentukan Elemen Kustom juga membuat Root Bayangan dan menyetel kontennya. Namun, banyak aplikasi web perlu merender konten sisi server atau HTML statis pada waktu build. Hal ini dapat menjadi bagian penting dalam memberikan pengalaman yang wajar kepada pengunjung yang mungkin tidak mampu menjalankan JavaScript.

Justifikasi untuk Rendering Sisi Server (SSR) bervariasi dari satu project ke project lainnya. Beberapa situs harus menyediakan HTML yang dirender server yang berfungsi penuh untuk memenuhi panduan aksesibilitas, situs yang lain memilih untuk memberikan pengalaman tanpa JavaScript dasar sebagai cara untuk menjamin performa yang baik pada koneksi atau perangkat yang lambat.

Secara historis, sulit untuk menggunakan Shadow DOM yang dikombinasikan dengan Rendering Sisi Server karena tidak ada cara bawaan untuk mengekspresikan Shadow Roots dalam HTML yang dihasilkan server. Ada juga implikasi performa saat melampirkan Root Bayangan ke elemen DOM yang telah dirender tanpanya. Hal ini dapat menyebabkan pergeseran tata letak setelah halaman dimuat, atau untuk sementara menampilkan flash konten tanpa gaya ("FOUC") saat memuat stylesheet Shadow Root.

Declarative Shadow DOM (DSD) menghapus batasan ini, yang menghadirkan Shadow DOM ke server.

Membangun Root Bayangan Declaratif

Root Bayangan Declaratif adalah elemen <template> dengan atribut shadowrootmode:

<host-element>
  <template shadowrootmode="open">
    <slot></slot>
  </template>
  <h2>Light content</h2>
</host-element>

Elemen template dengan atribut shadowrootmode terdeteksi oleh parser HTML dan segera diterapkan sebagai root bayangan dari elemen induknya. Memuat markup HTML murni dari contoh di atas hasil dalam hierarki DOM berikut:

<host-element>
  #shadow-root (open)
  <slot>
    ↳
    <h2>Light content</h2>
  </slot>
</host-element>

Contoh kode ini mengikuti konvensi panel Elemen Chrome DevTools untuk menampilkan konten Shadow DOM. Misalnya, karakter ↳ mewakili konten Light DOM yang ditempatkan.

Ini memberi kita manfaat dari enkapsulasi dan proyeksi slot Shadow DOM di HTML statis. JavaScript tidak diperlukan untuk menghasilkan seluruh pohon, termasuk Shadow Root.

Hidrasi komponen

Shadow DOM deklaratif dapat digunakan sendiri sebagai cara untuk mengenkapsulasi gaya atau menyesuaikan penempatan turunan, tetapi paling efektif saat digunakan dengan Elemen Kustom. Komponen yang dibuat menggunakan Elemen Kustom akan diupgrade secara otomatis dari HTML statis. Dengan diperkenalkannya Shadow DOM Declarative, sekarang Anda dapat membuat shadow root pada Elemen Kustom sebelum diupgrade.

Elemen Kustom yang diupgrade dari HTML yang menyertakan Root Bayangan Delaratif sudah akan menyertakan root bayangan tersebut. Ini berarti elemen akan memiliki properti shadowRoot yang sudah tersedia saat instance-nya dibuat, tanpa kode Anda secara eksplisit membuatnya. Sebaiknya periksa this.shadowRoot untuk root bayangan yang ada di konstruktor elemen Anda. Jika sudah ada nilai, HTML untuk komponen ini akan menyertakan Root Bayangan Declaratif. Jika nilainya null, berarti tidak ada Root Bayangan Declaratif di HTML atau browser tidak mendukung Shadow DOM Declarative.

<menu-toggle>
  <template shadowrootmode="open">
    <button>
      <slot></slot>
    </button>
  </template>
  Open Menu
</menu-toggle>
<script>
  class MenuToggle extends HTMLElement {
    constructor() {
      super();

      // Detect whether we have SSR content already:
      if (this.shadowRoot) {
        // A Declarative Shadow Root exists!
        // wire up event listeners, references, etc.:
        const button = this.shadowRoot.firstElementChild;
        button.addEventListener('click', toggle);
      } else {
        // A Declarative Shadow Root doesn't exist.
        // Create a new shadow root and populate it:
        const shadow = this.attachShadow({mode: 'open'});
        shadow.innerHTML = `<button><slot></slot></button>`;
        shadow.firstChild.addEventListener('click', toggle);
      }
    }
  }

  customElements.define('menu-toggle', MenuToggle);
</script>

Elemen Kustom telah lama ada, dan sampai sekarang tidak ada alasan untuk memeriksa root bayangan yang sudah ada sebelum membuatnya menggunakan attachShadow(). Shadow DOM deklaratif menyertakan perubahan kecil yang memungkinkan komponen yang ada untuk berfungsi meskipun demikian: memanggil metode attachShadow() pada elemen dengan Root Bayangan Declarative yang ada tidak akan memunculkan error. Sebagai gantinya, Shadow Root Declarative dikosongkan dan ditampilkan. Hal ini memungkinkan komponen lama yang tidak dibangun untuk Shadow DOM deklaratif terus berfungsi, karena root deklaratif dipertahankan hingga penggantian imperatif dibuat.

Untuk Elemen Kustom yang baru dibuat, properti ElementInternals.shadowRoot baru menyediakan cara eksplisit untuk mendapatkan referensi ke Root Bayangan deklaratif yang ada pada elemen, baik terbuka maupun tertutup. Ini dapat digunakan untuk memeriksa dan menggunakan Root Bayangan deklaratif apa pun, sambil tetap melakukan fallback ke attachShadow() jika tidak disediakan.

class MenuToggle extends HTMLElement {
  constructor() {
    super();

    const internals = this.attachInternals();

    // check for a Declarative Shadow Root:
    let shadow = internals.shadowRoot;
    if (!shadow) {
      // there wasn't one. create a new Shadow Root:
      shadow = this.attachShadow({
        mode: 'open'
      });
      shadow.innerHTML = `<button><slot></slot></button>`;
    }

    // in either case, wire up our event listener:
    shadow.firstChild.addEventListener('click', toggle);
  }
}
customElements.define('menu-toggle', MenuToggle);

Satu bayangan per root

Root Bayangan Declaratif hanya terkait dengan elemen induknya. Ini berarti root bayangan selalu ditempatkan bersama dengan elemen terkaitnya. Keputusan desain ini memastikan shadow root dapat di-streaming seperti dokumen HTML lainnya. Cara ini juga mudah untuk pembuatan dan pembuatan, karena menambahkan root bayangan ke elemen tidak memerlukan pemeliharaan registry dari shadow root yang sudah ada.

Efek dari mengaitkan root bayangan dengan elemen induknya adalah tidak mungkin bagi beberapa elemen untuk diinisialisasi dari <template> Root Bayangan Deklaratif yang sama. Namun, hal ini mungkin tidak penting dalam sebagian besar kasus ketika Shadow DOM deklaratif digunakan, karena konten dari setiap shadow root jarang identik. Meskipun HTML yang dirender oleh server sering berisi struktur elemen berulang, kontennya umumnya berbeda, misalnya, sedikit variasi dalam teks atau atribut. Karena konten Root Bayangan Delaratif serial sepenuhnya statis, mengupgrade beberapa elemen dari satu Root Bayangan Deklaratif hanya akan berfungsi jika elemen itu kebetulan identik. Terakhir, dampak root bayangan serupa yang berulang pada ukuran transfer jaringan relatif kecil karena efek kompresi.

Di masa mendatang, Anda dapat mengunjungi kembali root bayangan bersama. Jika DOM mendapatkan dukungan untuk template bawaan, Shadow Root deklaratif dapat diperlakukan sebagai template yang dibuat instance-nya guna membuat shadow root untuk elemen tertentu. Desain DOM Bayangan Deklarasi saat ini memungkinkan kemungkinan ini ada di masa mendatang dengan membatasi pengaitan root bayangan ke satu elemen.

Streamingnya keren

Mengaitkan Shadow Root Declarative secara langsung dengan elemen induknya akan menyederhanakan proses upgrade dan melampirkannya ke elemen tersebut. Shadow Roots deklaratif terdeteksi selama penguraian HTML, dan langsung dilampirkan saat tag <template> pembuka ditemukan. HTML yang telah diurai dalam <template> diuraikan langsung menjadi root bayangan, sehingga dapat "di-streaming": dirender saat diterima.

<div id="el">
  <script>
    el.shadowRoot; // null
  </script>

  <template shadowrootmode="open">
    <!-- shadow realm -->
  </template>

  <script>
    el.shadowRoot; // ShadowRoot
  </script>
</div>

Khusus parser

Shadow DOM deklaratif adalah fitur parser HTML. Ini berarti bahwa Root Bayangan Declaratif hanya akan diuraikan dan dilampirkan untuk tag <template> dengan atribut shadowrootmode yang ada selama penguraian HTML. Dengan kata lain, Root Bayangan deklaratif dapat dibuat selama penguraian HTML awal:

<some-element>
  <template shadowrootmode="open">
    shadow root content for some-element
  </template>
</some-element>

Menetapkan atribut shadowrootmode dari elemen <template> tidak akan melakukan apa pun, dan template tetap merupakan elemen template biasa:

const div = document.createElement('div');
const template = document.createElement('template');
template.setAttribute('shadowrootmode', 'open'); // this does nothing
div.appendChild(template);
div.shadowRoot; // null

Untuk menghindari beberapa pertimbangan keamanan yang penting, Shadow Root deklaratif juga tidak dapat dibuat menggunakan API penguraian fragmen seperti innerHTML atau insertAdjacentHTML(). Satu-satunya cara untuk mengurai HTML dengan menerapkan Root Bayangan Declaratif adalah dengan menggunakan setHTMLUnsafe() atau parseHTMLUnsafe():

<script>
  const html = `
    <div>
      <template shadowrootmode="open"></template>
    </div>
  `;
  const div = document.createElement('div');
  div.innerHTML = html; // No shadow root here
  div.setHTMLUnsafe(html); // Shadow roots included
  const newDocument = Document.parseHTMLUnsafe(html); // Also here
</script>

Rendering server dengan gaya

Stylesheet inline dan eksternal didukung sepenuhnya di dalam Root Bayangan deklaratif menggunakan tag <style> dan <link> standar:

<nineties-button>
  <template shadowrootmode="open">
    <style>
      button {
        color: seagreen;
      }
    </style>
    <link rel="stylesheet" href="/comicsans.css" />
    <button>
      <slot></slot>
    </button>
  </template>
  I'm Blue
</nineties-button>

Gaya yang ditentukan dengan cara ini juga sangat dioptimalkan: jika stylesheet yang sama ada di beberapa Root Bayangan Deklaratif, gaya tersebut hanya dimuat dan diuraikan sekali. Browser menggunakan CSSStyleSheet pendukung tunggal yang digunakan bersama oleh semua shadow root, sehingga menghilangkan overhead memori duplikat.

Stylesheet yang Dapat Dibangun tidak didukung dalam Shadow DOM Declarative. Hal ini karena saat ini tidak ada cara untuk membuat serialisasi stylesheet yang dapat dibuat di HTML, dan tidak ada cara untuk merujuknya saat mengisi adoptedStyleSheets.

Menghindari flash konten tanpa gaya

Salah satu potensi masalah di browser yang belum mendukung Shadow DOM Declarative adalah menghindari "flash of unstyled content" (FOUC), tempat konten mentah ditampilkan untuk Elemen Kustom yang belum diupgrade. Sebelum Shadow DOM deklaratif, salah satu teknik umum untuk menghindari FOUC adalah dengan menerapkan aturan gaya display:none ke Elemen Kustom yang belum dimuat, karena shadow root ini belum dilampirkan dan diisi. Dengan demikian, konten tidak akan ditampilkan hingga statusnya "siap":

<style>
  x-foo:not(:defined) > * {
    display: none;
  }
</style>

Dengan diperkenalkannya Shadow DOM deklaratif, Elemen Kustom dapat dirender atau ditulis dalam HTML sedemikian rupa sehingga konten bayangannya berada di tempatnya dan siap sebelum implementasi komponen sisi klien dimuat:

<x-foo>
  <template shadowrootmode="open">
    <style>h2 { color: blue; }</style>
    <h2>shadow content</h2>
  </template>
</x-foo>

Dalam hal ini, aturan display:none "FOUC" akan mencegah konten shadow root deklaratif ditampilkan. Namun, menghapus aturan tersebut akan menyebabkan browser tanpa dukungan Shadow DOM Delaratif menampilkan konten yang salah atau tanpa gaya hingga polyfill Shadow DOM deklaratif dimuat dan mengonversi template root bayangan menjadi root bayangan sungguhan.

Untungnya, hal ini dapat diatasi dalam CSS dengan memodifikasi aturan gaya FOUC. Pada browser yang mendukung Shadow DOM Declarative, elemen <template shadowrootmode> langsung dikonversi menjadi shadow root, tanpa membiarkan elemen <template> di hierarki DOM. Browser yang tidak mendukung Shadow DOM deklaratif mempertahankan elemen <template>, yang dapat kita gunakan untuk mencegah FOUC:

<style>
  x-foo:not(:defined) > template[shadowrootmode] ~ *  {
    display: none;
  }
</style>

Aturan "FOUC" yang direvisi menyembunyikan turunan saat mengikuti elemen <template shadowrootmode>, bukan menyembunyikan Elemen Kustom yang belum ditetapkan. Setelah Elemen Khusus ditentukan, aturan tidak lagi cocok. Aturan ini diabaikan di browser yang mendukung Shadow DOM deklaratif karena turunan <template shadowrootmode> dihapus selama penguraian HTML.

Deteksi fitur dan dukungan browser

Shadow DOM deklaratif telah tersedia sejak Chrome 90 dan Edge 91, tetapi menggunakan atribut non-standar lama yang disebut shadowroot, bukan atribut shadowrootmode standar. Atribut shadowrootmode dan perilaku streaming yang lebih baru tersedia di Chrome 111 dan Edge 111.

Sebagai API platform web baru, Shadow DOM Declarative belum mendapatkan dukungan luas di semua browser. Dukungan browser dapat dideteksi dengan memeriksa keberadaan properti shadowRootMode di prototipe HTMLTemplateElement:

function supportsDeclarativeShadowDOM() {
  return HTMLTemplateElement.prototype.hasOwnProperty('shadowRootMode');
}

Polyfill

Membangun polyfill yang disederhanakan untuk Shadow DOM deklaratif relatif mudah, karena polyfill tidak perlu mereplikasi semantik pengaturan waktu atau karakteristik khusus parser secara sempurna yang terkait dengan implementasi browser. Untuk mem-polyfill Declarative Shadow DOM, kita dapat memindai DOM untuk menemukan semua elemen <template shadowrootmode>, lalu mengonversinya menjadi Shadow Roots yang terpasang pada elemen induknya. Proses ini dapat dilakukan setelah dokumen siap, atau dipicu oleh peristiwa yang lebih spesifik, seperti siklus proses Elemen Kustom.

(function attachShadowRoots(root) {
  root.querySelectorAll("template[shadowrootmode]").forEach(template => {
    const mode = template.getAttribute("shadowrootmode");
    const shadowRoot = template.parentNode.attachShadow({ mode });
    shadowRoot.appendChild(template.content);
    template.remove();
    attachShadowRoots(shadowRoot);
  });
})(document);