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

مقدمة

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

مزيد من المعلومات حول الكتالوج في لوحة إدارة 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/ترتيب). انظر Parameters أدناه لمجموعة كاملة.

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

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

الـ منتج هو كيان كتالوجي (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)، وconditionValue. اجمع بين عدة شروط في المصفوفة لتصفية حسب معايير متعددة في وقت واحد. المرجع الكامل للشروط موجود في Parameters أدناه.

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

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

Parameters​

هذا الموديل يقبل مجموعة من معلمات المستخدم تسمى 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: 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"

signPrice: string
علامة تخزين الطلب لتثبيت السعر. إذا تم تعيين المعلمة، يتم تثبيت السعر لفترة معينة (انظر قسم تثبيت السعر أدناه).
مثال: "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غير موجودلا توجد صورة

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، الصور) بشكل جيد.

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