Декларативный Shadow DOM

Традиционный теневой DOM создаётся с помощью JavaScript (attachShadow). Для страниц, отображаемых на сервере, это означает, что теневое дерево остаётся пустым до запуска JS — и тем самым сводит на нет цель SSR: передать полный HTML уже в первом байте. Декларативный теневой DOM решает эту проблему.

Элемент <template> с shadowrootmode="open" объявляет теневой корень в HTML во время разбора. Браузер автоматически присоединяет теневой корень к родительскому элементу, а содержимое шаблона становится теневым деревом. JavaScript не требуется.

Декларативный теневой DOM обеспечивает полноценный рендеринг веб-компонентов на сервере: сервер встраивает всё теневое дерево в страницу, браузер разбирает и присоединяет его до выполнения какого-либо JS, а JS для гидратации может продолжить работу с уже полностью отображённой основы. Веб-компоненты получают те же возможности, что и SSR фреймворков.

Используются те же режимы, что и для императивного attachShadow: shadowrootmode="open" предоставляет доступ к теневому корню через element.shadowRoot, а shadowrootmode="closed" скрывает его. Поведение идентично соответствующей версии, подключаемой через JavaScript.

Браузер присоединяет теневой корень, когда впервые встречает элемент <template shadowrootmode>. После присоединения шаблон используется — последующий запрос к нему ничего не возвращает. Это соответствует жизненному циклу attachShadow: теневой корень существует столько же, сколько и элемент.

Дочерние элементы основного DOM — <p> за пределами <template> в примере — проецируются в элементы <slot> внутри теневого дерева, как и при императивном использовании теневого DOM. Принцип композиции тот же, различается только механизм присоединения.

Если <my-card> — зарегистрированный пользовательский элемент, процесс его обновления использует уже присоединённый теневой корень, а не вызывает attachShadow повторно. Класс пользовательского элемента может прочитать this.shadowRoot в своём connectedCallback, не создавая теневой корень.

Lit-html с помощью render, компоненты Astro и несколько других фреймворков теперь добавляют декларативный теневой DOM в результат SSR. Самостоятельная реализация тоже возможна: любая система шаблонов на основе строк может записывать шаблон с атрибутом режима теневого корня.

Декларативный теневой DOM поддерживается в Chrome, Edge, Safari и Firefox. Старые браузеры молча игнорируют элемент <template> — содержимое внутри шаблона остаётся невидимым, что обеспечивает корректное постепенное ухудшение для сред без поддержки.

Для более широкой поддержки небольшой скрипт может обойти DOM и преобразовать шаблоны с атрибутом режима теневого корня в настоящие теневые корни. Запускайте его до регистрации пользовательских элементов, чтобы последующие обновления компонентов увидели ожидаемое теневое дерево.

Декларативный теневой DOM дублирует структуру: содержимое <template> находится в HTML, хотя оно также встроено в класс компонента. На страницах с большим количеством одинаковых компонентов это увеличивает объём передаваемых данных. Фреймворки устраняют дублирование; самостоятельной реализации SSR может понадобиться делать то же самое.

Если вы создаёте веб-компоненты и заботитесь об отображении с первого байта или о поисковой оптимизации, внедряйте эту возможность уже сейчас. Она стабильна, поддерживается браузерами и значительно улучшает SSR для приложений на основе веб-компонентов. Для приложений без теневого DOM она неприменима.

Какую проблему решает декларативный теневой DOM по сравнению с императивным attachShadow?

Декларативный теневой DOM использует <template shadowrootmode="open"> внутри пользовательского элемента, чтобы присоединить теневой корень во время разбора; JS не требуется. Это обеспечивает настоящий SSR для веб-компонентов: теневое дерево, изолированные стили и слоты работают ещё до гидратации. Возможность поддерживается всеми современными браузерами; для старых доступен полифилл. Фреймворки Lit и Astro добавляют её автоматически.