Fare in modo che gli elementi personalizzati si comportino con i registri con ambito

Jayson Chen

Patrick Brosset

Data di pubblicazione: 9 marzo 2026

Gli elementi personalizzati consentono agli sviluppatori di app web di creare, condividere e riutilizzare componenti UI con i loro comportamenti unici, semplificando lo sviluppo. Tuttavia, quando la tua app riunisce diversi set di elementi personalizzati, le cose possono diventare complicate e possono verificarsi collisioni di nomi. I registri degli elementi personalizzati con ambito risolvono questo problema.

Il team di Microsoft Edge ha lavorato a questa funzionalità e siamo felici di annunciare che i registri degli elementi personalizzati con ambito sono ora disponibili per impostazione predefinita in Edge e Chrome 146, nonché in altri browser basati su Chromium. Ora puoi incapsulare elementi personalizzati, risolvendo un problema di lunga data per gli sviluppatori di librerie di componenti e microfrontend.

I registri degli elementi personalizzati con ambito sbloccano pattern importanti per gli sviluppatori web. Ora puoi utilizzare più librerie di elementi personalizzati, sviluppate in modo indipendente da più team, o più versioni della stessa libreria affiancate.

Che cos'è un registro di elementi personalizzati con ambito?

Oggi, ogni definizione di elemento personalizzato in una pagina web si trova in un unico registro condiviso all'indirizzo window.customElements. Ciò significa che se due librerie diverse tentano di definire un elemento personalizzato con lo stesso nome tag, ad esempio <my-button>, viene generato un errore e la pagina non funziona. Si tratta di un problema significativo nel mondo reale. Le applicazioni di grandi dimensioni che compongono le proprie interfacce utente da più team, sistemi di progettazione o microfrontend possono facilmente imbattersi in conflitti di denominazione. I registri di elementi personalizzati con ambito risolvono questo problema consentendoti di creare registri indipendenti. Ogni registro mantiene il proprio insieme di definizioni di elementi personalizzati, completamente isolato dal registro globale e dagli altri registri.

Crea un nuovo registro

Invece di definire ogni elemento personalizzato nel registro globale window.customElements:

1. Crea un nuovo registro chiamando new CustomElementRegistry().
2. Assegna al nuovo registro un ambito specifico (vedi Definizione dell'ambito del registro).
3. Definisci gli elementi che compongono il nuovo registro.

Poi, quando viene utilizzato un elemento personalizzato, il browser cerca la definizione dell'elemento nel registro associato, che non è necessariamente quello globale. Ciò significa che diverse parti della pagina possono utilizzare insiemi completamente diversi di definizioni di elementi personalizzati.

Definisci l'ambito del registro

Un registro di elementi personalizzati può essere limitato a un documento, a una radice ombra o a un singolo elemento.

Ambito di una radice ombra

Per limitare un nuovo registro a una radice ombra, utilizza l'opzione customElementRegistry quando chiami il metodo attachShadow(). Tutti gli elementi personalizzati all'interno di questa radice shadow utilizzeranno ora la definizione presente nel registro con ambito corrispondente:

// 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 shadow dichiarativo

Utilizza l'attributo shadowrootcustomelementregistry su un elemento <template> per comunicare al browser che la radice ombra risultante utilizza un registro con ambito anziché quello globale:

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

Come mostrato nell'esempio, l'attributo riserva spazio per il registro degli elementi personalizzati e l'utente deve definire e inizializzare il registro per l'ambito della radice shadow in un documento disconnesso

Puoi anche limitare un registro a un documento, ad esempio uno creato da document.implementation.createHTMLDocument(). In questo modo puoi clonare <template> elementi ed eseguire la manipolazione dei documenti fuori schermo, ognuno con i propri set isolati di definizioni dei componenti. A tal fine, utilizza il metodo 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>';

Ambito di un singolo elemento

Puoi anche associare un registro direttamente a un elemento e al relativo sottoalbero passando l'opzione customElementRegistry a document.createElement(). L'elemento e i relativi discendenti verranno risolti in base a questo registro, indipendentemente dalla parte del DOM in cui vengono inseriti in un secondo momento:

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

Scopri di più

Per saperne di più, consulta la demo di Edge e il relativo codice sorgente e leggi l'articolo di riferimento di MDN su CustomElementRegistry.

I registri degli elementi personalizzati con ambito sono ora attivati per impostazione predefinita sia in Microsoft Edge che in Chrome, nonché in altri browser basati su Chromium, grazie alla nostra collaborazione nell'ambito del progetto Chromium.

Non devi attivare alcuna impostazione o registrarti a una prova dell'origine. Puoi iniziare a utilizzare la funzionalità oggi stesso nei browser basati su Chromium.

Se hai bisogno che questa funzionalità venga implementata in altri browser, metti un Mi piace al problema dei registri degli elementi personalizzati con ambito e lascia un commento con i tuoi casi d'uso e le soluzioni alternative.

Se riscontri un bug nell'implementazione della funzionalità in un browser basato su Chromium, apri un problema per consentirci di esaminarlo all'indirizzo crbug.com/new.

Ci auguriamo che i registri degli elementi personalizzati con ambito semplifichino l'utilizzo dei componenti web.