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

المقدمة

احصل على قوالب المعاينة التي توحد حجم الصور وتنسيقها لصور سمات المنتج.

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

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

يتيح لك موديل TemplatePreviews توحيد معايير الصور عبر مشروعك. من خلال تطبيق قوالب المعاينة على سمات "الصورة" أو "مجموعة الصور"، يمكنك تقديم صور بحجم وقص متسقين وفقًا لتكوين القالب - عبر صور المنتجات، وصور المتغيرات، وصور السمات.

يمكنك إنشاء قوالب المعاينة في لوحة إدارة OneEntry (الإعدادات > قوالب المعاينة)، ويقوم هذا الموديل بجلب تلك التكوينات بحيث يتم عرض سمات المنتج التي تحتوي على صور بشكل متسق. SDK هو للقراءة فقط: لا يمكنك إنشاء قوالب المعاينة من خلاله.

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

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


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

احصل على قوالب المعاينة واقرأ نسبها:

// Fetch all preview templates, localized to English.
const previews = await TemplatePreviews.getTemplatePreviews("en_US");

previews.forEach((tpl) => {
  console.log(tpl.identifier, tpl.title, tpl.proportions.default.square);
});

// Or fetch a single preview template by its marker.
const swatch = await TemplatePreviews.getTemplatePreviewByMarker("color_swatch", "en_US");
console.log(swatch.proportions.default.horizontal);

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

ما هي معاينة القالب؟​

معاينة القالب (ITemplatesPreviewEntity) هي تكوين صورة لسمات المنتج:

  • المؤشر (identifier) - معرف فريد للإشارة إلى القالب (استخدم هذا، وليس المعرف)
  • العنوان (title) - اسم القالب المعروض في لوحة الإدارة (غير فريد)
  • النسب (proportions) - مجموعات معايير الصورة لكل اتجاه (أفقي، عمودي، مربع)
  • المحاذاة (alignmentType) - كيفية قص/مركز الصور

هيكل معاينة القالب​

interface ITemplatesPreviewEntity {
  id: number;
  title: string;
  proportions: {
    default: {
      horizontal: IProportion | null;   // { width, height, alignmentType }
      vertical: IProportion | null;     // { width, height, alignmentType }
      square: ISquare;                  // { side, alignmentType }
    };
  };
  identifier: string;
  version: number;
  attributeValues: IAttributeValues;
  position: number;
  isUsed: boolean;
  attributeSetIdentifier?: string | null;
}

قيمة عينة لـ proportions:

{
  default: {
    horizontal: { width: 234, height: 324, alignmentType: "middleBottom" },
    vertical:   { width: 2,   height: 3,   alignmentType: "leftTop" },
    square:     { side: 3,    alignmentType: "leftTop" },
  },
}

سير عمل معاينة القالب​

1. Create preview template in admin panel
   (Define proportions for attribute images)
   ↓
2. Assign template to an attribute type
   (e.g., "Color" attribute uses "color_swatch")
   ↓
3. Fetch templates via SDK
   (TemplatePreviews.getTemplatePreviews())
   ↓
4. Apply proportions to attribute images
   (Render images with consistent sizing)
   ↓
5. Consistent attribute image display
   (All color swatches same size)

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

يتم إنشاء قوالب المعاينة في لوحة الإدارة​

لا يمكنك إنشاء قوالب المعاينة عبر SDK - يتم إنشاؤها في لوحة إدارة OneEntry (الإعدادات > قوالب المعاينة). يحتاج كل قالب إلى اسم (غير فريد) ومؤشر فريد، بالإضافة إلى مجموعات نسب لثلاثة اتجاهات للصورة:

  • أفقي - العرض، الارتفاع، نوع المحاذاة
  • عمودي - العرض، الارتفاع، نوع المحاذاة
  • مربع - طول الجانب، نوع المحاذاة

SDK مخصص لـ جلب تكوينات قوالب المعاينة، وليس لإنشائها.

استخدم المؤشرات، وليس المعرفات​

قم بالإشارة إلى قوالب المعاينة بواسطة المؤشر (identifier) في كودك - المؤشرات مستقرة عبر البيئات. استخدم getTemplatePreviewByMarker(marker) لقالب واحد و getTemplatePreviews() لجميعها.

TemplatePreviews مقابل Templates​

TemplatePreviews مخصصة بشكل خاص لـ صور سمات المنتج:

الميزةTemplatePreviewsTemplates
الغرضمعاينات صور السماتعرض المحتوى العام
حالة الاستخدامعيّنات الألوان، معاينات الموادصور البطل، تخطيطات المنتجات
النطاقسمات المنتجات فقطالصفحات، الكتل، المنتجات

أفضل ممارسة: استخدم TemplatePreviews لصور السمات، وTemplates للمحتوى العام.

التخزين المؤقت​

تتغير قوالب المعاينة نادرًا - قم بتخزينها مؤقتًا (localStorage/sessionStorage في الواجهة الأمامية، Redis/ذاكرة في الخلفية؛ ~1 ساعة TTL هو نقطة انطلاق معقولة).

📊 جدول المرجع السريع​

الطريقةالوصفحالة الاستخدام
getTemplatePreviews()الحصول على جميع قوالب المعاينةقائمة بجميع قوالب السمات المتاحة
getTemplatePreviewByMarker()الحصول على قالب معاينة بواسطة المؤشرجلب تكوين قالب محدد

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

ما الفرق بين TemplatePreviews وTemplates؟​

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

كيف يمكنني تكوين أحجام مختلفة للصور الأفقية والعمودية والمربعة؟​

في لوحة الإدارة، قم بتكوين جميع الاتجاهات الثلاثة لكل قالب معاينة. يقوم النظام بالكشف عن اتجاه الصورة ويطبق مجموعة النسب المطابقة (أفقي، عمودي، أو مربع).

هل يمكنني تعيين قوالب معاينة مختلفة لأنواع السمات المختلفة؟​

نعم. أنشئ قوالب معاينة متعددة بمؤشرات مختلفة (مثل color_swatch، material_preview، pattern_thumbnail) وقم بتعيين كل منها لنوع السمة المناسب لضمان عرض متسق.

كيف يمكنني تطبيق قالب معاينة على صور السمات؟​

احصل على القالب عبر getTemplatePreviewByMarker() واستخدم نسبه لعرض صور السمات بأحجام متسقة. يتم تعيين قالب لنوع السمة في لوحة الإدارة.

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

  • استخدم المؤشرات، وليس المعرفات - المؤشرات مستقرة عبر البيئات.
  • استخدم مؤشرات دلالية - color_swatch، وليس preview_1.
  • قم بربط السمات بالقوالب - احتفظ بقالب واحد لكل نوع سمة لضمان الاتساق.
  • قم بتخزين قوالب المعاينة مؤقتًا - قلل من استدعاءات API للبيانات التي نادرًا ما تتغير.

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