Веб-компоненты: пользовательские элементы, shadow DOM и границы инкапсуляции

Что это такое

Веб-компоненты состоят из трёх возможностей браузера. Пользовательские элементы: класс, расширяющий HTMLElement, регистрируется через customElements.define("x-name", Class) (имя должно содержать дефис) и имеет обратные вызовы connectedCallback, disconnectedCallback и attributeChangedCallback для атрибутов из статического массива observedAttributes. Shadow DOM: attachShadow({ mode: "open" }) даёт элементу собственное поддерево; MDN указывает, что внутренние стили ограничены этим деревом, поэтому стили страницы не влияют на теневые элементы, а теневые стили — на страницу; <slot> проецирует в него дочерние элементы light DOM. Шаблоны: <template> хранит неактивную разметку, а <template shadowrootmode="open"> объявляет теневой корень в HTML, сформированном сервером, без скрипта.

Почему это важно

Пользовательские элементы — единственная модель компонентов, которую понимает сам браузер: они работают с любым фреймворком или без него, переживают миграции между фреймворками и применимы из обычного HTML, сформированного сервером. Цена — настоящая инкапсуляция: каждая задача, пересекающая границу (темы, формы, подписи, фокус, события), требует явного открытия доступа.

Как применять

• Явно предоставляйте возможности стилизации: пользовательские свойства для значений (они наследуются внутрь теневого дерева) и part="label" на внутренних элементах, чтобы страница могла использовать x-name::part(label); MDN описывает part как средство сделать теневой элемент видимым родительскому DOM.
• Сделайте элементы управления полноценными участниками форм с помощью static formAssociated = true и ElementInternals (setFormValue, setValidity); без этого пользовательское поле ввода никогда не отправляет значение.
• Предпочитайте автономные элементы; MDN отмечает, что Safari не планирует поддерживать настроенные встроенные элементы (is="...").
• Отрисовывайте начальное состояние декларативным shadow DOM, когда важны первое отображение или поисковые роботы, затем подключайте реализацию класса.
• Отражайте важное состояние в атрибутах, чтобы CSS и тесты могли выбирать по ним; сохраняйте mode: "open" (по MDN, закрытый режим — не сильный механизм безопасности, а лишь сигнал).
• Оформите x-name:not(:defined) для времени до запуска скрипта, чтобы содержимое не скакало при подключении реализации.

Типичные ошибки

Ссылки по ID не пересекают границу: <label for> или aria-labelledby на странице не могут указывать на поле ввода внутри теневого дерева, поэтому либо вставляйте элемент управления из light DOM через слот, либо задавайте подпись внутри. Глобальные сбросы стилей, утилитарные классы и спрайты значков внутри не действуют. Пользовательским событиям нужен composed: true, чтобы их слышали снаружи. Повторная регистрация одного имени вызывает исключение — проблема, когда два бандла поставляют один компонент. Инструменты разработчика показывают теневое дерево, а document.querySelector — нет.