بناء Widget قابل لإعادة الاستخدام بـ Web Components بدون Framework

أحيانًا تحتاج ودجت صغيرًا: بطاقة حالة، زر مشاركة، عداد، أو صندوق بحث. تحميل Framework كامل من أجل عنصر واحد قد يكون مبالغة، بينما Web Components تعطيك عناصر مخصصة يمكن إدراجها داخل HTML عادي. توضح MDN أن المنظومة تعتمد على Custom Elements وShadow DOM وHTML Templates، ويمكن تسجيل العنصر عبر customElements.define() [1].

فكرة الودجت

سننشئ عنصرًا اسمه ignis-status يقرأ خاصيتي label وvalue. واجهته الخارجية بسيطة، لكن تفاصيل CSS تظل داخل Shadow DOM حتى لا تتصادم مع موقع يضمّنه.

<ignis-status label="Build" value="Ready"></ignis-status>
<script type="module" src="/widgets/status.js"></script>

الهيكل الأساسي

const template = document.createElement('template');
template.innerHTML = `<style>:host{display:block;font:600 14px system-ui}.card{padding:14px;border:1px solid #ddd;border-radius:12px}.value{color:#b54b16}</style><div class="card"><span class="label"></span>: <strong class="value"></strong></div>`;
class IgnisStatus extends HTMLElement {
  static observedAttributes = ['label','value'];
  constructor(){ super(); this.attachShadow({mode:'open'}).append(template.content.cloneNode(true)); }
  connectedCallback(){ this.render(); }
  attributeChangedCallback(){ this.render(); }
  render(){ this.shadowRoot.querySelector('.label').textContent=this.getAttribute('label')||'Status'; this.shadowRoot.querySelector('.value').textContent=this.getAttribute('value')||'—'; }
}
customElements.define('ignis-status', IgnisStatus);

API صغيرة أفضل من تعقيد زائد

اجعل الخصائص قليلة وموثقة، واستخدم أحداثًا فقط عندما يحتاج الموقع الأب إلى معرفة تغيير داخلي. لا تجعل الودجت يقرأ localStorage أو يرسل بيانات إلى خدمة خارجية من غير تصريح. إذا كان يحتاج API، مرر الرابط أو البيانات بوضوح، وأظهر حالة loading وerror بدل ترك مساحة فارغة.

اختبار الدمج

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

مراجع رسمية

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

1. MDN — Web Components