جعل العناصر المخصّصة تتوافق مع السجلات ذات النطاق المحدود

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

نموذج shadow 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 والرمز المصدري، وقراءة مقالة مرجع CustomElementRegistry على MDN.

أصبحت سجلات العناصر المخصّصة ذات النطاق المحدود مفعّلة تلقائيًا في كل من Microsoft Edge وChrome، بالإضافة إلى المتصفّحات الأخرى المستندة إلى Chromium، وذلك بفضل تعاوننا من خلال مشروع Chromium.

لست بحاجة إلى تفعيل أي إعداد أو الاشتراك في مرحلة التجربة والتقييم. يمكنك بدء استخدام الميزة اليوم في المتصفّحات المستندة إلى Chromium.

إذا كنت بحاجة إلى تنفيذ هذه الميزة في متصفحات أخرى، يُرجى النقر على رمز الإعجاب في مشكلة سجلات العناصر المخصّصة ذات النطاق المحدود وكتابة تعليق يتضمّن حالات الاستخدام والحلول البديلة.

إذا عثرت على خطأ في تنفيذ الميزة في متصفّح يستند إلى Chromium، يمكنك إبلاغنا بالمشكلة لنتمكّن من التحقيق فيها على الرابط crbug.com/new.

نأمل أن تسهّل سجلّات العناصر المخصّصة ذات النطاق المحدود استخدام مكوّنات الويب.