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

المقدمة

إدارة منتجات التجارة الإلكترونية مع كتالوجات ديناميكية، وتصفية، وبحث.

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

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

يتيح الكتالوج إنشاء، وتحميل، وتحرير، وتصفية الكتالوجات من خلال واجهة بديهية. بالإضافة إلى التجارة الإلكترونية، يدعم تطبيقات بديلة مثل معارض الوسائط المتعددة، مما يوضح مرونته كأداة لإدارة المحتوى.

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

📖 شرح بسيط​

تخيل أنك تبني متجرًا إلكترونيًا يبيع:

  • 👟 أحذية رياضية - مع أحجام، وألوان، وأسعار
  • 📱 إلكترونيات - مع مواصفات، وصور، ومراجعات
  • 👕 ملابس - مع أحجام، ومواد، وبدائل
  • 📚 كتب - مع مؤلفين، وأسعار، ووصف

✅ بدلاً من ترميز كل منتج، أنت:

  • تضيف المنتجات في لوحة إدارة OneEntry (مع جميع التفاصيل)
  • تجلب المنتجات ديناميكيًا باستخدام هذا الموديل
  • تصفّي حسب الفئة، ونطاق السعر، والتوافر
  • تبحث عن المنتجات حسب الاسم أو الوصف
  • ترتب حسب السعر، والتاريخ، والشعبية
  • تحدث الأسعار/المخزون دون إعادة نشر

مثال من العالم الحقيقي:

❌ بدون موديل المنتجات (ترميز ثابت):
- إضافة منتج جديد → تغيير الكود → نشر
- تغيير السعر → تغيير الكود → نشر
- 1000 منتج = ملف كود ضخم

✅ مع موديل المنتجات (ديناميكي):
- إضافة منتج جديد → تحديث في الإدارة → يظهر مباشرة
- تغيير السعر → تحديث في الإدارة → يظهر مباشرة
- 10,000 منتج = استدعاءات API بسيطة

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

ما هو المنتج؟​

المنتج هو عنصر تبيعه، يحتوي على:

  • معلومات أساسية - الاسم، الوصف، SKU، السعر
  • صور - صور المنتج، المعرض
  • بدائل - أحجام، وألوان، وخيارات (مثل "تي شيرت أحمر حجم M")
  • المخزون - كمية المخزون، التوافر
  • سمات مخصصة - أي حقول تحددها (علامة تجارية، مادة، وزن، إلخ)
  • SEO - عنوان ميتا، وصف، كلمات مفتاحية
  • الحالة - نشط، مسودة، غير متوفر
  • التعريب - دعم متعدد اللغات

هيكل المنتج​

يمكن أن تحتوي المنتجات على هياكل مختلفة:

النوعالوصفالمثال
منتج بسيطعنصر واحد، بدون بدائلكتاب، ملصق
منتج مع بدائلخيارات متعددة (حجم، لون)تي شيرت (S/M/L، أحمر/أزرق)
منتج رقميعناصر قابلة للتنزيلكتاب إلكتروني، برنامج
حزمةمجموعة من المنتجاتحزمة البداية، مجموعة هدايا

تنظيم المنتج​

تُنظم المنتجات من خلال عدة ميزات رئيسية:

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

مثال على الهيكل:

📁 إلكترونيات
  ├─ 📱 هواتف ذكية
  │   ├─ آيفون 15 برو
  │   └─ سامسونج جالاكسي S24
  └─ 💻 حواسيب محمولة
      ├─ ماك بوك برو
      └─ ديل XPS

📁 ملابس
  ├─ 👕 تي شيرتات
  └─ 👖 جينز

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

هيكل الكتالوج​

مهم: فئات الكتالوج هي صفحات من نوع الكتالوج تم إنشاؤها من خلال موديل الصفحات. تحتاج إلى إنشاء فئات الكتالوج أولاً قبل إضافة المنتجات.

ميزات الكتالوج:

  • علامة تبويب المنتجات - مساحة العمل الرئيسية لإنشاء وإدارة عناصر الكتالوج
  • مرشحات المنتجات - البحث السريع باستخدام معايير محددة
  • روابط المنتجات - ربط المنتجات بناءً على معايير السمات (مثل، جميع الهواتف السوداء)
  • حالات المنتجات - شروط تصفية إضافية للتنظيم
  • تحميل الكتالوج - استيراد بيانات الكتالوج بكميات كبيرة
  • الإعدادات - خيارات التكوين مع حقول إدخال رقمية

طرق الحصول على المنتجات​

الطريقةمتى تستخدمهاالمثال
getProducts()قائمة المنتجات مع المرشحات/البحثصفحة كتالوج المتجر
getProductsByPageId()المنتجات من فئة معينة (حسب ID)صفحة الفئة
getProductsByPageUrl()المنتجات من فئة معينة (حسب URL)صفحة الفئة حسب URL
getProductById()الحصول على منتج واحد حسب IDصفحة تفاصيل المنتج
getRelatedProductsById()الحصول على منتجات ذات صلة/مشابهةقسم "قد تعجبك أيضًا"
searchProduct()البحث عن المنتجات حسب الاستعلاموظيفة البحث

شرح الترقيم ببساطة​

عندما يكون لديك 1000 منتج، لا تقوم بتحميلها جميعًا دفعة واحدة:

صيغة الإزاحة: offset = (pageNumber - 1) * limit

خيارات الترتيب​

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

sortKeyماذا يفعلمثال الاستخدام
priceترتيب حسب السعرعرض الأرخص أولاً
dateترتيب حسب تاريخ الإنشاءعرض أحدث المنتجات
titleترتيب أبجديقائمة المنتجات من A إلى Z
positionترتيب مخصص (افتراضي)ترتيب مختار من الإدارة
idترتيب حسب IDترتيب تقني

ترتيب:

  • ASC (تصاعدي) - من الأقل إلى الأعلى (A→Z، 0→9، رخيص→غالي)
  • DESC (تنازلي) - من الأعلى إلى الأقل (Z→A، 9→0، غالي→رخيص)

تصفية المنتجات​

استخدم المرشحات لتضييق النتائج:

علامات الشرط:

العلامةالمعنىالمثال
eqيساوي (مطابقة دقيقة)السعر = 50$
neqلا يساويالحالة ≠ "نفد"
inيحتوي على (واحد من)اللون في ["أحمر"، "أزرق"]
ninلا يحتوي علىالفئة ليست في ["أرشيف"]
mthأكبر منالسعر > 100$
lthأقل منالسعر < 50$
exsموجود (له قيمة)لديه خصم
nexsغير موجود (فارغ)لا يوجد خصم

حالة المنتج والروابط​

حالات المنتجات تخلق شروط تصفية إضافية تتجاوز عوامل التصفية الموجودة لتنظيم المنتجات بشكل أكثر تعقيدًا.

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

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

الطريقةالوصفحالة الاستخدام
getProducts()الحصول على جميع المنتجات مع التصفية/الترتيبصفحة الكتالوج الرئيسية
getProductById()الحصول على منتج واحد حسب IDصفحة تفاصيل المنتج
getProductsByPageId()الحصول على المنتجات من الفئة حسب IDصفحة الفئة
getProductsByPageUrl()الحصول على المنتجات من الفئة حسب URLصفحة الفئة حسب URL
getRelatedProductsById()الحصول على منتجات ذات صلة/مشابهةقسم "قد تعجبك أيضًا"
searchProduct()البحث عن المنتجات حسب الاستعلاموظيفة البحث
getProductsCount()الحصول على إجمالي عدد المنتجاتمعلومات الترقيم
getProductsCountByPageId()الحصول على عدد المنتجات حسب ID الفئةترقيم الفئة
getProductsCountByPageUrl()الحصول على عدد المنتجات حسب URL الفئةترقيم الفئة
getProductBlockById()الحصول على كتلة المنتج حسب IDكتل محتوى المنتج
getProductsEmptyPage()الحصول على هيكل صفحة المنتجات الفارغةمعالجة الحالة الفارغة
getProductsPriceByPageUrl()الحصول على أسعار المنتجات حسب URL الفئةتصفية الأسعار

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

هل يمكنني التصفية حسب معايير متعددة في وقت واحد؟​

نعم! يمكنك دمج عدة مرشحات في مصفوفة.

كيف أتعامل مع بدائل المنتجات (الأحجام، الألوان)؟​

تُخزن بدائل المنتجات في attributeValues.

كيف أطبق زر "تحميل المزيد"؟​

استخدم الإزاحة لتحميل المزيد من المنتجات.

هل يمكنني عرض المنتجات من فئات متعددة؟​

نعم، استخدم علامة الشرط category in.

كيف أطبق قسم "الوافدين الجدد"؟​

رتب حسب تاريخ الإنشاء أو استخدم الفئة الأم للترتيب اليدوي.

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

إعداد فئات الكتالوج​

مهم: قبل إضافة المنتجات، يجب عليك إنشاء فئات الكتالوج من خلال موديل الصفحات. فئات الكتالوج هي صفحات من نوع الكتالوج.

سير العمل:

  1. انتقل إلى موديل الصفحات في لوحة الإدارة
  2. أنشئ صفحات من نوع "كتالوج"
  3. تصبح هذه الصفحات فئات منتجاتك
  4. أضف المنتجات إلى هذه الفئات عبر كتالوج > منتجات

ميزات الكتالوج​

يوفر موديل الكتالوج أدوات شاملة:

  • علامة تبويب المنتجات - مساحة العمل الرئيسية لإنشاء/إدارة عناصر الكتالوج
  • مرشحات المنتجات - تمكين البحث السريع باستخدام معايير محددة
  • روابط المنتجات - ربط المنتجات ذات الصلة بناءً على السمات
  • حالات المنتجات - إنشاء شروط تصفية مخصصة
  • تحميل الكتالوج - استيراد المنتجات بكميات كبيرة
  • الإعدادات - تكوين سلوك الكتالوج

ما وراء التجارة الإلكترونية​

لا يقتصر الكتالوج على المنتجات - يمكن استخدامه لـ:

  • معارض الوسائط المتعددة - صور، فيديوهات، مجموعات فنون
  • عناصر المحفظة - أعمال تصميم، دراسات حالة
  • مكتبات الوثائق - موارد، تنزيلات
  • كتالوجات الأحداث - مؤتمرات، ندوات عبر الإنترنت
  • مجموعات الوصفات - طعام، مشروبات، طهي

تحسين الأداء​

قم بتخزين المنتجات التي يتم الوصول إليها بشكل متكرر لتقليل استدعاءات API وتحسين أوقات التحميل.

دائمًا تصفية المنتجات النشطة​

في الإنتاج، اعرض دائمًا المنتجات النشطة فقط عن طريق التصفية باستخدام statusId: 1.

التعامل مع الصور المفقودة​

قدم صور احتياطية للمنتجات التي لا تحتوي على صور للحفاظ على واجهة مستخدم متسقة.

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

  • استخدم دائمًا الترقيم (الحد + الإزاحة)
  • تصفية حسب statusId: 1 في الإنتاج
  • تخزين قوائم المنتجات لتقليل استدعاءات API
  • التعامل مع "نفد المخزون" بشكل لطيف
  • تقديم صور احتياطية
  • استخدام علامات للمنتجات المميزة (وليس IDs)
  • تنفيذ البحث مع تأخير
  • إضافة حالات تحميل في واجهة المستخدم

مزيد من المعلومات حول الكتالوج في لوحة إدارة OneEntry: https://doc.oneentry.cloudhttps://doc.oneentry.cloud/docs/category/catalog

تعريف موديل المنتجات​


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

هذا الموديل يقبل مجموعة من معلمات المستخدم تسمى userQuery. إذا لم يتم تمرير المعلمات إلى الطريقة، سيتم تطبيق القيمة الافتراضية. بعض الطرق تقبل الجسم كمعامل للتصفية. إذا كنت لا تريد إعداد الترتيب، مرر مصفوفة فارغة أو لا تمرر أي شيء.

المعلمات:


const userQuery = {
    offset: 0,
    limit: 30,
    sortOrder: 'DESC',
    sortKey: 'id',
}

المخطط

offset: number
معامل الترقيم. الافتراضي 0
مثال: 0

limit: number
معامل الترقيم. الافتراضي 30
مثال: 30

sortKey: string
الحقل المستخدم للترتيب (الافتراضي غير محدد - الترتيب حسب الموضع، القيم الممكنة: id، title، date، price، position)
القيم المتاحة: id، position، title، date، price

sortOrder: string
ترتيب الترتيب DESC | ASC (الافتراضي DESC)
مثال: "DESC"

بشكل افتراضي، يمكنك استرجاع 10 كائنات. وذلك بسبب حد السجل في إعدادات أذونات الموديل.
لعمل الترقيم بشكل صحيح، تحتاج إلى تكوين أذونات الموديل وفقًا لاحتياجاتك في القسم المقابل.

"conditionMarker" الذي يتم من خلاله تصفية القيم (غير محدد بشكل افتراضي)، القيم الممكنة:

'in' - يحتوي على,
'nin' - لا يحتوي على,
'eq' - يساوي,
'neq' - لا يساوي,
'mth' - أكبر من,
'lth' - أقل من,
'exs' - موجود,
'nexs' - غير موجود

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