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

المقدمة

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

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

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

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

📖 شرح بسيط​

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

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

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

المشاكل:

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

حل TemplatePreviews

الفوائد:

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

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

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

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

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

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

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

{
  id: 3,                                      // معرف فريد
  title: 'قوالب المعاينة',                     // اسم القالب (غير فريد)
  identifier: 'preview-templates',            // علامة القالب (فريدة)
  proportions: {                              // مجموعات معايير الصورة
    default: {                                // تكوين القالب الافتراضي
      horizontal: {                           // للصور الأفقية
        width: 234,                           // العرض بالبكسل
        height: 324,                          // الارتفاع بالبكسل
        alignmentType: 'middleBottom'         // نوع التمركز (محور الضغط)
      },
      vertical: {                             // للصور الرأسية
        width: 2,
        height: 3,
        alignmentType: 'leftTop'
      },
      square: {                               // للصور المربعة
        side: 3,                              // طول الجانب بالبكسل
        alignmentType: 'leftTop'
      },
    },
  },
  version: 0,                                 // رقم الإصدار
  attributeValues: {},                        // بيانات السمة الإضافية
  position: 1,                                // موضع العرض
  isUsed: false,                              // حالة الاستخدام
  attributeSetIdentifier: null                // مجموعة السمات المرتبطة
}

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

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

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

1. إنشاء قالب المعاينة في لوحة الإدارة
   (حدد الحجم لصور السمات)
   ↓
2. تعيين القالب لنوع السمة
   (على سبيل المثال، تستخدم سمة "اللون" "color_swatch")
   ↓
3. جلب القوالب عبر SDK
   (TemplatePreviews.getTemplatePreviews())
   ↓
4. تطبيق القالب على صور السمات
   (استخدم علامة القالب في عناوين الصور)
   ↓
5. عرض متسق لصورة السمة
   (جميع عينات الألوان بنفس الحجم)

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

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

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

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

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

لوحة إدارة OneEntry → الإعدادات → قوالب المعاينة → إنشاء قالب → تعيين الاسم/العلامة → تكوين المعايير → حفظ

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

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

التكوين:

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

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

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

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

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

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

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

يقوم 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)​

ما الفرق بين قوالب المعاينة والقوالب؟​

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

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

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

ما هو 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"
  }
);

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