تعريف العناصر باستخدام customElements.define
تسجيل فئة عنصر مخصص لدى المتصفح
تعريف العناصر باستخدام customElements.define درس مجاني في HTML Academy على CoddyKit. هذا هو الدرس 1 من أصل 4. يمكنك قراءة الدرس كاملاً أدناه مجاناً — ثم تمرن عليه مباشرة في المتصفح باستخدام محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7. هذا الدرس جزء من مسار التعلم في HTML Academy، وتقدمك يتزامن عبر الويب وتطبيق CoddyKit. تتضمن دورة HTML Academy 4 دروس في المجموع.
ما العناصر المخصصة؟
تتيح لك العناصر المخصصة ابتكار وسوم HTML خاصة بك مدعومة بفئة JavaScript. بعد تعريفها، يتصرف <my-card> مثل أي عنصر مضمّن: يمكن كتابته في HTML والاستعلام عنه وتنسيقه وبرمجته واستخدامه داخل أطر العمل دون تغيير.
متطلب الواصلة
يجب أن يتضمن اسم كل عنصر مخصص واصلة واحدة على الأقل — user-avatar وapp-button وmy-card. تميّز الواصلة العناصر المخصصة عن وسوم HTML المضمّنة الحالية والمستقبلية، وتفرضها المواصفة.
تعريف فئة
العنصر المخصص هو فئة تمتد من HTMLElement (أو من فئة فرعية مضمّنة). يمكن للفئة تعريف مُنشئ وعمليات استدعاء لدورة الحياة. وتصبح الخصائص والأساليب العامة في الفئة واجهة البرمجة النصية للعنصر.
class MyCard extends HTMLElement {
constructor() {
super();
this.textContent = "Hello from MyCard";
}
}التسجيل باستخدام define
يسجل customElements.define("my-card", MyCard) الفئة تحت اسم الوسم. بعد التسجيل، تتم ترقية كل عناصر <my-card> الموجودة حاليًا والمستقبلية في المستند إلى مثيلات من الفئة.
super() إلزامية
يجب أن يستدعي المُنشئ super() كأول عبارة فيه قبل الوصول إلى this. يؤدي تخطي super() إلى طرح الخطأ "Failed to construct 'HTMLElement'". تعامل مع ذلك على أنه قاعدة مُنشئ فئة JavaScript القياسية.
لا تقرأ DOM في المُنشئ
لا يجوز للمُنشئ قراءة سمات العنصر أو أبنائه — فقد لا يكون قد تم تحليلها بعد وقت الإنشاء. انقل الإعداد الذي يتعامل مع DOM إلى connectedCallback، الذي لا يُشغّل إلا بعد وجود العنصر في المستند.
التسجيل دائم
لا يمكن تسجيل اسم عنصر إلا مرة واحدة في كل صفحة. تؤدي إعادة تعريف الاسم نفسه إلى طرح NotSupportedError. أعد تحميل الصفحة لاختبار التغييرات أثناء التطوير؛ وفي بيئة الإنتاج، سجّل كل مكوّن مرة واحدة عند بدء التشغيل.
Polyfills
تتوفر العناصر المخصصة في كل متصفح حديث. أما المتصفحات القديمة جدًا (التي انقرض معظمها)، فيوفر لها polyfill المسمى webcomponents.js بديلًا. يمكن للمشاريع الجديدة استخدام التنفيذ الأصلي والاستغناء عن polyfill تمامًا.
اكتشاف حالة التعريف
تعيد customElements.get("my-card") الفئة إذا كانت معرّفة، وتعيد undefined خلاف ذلك. وتعيد customElements.whenDefined("my-card") وعدًا يُحلّ بمجرد تسجيل العنصر — وهذا مفيد للشيفرة التي تحتاج إلى الانتظار حتى تحميل التعريفات المتأخرة.
customElements.whenDefined("my-card").then((Class) => {
console.log("MyCard is ready");
});استخدام العنصر
بعد تعريف العنصر، استخدمه تمامًا مثل أي وسم مضمّن: اكتبه في HTML (<my-card></my-card>)، أو أنشئه عبر document.createElement("my-card")، أو أنشئ مثيلًا عبر new MyCard() وأدرجه. تنتج المسارات الثلاثة نفسها مثيلًا تمت ترقيته.
اصطلاحات التسمية
أضف بادئة إلى العناصر المخصصة باسم المشروع أو الشركة (cd-card وapp-modal) لتجنب التعارض مع المكتبات الأخرى في الصفحة نفسها. منظومة مكوّنات الويب غير مجمّعة — إذ يمكن لأي جهة موجودة في صفحتك تسجيل أي اسم، ويفوز التسجيل الأول.
اختبار المعرفة
لماذا يجب أن يحتوي اسم كل عنصر مخصص على واصلة؟
الملخص
العناصر المخصصة هي فئات JavaScript تمتد من HTMLElement، وتُسجّل عبر customElements.define("name", Class)، حيث يجب أن يتضمن الاسم واصلة. يجب أن يستدعي المُنشئ super() أولًا، وألا يقرأ DOM؛ فأجّل عمل DOM إلى connectedCallback. تتصرف العناصر المعرّفة تمامًا مثل الوسوم المضمّنة في كل مكان.
الأسئلة الشائعة
هل درس «تعريف العناصر باستخدام customElements.define» مجاني؟
نعم — نص درس «تعريف العناصر باستخدام customElements.define» كامل متاح مجاناً هنا على الويب. لتمرينه بشكل تفاعلي (محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7) وفتح باقي دورة HTML Academy، انتقل إلى CoddyKit PRO. تتضمن دورة HTML Academy 4 دروس في المجموع.
ماذا ستتعلم في «تعريف العناصر باستخدام customElements.define»؟
تسجيل فئة عنصر مخصص لدى المتصفح تتمرن على HTML Academy مع أكواد عملية تشغلها مباشرة في المتصفح، ومدرس ذكاء اصطناعي متاح 24/7 يجيب على أسئلتك أثناء عملك.
هل أحتاج إلى خبرة سابقة لأبدأ HTML Academy؟
لا تُشترط خبرة سابقة. HTML Academy على CoddyKit منظم للمبتدئين حتى المتقدمين، لذا يمكنك البدء من هنا أو من البداية والتقدم بسرعتك الخاصة. هذا هو الدرس 1 من أصل 4.
كم من الوقت يستغرق درس «تعريف العناصر باستخدام customElements.define»؟
معظم دروس CoddyKit تستغرق حوالي 5–10 دقائق. كل منها موجز وتفاعلي، لذا تحرز تقدماً مستمراً وتستأنف من حيث توقفت عبر الويب والتطبيق.
هل يمكنني كتابة وتشغيل أكواد في درس HTML Academy هذا؟
نعم. كل درس في HTML Academy يتضمن محرر أكواد مدمج، لذا تكتب وتشغل أكواداً حقيقية مباشرة في متصفحك وتحصل على تعليقات فورية من الذكاء الاصطناعي — بدون إعداد محلي.
جميع الدروس في هذه الدورة
- تعريف العناصر باستخدام customElements.define
- connectedCallback وdisconnectedCallback
- السمات المرصودة وattributeChangedCallback
- توسيع العناصر المضمّنة