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

المقدمة

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

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

تقوم قوالب المعاينة بتكوين معايير الصور المستخدمة في السمات، مما يوفر صورًا موحدة وفقًا للمواصفات المحددة في قالب المعاينة. وهذا يضمن عرضًا متسقًا للصور عبر صور المنتجات وصور المتغيرات والصور المعتمدة على السمات.

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

📖 شرح بسيط​

تحتاج كل تطبيقات التجارة الإلكترونية إلى صور منتجات متسقة عبر السمات:

  • 🎨 عينة الألوان - متغيرات لون المنتج (أحمر، أزرق، أخضر) مع صور المعاينة
  • 📏 مخططات الأحجام - صور سمات الحجم (صغير، متوسط، كبير) مع أدلة بصرية
  • 🖼️ معاينات المواد - صور سمات المواد (جلد، قطن، حرير) مع القوام
  • 💎 خيارات التشطيب - صور تشطيب السطح (لامع، غير لامع، ساتان) مع أمثلة بصرية
  • 👗 معاينات الأنماط - صور سمات الأنماط (مخطط، صلب، مزهر) مع عينات
  • 🏷️ معارض السمات - حجم صورة متسق لجميع سمات المنتجات

المشكلة مع صور السمات غير المتسقة

المشاكل:

  • 🎨 عرض غير متسق - صور السمات المختلفة لها أحجام مختلفة
  • 📊 صعوبة الصيانة - يتطلب التغيير تحرير مكونات متعددة
  • 🔄 عدم القابلية لإعادة الاستخدام - نفس منطق الحجم مكرر في كل مكان
  • 🖼️ تجربة مستخدم ضعيفة - تبدو صور السمات غير متناسقة وغير احترافية

حل TemplatePreviews

الفوائد:

  • 🎨 عرض متسق - جميع صور السمات تستخدم نفس القالب
  • 📊 صيانة سهلة - تغيير القالب في لوحة الإدارة
  • 🔄 قابل لإعادة الاستخدام - نفس القالب عبر جميع السمات
  • 🖼️ تجربة مستخدم احترافية - صور سمات متناسقة وموحدة

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

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

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

  • صور السمات - الصور المرتبطة بسمات المنتج (اللون، الحجم، المادة)
  • حجم المعاينة - الأبعاد لعرض صورة السمة
  • إعدادات القص - كيفية قص صور السمات
  • علامة - معرف فريد للإشارة إلى القالب
  • الاتساق - نفس القالب يضمن عرض موحد لصور السمات

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

كل معاينة قالب لها هذا الهيكل:

{
  id: 3,                                      // Unique identifier
  title: 'Preview Templates',                 // Template name (non-unique)
  identifier: 'preview-templates',            // Template marker (unique)
  proportions: {                              // Image parameter sets
    default: {                                // Default template configuration
      horizontal: {                           // For horizontal images
        width: 234,                           // Width in pixels
        height: 324,                          // Height in pixels
        alignmentType: 'middleBottom'         // Centering type (compression axis)
      },
      vertical: {                             // For vertical images
        width: 2,
        height: 3,
        alignmentType: 'leftTop'
      },
      square: {                               // For square images
        side: 3,                              // Side length in pixels
        alignmentType: 'leftTop'
      },
    },
  },
  version: 0,                                 // Version number
  attributeValues: {},                        // Additional attribute data
  position: 1,                                // Display position
  isUsed: false,                              // Usage status
  attributeSetIdentifier: null                // Associated attribute set
}

الحقول الرئيسية:

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

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

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

لماذا تستخدم موديل TemplatePreviews؟​

الفائدةالوصف
سمات متسقةجميع صور السمات بنفس الحجم
تحسين الصورتغيير الحجم والضغط تلقائيًا
صيانة سهلةتغيير القالب، يحدث تحديثات لجميع السمات
تجربة مستخدم أفضلعرض موحد واحترافي للسمات
تكامل CDNتسليم محسّن لصور السمات
تكوينات قابلة لإعادة الاستخدامنفس القالب لجميع عينات الألوان

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

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

لا يمكنك إنشاء معاينات القالب عبر SDK - يتم إنشاؤها في لوحة إدارة OneEntry:

OneEntry Admin Panel → Settings → Preview Templates → Create Template → Set Name/Marker → Configure Parameters → Save

عملية الإنشاء:

  • قدم اسمًا (معرف غير فريد)
  • قدم علامة (معرف فريد)
  • انقر على "إنشاء" لإنهاء

التكوين:

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

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

معاينات القالب مقابل القوالب​

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

الميزةTemplatePreviewsالقوالب
الغرضمعاينات صور السماتصور المحتوى العامة
حالة الاستخدامعينات الألوان، معاينات الموادصور البطل، صور المنتجات
النطاقسمات المنتج فقطالصفحات، الكتل، المنتجات
المثالعينة لون 50×50لافتة بطل 1920×1080

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

تطبيق القوالب على صور السمات​

يقوم OneEntry تلقائيًا بتحسين صور السمات بناءً على قوالب المعاينة

تعيين معاينة القالب​

تُعيّن قوالب المعاينة عادةً لأنواع السمات المحددة

عرض سمات متسق​

استخدم معاينات القالب لضمان عرض موحد لصور السمات

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

interface ITemplatesPreviewEntity {
  id: number;
  title: string;
  proportions: {
    default: {
      horizontal: IProportion | null;
      vertical: IProportion | null;
      square: ISquare;
    };
  };
  identifier: string;
  version: number;
  attributeValues: AttributeType;
  position: number;
  isUsed: boolean;
  attributeSetIdentifier?: string | null;
}

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

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

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

لإنشاء/تحرير معاينات القالب: استخدم لوحة إدارة OneEntry.

تحسين صورة السمة​

CDN OneEntry يقوم تلقائيًا بتحسين صور السمات بناءً على إعدادات قالب المعاينة:

  • تغيير الحجم تلقائيًا
  • تحويل التنسيق (JPEG، PNG، WebP)
  • الضغط
  • القص
  • التخزين المؤقت

ما عليك سوى الإشارة إلى علامة القالب

تخزين مؤقت لمعاينة القالب​

نادراً ما تتغير معاينات القالب - نفذ التخزين المؤقت:

  • الواجهة الأمامية: localStorage، sessionStorage
  • الواجهة الخلفية: Redis، ذاكرة التخزين المؤقت
  • TTL: ساعة واحدة موصى بها

عرض سمات متسق​

استخدم نفس قالب المعاينة لنفس نوع السمة:

  • جميع سمات الألوان → قالب color_swatch
  • جميع سمات المواد → قالب material_preview
  • جميع سمات الأنماط → قالب pattern_thumbnail

الاتساق يحسن تجربة المستخدم ويبدو احترافيًا.

أحجام القوالب الموصى بها​

أحجام صور السمات الشائعة:

  • عينات الألوان: 50×50 إلى 100×100
  • معاينات المواد: 80×80 إلى 150×150
  • صور الأنماط: 60×60 إلى 120×120
  • مخططات الأحجام: 100×80 إلى 200×150
  • معاينات التشطيب: 75×75 إلى 100×100

تقنية LQIP​

تستخدم قوالب المعاينة تقنية Low-Quality Image Placeholder (LQIP) لأداء تحميل مثالي:

كيف تعمل:

  • تعيد هيكل مصفوفة ذات عنصرين:
    1. صورة مصغرة - تنسيق WebP، محسّنة للتحميل السريع (بضع مئات من البايتات)
    2. معاينة تم إنشاؤها - صورة بدقة كاملة تحل محل الصورة المصغرة بعد التحميل

✅ الفوائد:

  • عرض فوري مع الصورة المصغرة
  • انتقال سلس إلى الجودة الكاملة
  • تقليل استهلاك النطاق الترددي
  • تجربة مستخدم أفضل

حذف القوالب​

لإزالة قالب:

  1. حدد القالب في لوحة الإدارة
  2. انقر على أيقونة الحذف
  3. أكد الإزالة

ملاحظة: يمكن حذف القوالب غير المستخدمة فقط.

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

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

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

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

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

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

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

ما هو LQTP ولماذا هو مهم؟​

LQIP (Low-Quality Image Placeholder) يقوم بتحميل صورة مصغرة صغيرة أولاً (بضع مئات من البايتات)، ثم يستبدلها بالصورة عالية الجودة. يوفر هذا ردود فعل بصرية فورية ويحسن الأداء المدرك، خاصة على الاتصالات البطيئة.

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

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

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

تُطبق قوالب المعاينة تلقائيًا عند تكوينها في لوحة الإدارة. جلب القالب عبر getTemplatesPreviewByMarker() واستخدم الأبعاد لعرض صور السمات بأحجام متسقة.

ما هي الأحجام الموصى بها لصور السمات؟​

احتفظ بصور السمات صغيرة: 50-150 بكسل لأداء مثالي. الأحجام الشائعة: عينات الألوان (50×50 إلى 100×100)، معاينات المواد (80×80 إلى 150×150)، صور الأنماط (60×60 إلى 120×120).

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

  • استخدم العلامات، وليس المعرفات - العلامات مستقرة عبر البيئات
  • قم بتخزين قوالب المعاينة مؤقتًا - تقليل استدعاءات API للبيانات التي نادرًا ما تتغير
  • أنشئ أحجام متسقة - نفس نوع السمة = نفس حجم القالب
  • استخدم تنسيق WebP - ضغط أفضل لصور السمات
  • حدد إعدادات الجودة - توازن الجودة مقابل حجم الملف (80-90 موصى به)
  • قم بربط السمات بالقوالب - أنشئ خريطة attributeType → template
  • استخدم علامات دلالية - color_swatch، وليس preview_1
  • اختبر على الهواتف المحمولة - تأكد من أن صور السمات تبدو جيدة على الشاشات الصغيرة

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

تعريف موديل TemplatePreviews​


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

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