جهت‌گیری اجزای وب

«مؤلفه‌های وب» عبارت‌اند از «عناصر سفارشی»، Shadow DOM، و «الگوهای HTML»: اصول اولیه پلاتفرم برای مؤلفه‌های قابل‌استفاده مجدد و مستقل از چارچوب که نشان‌گذاری و سبک‌های آن‌ها از سند کپسوله‌سازی شده‌اند. از آن‌ها برای سیستم‌های طراحی، ابزاره‌های جاسازی‌شدنی، و واسط کاربر مستقل استفاده کنید.

قوانین زیر چندجانبه هستند. راهنمای خاص برای تکلیف موردنظر را بازیابی کنید؛ هر راهنما بافت موردنیاز خود را مجدداً بیان می‌کند و میاناهای برنامه‌سازی کاربردی و مشکلات منحصربه‌فرد آن را مستند می‌کند.

تصمیم بگیرید که آیا اصلاً به عنصر سفارشی نیاز دارید یا نه

فقط زمانی از عنصر سفارشی استفاده کنید که به رفتار کپسوله‌شده، چرخه حیات، یا میانای برنامه‌سازی کاربردی با پشتیبانی JS با قابلیت استفاده مجدد در برچسب نیاز دارید. در شرایط زیر، نباید آن را بسازید:

• یک عنصر HTML ساده با CSS کافی است. یک <button> یا <details> با سبک‌دهی، دسترس‌پذیرتر و ارزان‌تر از پیاده‌سازی مجدد است.
• این چیز صرفاً نمایشی است و هیچ رفتاری ندارد. کلاس در عنصر بومی عملکرد بهتری دارد و با @layer یا @scope قابل‌محدودسازی است.
• فقط به محدوده سبک در سرور بدون تعامل نیاز دارید؛ برگه سبک نگارش محدودشده یا Declarative Shadow DOM (بدون ارتقا) ممکن است کافی باشد.

بازسازی معناشناسی بومی (یک <my-button> سفارشی که تمرکز، فعال‌سازی، و ARIA را بازآفرینی می‌کند) رایج‌ترین سوءاستفاده است: تنها درصورتی‌که از عنصر بومی مجدداً استفاده کنید، دسترس‌پذیری پلاتفرم را به‌طور رایگان به ارث می‌برید. وقتی که یک پوشاننده به سبک <my-button> تضمین می‌شود — معمولاً برای قلاب‌های سبک‌بندی مشترک، نشانه‌گذاری اضافی، یا رفتاری که یک عنصر بومی نمی‌تواند بیان کند — <button> واقعی را بپوشانید به‌جای اینکه آن را دوباره پیاده‌سازی کنید (برای ارسال سبک‌ها به یک عنصر بومی داخلی، به سبک‌بندی مؤلفه‌های وب مراجعه کنید).

آزمون این است که آیا به حالت کپسوله‌شده، میانای برنامه‌سازی کاربردی اسکریپت‌پذیر، یا رفتاری که عنصر بومی نمی‌تواند بیان کند نیاز دارید یا نه — نه صرفاً ظاهری متفاوت. کلید ضامن پسندیدن/موردعلاقه واجدشرایط است: این کلید وضعیت دامنه قفل‌شده را حمل می‌کند، آن وضعیت را به‌عنوان قلاب سبک‌دهی برای صفحه اطراف نشان می‌دهد، و رویداد change خودش را ارسال می‌کند — هیچ‌کدام از این‌ها را <button> سبک‌دهی‌شده به شما نمی‌دهد. دکمه‌ای که فقط هنگام فشار دادن تغییر رنگ می‌دهد، به <button> + CSS نمی‌رسد. وقتی آن را می‌سازید، وضعیت آن را با وضعیت یا مشخصه سفارشی مناسب مدل‌سازی کنید (به عناصر سفارشی مراجعه کنید).

ابزار را با پایگاه کد مطابقت دهید

اینکه چیزی باید عنصر سفارشی باشد یا نه به این بستگی دارد که پروژه درحال‌حاضر از چه چیزی استفاده می‌کند. عوامل معمولاً بیش‌ازحد انتزاعی عمل می‌کنند و با اشتیاق زیاد به سراغ عناصر جدید می‌روند — درصورت تردید، گزینه سبک‌تر (عنصر بومی، CSS، الگوی سرور) معمولاً درست است و اگر استفاده مجدد یا رفتار واقعاً ایجاب کند، می‌توانید بعداً آن را به عنصر سفارشی ارتقا دهید. اکتشاف، با اولویت تقریبی:

• پایگاه کد ازقبل مدل مؤلفه دارد (React،‏ Vue،‏ Svelte،‏ …). به‌طور پیش‌فرض از مؤلفه آن چارچوب برای میانای کاربر درون‌برنامه استفاده کنید. فقط زمانی به‌سراغ عنصر سفارشی بروید که آن چیز باید از چارچوب فرار کند یا بیشتر از آن عمر کند: یک عنصر اولیه سیستم طراحی که بین برنامه‌ها یا چارچوب‌ها مشترک است، یک ابزاره که در نشانه‌گذاری‌ای که چارچوب کنترل نمی‌کند قرار داده شده است، یا خروجی‌ای که باید به‌عنوان HTML ساده کار کند (ایمیل، CMS، قطعات SSR). برای نماهای درون‌برنامه معمولی، سیستم مؤلفه موازی راه‌اندازی نکنید.
• بدون ابزار، عمدتاً نشانه‌گذاری ایستا. HTML + CSS ساده یا الگو/جزئی سرور را ترجیح دهید. عنصر سفارشی فقط زمانی ارزش استفاده دارد که واقعاً به رفتار، چرخه حیات، یا میانای برنامه‌سازی کاربردی مبتنی بر جاوااسکریپت در برچسب نیاز داشته باشید — نه صرفاً برای هم‌رسانی نشان‌گذاری، که یک سرور شامل یا <template> بدون ارسال هیچ جاوااسکریپتی انجام می‌دهد.
• تولیدکننده سایت ایستا با جزایر تعاملی. نشانه‌گذاری را به‌صورت ایستا رندر کنید؛ عنصر سفارشی را برای بخش تعاملی رزرو کنید. برای «نشانه‌گذاری زیاد، تعامل کم»، نشانه‌گذاری را در Light DOM (یا Declarative Shadow DOM) نگه دارید و اجازه دهید یک عنصر سفارشی کوچک به‌تدریج آن را بهبود بخشد، به‌جای اینکه همه چیز را از JS بازپرداز کند.
• به‌جای آن می‌توانید عنصر داخلی را بیشتر فشار دهید. استفاده از یک عنصر بومی تا حد امکان (CSS، چند شنونده، عنصر شبه گاه‌به‌گاه) معمولاً به یک عنصر سفارشی ترجیح داده می‌شود، زیرا شما دسترسی‌پذیری و رفتار پلتفرم را به‌طور رایگان حفظ می‌کنید. وقتی راه‌حل‌های موقت دیگر قابل‌حفظ نباشند، به عنصر سفارشی روی بیاورید — یعنی زمانی که مجبور باشید با رفتار داخلی عنصر مبارزه کنید یا تجربه نوشتن بدتر از یک API مؤلفه تمیز شود. نیاز به کمی جاوااسکریپت در یک عنصر داخلی، به‌خودی‌خود، دلیلی برای جایگزینی آن نیست.

قوانین متقاطع

این موارد در همه راهنماهای زیر اعمال می‌شود:

• اجباری: نام برچسب باید قالب کبابی با حداقل یک خط تیره باشد (برای مثال، my-element). این همان چیزی است که عناصر سفارشی را از عناصر داخلی فعلی و آینده متمایز می‌کند.
• اجباری: ابتدا super() را در سازنده فراخوانی کنید، قبل‌از اینکه this را لمس کنید؛ فراخوانی آن پس‌از هر عبارتی که this را می‌خواند یا می‌نویسد، خطا ایجاد می‌کند.
• اجباری: از عناصر معنایی (<button>، <nav>، <ul>) در الگوهای سایه استفاده کنید. بیشتر خرابی‌های دسترس‌پذیری در درخت‌های سایه ناشی از نشانه‌گذاری غیرمعنایی است؛ شکاف نقش آنچه را که نمایش می‌دهد تغییر نمی‌دهد.
• اجباری: ارجاع‌های ARIA id (aria-labelledby، aria-describedby، aria-controls) نمی‌توانند از مرز سایه عبور کنند؛ عنصر ارجاع‌دهنده و id که به آن اشاره می‌کند باید در یک درخت باشند.
• attachShadow({ mode: 'open' }) را ترجیح دهید تا ابزارهای توسعه، اسکریپت‌های صفحه، و آب‌رسانی سرور بتوانند به element.shadowRoot دسترسی پیدا کنند. از 'closed' فقط زمانی استفاده کنید که باید ساختار داخلی را از اسکریپت‌های صفحه پنهان کنید.
• از عناصر توکار سفارشی‌شده (extends HTMLButtonElement با is="…") اجتناب کنید؛ Safari برای همیشه از ارائه آن‌ها خودداری کرده است.

ماتریس راهنمای مورد استفاده

تکلیف را شناسایی کنید و راهنمای آن را بازیابی کنید: