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

المقدمة

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

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

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

تتيح لك وحدة Blocks استرجاع مكونات المحتوى القابلة لإعادة الاستخدام (الكتل) — مجموعات من السمات التي تقوم بإنشائها مرة واحدة في لوحة الإدارة وإعادة استخدامها عبر الصفحات وصفحات المنتجات: الرؤوس، والتذييلات، واللافتات، والشهادات، والمنزلقات، وودجات المنتجات/التوصيات. قم بتحديث كتلة واحدة وستتغير في كل مكان تُستخدم فيه.

SDK هو للقراءة فقط: يمكنك استرجاع الكتل هنا وإنشاءها أو تعديلها في لوحة إدارة OneEntry.

🚀 البدء السريع​

قم بتهيئة الوحدة من defineOneEntry:


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

استرجع كتلة واحدة بواسطة علامتها واقرأ سماتها:

// Fetch the "footer" block.
const block = await Blocks.getBlockByMarker("footer", "en_US");

console.log(block.identifier, block.type, block.isVisible);
// "footer" "common_block" true

// Custom fields live in attributeValues.
console.log(block.attributeValues);

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

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

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

  • identifier — علامة فريدة تُستخدم للإشارة إليها في الكود (استخدم العلامة دائمًا؛ فهي لا تتغير أبدًا)
  • localizeInfos — بيانات محلية (مثل title)، محتوى مختلف لكل لغة
  • type — نوع BlockType الذي يحدد ما تقوم الكتلة بعرضه
  • isVisible — علامة الرؤية
  • attributeValues — حقول مخصصة تقوم بتعريفها عبر AttributesSets

هيكل الكتلة​

{
  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 (marker)
  type: 'common_block', // block type
  templateIdentifier: null, // template identifier
  isVisible: true, // visibility
  attributeValues: {}, // block attributes
}

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

  • قم بالإشارة إلى الكتل بواسطة العلامة (identifier) في الكود — العلامات لا تتغير أبدًا.
  • تُنشأ الكتل في لوحة الإدارة. SDK هو للقراءة فقط.
  • الحقول المخصصة تأتي من AttributesSets. أمثلة: كتلة تذييل (حقوق الطبع والنشر، روابط اجتماعية، معلومات الاتصال)، لافتة بطل (عنوان، CTA، صورة خلفية)، شهادة (مؤلف، صورة، اقتباس، تقييم).
  • الكتل مقابل الصفحات. الصفحة هي وثيقة مكتفية ذاتيًا مع عنوان URL (مثل /about) تم إنشاؤها في وحدة الصفحات؛ الكتلة هي مكون قابل لإعادة الاستخدام تقوم بإدراجه في الصفحات.

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

الطريقةماذا تفعلمتى تستخدم
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_blockgetFrequentlyOrderedProducts()
trending_blockgetTrending()
recently_viewed_blockgetRecentlyViewed()
repeat_purchase_blockgetRepeatPurchase()
slider_blockgetSlides()
personal_recommendations_blockgetPersonalRecommendations()
cart_complement_blockgetCartComplement() / getCartComplementByProductIds()
cart_similar_blockgetCartSimilar() / getCartSimilarByProductIds()
wishlist_similar_blockgetWishlistSimilar() / getWishlistSimilarByProductIds()

تُدار كتل التخصيص (التي تم مشاهدتها مؤخرًا، الشراء المتكرر، التوصيات الشخصية، السلة/قائمة الرغبات) بواسطة نشاط المستخدم المتعقب وتعمل لكل من المستخدمين المصرح لهم والضيوف (انظر وضع الضيف).

تثبيت السعر (signPrice)​

تقبل طرق كتل المنتجات والتوصيات (getCartSimilar, getRecentlyViewed, getTrending, getPersonalRecommendations, getRepeatPurchase, getCartComplement, getFrequentlyOrderedProducts, …) وسيطًا اختياريًا signPrice. يأخذ علامة تخزين الطلب ويطلب من الخادم تثبيت أسعار المنتجات المسترجعة لفترة محدودة، بحيث يكون السعر الذي يراه العميل في ويدجت التوصية هو السعر الذي يدفعه عند الخروج.

signPrice — نوع string

علامة تخزين الطلب لتثبيت السعر. إذا تم تعيين المعامل، يتم تثبيت السعر لفترة معينة.

  • في طرق التوصية، يكون signPrice هو آخر معامل موضعي (بعد langCode).
  • في المتغيرات …ByProductIds (getCartSimilarByProductIds, getCartComplementByProductIds, …) هو حقل من body الطلب (body.signPrice).

كل منتج مسترجع يحمل بعد ذلك رمز signedPrice الذي يشفر السعر المثبت:


const products = await Blocks.getCartSimilar("cart_similar_block", "en_US", "orders");

const signedPrice = products[0].signedPrice;

➡️ أعد استخدام هذا الرمز عند إنشاء الطلب — انظر قسم سعر المنتج المثبت (signedPrice) في وحدة الطلبات. يوجد نفس معامل تثبيت السعر أيضًا في وحدة المنتجات (في userQuery.signPrice).

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

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

  • الصفحات/صفحات المنتجات — صفحات مكتفية ذاتيًا مع عناوين URL (مثل /about) تم إنشاؤها في وحدة الصفحات، والتي تضيف إليها كتل ومكونات أخرى.
  • الكتل — مكونات قابلة لإعادة الاستخدام تُدرج في الصفحات (مثل تذييل).

فكر في الصفحة كوثيقة كاملة والكتلة كفقرة تعيد استخدامها عبر الوثائق.

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

قم بتحريرها في لوحة إدارة OneEntry (قسم الكتل). يتم تحديث جميع الصفحات التي تستخدم تلك الكتلة تلقائيًا.

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

يفضل العديد من الكتل الصغيرة والمركزة (مثل header_logo, footer_social_links) على كتلة كبيرة واحدة entire_page_layout — الكتل الصغيرة أسهل في إعادة الاستخدام والصيانة.

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

تحقق من حقل isVisible في الكتلة المسترجعة.

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

قم بلف الاسترجاع في try/catch وقم بعرض بديل عندما لا يتم العثور على كتلة.

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

  • أنشئ كتل صغيرة ومركزة (مسؤولية واحدة).
  • استخدم علامات وصفية (global_footer، وليس block1)؛ بالأحرف الصغيرة مع شرطات سفلية.
  • قم بالإشارة إلى الكتل بواسطة العلامة في الكود — العلامات لا تتغير أبدًا.
  • قم بتخزين الكتل في الذاكرة — فهي تتغير نادرًا.
  • تعامل مع الكتل المفقودة بشكل سلس (try/catch).

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