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

المقدمة

استرجع تسميات حالة المنتج ("جديد"، "تخفيض"، "نفد من المخزون") لتوسيم وتصنيف عناصر الكتالوج.

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

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

يوفر موديل ProductStatuses شروط تصفية إضافية لعناصر الكتالوج بجانب الفلاتر المعتمدة على السمات. تتيح لك حالات المنتجات إنشاء تسميات مخصصة - مثل "وصول جديد"، "الأكثر مبيعًا"، "تخفيض"، "نفد من المخزون" - لتوسيم وتنظيم وتصنيف المنتجات في كتالوج التجارة الإلكترونية الخاص بك.

تقوم بتعريف تسميات الحالة في لوحة تحكم OneEntry (الكتالوج > حالات المنتجات)، وتعيينها للمنتجات، واستخدام هذا الموديل لـ استرجاع الحالات وتصنيف المنتجات بناءً عليها. SDK هو للقراءة فقط: لا يمكنك إنشاء حالات من خلاله.

🚀 البدء السريع​

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


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

استرجع جميع الحالات واقرأ حقولها:

// Fetch every product status, localized to English.
const statuses = await ProductStatuses.getProductStatuses("en_US");

statuses.forEach((status) => {
  console.log(status.identifier, status.localizeInfos.title, status.isDefault);
});

// Or fetch a single status by its marker.
const sale = await ProductStatuses.getProductsByStatusMarker("sale", "en_US");
console.log(sale.localizeInfos.title); // "Sale"

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

ما هي حالة المنتج؟​

حالة المنتج (IProductStatusEntity) هي تسمية/علامة مخصصة للمنتجات:

  • اسم الحالة (localizeInfos) - اسم العرض المحلي (مثل "وصول جديد"، "تخفيض")
  • علامة الحالة (identifier) - معرف فريد يستخدم للتصفية
  • علامة افتراضية (isDefault) - ما إذا كانت هذه هي الحالة الافتراضية
  • الموقع (position) - ترتيب العرض

سير عمل حالة المنتج​

1. Create status in admin panel
   (e.g., "New Arrival")
   ↓
2. Assign status to products
   (Select products in admin)
   ↓
3. Fetch statuses via SDK
   (ProductStatuses.getProductStatuses())
   ↓
4. Display status badges on products
   (Render badges in product listings)
   ↓
5. Filter products by status marker
   (Products.getProducts([{ statusMarker }], langCode))

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

يتم إنشاء الحالات في لوحة التحكم​

لا يمكنك إنشاء حالات عبر SDK - يتم إنشاؤها في لوحة تحكم OneEntry (الكتالوج > حالات المنتجات). تحتاج كل حالة إلى اسم (مطلوب) وعلامة فريدة (مطلوبة).

قيود العلامة:

  • فقط الحروف اللاتينية (a-z, A-Z) والأرقام (0-9)
  • يسمح باستخدام الشرطة السفلية (_) والشرطة (-)
  • لا مسافات أو رموز خاصة
  • يجب أن تكون فريدة عبر جميع الحالات

SDK مخصص لـ استرجاع الحالات وتصفية المنتجات، وليس لإنشاء الحالات.

حالة واحدة لكل منتج​

يشير المنتج إلى حالة واحدة كحد أقصى. يحمل كائن المنتج statusIdentifier (علامة الحالة، أو null):

const product = await Products.getProductById(123);
console.log(product.statusIdentifier); // "in_stock" - status marker, or null

التصفية حسب الحالة​

لتصفية المنتجات حسب الحالة، استخدم دالة getProducts(body, langCode, userQuery) من موديل المنتجات. مرر حقل statusMarker داخل مصفوفة IFilterParams لجلب المنتجات بحالة معينة.

التحقق من وجود علامة​

validateMarker(marker) تعيد true إذا كانت العلامة موجودة وfalse خلاف ذلك. نظرًا لأن SDK لا يمكنه إنشاء حالات، استخدمه للتحقق من علامة قبل الإشارة إليها في كودك.

الحالة مقابل السمات​

ProductStatuses تختلف عن سمات المنتج:

الميزةProductStatusesالسمات
الغرضتسميات/شارات/فلاترخصائص المنتج
أمثلة"جديد"، "تخفيض"، "مميز"اللون، الحجم، المادة
لكل منتجحالة واحدةالعديد من السمات
التصفيةبسيطة (حسب علامة الحالة)معقدة (نطاقات، قيم)
حالة الاستخدامتسميات تسويقيةمواصفات المنتج

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

📊 جدول مرجعي سريع​

الطريقةالوصفحالة الاستخدام
getProductStatuses()الحصول على جميع حالات المنتجاتقائمة بجميع الحالات المتاحة
getProductsByStatusMarker()الحصول على حالة منتج بواسطة العلامةجلب الحالة بواسطة المعرف
validateMarker()التحقق مما إذا كانت العلامة موجودةالتحقق من العلامة قبل الاستخدام

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

ما الفرق بين حالات المنتجات وسمات المنتجات؟​

حالات المنتجات هي تسميات تسويقية (جديد، تخفيض، مميز) للتصفية والتوسيم، بينما السمات هي مواصفات المنتج (اللون، الحجم، المادة). استخدم الحالات للتسميات الترويجية والسمات لخصائص المنتج.

هل يمكن أن يكون للمنتج حالات متعددة في نفس الوقت؟​

لا. يشير المنتج إلى حالة واحدة كحد أقصى، تظهر كـ statusIdentifier (علامة الحالة) على كائن المنتج.

كيف يمكنني تصفية المنتجات حسب الحالة؟​

استخدم دالة getProducts(body, langCode, userQuery) من موديل المنتجات. مرر حقل statusMarker داخل مصفوفة IFilterParams لجلب المنتجات بحالة معينة.

كيف يمكنني التحقق مما إذا كانت علامة الحالة موجودة؟​

استخدم validateMarker() - تعيد true إذا كانت العلامة موجودة وfalse خلاف ذلك. لا يمكن لـ SDK إنشاء حالات؛ يتم تعريف العلامات في لوحة التحكم وفقًا لقواعد التسمية (الحروف اللاتينية، الأرقام، الشرطة السفلية، والشرطة فقط).

هل يمكنني تغيير ترتيب الحالات المعروضة؟​

نعم. في لوحة التحكم، يمكنك سحب وإفلات الحالات لإعادة ترتيبها. يؤثر هذا على حقل position، الذي يحدد ترتيب العرض في تطبيقك.

كيف يمكنني إضافة تنسيق مخصص لشارات الحالة؟​

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

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

  • استخدم علامات وصفية - new_arrival، وليس status1.
  • تحقق قبل الإشارة - استدعِ validateMarker() قبل كتابة علامة بشكل ثابت.
  • عرض شارة الحالة - عرض شارة statusIdentifier للمنتج في القوائم.
  • تخزين الحالات مؤقتًا - نادرًا ما تتغير، لذا قم بتخزينها مؤقتًا لأداء أفضل.

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