Настройте пользовательские элементы на взаимодействие с реестрами, имеющими ограниченную область видимости.

Jayson Chen

Patrick Brosset

Опубликовано: 9 марта 2026 г.

Пользовательские элементы позволяют разработчикам веб-приложений создавать, совместно использовать и повторно применять компоненты пользовательского интерфейса с их уникальным поведением, упрощая разработку. Но когда ваше приложение объединяет различные наборы пользовательских элементов, могут возникнуть сложности и конфликты имен. Реестры пользовательских элементов с ограниченной областью видимости решают эту проблему!

Команда Microsoft Edge работала над этой функцией, и мы рады сообщить, что теперь в Edge и Chrome 146, а также в других браузерах на основе Chromium, по умолчанию доступны реестры пользовательских элементов с ограниченной областью видимости. Теперь вы можете инкапсулировать пользовательские элементы, решая давнюю проблему разработчиков компонентов и микрофронтенд-библиотек.

Ограниченные реестры пользовательских элементов открывают важные возможности для веб-разработчиков. Теперь вы можете использовать несколько библиотек пользовательских элементов, разработанных независимо разными командами, или несколько версий одной и той же библиотеки одновременно.

Что такое реестр пользовательских элементов с ограниченной областью действия?

Сегодня каждое определение пользовательского элемента на веб-странице хранится в едином общем реестре по адресу window.customElements . Это означает, что если две разные библиотеки попытаются определить пользовательский элемент с одним и тем же именем тега, например, <my-button> , будет выдана ошибка, и страница перестанет работать. Это серьезная проблема в реальном мире. Крупные приложения, пользовательские интерфейсы которых формируются несколькими командами, системами дизайна или микрофронтендами, могут легко столкнуться с конфликтами имен. Реестры пользовательских элементов с ограниченной областью видимости решают эту проблему, позволяя создавать независимые реестры . Каждый реестр поддерживает свой собственный набор определений пользовательских элементов, полностью изолированный от глобального реестра и друг от друга.

Создайте новый реестр

Вместо того чтобы определять каждый пользовательский элемент в глобальном реестре window.customElements :

1. Создайте новый реестр, вызвав метод new CustomElementRegistry() .
2. Укажите для нового реестра конкретную область действия (см. раздел «Определение области действия реестра»).
3. Определите элементы, которые войдут в новый реестр.

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

Проверьте свой реестр.

Реестр пользовательских элементов может быть ограничен либо документом, либо теневым корневым элементом, либо отдельным элементом.

Область видимости для теневого корня

Чтобы ограничить область действия нового реестра корневым теневым элементом, используйте параметр customElementRegistry при вызове метода attachShadow() . Все пользовательские элементы, находящиеся внутри этого корневого теневого элемента, теперь будут использовать определение, содержащееся в соответствующем реестре с заданной областью действия:

// Create your custom registry.
const registry = new CustomElementRegistry();
// Define a custom element in the new registry.
registry.define('my-card', class extends HTMLElement {
  connectedCallback() {
    this.textContent = 'Hello from scoped registry!';
  }
});

// Create shadow root, providing it with your new custom element registry.
const host = document.querySelector('#host');
const shadow = host.attachShadow({
  mode: 'open',
  customElementRegistry: registry,
});

shadow.innerHTML = '<my-card></my-card>';

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

Используйте атрибут shadowrootcustomelementregistry для элемента <template> , чтобы сообщить браузеру, что результирующий теневой корень использует реестр с ограниченной областью видимости, а не глобальный:

<my-host>
  <template shadowrootmode="open" shadowrootcustomelementregistry>
    <my-widget></my-widget>
  </template>
</my-host>

  const registry = new CustomElementRegistry();
  registry.define('my-widget', class extends HTMLElement {
    connectedCallback() { this.textContent = 'Scoped!'; }
  });

  const shadow = document.querySelector('my-host').shadowRoot;
  registry.initialize(shadow);

Как показано в примере, атрибут резервирует место для реестра пользовательских элементов, и пользователю необходимо определить и инициализировать реестр для теневого корня. Область видимости ограничена несвязанным документом.

Вы также можете ограничить область действия реестра документом, например, созданным с помощью document.implementation.createHTMLDocument() . Это позволяет клонировать элементы <template> и выполнять манипуляции с документом вне экрана, каждый со своим собственным изолированным набором определений компонентов. Для этого используйте метод CustomElementRegistry.initialize() :

// Create a new registry.
const registry = new CustomElementRegistry();
registry.define('app-widget', AppWidget);

// Create a document, and use registry.initialize() to scope the registry to the document.
const doc = document.implementation.createHTMLDocument('');
registry.initialize(doc);

doc.body.innerHTML = '<app-widget></app-widget>';

Область применения к отдельному элементу

Вы также можете напрямую связать реестр с элементом и его поддеревом, передав параметр customElementRegistry методу document.createElement() . Элемент и его потомки будут обращаться к этому реестру независимо от того, в какую часть DOM они будут впоследствии вставлены:

// Create a registry and define a custom element in it.
const registry = new CustomElementRegistry();
registry.define('fancy-label', FancyLabel);

// Create a new DOM element and scope the new registry to it.
const el = document.createElement('fancy-input', {
  customElementRegistry: registry,
});

// Use a custom element in the new DOM element.
el.innerHTML = '<fancy-label>Name</fancy-label>';

Узнать больше

Чтобы узнать больше, ознакомьтесь с демонстрацией Edge и ее исходным кодом , а также прочтите справочную статью MDN о CustomElementRegistry.

Благодаря нашему сотрудничеству в рамках проекта Chromium, теперь в Microsoft Edge и Chrome, а также в других браузерах на основе Chromium, по умолчанию включены пользовательские реестры элементов с ограниченной областью видимости.

Вам не нужно включать какие-либо настройки или регистрироваться для пробного периода. Вы можете начать использовать эту функцию уже сегодня в браузерах на основе Chromium.

Если вам необходимо реализовать эту функцию в других браузерах, поставьте лайк запросу "Scoped custom element registryes" и оставьте комментарий с описанием ваших сценариев использования и обходных решений.

Если вы обнаружите ошибку в реализации этой функции в браузере на основе Chromium, создайте заявку для расследования на сайте crbug.com/new .

Мы надеемся, что реестры пользовательских элементов с ограниченной областью видимости упростят использование веб-компонентов.