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

مقدمة

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

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

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

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

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

🚀 بدء سريع​

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


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

استرجع صفحة من المنتجات واقرأ حقولها:

// Fetch the first 20 products (empty body = no filters).
const { items, total } = await Products.getProducts([], "en_US", { limit: 20 });

console.log(`Loaded ${items.length} of ${total} products`);

items.forEach((product) => {
  console.log(product.id, product.localizeInfos.title, product.price);
});

تشارك معظم طرق الإدراج نفس الشكل: فلتر اختياري body، وlangCode، و**userQuery** اختياري (ت pagination/ترتيب). انظر المعلمات أدناه لمجموعة كاملة.

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

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

الـ منتج هو كيان كتالوجي (IProductsEntity) يتكون من:

  • معلومات أساسية - localizeInfos (العنوان، إلخ)، sku، price
  • صور - صور المنتج / المعرض (مخزنة كخصائص)
  • خصائص مخصصة - أي حقول تحددها (attributeValues): العلامة التجارية، المادة، الحجم، اللون، المتغيرات، المخزون، …
  • التعريب - محتوى لكل لغة

لا توجد أنواع منتجات ثابتة في SDK — أي هيكل (متغيرات، خيارات، تنزيلات، حزم) يتم نمذجته مع الخصائص المخصصة التي تقوم بتكوينها للكتالوج.

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

تُنظم المنتجات من خلال عدة ميزات كتالوجية:

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

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

📁 Electronics
  ├─ 📱 Smartphones
  │   ├─ iPhone 15 Pro
  │   └─ Samsung Galaxy S24
  └─ 💻 Laptops
      ├─ MacBook Pro
      └─ Dell XPS

📁 Clothing
  ├─ 👕 T-Shirts
  └─ 👖 Jeans

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

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

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

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

توفر لوحة تحكم الكتالوج أيضًا تحميل الكتالوج بالجملة، فلاتر المنتجات، روابط المنتجات، حالات المنتجات، وإعدادات لكل كتالوج.

الترقيم​

لا تقم بتحميل كل شيء دفعة واحدة — انتقل عبر النتائج باستخدام limit وoffset:

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

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

الترتيب​

مرر sortKey وsortOrder في userQuery:

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

ترتيب: ASC (منخفض→مرتفع) أو DESC (مرتفع→منخفض، افتراضي).

التصفية​

تتم التصفية من خلال body الطلب (مصفوفة من IFilterParams)، وليس userQuery. كل شرط يجمع بين attributeMarker، وconditionMarker (eq، neq، in، nin، mth، lth، exs، nexs، pat، same، same_part)، وconditionValue. اجمع بين عدة شروط في المصفوفة لتصفية حسب معايير متعددة في وقت واحد. المرجع الكامل للشروط موجود في المعلمات أدناه.

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

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

المعلمات​

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


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

ملاحظة: شكل userQuery يعتمد على الطريقة. الحقول أعلاه هي القاعدة الشائعة (IProductsQueryBase)، المستخدمة من قبل getProducts، getProductsByPageId، getProductsByPageUrl وgetProductsEmptyPage. تختلف الطرق الأخرى: getRelatedProductsById تقبل أيضًا statusMarker وtemplateMarker؛ getProductsPriceByPageUrl تقبل أيضًا statusMarker (بدون sortKey)؛ getProductsByIds تقبل فقط signPrice. تتم التصفية (attributeMarker / conditionMarker / conditionValue) من خلال body الطلب، وليس userQuery — انظر أدناه.

المخطط

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

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

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

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

signPrice: سلسلة
علامة تخزين الطلب لتثبيت السعر. إذا تم تعيين المعلمة، يتم تثبيت السعر لفترة معينة (انظر قسم تثبيت السعر أدناه).
مثال: "orders"

حقول محددة للطرق: statusMarker (getRelatedProductsById، getProductsPriceByPageUrl) وtemplateMarker (getRelatedProductsById) — string | null، الافتراضي null.

استخدم الشروط للعثور على بيانات منتجات محددة:

attributeMarker: المعرف النصي للخاصية المفهرسة التي يتم تصفية القيم بناءً عليها. conditionMarker: نوع الشرط الذي سيتم تطبيقه على قيمة الخاصية.

Markerالمعنىمثال
eqيساويstatusId = 1 (نشط فقط)
neqلا يساويcategory ≠ "أرشيف"
inيحتوي على (واحد من)category in ["إلكترونيات"، "كتب"]
ninلا يحتوي علىbrand not in ["علامة مزيفة"]
mthأكبر منprice > 100
lthأقل منstock < 10
exsموجود (له قيمة)لديه وصف
nexsغير موجودلا توجد صورة
patيتطابق مع النمطtitle matches "jacket"
sameيتطابق مع القيمة تمامًاsku is exactly "ABC-123"
same_partيتطابق مع جزء من القيمة تمامًاجزء من sku هو بالضبط "ABC"

conditionValue: القيمة التي يتم المقارنة بها.

تثبيت السعر (signPrice)​

عند جلب المنتجات يمكنك تمرير معلمة signPrice اختيارية داخل userQuery (وهي أيضًا حجة في طرق التوصية من وحدة Blocks). تقبل علامة تخزين الطلب وتطلب من الخادم تأمين السعر المعاد لفترة محدودة.

signPrice — نوع string

علامة تخزين الطلب لتثبيت السعر. إذا تم تعيين المعلمة، يتم تثبيت السعر لفترة معينة.

لماذا تستخدمه. يمكن أن تتغير الأسعار أثناء تسوق العميل — يبدأ خصم، أو يقوم مسؤول بتحرير السعر. يضمن signPrice أن السعر المعروض في الكتالوج أو السلة هو بالضبط السعر المفروض عند الخروج، لذا لا يمكن أن يتغير بين التصفح والطلب.

كيف يعمل:

  1. جلب المنتجات مع تعيين signPrice إلى علامة تخزين الطلب الخاصة بك (على سبيل المثال، "orders").
  2. كل منتج معاد يحمل الآن حقل signedPrice — رمز موقّع يشفر السعر المؤمّن.
  3. أرسل رمز signedPrice هذا عند إنشاء الطلب، حتى يلتزم الخادم بالسعر الثابت.

const { items } = await Products.getProducts([], "en_US", {
  signPrice: "orders"
});

const signedPrice = items[0].signedPrice;

➡️ يتم استهلاك الرمز المعاد بواسطة createOrder(). انظر أين تأخذه وكيف تمرره في قسم سعر المنتج الثابت (signedPrice) من وحدة الطلبات.

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

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

نعم — مرر عدة شروط في مصفوفة body؛ يتم دمجها معًا:

const { items } = await Products.getProducts(
  [
    { attributeMarker: "price", conditionMarker: "mth", conditionValue: 100 },
    { attributeMarker: "brand", conditionMarker: "in", conditionValue: ["apple", "samsung"] },
  ],
  "en_US",
);

كيف أتعامل مع متغيرات المنتج (الأحجام، الألوان)؟​

تُخزن المتغيرات في attributeValues للمنتج — اقرأها من كائن المنتج المسترجع. الهيكل هو أي مجموعة خصائص قمت بتكوينها للكتالوج.

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

قم بزيادة offset بمقدار limit في كل نقرة وأضف العناصر الجديدة إلى قائمتك (استخدم total لمعرفة متى تتوقف).

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

نعم — قم بالتصفية باستخدام خاصية category وعلامة الشرط in، مع تمرير قائمة بقيم الفئات.

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

رتب حسب تاريخ الإنشاء: userQuery: { sortKey: "date", sortOrder: "DESC" }.

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

  • قم دائمًا بالتصفية (limit + offset) — لا تقم بجلب الكتالوج بالكامل دفعة واحدة.
  • قم بتخزين قوائم المنتجات للفئات التي يتم الوصول إليها بشكل متكرر لتقليل استدعاءات API.
  • استخدم signPrice عندما تتغذى الأسعار في سلة/خروج حتى لا يمكن أن تتغير السعر.
  • تعامل مع النتائج الفارغة (total === 0) والحقول المفقودة (price، الصور) بشكل جيد.

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