JavaScript Academy · درس

تعريف العناصر المخصصة

سجّلوا العناصر باستخدام واجهة customElements API.

تعريف العناصر المخصصة درس مجاني في JavaScript Academy على CoddyKit. هذا هو الدرس 1 من أصل 4. يمكنك قراءة الدرس كاملاً أدناه مجاناً — ثم تمرن عليه مباشرة في المتصفح باستخدام محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7. هذا الدرس جزء من مسار التعلم في JavaScript Academy، وتقدمك يتزامن عبر الويب وتطبيق CoddyKit. تتضمن دورة JavaScript Academy 4 دروس في المجموع.

ما هي العناصر المخصصة؟

تتيح لك العناصر المخصصة تعريف وسوم HTML الخاصة بك، مدعومة بفئات JavaScript. وبدلًا من تركيب مجموعة من عناصر div، تنشئ مكوّنًا قابلًا لإعادة الاستخدام ومستقلًا بذاته، مثل <user-card>.

تُعد جزءًا من معيار Web Components.
تعمل أصلًا في المتصفحات، ولا تتطلب إطار عمل.
يجب أن يحتوي اسم العنصر المخصص على واصلة (مثل my-button).

سجل customElements

يكشف المتصفح عن سجل عام في window.customElements. سجّل وسمًا جديدًا باستدعاء customElements.define(name, constructor).

بعد تعريفه، يُرقّى كل وسم مطابق في المستند ليصبح مثيلًا من فئتك.

// Register a tag named 'hello-world'
customElements.define('hello-world', HelloWorld);

// After this, every <hello-world> in the page
// becomes an instance of the HelloWorld class.

توسيع HTMLElement

العنصر المخصص هو فئة تستخدم extends HTMLElement. وتمنح الفئة الأساسية عنصرك جميع إمكانات DOM القياسية، مثل السمات والأحداث والتنسيق.

استدعِ super() دائمًا أولًا في المُنشئ حتى تتم تهيئة العنصر بصورة صحيحة.

class HelloWorld extends HTMLElement {
  constructor() {
    super(); // required, sets up the element
  }
}

customElements.define('hello-world', HelloWorld);

عرض المحتوى

يمكنك داخل العنصر ضبط this.innerHTML أو استخدام أساليب DOM لإنشاء المحتوى. ومن الأنماط الشائعة عرض المحتوى عند اتصال العنصر بالصفحة.

class HelloWorld extends HTMLElement {
  connectedCallback() {
    this.innerHTML = '<p>Hello from a custom element!</p>';
  }
}

customElements.define('hello-world', HelloWorld);

استخدام العنصر في HTML

بعد التسجيل، استخدم وسمك مثل أي عنصر مضمّن. ويمكنك وضعه مباشرةً في الترميز أو إنشاؤه باستخدام document.createElement.

// In HTML:
// <hello-world></hello-world>

// Or in JavaScript:
const el = document.createElement('hello-world');
document.body.appendChild(el);

قواعد المُنشئ

يُنفّذ المُنشئ عند إنشاء مثيل. وهناك قواعد صارمة:

استدعِ super() أولًا.
لا تفحص السمات أو العناصر الفرعية ولا تضفها هنا.
أجّل العمل على DOM إلى connectedCallback.

استخدم المُنشئ فقط لإعداد الحالة الأولية وإعداد مستمعات الأحداث.

class CounterButton extends HTMLElement {
  constructor() {
    super();
    this.count = 0; // safe: just internal state
  }
}

customElements.define('counter-button', CounterButton);

إضافة السلوك

بما أن العنصر الخاص بكم هو عقدة DOM حقيقية، يمكنكم إرفاق مستمعي الأحداث به وتحديث محتواه استجابةً للتفاعل.

class CounterButton extends HTMLElement {
  constructor() {
    super();
    this.count = 0;
  }
  connectedCallback() {
    this.textContent = 'Clicked 0 times';
    this.addEventListener('click', () => {
      this.count++;
      this.textContent = 'Clicked ' + this.count + ' times';
    });
  }
}
customElements.define('counter-button', CounterButton);

شرط الشرطة

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

my-widget صالح.
mywidget غير صالح ويؤدي إلى ظهور خطأ.
الأسماء غير حساسة لحالة الأحرف، لكنها تُكتب بأحرف صغيرة.

// Valid:
customElements.define('app-header', AppHeader);

// Invalid - throws SyntaxError (no hyphen):
// customElements.define('appheader', AppHeader);

whenDefined و get

طريقتان مفيدتان في السجل:

customElements.get(name) تُعيد الباني، أو undefined إذا لم يكن العنصر مسجّلًا.
customElements.whenDefined(name) تُعيد Promise تُحلّ بمجرد تعريف العنصر.

customElements.whenDefined('hello-world').then(() => {
  console.log('hello-world is ready to use');
});

const Ctor = customElements.get('hello-world');

التعريف مرة واحدة فقط

يمكن تسجيل كل اسم مرة واحدة فقط. يؤدي استدعاء define باستخدام اسم مستخدم من قبل إلى ظهور خطأ. احرصوا على منع التسجيل المزدوج في الوحدات المشتركة.

if (!customElements.get('hello-world')) {
  customElements.define('hello-world', HelloWorld);
}

أهمية العناصر المخصصة

تمنحكم العناصر المخصصة واجهة مستخدم معزولة وقابلة لإعادة الاستخدام، من دون الاعتماد على إطار عمل. وهي:

توحّد إعادة استخدام المكونات عبر أي بنية تقنية.
تتكامل مع دورة الحياة الخاصة بالمتصفح.
تتوافق طبيعيًا مع Shadow DOM والقوالب (وسنتناولها لاحقًا).

اختبار سريع

اختبروا مدى فهمكم لتعريف العناصر المخصصة.

مراجعة

تعلمتم كيفية تعريف العناصر المخصصة:

يسجّل customElements.define(name, class) وسمًا.
يمتد الصنف من HTMLElement ويستدعي super() أولًا.
يجب أن تتضمن الأسماء شرطة.
اعرضوا المحتوى في connectedCallback وليس في الباني.
يساعدكم كل من get وwhenDefined على التحقق من حالة التسجيل.

سنستكشف بعد ذلك دورة الحياة الكاملة للعنصر المخصص.

الأسئلة الشائعة

هل درس «تعريف العناصر المخصصة» مجاني؟

نعم — نص درس «تعريف العناصر المخصصة» كامل متاح مجاناً هنا على الويب. لتمرينه بشكل تفاعلي (محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7) وفتح باقي دورة JavaScript Academy، انتقل إلى CoddyKit PRO. تتضمن دورة JavaScript Academy 4 دروس في المجموع.

ماذا ستتعلم في «تعريف العناصر المخصصة»؟

سجّلوا العناصر باستخدام واجهة customElements API. تتمرن على JavaScript Academy مع أكواد عملية تشغلها مباشرة في المتصفح، ومدرس ذكاء اصطناعي متاح 24/7 يجيب على أسئلتك أثناء عملك.

هل أحتاج إلى خبرة سابقة لأبدأ JavaScript Academy؟

لا تُشترط خبرة سابقة. JavaScript Academy على CoddyKit منظم للمبتدئين حتى المتقدمين، لذا يمكنك البدء من هنا أو من البداية والتقدم بسرعتك الخاصة. هذا هو الدرس 1 من أصل 4.

كم من الوقت يستغرق درس «تعريف العناصر المخصصة»؟

معظم دروس CoddyKit تستغرق حوالي 5–10 دقائق. كل منها موجز وتفاعلي، لذا تحرز تقدماً مستمراً وتستأنف من حيث توقفت عبر الويب والتطبيق.

هل يمكنني كتابة وتشغيل أكواد في درس JavaScript Academy هذا؟

نعم. كل درس في JavaScript Academy يتضمن محرر أكواد مدمج، لذا تكتب وتشغل أكواداً حقيقية مباشرة في متصفحك وتحصل على تعليقات فورية من الذكاء الاصطناعي — بدون إعداد محلي.

جميع الدروس في هذه الدورة

← العودة إلى JavaScript Academy