انتقل إلى المحتوى الرئيسي

المقدمة

قم بإنشاء كتل محتوى قابلة لإعادة الاستخدام يمكن استخدامها عبر صفحات متعددة.

🎯 ماذا يفعل هذا الوحدة؟​

تتيح لك وحدة Blocks استخدام مكونات محتوى قابلة لإعادة الاستخدام (كتل) تحتوي على مجموعات من السمات ويمكن استخدامها في صفحات متعددة - مثل الرؤوس، والتذييلات، واللافتات، والشهادات، أو أي محتوى متكرر.

فكر في الأمر ككتل LEGO لموقعك الإلكتروني - تقوم بإنشاء كتلة مرة واحدة، وتعيد استخدامها في كل مكان تحتاجه. قم بتغيير الكتلة مرة واحدة، وستتحدث في كل مكان تلقائيًا.

📖 شرح بسيط​

تخيل أنك تبني موقعًا إلكترونيًا يحتوي على:

  • 🔝 رأس - شعار، قائمة تنقل (نفس الشيء في كل صفحة)
  • 🔽 تذييل - معلومات الاتصال، روابط اجتماعية (نفس الشيء في كل صفحة)
  • 📢 لافتة ترويجية - عرض خاص (يظهر في صفحات متعددة)
  • ⭐ شهادات - مراجعات العملاء (تُستخدم في أماكن مختلفة)
  • 📞 نموذج الاتصال - يظهر في صفحات متعددة

بدلاً من نسخ هذا المحتوى إلى كل صفحة:

  • ✅ أنشئ مرة واحدة ككتلة
  • ✅ أدخل الكتلة حيثما تحتاجها
  • ✅ قم بالتحديث في مكان واحد → التغييرات تحدث في كل مكان تلقائيًا
  • ✅ حافظ على محتواك DRY (لا تكرر نفسك)

مثال من العالم الحقيقي:

بدون كتل (نسخ ولصق):

  • تحديث التذييل → تحرير 50 صفحة يدويًا ❌
  • إضافة رابط اجتماعي → تحديث في كل مكان ❌
  • محتوى غير متسق عبر الصفحات ❌

مع الكتل (قابلة لإعادة الاستخدام):

  • تحديث كتلة التذييل → تغييرات على جميع الصفحات الـ 50 على الفور ✅
  • إضافة رابط اجتماعي → تحديث مرة واحدة ✅
  • دائمًا متسق ✅

✨ المفاهيم الأساسية​

ما هي الكتلة؟​

الكتلة هي مكون محتوى قابل لإعادة الاستخدام يحتوي على:

  • المحتوى - نص، صور، روابط، أي بيانات
  • السمات - حقول مخصصة تحددها
  • المؤشر - معرف فريد للإشارة إليه
  • الحالة - نشط، مسودة، مؤرشف

الكتلة مقابل الصفحة​

الميزةالصفحةالكتلة
الغرضمحتوى صفحة كاملةمكون قابل لإعادة الاستخدام
الرابطلها رابط خاص بها (/about)لا رابط (مضمنة)
الاستخدامتُعرض مباشرةتُدرج في الصفحات
المثالصفحة من نحنتذييل، رأس

الفرق الرئيسي: الصفحات هي وجهات، الكتل هي لبنات البناء.

أنواع الكتل الشائعة​

كتل نموذجية قد تقوم بإنشائها:

نوع الكتلةمحتوى المثالحيث تُستخدم
رأسشعار، قائمة تنقل، بحثكل صفحة
تذييلاتصال، روابط، حقوق الطبعكل صفحة
لافتة بطلصورة كبيرة + زر CTAالصفحة الرئيسية، صفحات الهبوط
شهاداتمراجعات العملاءصفحات متعددة
نموذج الاتصالنموذج بريد إلكترونيصفحة الاتصال، النوافذ المنبثقة
لافتة ترويجيةتنبيه عرض خاصصفحات مختارة
روابط اجتماعيةأيقونات فيسبوك، تويترتذييل، شريط جانبي
اشتراك في النشرة الإخباريةصندوق اشتراك بالبريد الإلكترونيتذييل، مدونة

قابلية إعادة استخدام الكتل​

يمكن أن تكون الكتل:

  • ✅ مستخدمة في صفحات متعددة
  • ✅ محدثة مرة واحدة، تنعكس في كل مكان
  • ✅ محلية (محتوى مختلف لكل لغة)

📋 ما تحتاج لمعرفته​

تحديد الكتلة​

ثلاث طرق لتحديد الكتل:

الطريقةمتى تستخدمالمثال
قائمة الكللوحة تحكم المسؤول، محدد الكتلgetBlocks()
حسب المؤشرالإشارة في الكود (أفضل ممارسة)footer, header, promo_banner
بحث عن الكتلالإشارات الداخليةsearchBlock('foo')

أفضل ممارسة: استخدم دائمًا المؤشرات في كودك (فهي لا تتغير أبدًا).

هيكل الكتلة​

كل كتلة تحتوي على هذه الحقول الرئيسية:

{
  id: 3, // معرف فريد
  localizeInfos: { // بيانات الكتلة المحلية
    title: 'Block', // عنوان الكتلة المحلي
  },
  version: 0, // إصدار الكتلة
  position: 1, // موضع الكتلة في مصفوفة الكتل
  identifier: 'block', // معرف الكتلة
  type: 'common_block', // نوع الكتلة
  templateIdentifier: null, // معرف القالب
  isVisible: true, // الرؤية
  attributeValues: {}, // سمات الكتلة
}

السمات المخصصة​

تستخدم الكتل AttributeSets للحقول المخصصة:

أمثلة:

  • كتلة التذييل: نص حقوق الطبع، روابط اجتماعية، معلومات الاتصال
  • لافتة البطل: عنوان رئيسي، عنوان فرعي، زر CTA، صورة خلفية
  • شهادة: اسم المؤلف، صورة، اقتباس، تقييم
  • نموذج الاتصال: تكوين الحقول، نص زر الإرسال

تعرف على المزيد: انظر وحدة AttributeSets

📊 جدول مرجعي سريع - الطرق الشائعة​

الطريقةماذا تفعلمتى تستخدم
getBlocks()الحصول على جميع الكتل (مقيدة، مصفاة)قائمة بجميع الكتل المتاحة
getBlockByMarker()الحصول على كتلة حسب المؤشرجلب كتلة معينة في الكود
searchBlock()البحث عن الكتلجلب الكتل

❓ الأسئلة الشائعة (FAQ)​

ما الفرق بين الكتل والصفحات؟​

  • الصفحات - صفحات كاملة مستقلة مع روابط (مثل، /about)
  • الكتل - مكونات قابلة لإعادة الاستخدام تُدرج في الصفحات (مثل، التذييل)

فكر في الأمر كالتالي:

  • الصفحة = وثيقة كاملة
  • الكتلة = فقرة تعيد استخدامها في مستندات متعددة

كيف يمكنني تحديث محتوى كتلة؟​

قم بتحديثه في لوحة تحكم OneEntry:

  1. انتقل إلى قسم الكتل
  2. ابحث عن كتلتك (مثل، "التذييل")
  3. تحرير السمات
  4. حفظ

جميع الصفحات التي تستخدم تلك الكتلة تتحدث تلقائيًا! ✨

هل يجب أن أنشئ العديد من الكتل الصغيرة أم عدد قليل من الكتل الكبيرة؟​

العديد من الكتل الصغيرة هو الأفضل:

✅ جيد (صغير، مركز):

- header_logo
- header_navigation
- footer_copyright
- footer_social_links

❌ تجنب (كبير جدًا):

- entire_page_layout (يحتوي على كل شيء)

لماذا؟ الكتل الصغيرة أسهل في إعادة الاستخدام والصيانة.

هل يمكنني استخدام نفس الكتلة عدة مرات في صفحة واحدة؟​

نعم! جلب مرة واحدة، عرض عدة مرات.

كيف يمكنني إظهار/إخفاء الكتل بشكل شرطي؟​

تحقق من statusId و isVisible

هل يمكنني إنشاء كتل ديناميكيًا عبر API؟​

SDK هو للقراءة فقط. لإنشاء كتل، استخدم لوحة تحكم OneEntry.

كيف يمكنني التعامل مع الكتل المفقودة بشكل سلس؟​

استخدم دائمًا try/catch

💡 ملاحظات مهمة​

أفضل ممارسات مؤشرات الكتل​

✅ أسماء مؤشرات جيدة:

  • وصفية: global_footer, homepage_hero
  • استخدم الشرطات السفلية: contact_form
  • أحرف صغيرة: promo_banner
  • تشير إلى النطاق: global_header مقابل blog_header

❌ أسماء مؤشرات سيئة:

  • عامة: block1, content
  • مسافات: my block
  • حالة مختلطة: MyBlock, ProMoBanner

تخزين الكتل​

تتغير الكتل نادرًا → خزّنها!

🎓 أفضل الممارسات​

  • أنشئ كتل صغيرة ومركزة (مسؤولية واحدة)
  • استخدم مؤشرات وصفية (footer، وليس block1)
  • خزّن الكتل لتقليل استدعاءات API
  • تعامل مع الكتل المفقودة بشكل سلس (try/catch)
  • وثق ما هي كل كتلة
  • حافظ على هيكل الكتلة متسقًا
  • اختبر تغييرات الكتلة قبل النشر
  • استخدم statusId لمعاينة التغييرات

مزيد من المعلومات حول واجهة مستخدم الوحدة https://doc.oneentry.cloud/docs/blocks/introduction

تعريف وحدة الكتل​


const { Blocks } = defineOneEntry(
  "your-project-url", {
    "token": "your-app-token"
  }
);

🔗 الوثائق ذات الصلة​