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

Templates

جلب قوالب العرض التي تتحكم في كيفية عرض الصفحات والكتل والمنتجات في تطبيقك.

مزيد من المعلومات حول القوالب في لوحة إدارة OneEntry: https://doc.oneentry.cloud/docs/category/templates (يفتح في علامة تبويب جديدة)

تصف القوالب بنية كياناتك ومظهرها خارج الشيفرة. تنشئها في لوحة إدارة OneEntry (Settings > Templates) وتربطها بمكوّناتك؛ وتجلبها وحدة Templates، فيمكنك تغيير طريقة عرض الكيان بتبديل قالبه، دون إعادة النشر.

بدء سريع​

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


const {  } = defineOneEntry(
  , {
    
  }
);

اجلب القوالب واقرأ تهيئتها:

// Fetch all templates of a given BlockType.
const productTemplates = await Templates.getTemplateByType("product", "en_US");
if ('statusCode' in productTemplates) throw new Error(productTemplates.message);

productTemplates.forEach((tpl) => {
  console.log(tpl.identifier, tpl.title, tpl.generalTypeName);
});

// Or fetch a single template by its marker.
const card = await Templates.getTemplateByMarker("product_thumbnail", "en_US");
if ('statusCode' in card) throw new Error(card.message);
console.log(card.attributeValues);

كائن القالب​

القالب (ITemplateEntity) تهيئة عرض تحدد كيفية ظهور المحتوى:

  • generalTypeName: فئة الكيان التي ينطبق عليها القالب، وهي BlockType مثل product أو common_page أو common_block أو form أو order.
  • title: اسم القالب المعروض في لوحة الإدارة. ليس فريدًا.
  • identifier: العلامة الفريدة التي تشير إليها في الكود.
  • attributeValues: خريطة قيم السمات مفهرسة بالعلامة.
  • attributeSetIdentifier: مجموعة السمات المرتبطة، إن وُجدت.
interface ITemplateEntity {
  id: number;                              // Unique identifier
  title: string;                           // Template name (non-unique)
  identifier: string;                      // Template marker (unique)
  generalTypeId: number;                   // Type ID reference
  version: number;                         // Version number
  generalTypeName: BlockType;              // General type name
  attributeSetIdentifier: string | null;   // Associated attribute set
  attributeValues: IAttributeValues;       // Map of attribute values keyed by marker
  position: number;                        // Sort position
}

أنواع القوالب​

نوع القالب هو generalTypeName الخاص به، وهو قيمة من BlockType. تقبل getTemplateByType(type) قيمة BlockType نفسها. القيم الشائعة:

النوعفئة الكيانأمثلة على حالات الاستخدام
productالمنتجاتتفاصيل المنتج، عرض المنتج
catalog_pageصفحات الكتالوجقوائم الفئات، نتائج البحث
common_pageالصفحات العاديةتدوينة، صفحة هبوط، صفحة من نحن
error_pageصفحات الأخطاءصفحة 404، صفحة 500، تخطيطات أخطاء مخصّصة
common_blockكتل المحتوىبطاقات المحتوى، اللافتات، الأقسام، عناصر الواجهة
formالنماذجنموذج الاتصال، نموذج التسجيل، الاستبيان
orderالطلباتتأكيد الطلب، سجل الطلبات
serviceكيانات الخدماتمحتوى متعلق بالخدمات. لا تقبله getTemplateByType() بعد

تفشل getTemplateByType('service') حاليًا بالخطأ 400 (type must be a valid enum value). هذه مشكلة معروفة في المنصة.

إنشاء القوالب​

SDK للقراءة فقط: لا يمكنك إنشاء القوالب من خلاله. أنشئها في لوحة إدارة OneEntry (Settings > Templates). يحتاج كل قالب إلى اسم (ليس فريدًا)، وعلامة فريدة، ونوع (فئة الكيان التي ينطبق عليها).

جلب القوالب​

أشِر إلى القوالب في الكود بالعلامة (identifier)، لا بالمعرّف: العلامات ثابتة عبر البيئات، أما المعرّفات فليست كذلك. استخدم getTemplateByMarker(marker) لقالب واحد، وgetTemplateByType(type) لجميع القوالب من BlockType واحد، وgetAllTemplates() لكل القوالب مجمّعة حسب النوع.

تُعيد getTemplateByMarker() كائن IError (statusCode: 404) عندما لا يحمل أي قالب تلك العلامة. وتُعيد getTemplateByType() مصفوفة فارغة عندما لا تكون للنوع قوالب، وIError (statusCode: 400) عندما لا يكون النوع BlockType صالحًا. تُعيد getAllTemplates() حاليًا كائنًا فارغًا ({}) بدلًا من IError عند فشل الطلب (مثلًا، مع رمز تطبيق غير صالح)، لذا تحقّق من النتيجة الفارغة.

نادرًا ما تتغير القوالب، لذا فهي مرشّحة جيدة للتخزين المؤقت.

Templates مقابل TemplatePreviews​

تضبط القوالب عرض المحتوى العام (الصفحات والكتل والمنتجات). أما TemplatePreviews فتحدد كيف تقصّ OneEntry الصور إلى معاينات لسمات الصور والملفات المرفوعة.

الطرق​

الطريقةالوصفحالة الاستخدام
getAllTemplates()جلب جميع القوالب مجمّعة حسب النوععرض جميع القوالب المتاحة
getTemplateByType()جلب القوالب حسب نوع الكيانجلب قوالب نوع كيان محدد
getTemplateByMarker()جلب قالب حسب العلامةجلب إعدادات قالب محدد

ذات صلة​