使用範圍登錄檔讓自訂元素運作

Jayson Chen
Jayson Chen
LinkedIn
Patrick Brosset
Patrick Brosset
首頁

發布日期：2026 年 3 月 9 日

網頁應用程式開發人員可透過自訂元素建構、分享及重複使用具有獨特行為的 UI 元件，讓開發作業更輕鬆。但如果應用程式匯集了不同組的自訂元素，情況可能會變得混亂，並發生名稱衝突。範圍限定的自訂元素登錄程序可解決這個問題！

Microsoft Edge 團隊已開發這項功能，我們很開心宣布，從 Edge 和 Chrome 146 版，以及其他採用 Chromium 的瀏覽器開始，範圍自訂元素登錄檔現在預設為可用。您現在可以封裝自訂元素，解決元件和微前端程式庫開發人員長期以來的痛點。

Browser Support

  • Chrome: 146.
  • Edge: 146.
  • Firefox: not supported.
  • Safari: 26.

Source

網頁程式開發人員可透過範圍內的自訂元素登錄，解鎖重要模式。 現在，您可以並行使用多個團隊各自開發的多個自訂元素程式庫，或同一程式庫的多個版本。

兩個樣式截然不同的按鈕。

什麼是範圍限定的自訂元素登錄？

目前，網頁上的每個自訂元素定義都位於 window.customElements 的單一共用登錄檔中。也就是說，如果兩個不同的程式庫都嘗試定義具有相同標記名稱 (例如 <my-button>) 的自訂元素，系統就會擲回錯誤，導致網頁中斷。這在現實世界中是個重大問題。如果大型應用程式的使用者介面是由多個團隊、設計系統或微前端組成，很容易發生命名衝突。範圍內的自訂元素登錄程序可讓您建立獨立登錄程序，解決這個問題。每個登錄檔都會維護自己的自訂元素定義集，完全與全域登錄檔和其他登錄檔隔離。

建立新喜願清單

您不必在全域 window.customElements 登錄中定義每個自訂元素：

  1. 呼叫 new CustomElementRegistry() 建立新登錄。
  2. 為新登錄檔指定範圍 (請參閱「設定登錄檔範圍」)。
  3. 定義要納入新登錄檔的元素。

接著，當使用自訂元素時，瀏覽器會從相關聯的登錄檔 (不一定是全域登錄檔) 查閱元素的定義。也就是說，網頁的不同部分可以使用完全不同的自訂元素定義集。

設定登錄範圍

自訂元素登錄檔的範圍可以是文件、陰影根或個別元素。

範圍為陰影根

如要將新登錄範圍設為陰影根，請在呼叫 attachShadow() 方法時使用 customElementRegistry 選項。現在，位於該陰影根目錄中的所有自訂元素都會使用相應範圍註冊表中的定義：

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

宣告式 Shadow DOM

在 <template> 元素上使用 shadowrootcustomelementregistry 屬性，告知瀏覽器產生的陰影根目錄使用範圍註冊表，而非全域註冊表：

<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 的瀏覽器中使用這項功能。

如需在其他瀏覽器中實作這項功能，請對範圍限定的自訂元素登錄問題按讚，並留言說明您的用途和解決方法。

如果您在使用 Chromium 架構的瀏覽器時，發現這項功能的實作方式有錯誤，請前往 crbug.com/new 開啟問題，以利我們進行調查。

希望範圍限定的自訂元素登錄程序，能讓您更輕鬆地使用網頁元件。