توسيع العناصر المضمّنة

يحدد المعيار نوعين من العناصر المخصّصة: العناصر المستقلة، التي توسّع HTMLElement وتُستخدم كـ <my-card>، والعناصر المضمّنة المخصّصة، التي توسّع فئة مضمّنة محددة وتُستخدم كـ <button is="my-button">. وترث العناصر المضمّنة المخصّصة دلالات العناصر الأصلية تلقائيًا.

لا يحصل <my-button> المستقل على أي من سلوك <button> المضمّن — فلا تفعيل بالضغط على Enter أو Space، ولا مشاركة في النماذج، ولا role="button" لتقنيات المساعدة. أما الزر المضمّن المخصّص (is="my-button") فيرث كل ذلك تلقائيًا.

وسّع فئة HTML المحددة بدلًا من HTMLElement: class MyButton extends HTMLButtonElement {}. يحتفظ العنصر بكل سلوكه المضمّن — إرسال النماذج، وإدارة التركيز، وحالة التعطيل — وتضيف تحسيناتك فوق ذلك.

customElements.define("my-button", MyButton, { extends: "button" }). يخبر المعامل الثالث السجلَّ بعلامة HTML المضمّنة التي يوسّعها العنصر. وبدونه، يفشل التسجيل بإطلاق استثناء.

استخدم العناصر المضمّنة المخصّصة مع سمة is على العلامة الموجودة: <button is="my-button">Click</button>. أما كتابة <my-button> بدلًا من ذلك فتنشئ عنصرًا مستقلًا وتفقده السلوك المضمّن.

رفض Safari تنفيذ العناصر المضمّنة المخصّصة، مستندًا إلى مخاوف تتعلق بإمكانية الوصول. وهي تعمل في Chrome وEdge وFirefox؛ أما في Safari فتُتجاهل سمة is ويتصرف العنصر كأنه <button> عادي. استخدم polyfill الرسمي عند الحاجة إلى دعم Safari.

يعيد polyfill @ungap/custom-elements دعم العناصر المضمّنة المخصّصة في Safari. وهو صغير الحجم ويحظى بصيانة جيدة؛ أدرجه عندما يحتاج فريقك إلى دعم المتصفحات المختلفة دون التخلي عن نمط سمة is.

إذا كان دعم Safari دون polyfill مهمًا، فأنشئ عنصرًا مستقلًا بدلًا من ذلك وكرّر السلوك المطلوب يدويًا: أضف role="button" وtabindex="0" ومعالجات لوحة المفاتيح لـ Enter وSpace، واربطه بالنماذج عبر واجهة ElementInternals API.

يمكن للعناصر المستقلة المشاركة في إرسال النماذج عبر تعيين static formAssociated = true واستخدام this.attachInternals(). ويوفر كائن ElementInternals الناتج الدالتين setFormValue وsetValidity للتكامل الكامل مع النماذج.

اختر العناصر المضمّنة المخصّصة للمكونات التي تتصرف في الغالب مثل عنصر مضمّن، كزر متطور أو حقل إدخال ذكي، عندما تكون منصتك تدعم Chrome وFirefox أو عندما تقبل استخدام polyfill. واختر العناصر المستقلة للمكونات الجديدة بالكامل، مثل البطاقات ومربعات الحوار، التي لا يوجد لها نظير مضمّن.

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

ما الميزة العملية لتوسيع HTMLButtonElement، أي إنشاء عنصر مضمّن مخصّص، بدلًا من توسيع HTMLElement، أي إنشاء عنصر مستقل، لمكوّن يشبه الزر؟

توسّع العناصر المضمّنة المخصّصة فئة HTML محددة، مثل HTMLButtonElement أو HTMLInputElement، وتُستخدم عبر سمة is، مع وراثة كل السلوك الأصلي. سجّلها باستخدام خيار { extends: "button" }. لا يدعم Safari هذه العناصر أصلًا — فاستخدم polyfill أو عناصر مستقلة مع تكرار السلوك يدويًا عند الحاجة إلى دعم كامل للمتصفحات المختلفة.