المقدمة

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

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

موديل 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.

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

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

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

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

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

سير العمل:

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

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

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

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

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

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

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

تحسين الأداء

قم بتخزين المنتجات التي يتم الوصول إليها بشكل متكرر لتقليل استدعاءات 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"

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

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

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

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

المقدمة

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

📖 شرح بسيط​

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

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

هيكل المنتج​

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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