المقدمة
كتل المحتوى القابلة لإعادة الاستخدام التي يمكن استخدامها عبر صفحات متعددة.
مزيد من المعلومات حول واجهة مستخدم الوحدة https://doc.oneentry.cloud/docs/category/blocks
🎯 ماذا تفعل هذه الوحدة؟
تتيح لك وحدة Blocks استخدام مكونات المحتوى القابلة لإعادة الاستخدام (الكتل) التي تحتوي على مجموعات من السمات ويمكن استخدامها عبر صفحات متعددة وصفحات المنتجات - مثل الرؤوس، والتذييلات، واللافتات، والشهادات، أو أي محتوى متكرر.
فكر في الأمر ككتل LEGO لموقعك الإلكتروني - تقوم بإنشاء كتلة مرة واحدة، وتعيد استخدامها في كل مكان تحتاجه. قم بتغيير الكتلة مرة واحدة، وستتحدث تلقائيًا في كل مكان.
📖 شرح بسيط
تخيل أنك تبني موقعًا إلكترونيًا يحتوي على:
- 🔝 رأس - شعار، قائمة تنقل (نفس الشيء في كل صفحة)
- 🔽 تذييل - معلومات الاتصال، روابط التواصل الاجتماعي (نفس الشيء في كل صفحة)
- 📢 لافتة ترويجية - عرض خاص (تظهر في صفحات متعددة)
- ⭐ شهادات - مراجعات العملاء (تُستخدم في أماكن مختلفة)
- 📞 نموذج الاتصال - يظهر في صفحات متعددة
بدلاً من نسخ هذا المحتوى إلى كل صفحة:
- ✅ أنشئ مرة واحدة ككتلة
- ✅ أدخل الكتلة حيثما تحتاجها
- ✅ قم بالتحديث في مكان واحد → التغييرات تحدث في كل مكان تلقائيًا
- ✅ حافظ على محتواك DRY (لا تكرر نفسك)
مثال من العالم الحقيقي:
بدون الكتل (نسخ ولصق):
- تحديث التذييل → تحرير 50 صفحة يدويًا ❌
- إضافة رابط اجتماعي → تحديث في كل مكان ❌
- محتوى غير متسق عبر الصفحات ❌
مع الكتل (قابلة لإعادة الاستخدام):
- تحديث كتلة التذييل → تغييرات على جميع الصفحات الـ 50 على الفور ✅
- إضافة رابط اجتماعي → تحديث مرة واحدة ✅
- دائمًا متسق ✅
✨ المفاهيم الأساسية
ما هي الكتلة؟
الكتلة هي مكون محتوى قابل لإعادة الاستخدام يحتوي على:
- المحتوى - نصوص، صور، روابط، أي بيانات
- السمات - حقول مخصصة تحددها
- المؤشر - معرف فريد للإشارة إليها
- الحالة - نشط، مسودة، مؤرشف
قابلية إعادة استخدام الكتل
يمكن استخدام الكتل:
- ✅ على صفحات متعددة وإذا تم تحديث الكتل، يتم تحديثها في كل مكان
- ✅ محلية (محتوى مختلف لكل لغة)
📋 ما تحتاج إلى معرفته
أفضل الممارسات: استخدم دائمًا المؤشرات في كودك (فهي لا تتغير أبدًا).
هيكل الكتلة
كل كتلة تحتوي على هذه الحقول الرئيسية:
{
id: 3, // unique ID
localizeInfos: { // block localized data
title: 'Block', // block localized title
},
version: 0, // block version
position: 1, // block position in array of blocks
identifier: 'block', // block identifier
type: 'common_block', // block type
templateIdentifier: null, // template identifier
isVisible: true, // visibility
attributeValues: {}, // block attributes
}
السمات المخصصة
تستخدم الكتل AttributesSets للحقول المخصصة:
أمثلة:
- كتلة التذييل: نص حقوق الطبع والنشر، روابط التواصل الاجتماعي، معلومات الاتصال
- لافتة البطل: عنوان، عنوان فرعي، زر CTA، صورة خلفية
- شهادة: اسم المؤلف، صورة، اقتباس، تقييم
- نموذج الاتصال: تكوين الحقول، نص زر الإرسال
تعلم المزيد: انظر وحدة AttributesSets
📊 جدول مرجعي سريع - الطرق الشائعة
| الطريقة | ماذا تفعل | متى تستخدم |
|---|---|---|
| getBlocks() | الحصول على جميع الكتل (مقيدة، مصفاة) | قائمة بجميع الكتل المتاحة |
| getBlockByMarker() | الحصول على كتلة بواسطة المؤشر | جلب كتلة معينة في الكود |
| searchBlock() | البحث عن الكتل | جلب الكتل |
| getFrequentlyOrderedProducts() | المنتجات التي تم طلبها بشكل متكرر | "غالبًا ما يتم طلبها معًا" |
| getCartComplement() | "أكمل سلتك" حسب سياق السلة | البيع المتقاطع من السلة |
| getCartComplementByProductIds() | "أكمل سلتك" حسب معرفات المنتجات | البيع المتقاطع للمنتجات المعطاة |
| getCartSimilar() | "مماثل للسلة" حسب سياق السلة | بدائل لعناصر السلة |
| getCartSimilarByProductIds() | "مماثل للسلة" حسب معرفات المنتجات | بدائل للمنتجات المعطاة |
| getWishlistSimilar() | "مماثل لقائمة الرغبات" حسب قائمة الرغبات | بدائل لعناصر قائمة الرغبات |
| getWishlistSimilarByProductIds() | "مماثل لقائمة الرغبات" حسب معرفات المنتجات | بدائل للمنتجات المعطاة |
| getPersonalRecommendations() | التوصيات الشخصية | تغذية المنتجات المخصصة |
| getRecentlyViewed() | المنتجات التي تم مشاهدتها مؤخرًا | "المنتجات التي تم مشاهدتها مؤخرًا" |
| getRepeatPurchase() | المنتجات للشراء المتكرر | "اشترِ مرة أخرى" |
| getTrending() | المنتجات الرائجة | "الرائجة الآن" |
| getSlides() | شجرة شرائح كتلة السلايدر | عرض سلايدر/دوار |
🧩 أنواع الكتل
تحدد type للكتلة (الـ BlockType) ما يتم عرضه. بالإضافة إلى الأنواع الأساسية (common_block, product_block, similar_products_block, form, وغيرها)، الأنواع التالية من كتل المنتجات والتخصيص متاحة:
| نوع الكتلة | الطريقة |
|---|---|
frequently_ordered_block | getFrequentlyOrderedProducts() |
trending_block | getTrending() |
recently_viewed_block | getRecentlyViewed() |
repeat_purchase_block | getRepeatPurchase() |
slider_block | getSlides() |
personal_recommendations_block | getPersonalRecommendations() |
cart_complement_block | getCartComplement() / getCartComplementByProductIds() |
cart_similar_block | getCartSimilar() / getCartSimilarByProductIds() |
wishlist_similar_block | getWishlistSimilar() / getWishlistSimilarByProductIds() |
تستند كتل التخصيص (التي تم مشاهدتها مؤخرًا، الشراء المتكرر، التوصيات الشخصية، السلة/قائمة الرغبات) إلى نشاط المستخدم المتعقب وتعمل لكل من المستخدمين المصرح لهم والضيوف (انظر وضع الضيف).
❓ الأسئلة الشائعة (FAQ)
ما الفرق بين الكتل والصفحات؟
- الصفحات/صفحات المنتجات - صفحات مكتفية ذاتيًا تمامًا مع عناوين URL (مثل
/about) يمكنك إضافة كتل ومكونات صفحة أخرى يمكن إعادة استخدامها عبر صفحات متعددة. - الكتل - مكونات قابلة لإعادة الاستخدام يتم إدراجها في الصفحات (مثل، التذييل)
فكر في الأمر كالتالي:
- الصفحة = وثيقة كاملة
- الكتلة = فقرة تعيد استخدامها في مستندات متعددة
كيف يمكنني تحديث محتوى كتلة؟
قم بتحديثه في OneEntry لوحة الإدارة:
- انتقل إلى قسم الكتل
- ابحث عن كتلتك (مثل "التذييل")
- تحرير السمات
- حفظ
جميع الصفحات التي تستخدم تلك الكتلة تتحدث تلقائيًا! ✨
هل يجب أن أنشئ العديد من الكتل الصغيرة أم عدد قليل من الكتل الكبيرة؟
العديد من الكتل الصغيرة هو الأفضل:
✅ جيد (صغير، مركز):
- header_logo
- header_navigation
- footer_copyright
- footer_social_links
❌ تجنب (كبير جدًا):
- entire_page_layout (contains everything)
لماذا؟ الكتل الصغيرة أسهل في إعادة الاستخدام والصيانة.
كيف يمكنني إظهار/إخفاء الكتل بشكل شرطي؟
تحقق من حقل 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لمعاينة التغييرات
تعريف وحدة الكتل
const { Blocks } = defineOneEntry( "your-project-url", { "token": "your-app-token" });
🔗 الوثائق ذات الصلة
- وحدة الصفحات - إدارة الصفحات التي تستخدم الكتل
- وحدة AttributesSets - تعريف سمات الكتل
- وحدة المنتجات - استخدام الكتل في صفحات المنتجات