واجهات برمجة تطبيقات HTML

في مقدّمة هذه السلسلة، يُقال إنّ "عناصر HTML هي العقد التي تشكّل نموذج تمثيل المستند". لقد ناقشنا نوع عقد العناصر. في هذا القسم، نناقش واجهات برمجة التطبيقات للعناصر التي تتيح طلب البحث عن هذه العقد.

نموذج DOM وAOM

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

شجرة عقد MLW تعرِض العناصر والعقد النصية

لا تقدّم أدوات المتصفّح عروضًا مرئية للشجرة مثل تلك الواردة أعلاه، ولكن يمكنك الاطّلاع على العقد في "أداة فحص العناصر".

نموذج العناصر في المستند (DOM)/ARIA

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

مثال على إدارة الأداء

واجهات برمجة تطبيقات عناصر HTML

الحرف الأوسط في DOM هو "obj." تمامًا مثل مثال كائن person أو car من معظم دروس التعرّف على برمجة المشروعات الموجّهة للكائنات، كل عقدة في شجرة المستند هي كائن يمكن التلاعب به باستخدام JavaScript.

يقدّم المتصفّح العديد من واجهتَي برمجة التطبيقات اللتين توفّران طُرقًا وأحداثًا وعمليات طلب واستعلام عن المواقع وتعديلها متوافقة مع اللغة الأصلية. تحتوي عقد العناصر على معلومات عن جميع السمات التي تم ضبطها على العنصر. يمكنك استخدام واجهات HTML للوصول إلى معلومات عن سمات العنصر. على سبيل المثال، يمكننا استخدام HTMLImageElement.alt للحصول على سمات alt لجميع الصور:

let allImages = document.querySelectorAll('img');
allImages.forEach((imageInstance) => {
  console.log(imageInstance.alt);
});

توفّر واجهات HTML أكثر من مجرد إمكانية الوصول إلى سمات العنصر، بل يمكنك الوصول إلى الكثير من المعلومات. يمكننا العثور على العنصر HTMLElement.offsetHeight للقراءة فقط للحصول على ارتفاع كل قسم في صفحتنا، نسبةً إلى التنسيق.

let allSections = document.querySelectorAll('section');
allSections.forEach((sectionInstance) => {
  console.log(sectionInstance.offsetHeight);
});

إذا غيّر المستخدم اتجاه جهازه أو غيّر عرض مساحة العرض، سيتغيّر ارتفاع كل <section> وستتم تعديل سمات DOM تلقائيًا وفقًا لذلك.

لا تقتصر واجهات برمجة التطبيقات لواجهة HTML على الوصول إلى قيم السمات. يقدّم نموذج DOM إحصاءات عن الحالة الحالية لواجهة المستخدم. يمكن لواجهات برمجة تطبيقات HTML الوصول إلى كل هذه المعلومات. يمكنك الاطّلاع على مدة الفيديو، ومكان عرض الفيديو في التشغيل الحالي، ومعرفة ما إذا كان قد انتهى تشغيل الفيديو (أو الصوت) باستخدام رمزَي HTMLMediaElement.duration، HTMLMediaElement.currentTime، HTMLMediaElement.ended على التوالي.

واجهات العناصر المتاحة

إنّ معظم عناصر HTML التي تناولناها حتى الآن في هذه السلسلة والتي لم نتناولها بعد، باستثناء بعض عناصر التقسيم، لها واجهة DOM مرتبطة بها. تم تسمية الواجهة الأساسية لجميع العناصر بشكل مناسب باسم العنصر. يكتسِب HTMLElement سمات واجهة Element، وتكتسِب منه كل الواجهات المتعلّقة بعناصر HTML. يتم تنفيذ بعض الواجهات الخاصة بالعناصر من خلال عناصر متعددة متشابهة.

تشمل الواجهات ما يلي:

اصطلاح التسمية هو "HTML" متبوعًا بعنصر أو مجموعة من العناصر بتنسيق الأحرف اللاتينية الكبيرة، متبوعًا بـ "عنصر"، ولكن لا يتّبع الجزء الخاص بالعنصر أو مجموعة العناصر نمطًا دقيقًا. لا داعي للقلق. ليس عليك حفظ هذه الخطوات. من المهم معرفة أنّ هذه الإعدادات متوفّرة حتى تتمكّن من البحث عنها عند الحاجة.

إذا كانت لديك مجموعة من العناصر، تتوفّر أيضًا بعض واجهات المجموعات. على سبيل المثال، تعرض الطريقة HTMLCollection.namedItem() أول عنصر في المجموعة التي تتطابق سمة id أو name فيها مع المَعلمة، أو تعرض قيمة فارغة إذا لم يتطابق أي عنصر.

لا تتضمّن أكثر من 30 عنصرًا واجهة DOM مرتبطة بها غير HTMLElement، بما في ذلك <address> و<article> <section> و<nav> و<header> و<footer> و<aside> و<hgroup>. إنّ العديد من العناصر التي لا تتيح استخدام أي سمات غير متوقّفة نهائيًا وغير عالمية تتضمّن واجهات خاصة بالعناصر، مثل HTMLPElement (عنصر <p>) وHTMLUnknownElement (<😃> أو أي عناصر أخرى غير محدّدة)، ولكنّ هذه الواجهات لا تنفّذ أي خصائص أو طرق إضافية بالإضافة إلى الخصائص والطُرق المُكتسَبة من HTMLElement، وهي غير مُدرَجة أعلاه.

طرق وخصائص واجهة برمجة التطبيقات المتكرّرة

إذا كانت الواجهة تتضمّن اسم الطريقة أو السمة نفسهما اللذَين تتضمّنهما الواجهة التي تُكتسَب منها، ستحلّ الطريقة أو السمة المكتسَبة محلّ الطريقة أو السمة المُكتسَبة. بعبارة أخرى، تلغي الطرق والسمات الرئيسية السمات الفرعية. عند الوصول إلى السمةَين alt وoffsetHeight في واجهات برمجة تطبيقات عناصر HTML باستخدام imageInstance.alt و sectionInstance.offsetHeight على التوالي، لم يحدّد الرمز المبرمَج واجهة برمجة التطبيقات التي يتم الوصول إليها. بشكل عام، لا يشكّل ذلك مشكلة، كما هو الحال في هذين المثالَين.

ومع ذلك، هناك بعض الحالات التي يمكن أن يؤدي فيها التكرار إلى حدوث مشكلة. على سبيل المثال، HTMLCollection.length هي للقراءة فقط، في حين أنّ الواجهة المُكتسَبة، HTMLOptionsCollection، تتضمّن سمة length (لا يتم عرضها إلا من خلال سمة options في <select>) مع إذن الوصول للقراءة والكتابة. يمكن استخدام HTMLOptionsCollection لضبط حجم المجموعة.

الواجهات الأخرى

هناك واجهات إضافية تتيح التلاعب بمواقع الفروع لعقد DOM. ترث الواجهة EventTarget الواجهات Node وWindow، والتي تقدّم بدورها addEventListener() وremoveEventListener(). بدورها، ترث واجهات Element وDocument وDocumentFragment (التي رأيناها في العناصر المخصّصة) من Node، وترث واجهة HTMLElement من Element.

واجهة node

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

تستخدِم الدالة الشهيرة "التنقّل في DOM" التي وضعها دوغلاس كروكفورد سمتَي firstChild وnextSibling الخاصة بالعقدة.

const walk_the_DOM = function walk(node, callback) {
  callback(node);
  node = node.firstChild;
  while (node) {
    walk(node, callback);
    node = node.nextSibling;
  }
};

لقد استخدمنا طريقتَي appendChild() و cloneNode() في Node لتحديد العناصر المخصّصة. توفّر واجهة Node العديد من السمات والأساليب المفيدة لطلب البيانات من DOM ومعالجتها.

customElements.define('star-rating',
  class extends HTMLElement {
    constructor() {
      super(); // Always call super first in constructor
      const starRating = document.getElementById('star-rating-template').content;
      const shadowRoot = this.attachShadow({
        mode: 'open'
      });
      shadowRoot.appendChild(starRating.cloneNode(true));
    }
  });

الطريقة attachShadow() هي طريقة لواجهة Element. تتوفّر أيضًا واجهة shadowRoot لسمة Shadow DOM API التي يتم عرضها بشكل منفصل عن شجرة نموذج DOM الرئيسية للمستند.

واجهات Document وHTMLDocument

تستمد واجهة Document خصائصها من Node. ويمثّل صفحة الويب التي تم تحميلها في المتصفّح، سواء كان المستند بتنسيق HTML أو SVG أو XML أو MathML أو غير ذلك. ترث واجهة Document أيضًا واجهة HTMLDocument.

يتيح document الوصول السريع إلى أنواع العقد وإنشاء مجموعات من أنواع عناصر معيّنة، مثل document.body وdocument.styleSheets. يتيح عنصر HTMLDocument الوصول إلى المعلومات ذات الصلة بالمستند والتي لا يمكن العثور عليها في عقد HTML، مثل Document.location Document.lastModified وDocument.Cookie.

تتوفّر عدة واجهات برمجة تطبيقات استنادًا إلى الميزات التي تظهر من خلال واجهة المستند، بما في ذلك Drag and Drop API وFullScreen API. يكتسب كلاهما القيمة من Element.

واجهة Window

تتضمّن واجهة Window عناصر متاحة على مستوى العالم خارج DOM يمكن استخدامها للتلاعب بـ DOM. يوفّر Window الدوالّ ونطاقات الأسماء والكائنات وعناصر الإنشاء الموثَّقة في JavaScript ومراجع DOM في MDN.

واجهة Window هي واجهة برمجة التطبيقات للكائن الذي يحتوي على المستند. عنصر window الشامل هو النافذة التي يتم فيها تنفيذ النص البرمجي. تحتوي كل علامة تبويب في المتصفّح على عنصر Window خاص بها. يمكن لواجهة Window طلب البحث عن محتوى علامة التبويب بالإضافة إلى النافذة والجهاز بشكل عام. على سبيل المثال، يمكن استخدام الطريقة resizeTo() لتغيير حجم نافذة المتصفّح، وتوفّر السمة devicePixelRatio إمكانية الوصول إلى وحدات البكسل في شاشة الجهاز. عند الوصول إلى معلومات عن علامة التبويب التي يظهر فيها المحتوى بدلاً من شجرة DOM التي تعرضها علامة التبويب، من المرجّح أن تكون النافذة هي الواجهة التي تبحث عنها.

تتوفّر عدة واجهات برمجة تطبيقات استنادًا إلى الميزات التي تظهر من خلال واجهة Window، بما في ذلك واجهات برمجة التطبيقات Web Workers وIndexedDB.

التحقّق من فهمك

اختبِر معلوماتك حول واجهات برمجة التطبيقات HTML.

ما هو الحرف O في DOM؟

الاتجاه
يُرجى إعادة المحاولة.
الكائن
إجابة صحيحة.
خارجي
يُرجى إعادة المحاولة.

ما هي الواجهة التي يمكنها مساعدتك في معرفة معلومات عن علامة التبويب التي يتضمّن المحتوى؟

نافذة
إجابة صحيحة.
مستند
يُرجى إعادة المحاولة.
العقدة
يُرجى إعادة المحاولة.