مقدمة حول مكوّنات الويب

مكوّنات الويب هي عناصر مخصّصة وShadow DOM ونماذج HTML: وهي العناصر الأساسية في المنصة للمكوّنات القابلة لإعادة الاستخدام وغير المرتبطة بإطار عمل معيّن، والتي يتم تضمين ترميزها وأنماطها في المستند. ويمكنك استخدامها لأنظمة التصميم والتطبيقات المصغّرة القابلة للتضمين وواجهة المستخدم المستقلة.

القواعد أدناه شاملة. استرِدّ الدليل المحدّد للمهمة التي تريد تنفيذها، فكل دليل يعيد صياغة السياق الذي يحتاجه ويوثّق واجهات برمجة التطبيقات والأخطاء الفريدة له.

تحديد ما إذا كنت بحاجة إلى عنصر مخصّص

لا تستخدِم عنصرًا مخصّصًا إلا عندما تحتاج إلى سلوك مغلَّف أو مراحل نشاط أو واجهة برمجة تطبيقات مستندة إلى JavaScript وقابلة لإعادة الاستخدام في علامة. لا تنشئ مهارة في الحالات التالية:

• يكفي استخدام عنصر HTML عادي مع CSS، لأنّ استخدام <button> أو <details> منسَّق يسهّل الوصول إلى المحتوى ويقلّل التكلفة مقارنةً بإعادة التنفيذ.
• هذا العنصر هو مجرد عنصر عرض بدون سلوك. إنّ استخدام فئة على عنصر أصلي يوفّر أداءً أفضل ويمكن تحديد نطاقه باستخدام @layer أو @scope.
• تحتاج فقط إلى تحديد نطاق الأنماط على الخادم بدون أي تفاعل، وقد تكون ورقة الأنماط المحدّدة النطاق أو نموذج Shadow DOM التعريفي (بدون ترقية) كافية.

إنّ إعادة إنشاء الدلالات الأصلية (عنصر <my-button> مخصّص يعيد إنشاء التركيز والتفعيل وARIA) هي أكثر حالات إساءة الاستخدام شيوعًا: يمكنك الاستفادة من ميزات تسهيل الاستخدام في المنصة مجانًا فقط إذا أعدت استخدام العنصر الأصلي. عندما يكون استخدام برنامج تضمين على نمط <my-button> مضمونًا، عادةً ما يكون ذلك من أجل استخدام عناصر ربط مشتركة للأنماط أو ترميز إضافي أو سلوك لا يمكن لعنصر أصلي التعبير عنه، يمكنك تضمين العنصر <button> الحقيقي بدلاً من إعادة تنفيذه (راجِع تنسيق مكوّنات الويب لإعادة توجيه الأنماط إلى عنصر أصلي داخلي).

يتمثل الاختبار في ما إذا كنت بحاجة إلى حالة مغلفة أو واجهة برمجة تطبيقات قابلة للبرمجة أو سلوك لا يمكن للعنصر الأصلي التعبير عنه، وليس مجرد مظهر مختلف. يُعدّ زر الإعجاب/المفضّلة مؤهلاً: فهو يحمل حالة النطاق المغلق، ويعرض هذه الحالة كخطاف تصميم للصفحة المحيطة، ويرسل حدث change الخاص به، ولا يمنحك أي من هذه العناصر <button> منسقًا. الزر الذي يتغيّر لونه فقط عند الضغط عليه لا يفي بالغرض: استخدِم <button> وCSS. عند إنشائه، يمكنك تصميم حالته باستخدام حالة أو سمة مخصّصة حسب الاقتضاء (راجِع العناصر المخصّصة).

مطابقة الأداة مع قاعدة الرموز البرمجية

يعتمد تحديد ما إذا كان يجب أن يكون العنصر مخصّصًا على ما يستخدمه المشروع حاليًا. يميل الوكلاء إلى الإفراط في التجريد والوصول إلى عنصر جديد بشغف كبير، وعند الشك، يكون الخيار الأسهل (عنصر أصلي أو CSS أو نموذج خادم) هو الخيار الصحيح عادةً، ويمكنك الترقية إلى عنصر مخصّص لاحقًا إذا كانت إعادة الاستخدام أو السلوك يتطلبان ذلك فعليًا. الإعدادات الإرشادية، حسب الأولوية التقريبية:

• تحتوي قاعدة الرموز البرمجية على نموذج مكوّنات (React أو Vue أو Svelte أو غيرها). يمكنك استخدام مكوّن إطار العمل هذا تلقائيًا لواجهة المستخدم داخل التطبيق. لا تستخدِم العناصر المخصّصة إلا عندما يكون من الضروري أن يتجاوز العنصر إطار العمل أو يستمر بعده: مثل عنصر أساسي في نظام التصميم تتم مشاركته بين التطبيقات أو أُطر العمل، أو تطبيق مصغّر يتم إدراجه في ترميز لا يتحكّم فيه إطار العمل، أو مخرجات يجب أن تعمل كملف HTML عادي (البريد الإلكتروني، أو نظام إدارة المحتوى، أو أجزاء العرض من جهة الخادم). لا تستخدِم نظام مكوّنات موازٍ لطرق العرض العادية داخل التطبيق.
• لا يتطلب استخدام أدوات، ويعتمد في الغالب على الترميز الثابت. يُفضَّل استخدام HTML وCSS العاديَين أو نموذج/جزء من الخادم. يُعدّ العنصر المخصّص مفيدًا فقط عندما تحتاج إلى سلوك أو مراحل نشاط أو واجهة برمجة تطبيقات مستندة إلى JS في العلامة، وليس فقط لمشاركة الترميز الذي يتضمّنه الخادم أو <template> بدون إرسال أي رمز JS.
• منشئ مواقع إلكترونية ثابتة مع جُزر تفاعلية اعرض الترميز بشكل ثابت، واحتفظ بالعنصر المخصّص للجزء التفاعلي. بالنسبة إلى "الترميز الكثير والتفاعل القليل"، احتفِظ بالترميز في Light DOM (أو Declarative Shadow DOM) واسمح لعنصر مخصّص صغير بتحسينه تدريجيًا، بدلاً من إعادة عرض كل شيء من JS.
• يمكنك بدلاً من ذلك استخدام عنصر مدمج بشكل أكبر. من الأفضل عادةً استخدام عنصر أصلي إلى أقصى حد ممكن (CSS، وبعض المستمعين، والعنصر الزائف العرضي) بدلاً من عنصر مخصّص، لأنّك تحتفظ بإمكانية الوصول إلى المنصة وسلوكها مجانًا. انتقِل إلى عنصر مخصّص عندما تتوقف الحلول البديلة عن الصيانة، أي عندما تواجه السلوك المضمّن للعنصر، أو تصبح تجربة التأليف أسوأ من واجهة برمجة تطبيقات المكوّنات النظيفة. إنّ الحاجة إلى استخدام القليل من JS في عنصر مضمّن ليست سببًا كافيًا لاستبداله.

القواعد الشاملة

تنطبق هذه الإرشادات على كل دليل أدناه:

• إلزامي: يجب أن يكون اسم العلامة بتنسيق kebab-case مع شرطة واحدة على الأقل (مثل my-element)، لأنّ ذلك يميّز العناصر المخصّصة عن العناصر المضمّنة الحالية والمستقبلية.
• MANDATORY: call super() first in the constructor, before touching this; calling it after any statement that reads or writes this throws.
• إلزامي: استخدِم العناصر الدلالية (<button> و<nav> و<ul>) داخل نماذج الظل. تحدث معظم حالات فشل تسهيل الاستخدام في أشجار الظل بسبب الترميز غير الدلالي، حيث لا تغيّر الفتحة دور ما تعرضه.
• إلزامي: لا يمكن لمراجع ARIA id (aria-labelledby وaria-describedby وaria-controls) تجاوز حدود الظل، ويجب أن يكون العنصر المرجعي وid الذي يشير إليه في الشجرة نفسها.
• يُفضَّل استخدام attachShadow({ mode: 'open' }) لكي تتمكّن أدوات المطوّرين والنصوص البرمجية للصفحة وعملية ترطيب الخادم من الوصول إلى element.shadowRoot. استخدِم 'closed' فقط عندما تحتاج إلى إخفاء البنية الداخلية عن نصوص الصفحة البرمجية.
• تجنَّب العناصر المضمّنة المخصّصة (extends HTMLButtonElement مع is="…")، لأنّ Safari رفض نهائيًا إرسالها.

مصفوفة دليل حالات الاستخدام

حدِّد المهمة واسترجع دليلها: