Dostosowywanie działania elementów niestandardowych za pomocą rejestrów o ograniczonym zakresie

Jayson Chen

Patrick Brosset

Data publikacji: 9 marca 2026 r.

Elementy niestandardowe umożliwiają twórcom aplikacji internetowych tworzenie, udostępnianie i ponowne wykorzystywanie komponentów interfejsu z ich unikalnymi zachowaniami, co ułatwia programowanie. Gdy jednak aplikacja łączy różne zestawy elementów niestandardowych, może to prowadzić do nieporządku i konfliktów nazw. Rejestry elementów niestandardowych o ograniczonym zakresie rozwiązują ten problem.

Zespół Microsoft Edge pracował nad tą funkcją i z przyjemnością informujemy, że zakresowe rejestry niestandardowych elementów są teraz domyślnie dostępne w Edge i Chrome 146, a także w innych przeglądarkach opartych na Chromium. Możesz teraz enkapsulować elementy niestandardowe, co rozwiązuje długotrwały problem deweloperów bibliotek komponentów i mikrofrontendów.

Rejestry elementów niestandardowych o określonym zakresie udostępniają programistom ważne wzorce. Teraz możesz używać wielu bibliotek elementów niestandardowych opracowanych niezależnie przez różne zespoły lub wielu wersji tej samej biblioteki.

Co to jest rejestr elementów niestandardowych o określonym zakresie?

Obecnie każda definicja elementu niestandardowego na stronie internetowej znajduje się w jednym, wspólnym rejestrze pod adresem window.customElements. Oznacza to, że jeśli 2 różne biblioteki spróbują zdefiniować element niestandardowy o tej samej nazwie tagu, np. <my-button>, zostanie zgłoszony błąd i strona przestanie działać. To poważny problem w rzeczywistości. W przypadku dużych aplikacji, których interfejsy użytkownika są tworzone przez wiele zespołów, systemów projektowania lub mikrofrontendów, łatwo może dojść do kolizji nazw. Rejestry elementów niestandardowych o określonym zakresie rozwiązują ten problem, umożliwiając tworzenie niezależnych rejestrów. Każdy rejestr zawiera własny zestaw definicji elementów niestandardowych, całkowicie odizolowany od rejestru globalnego i od innych rejestrów.

Tworzenie nowego rejestru

Zamiast definiować każdy element niestandardowy w globalnym rejestrze window.customElements:

1. Utwórz nowy rejestr, wywołując funkcję new CustomElementRegistry().
2. Nadaj nowemu rejestrowi określony zakres (patrz Określanie zakresu rejestru).
3. Określ elementy, które mają się znaleźć w nowym rejestrze.

Gdy używany jest element niestandardowy, przeglądarka wyszukuje jego definicję w powiązanym rejestrze, który niekoniecznie jest rejestrem globalnym. Oznacza to, że różne części strony mogą używać zupełnie różnych zestawów definicji elementów niestandardowych.

Określanie zakresu rejestru

Rejestr elementów niestandardowych może być ograniczony do dokumentu, korzenia cienia lub pojedynczego elementu.

Ustaw zakres na cień korzenia

Aby ograniczyć zakres nowego rejestru do elementu shadow root, użyj opcji customElementRegistry podczas wywoływania metody attachShadow(). Wszystkie elementy niestandardowe znajdujące się w tym korzeniu cienia będą teraz korzystać z definicji w odpowiednim zarejestrowanym zakresie:

// 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>';

Deklaratywny shadow DOM

Użyj atrybutu shadowrootcustomelementregistry w elemencie <template>, aby poinformować przeglądarkę, że wynikowy root cienia korzysta z rejestru o ograniczonym zakresie, a nie z rejestru globalnego:

<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);

Jak pokazano w przykładzie, atrybut rezerwuje miejsce dla rejestru elementów niestandardowych, a użytkownik musi zdefiniować i zainicjować rejestr, aby określić zakres shadow root w odłączonym dokumencie.

Możesz też ograniczyć zakres rejestru do dokumentu, np. utworzonego przez document.implementation.createHTMLDocument(). Dzięki temu możesz klonować<template> elementy i manipulować dokumentami poza ekranem, a każda z tych czynności ma własne, odseparowane zestawy definicji komponentów. Aby to zrobić, użyj metody 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>';

Ustawianie zakresu na pojedynczy element

Możesz też powiązać rejestr bezpośrednio z elementem i jego poddrzewem, przekazując opcję customElementRegistry do document.createElement(). Element i jego elementy podrzędne będą rozpoznawane w tym rejestrze niezależnie od tego, w której części DOM zostaną później wstawione:

// 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>';

Więcej informacji

Więcej informacji znajdziesz w wersji demonstracyjnej Edge i jej kodzie źródłowym oraz w artykule referencyjnym CustomElementRegistry w MDN.

Dzięki naszej współpracy w ramach projektu Chromium zakresowe rejestry elementów niestandardowych są teraz domyślnie włączone w przeglądarkach Microsoft Edge i Chrome, a także w innych przeglądarkach opartych na Chromium.

Nie musisz włączać żadnych ustawień ani rejestrować się w testowaniu origin. Możesz zacząć korzystać z tej funkcji już dziś w przeglądarkach opartych na Chromium.

Jeśli chcesz, aby ta funkcja została wdrożona w innych przeglądarkach, polub ten problem dotyczący rejestrów elementów niestandardowych o ograniczonym zakresie i dodaj komentarz z opisem swoich przypadków użycia i obejść.

Jeśli znajdziesz błąd w implementacji funkcji w przeglądarce opartej na Chromium, otwórz zgłoszenie, abyśmy mogli je zbadać. Zrobisz to na stronie crbug.com/new.

Mamy nadzieję, że rejestry elementów niestandardowych o określonym zakresie ułatwią korzystanie z komponentów internetowych.