वेब कॉम्पोनेंट का ओरिएंटेशन

वेब कॉम्पोनेंट में कस्टम एलिमेंट, शैडो डीओएम, और एचटीएमएल टेंप्लेट शामिल होते हैं. ये प्लैटफ़ॉर्म के ऐसे प्रिमिटिव होते हैं जिनका इस्तेमाल बार-बार किया जा सकता है और जो फ़्रेमवर्क पर निर्भर नहीं होते. इनके मार्कअप और स्टाइल, दस्तावेज़ से अलग होते हैं. इनका इस्तेमाल डिज़ाइन सिस्टम, एम्बेड किए जा सकने वाले विजेट, और सेल्फ़-कंटेन्ड यूज़र इंटरफ़ेस (यूआई) के लिए करें.

यहां दिए गए नियम, सभी तरह के कॉन्टेंट पर लागू होते हैं. अपने टास्क के लिए खास गाइड पाएं. हर गाइड में, टास्क के लिए ज़रूरी कॉन्टेक्स्ट, एपीआई, और उससे जुड़ी समस्याओं के बारे में बताया जाता है.

यह तय करना कि आपको कस्टम एलिमेंट की ज़रूरत है या नहीं

कस्टम एलिमेंट का इस्तेमाल सिर्फ़ तब करें, जब आपको किसी टैग पर एन्कैप्सुलेटेड बिहेवियर, लाइफ़साइकल या फिर से इस्तेमाल किए जा सकने वाले JS-आधारित एपीआई की ज़रूरत हो. इन मामलों में, कोई भी प्लान न बनाएं:

• सीएसएस के साथ एक सामान्य एचटीएमएल एलिमेंट का इस्तेमाल किया जा सकता है. स्टाइल किया गया <button> या <details>, फिर से लागू करने की तुलना में ज़्यादा सुलभ और सस्ता होता है.
• यह एलिमेंट सिर्फ़ प्रज़ेंटेशन के लिए है और इसका कोई व्यवहार नहीं है. नेटिव एलिमेंट पर क्लास का इस्तेमाल करने से, बेहतर परफ़ॉर्मेंस मिलती है. साथ ही, @layer या @scope का इस्तेमाल करके, क्लास को स्कोप किया जा सकता है.
• आपको सिर्फ़ सर्वर पर स्टाइल स्कोपिंग की ज़रूरत है, जिसमें कोई इंटरैक्टिविटी न हो. इसके लिए, स्कोप की गई स्टाइलशीट या डिक्लेरेटिव शैडो डीओएम (बिना अपग्रेड के) काफ़ी हो सकता है.

नेटिव सिमैंटिक को फिर से बनाना (एक कस्टम <my-button> जो फ़ोकस, ऐक्टिवेशन, और ARIA को फिर से बनाता है) सबसे आम दुरुपयोग है: आपको प्लैटफ़ॉर्म की सुलभता सुविधा का फ़ायदा बिना किसी शुल्क के सिर्फ़ तब मिलता है, जब नेटिव एलिमेंट का फिर से इस्तेमाल किया जाता है. जब <my-button>-स्टाइल रैपर की ज़रूरत होती है — आम तौर पर, शेयर किए गए स्टाइलिंग हुक, अतिरिक्त मार्कअप या नेटिव एलिमेंट से नहीं दिखाए जा सकने वाले व्यवहार के लिए — तो असली <button> को रैप करें, न कि उसे फिर से लागू करें. स्टाइल को किसी इंटरनल नेटिव एलिमेंट पर फ़ॉरवर्ड करने के लिए, वेब कॉम्पोनेंट की स्टाइलिंग देखें.

यह टेस्ट इस बात पर निर्भर करता है कि आपको एनकैप्सुलेटेड स्टेट, स्क्रिप्टेबल एपीआई या नेटिव एलिमेंट से न दिखने वाले व्यवहार की ज़रूरत है या नहीं. यह सिर्फ़ अलग लुक के बारे में नहीं है. पसंद/पसंदीदा टॉगल की ज़रूरी शर्तें: इसमें लैच की गई डोमेन स्टेट होती है, उस स्टेट को आस-पास के पेज के लिए स्टाइलिंग हुक के तौर पर दिखाया जाता है, और अपना change इवेंट भेजा जाता है. इनमें से कोई भी सुविधा, स्टाइल किए गए <button> में नहीं मिलती. ऐसा बटन जिसका रंग सिर्फ़ दबाने पर बदलता है, वह <button> + सीएसएस के लिए ज़रूरी शर्तों को पूरा नहीं करता. इसे बनाते समय, ज़रूरत के हिसाब से कस्टम स्टेट या एट्रिब्यूट का इस्तेमाल करके, इसकी स्थिति को मॉडल करें. इसके बारे में ज़्यादा जानने के लिए, कस्टम एलिमेंट देखें.

टूल को कोड बेस से मैच करना

कोई एलिमेंट कस्टम एलिमेंट होना चाहिए या नहीं, यह इस बात पर निर्भर करता है कि प्रोजेक्ट में पहले से क्या इस्तेमाल किया जा रहा है. एजेंट अक्सर ज़्यादा एब्स्ट्रैक्ट करते हैं और नए एलिमेंट तक पहुंचने के लिए बहुत उत्सुक होते हैं — अगर आपको कोई संदेह है, तो हल्का विकल्प (नेटिव एलिमेंट, सीएसएस, सर्वर टेंप्लेट) आम तौर पर सही होता है. अगर फिर से इस्तेमाल करने या व्यवहार की ज़रूरत हो, तो बाद में कस्टम एलिमेंट का इस्तेमाल किया जा सकता है. ह्यूरिस्टिक्स (तय नियम), प्राथमिकता के हिसाब से:

• कोड बेस में पहले से ही कोई कॉम्पोनेंट मॉडल (React, Vue, Svelte, …) मौजूद है. इन-ऐप्लिकेशन यूज़र इंटरफ़ेस (यूआई) के लिए, उस फ़्रेमवर्क के कॉम्पोनेंट को डिफ़ॉल्ट के तौर पर सेट करें. कस्टम एलिमेंट का इस्तेमाल सिर्फ़ तब करें, जब आपको फ़्रेमवर्क से बाहर निकलना हो या उससे आगे जाना हो: ऐप्लिकेशन या फ़्रेमवर्क के बीच शेयर किया गया डिज़ाइन-सिस्टम प्रिमिटिव, मार्कअप में डाला गया ऐसा विजेट जिसे फ़्रेमवर्क कंट्रोल नहीं करता या ऐसा आउटपुट जो सादे एचटीएमएल (ईमेल, कॉन्टेंट मैनेजमेंट सिस्टम, एसएसआर फ़्रैगमेंट) के तौर पर काम करना चाहिए. ऐप्लिकेशन में सामान्य व्यू के लिए, कोई पैरलल कॉम्पोनेंट सिस्टम न बनाएं.
• कोई टूल नहीं, ज़्यादातर स्टैटिक मार्कअप. सादे एचटीएमएल + सीएसएस या सर्वर टेंप्लेट/पार्शियल का इस्तेमाल करें. कस्टम एलिमेंट का इस्तेमाल सिर्फ़ तब किया जाता है, जब आपको टैग पर किसी व्यवहार, लाइफ़साइकल या JS-आधारित एपीआई की ज़रूरत हो. इसका इस्तेमाल सिर्फ़ मार्कअप शेयर करने के लिए नहीं किया जाता. मार्कअप शेयर करने के लिए, सर्वर में शामिल किया गया एलिमेंट या <template> का इस्तेमाल किया जाता है. इसके लिए, किसी JS की ज़रूरत नहीं होती.
• इंटरैक्टिविटी के आइलैंड के साथ स्टैटिक साइट जनरेटर. मार्कअप को स्टैटिक तौर पर रेंडर करें. कस्टम एलिमेंट को इंटरैक्टिव पार्ट के लिए रिज़र्व करें. "ज़्यादा मार्कअप, कम इंटरैक्टिविटी" के लिए, मार्कअप को लाइट डीओएम (या डिक्लेरेटिव शैडो डीओएम) में रखें. साथ ही, पसंद के मुताबिक बनाए गए छोटे एलिमेंट को धीरे-धीरे बेहतर बनाने दें. इसके लिए, जेएस से सब कुछ फिर से रेंडर करने की ज़रूरत नहीं है.
• इसके बजाय, पहले से मौजूद किसी एलिमेंट को और आगे पुश किया जा सकता है. नेटिव एलिमेंट को ज़्यादा से ज़्यादा इस्तेमाल करना (सीएसएस, कुछ लिसनर, कभी-कभी इस्तेमाल होने वाला सूडो-एलिमेंट), आम तौर पर कस्टम एलिमेंट से बेहतर होता है. ऐसा इसलिए, क्योंकि आपको प्लैटफ़ॉर्म की सुलभता और व्यवहार की सुविधाएं बिना किसी शुल्क के मिलती हैं. जब वर्कअराउंड को मैनेज करना मुश्किल हो जाए, तो कस्टम एलिमेंट का इस्तेमाल करें. ऐसा तब होता है, जब आपको एलिमेंट के पहले से मौजूद व्यवहार से परेशानी हो रही हो या ऑथरिंग का अनुभव, क्लीन कॉम्पोनेंट एपीआई से भी खराब हो जाए. किसी पहले से मौजूद एलिमेंट में थोड़ा सा JS इस्तेमाल करने की ज़रूरत पड़ने का मतलब यह नहीं है कि उसे बदल दिया जाए.

सभी पर लागू होने वाले नियम

ये दिशा-निर्देश, नीचे दी गई हर गाइड पर लागू होते हैं:

• ज़रूरी: टैग का नाम केबाब केस में होना चाहिए.साथ ही, उसमें कम से कम एक हाइफ़न होना चाहिए. जैसे, my-element. इससे कस्टम एलिमेंट, मौजूदा और आने वाले समय में उपलब्ध होने वाले बिल्ट-इन एलिमेंट से अलग दिखते हैं.
• ज़रूरी: this को ऐक्सेस करने से पहले, कंस्ट्रक्टर में सबसे पहले super() को कॉल करें. this को पढ़ने या लिखने वाले किसी भी स्टेटमेंट के बाद इसे कॉल करने पर, गड़बड़ी का मैसेज दिखता है.
• ज़रूरी: शैडो टेंप्लेट में सिमैंटिक एलिमेंट (<button>, <nav>, <ul>) का इस्तेमाल करें. शैडो ट्री में सुलभता से जुड़ी ज़्यादातर गड़बड़ियां, नॉन-सिमैंटिक मार्कअप की वजह से होती हैं. स्लॉट, प्रोजेक्ट की भूमिका को नहीं बदलता.
• ज़रूरी: ARIA id रेफ़रंस (aria-labelledby, aria-describedby, aria-controls) शैडो बाउंड्री को पार नहीं कर सकते. रेफ़रंस देने वाला एलिमेंट और वह id जिस पर वह ले जाता है, दोनों एक ही ट्री में होने चाहिए.
• attachShadow({ mode: 'open' }) को प्राथमिकता दें, ताकि डेवलपर टूल, पेज स्क्रिप्ट, और सर्वर हाइड्रेशन element.shadowRoot तक पहुंच सकें. 'closed' का इस्तेमाल सिर्फ़ तब करें, जब आपको पेज स्क्रिप्ट से इंटरनल स्ट्रक्चर को छिपाना हो.
• पसंद के मुताबिक बनाए गए बिल्ट-इन एलिमेंट (extends HTMLButtonElement के साथ is="…") का इस्तेमाल करने से बचें. Safari ने इन्हें शिप करने से हमेशा के लिए मना कर दिया है.

इस्तेमाल के उदाहरण वाली गाइड का मैट्रिक्स

टास्क की पहचान करें और उसकी गाइड पाएं: