Kapsamlı kayıtlarla özel öğelerin davranışını belirleme

Jayson Chen

Patrick Brosset

Yayın tarihi: 9 Mart 2026

Özel öğeler, web uygulaması geliştiricilerinin benzersiz davranışlara sahip kullanıcı arayüzü bileşenleri oluşturmasına, paylaşmasına ve yeniden kullanmasına olanak tanıyarak geliştirmeyi kolaylaştırır. Ancak uygulamanız farklı özel öğe gruplarını bir araya getirdiğinde işler karışabilir ve ad çakışmaları oluşabilir. Kapsamlı özel öğe kayıtları bu sorunu çözer.

Microsoft Edge ekibi bu özellik üzerinde çalıştı ve kapsamlı özel öğe kayıtlarının artık Edge ve Chrome 146'dan başlayarak diğer Chromium tabanlı tarayıcılarda varsayılan olarak kullanılabildiğini duyurmaktan heyecan duyuyoruz. Artık özel öğeleri kapsayabilir, böylece bileşen ve mikro ön uç kitaplıklarının geliştiricileri için uzun süredir devam eden bir sorunu çözebilirsiniz.

Kapsamlı özel öğe kayıtları, web geliştiriciler için önemli kalıpların kilidini açar. Artık birden fazla ekip tarafından bağımsız olarak geliştirilen birden fazla özel öğe kitaplığını veya aynı kitaplığın birden fazla sürümünü yan yana kullanabilirsiniz.

Kapsamlı özel öğe kaydı nedir?

Günümüzde, bir web sayfasındaki her özel öğe tanımı window.customElements adresindeki tek bir paylaşılan kayıt defterinde bulunur. Bu, aynı etiket adına sahip bir özel öğeyi (ör. <my-button>) tanımlamaya çalışan iki farklı kitaplık olduğunda bir hata oluşacağı ve sayfanın bozulacağı anlamına gelir. Bu, gerçek dünyada önemli bir sorundur. Kullanıcı arayüzlerini birden fazla ekip, tasarım sistemi veya mikro ön uçtan oluşturan büyük uygulamalarda ad çakışmaları kolayca yaşanabilir. Kapsamlı özel öğe kayıtları, bağımsız kayıtlar oluşturmanıza olanak tanıyarak bu sorunu çözer. Her kayıt defteri, genel kayıt defterinden ve birbirinden tamamen ayrı, kendi özel öğe tanımları kümesini tutar.

Yeni bir kayıt oluşturma

Her özel öğeyi genel window.customElements kaydında tanımlamak yerine:

1. new CustomElementRegistry() işlevini çağırarak yeni bir kayıt oluşturun.
2. Yeni kayıt defterinize belirli bir kapsam verin (bkz. Kayıt defterinizin kapsamını belirleme).
3. Yeni kayıt defterine eklenecek öğeleri tanımlayın.

Ardından, özel bir öğe kullanıldığında tarayıcı, öğenin tanımını ilişkili kayıt defterinden (küresel olan değil) arar. Bu, sayfanızın farklı bölümlerinde tamamen farklı özel öğe tanımları kullanılabileceği anlamına gelir.

Kayıt defterinizin kapsamını belirleme

Özel öğe kaydı, bir doküman, bir gölge kökü veya tek bir öğe ile sınırlandırılabilir.

Gölge köküne kapsam belirleme

Yeni bir kayıt defterini gölge köküne göre kapsamlandırmak için attachShadow() yöntemini çağırırken customElementRegistry seçeneğini kullanın. Bu gölge kökünün içindeki tüm özel öğeler artık ilgili kapsamlı kayıt defterindeki tanımı kullanır:

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

Bildirimsel gölge DOM

Tarayıcıya, sonuçtaki gölge kökünün genel kayıt yerine kapsamlı bir kayıt kullandığını bildirmek için <template> öğesinde shadowrootcustomelementregistry özelliğini kullanın:

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

Örnekte gösterildiği gibi, özellik özel öğe kayıt otoritesi için alan ayırır ve kullanıcının, kayıt otoritesini ayrılmış bir belgeye gölge kökü kapsamı için tanımlayıp ilk kullanıma hazırlaması gerekir.

Ayrıca, bir kayıt defterini document.implementation.createHTMLDocument() tarafından oluşturulanlar gibi bir belgeyle de sınırlayabilirsiniz. Bu sayede, her biri kendi izole bileşen tanımları kümesine sahip olan <template> öğelerini klonlayabilir ve ekran dışı doküman işlemleri yapabilirsiniz. Bunu yapmak için CustomElementRegistry.initialize() yöntemini kullanın:

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

Kapsamı tek bir öğeyle sınırlama

Ayrıca, customElementRegistry seçeneğini document.createElement()'ye ileterek bir kayıt defterini doğrudan bir öğeyle ve alt ağacıyla da ilişkilendirebilirsiniz. Öğe ve alt öğeleri, DOM'un hangi bölümüne daha sonra eklenirse eklensin, söz konusu kayıt otoritesine göre çözümlenir:

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

Daha fazla bilgi

Daha fazla bilgi edinmek için Edge demosunu ve kaynak kodunu inceleyin, MDN'nin CustomElementRegistry referans makalesini okuyun.

Kapsamlı özel öğe kayıtları, Chromium projesi kapsamındaki işbirliğimiz sayesinde artık Microsoft Edge ve Chrome'un yanı sıra diğer Chromium tabanlı tarayıcılarda da varsayılan olarak etkinleştirilmiştir.

Herhangi bir ayarı etkinleştirmeniz veya bir kaynak denemesine kaydolmanız gerekmez. Bu özelliği bugün Chromium tabanlı tarayıcılarda kullanmaya başlayabilirsiniz.

Bu özelliğin diğer tarayıcılarda da uygulanması gerektiğini düşünüyorsanız Kapsamlı özel öğe kayıtları sorununa olumlu tepki verin ve kullanım alanlarınız ile geçici çözümlerinizi içeren bir yorum bırakın.

Chromium tabanlı bir tarayıcıda özelliğin uygulanmasıyla ilgili bir hata bulursanız crbug.com/new adresinden sorunu bize bildirin.

Kapsamlı özel öğe kayıtlarının web bileşenlerinin kullanımını kolaylaştıracağını umuyoruz.