المقدمة

حدد حقولًا مخصصة لمحتواك دون الحاجة إلى تعديل الكود.

مزيد من المعلومات حول واجهة مستخدم الوحدة https://doc.oneentry.cloud/docs/category/attributes

---

🎯 ماذا تفعل هذه الوحدة؟

تتيح لك وحدة AttributesSets قراءة تعريفات الحقول المخصصة (مجموعات السمات) المستخدمة في محتواك - المنتجات، الصفحات، النماذج، الكتل، والمزيد. مجموعة السمات هي المخطط الذي يصف الحقول التي تمتلكها الكيان ونوع كل حقل؛ تقوم بتعريفها في لوحة إدارة OneEntry وتfetch هيكلها باستخدام هذه الوحدة.

ملاحظة: تصف مجموعات السمات المخطط، وليس القيم. تعيش القيم الفعلية على الكيانات نفسها (صفحة، منتج، إلخ) تحت attributeValues. الاستثناء الوحيد هو نوع timeInterval، الذي يمكن أن يحمل قيمًا - انظر الأمثلة أدناه.

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

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

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

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

// Get every attribute in the "productAttributes" set.
const attributes = await AttributesSets.getAttributesByMarker(
  "productAttributes",
  "en_US",
);

attributes.forEach((attr) => {
  console.log(attr.marker, attr.type, attr.localizeInfos.title);
});

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

السمة، مجموعة السمات، القيمة

المصطلح	ما هو	مثال
السمة	تعريف حقل واحد (علامة + نوع)	price (float)
مجموعة السمات	مجموعة من السمات - مخطط الكيان	مجموعة "المنتج"
القيمة	البيانات التي يخزنها الكيان لسمة معينة	19.99 على منتج معين

تجمع مجموعة السمات السمات في مخطط قابل لإعادة الاستخدام. يمكن ربط نفس المجموعة بعدة كيانات، لذا فإن تغيير المجموعة يغير الحقول المتاحة في كل مكان يتم استخدامه.

العلامات

العلامة هي المعرف الفني الذي تستخدمه في الكود (مثل product_name). وهي تتطابق مع العنوان القابل للقراءة البشرية المعروض في لوحة الإدارة.

product.attributeValues.product_name; // "product_name" is the marker

قواعد العلامات:

• يجب أن تكون فريدة
• لا مسافات (استخدم _)
• لا يمكن أن تبدأ برقم
• استخدم الحروف الصغيرة للاتساق

✅ جيد: product_name, price_usd, main_image — ❌ سيء: product name, 2nd_price, Product Name

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

مجموعات السمات المشتركة

إذا تم استخدام مجموعة سمات من قبل عدة كيانات، فإن التغييرات تنتشر إلى جميعها:

• إضافة سمة - تظهر في كل كيان يستخدم المجموعة؛ يحتفظ المحتوى الموجود بقيمه ويبدأ الحقل الجديد فارغًا.
• إزالة سمة - تتم إزالتها من كل كيان يستخدم المجموعة، وتُحذف القيم الموجودة بشكل دائم.

لا يمكنك حذف سمة بينما لا تزال مستخدمة في مجموعة سمات.

المدققون

يمكن أن تحمل السمات مدققين لفرض جودة البيانات - الحقول المطلوبة، الحد الأدنى/الحد الأقصى للطول، حدود حجم الملف، أبعاد بكسل الصورة، نطاقات التاريخ، وقيمة افتراضية. يتم إرجاع تكوين المدققين على كل سمة تحت validators.

انقر لرؤية أمثلة المدققين

• requiredValidator: يتطلب إدخال قيمة.

{
  "type": "string",
  "value": {},
  "marker": "string",
  "position": 1,
  "listTitles": [],
  "validators": {
    "requiredValidator": {
      "strict": true
    }
  },
  "localizeInfos": {
    "title": "Currency"
  },
  "additionalFields": {
    "extra": {
      "type": "integer",
      "value": "10",
      "marker": "extra"
    }
  }
}

---

• defaultValueValidator: يوفر قيمة افتراضية للحقل.

{
  "type": "string",
  "value": {},
  "marker": "string",
  "position": 1,
  "listTitles": [],
  "validators": {
    "defaultValueValidator": {
      "customErrorText": "Custom error",
      "fieldDefaultValue": "usd",
      "fieldDefaultValue2": ""
    }
  },
  "localizeInfos": {
    "title": "String"
  },
  "additionalFields": {
    "extra": {
      "type": "integer",
      "value": "10",
      "marker": "extra"
    }
  }
}

---

تعلم المزيد: انظر Validators للتكوين التفصيلي.

السمات المتداخلة

يمكنك إرفاق حقول إضافية بسمة عبر Additional Fields (يتم إرجاعها تحت additionalFields).

---

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

الطريقة	ما تفعله
getAttributes()	الحصول على جميع كائنات مجموعة السمات.
getAttributesByMarker()	الحصول على جميع السمات لمجموعة، مع البيانات من مجموعة السمات.
getAttributeSetByMarker()	الحصول على كائن مجموعة سمات واحدة بواسطة العلامة.
getSingleAttributeByMarkerSet()	الحصول على سمة واحدة (مع بيانات المجموعة) بواسطة علامة المجموعة وعلامة السمة.

---

📚 أنواع البيانات المتاحة

لكل سمة نوع type. اختر النوع المناسب لكل حقل.

النوع	الأفضل له	مثال الاستخدام
string	نص قصير (< 255 حرف)	اسم المنتج، البريد الإلكتروني
text	نص طويل منسق	منشور مدونة، وصف
textWithHeader	نص مع عنوان	أقسام المقالات
integer	أعداد صحيحة	الكمية، العمر
real	أرقام عشرية عالية الدقة	بيانات علمية
float	أرقام عشرية	السعر، التقييم
date	مجرد التاريخ	تاريخ الميلاد، الموعد النهائي
dateTime	تاريخ + وقت	بدء الحدث، نشر في
time	مجرد الوقت	ساعات العمل
file	أي ملف	PDF، مستند
image	صورة واحدة	صورة شخصية، شعار
groupOfImages	صور متعددة	معرض صور
radioButton	اختيار واحد	الحجم (S/M/L)
list	اختيار منسدلة	الدولة، الفئة
button	إجراء تفاعلي	إرسال النموذج، CTA
spam	حماية من البريد العشوائي	حقل مصيدة ضد الروبوتات
entity	رابط لمحتوى آخر	منتجات ذات صلة
timeInterval	نطاقات التاريخ/الوقت	الجداول، فترة الترويج

اختيار نوع

• نص: string (سطر واحد)، text (فقرات منسقة)، textWithHeader (نص مع عنوان).
• أرقام: integer (بدون كسور)، float (كسور قياسية)، real (دقة إضافية).
• تاريخ/وقت: date، time، dateTime، أو timeInterval (نطاقات/جداول).
• ملفات/صور: file (أي مستند)، image (صورة واحدة)، groupOfImages (معرض).
• خيارات: radioButton (اختر واحدًا)، list (منسدلة).
• متقدم: entity (رابط لصفحات/منتجات أخرى)، button (إجراء تفاعلي)، spam (حماية من الروبوتات).

---

📖 أمثلة على نوع البيانات

فيما يلي أمثلة تقنية على هيكل كل نوع بيانات كما يتم إرجاعه بواسطة واجهة برمجة التطبيقات.

💡 البيانات التي يتم إرجاعها في مجموعة السمات لا تتضمن القيم الفعلية للسمات - تلك تعيش على كيانات محددة (صفحات، منتجات، إلخ). الاستثناء الوحيد هو timeInterval، الذي يمكن أن يحمل قيمًا عندما يتم تحديد المربع المقابل في لوحة الإدارة.

انقر لرؤية جميع أمثلة نوع البيانات

مرجع أنواع البيانات

• نص: نص بسيط، على سبيل المثال، "مرحبًا، العالم!".

{
  "type": "string",
  "value": {},
  "marker": "string",
  "position": 1,
  "listTitles": [],
  "validators": {
    "requiredValidator": {
      "strict": true
    }
  },
  "localizeInfos": {
    "title": "String"
  },
  "additionalFields": {
    "Extra": {
      "type": "integer",
      "value": "10",
      "marker": "Extra"
    }
  }
}

---

• نص: نص أطول، غالبًا ما يكون منسقًا، على سبيل المثال، مقال أو رسالة.

{
  "type": "text",
  "value": {},
  "marker": "text",
  "position": 2,
  "listTitles": [],
  "validators": {},
  "localizeInfos": {
    "title": "Text"
  },
  "additionalFields": {}
}

---

• نص مع عنوان: نص مع عنوان يمكن استخدامه للدلالة على موضوع أو فئة.

{
  "type": "textWithHeader",
  "value": {},
  "marker": "text_with_header",
  "position": 3,
  "listTitles": [],
  "validators": {},
  "localizeInfos": {
    "title": "Text With Header"
  },
  "additionalFields": {}
}

---

• عدد صحيح: عدد صحيح، على سبيل المثال، 5، 100، -2.

{
  "type": "integer",
  "value": {},
  "marker": "integer",
  "position": 4,
  "listTitles": [],
  "validators": {},
  "localizeInfos": {
    "title": "Integer"
  },
  "additionalFields": {}
}

---

• حقيقي: نفس الشيء مثل Float، ولكن بدقة أعلى.

{
  "type": "real",
  "value": {},
  "marker": "real_number",
  "position": 5,
  "listTitles": [],
  "validators": {},
  "localizeInfos": {
    "title": "Real Number"
  },
  "additionalFields": {}
}

---

• عائم: رقم عائم يمكن أن يحتوي على جزء عشري، على سبيل المثال، 3.14، 1.5، -0.25.

{
  "type": "float",
  "value": {},
  "marker": "float",
  "position": 6,
  "listTitles": [],
  "validators": {},
  "localizeInfos": {
    "title": "Float"
  },
  "additionalFields": {}
}

---

• تاريخ ووقت: مجموعة من التاريخ والوقت، على سبيل المثال، 2023-10-27 10:00:00.

{
  "type": "dateTime",
  "value": {},
  "marker": "date_time",
  "position": 7,
  "listTitles": [],
  "validators": {},
  "localizeInfos": {
    "title": "DateTime"
  },
  "additionalFields": {}
}

---

• تاريخ: تاريخ، على سبيل المثال، 2023-10-27.

{
  "type": "date",
  "value": {},
  "marker": "date",
  "position": 8,
  "listTitles": [],
  "validators": {},
  "localizeInfos": {
    "title": "Date"
  },
  "additionalFields": {}
}

---

• وقت: وقت، على سبيل المثال، 10:00:00.

{
  "type": "time",
  "value": {},
  "marker": "time",
  "position": 9,
  "listTitles": [],
  "validators": {},
  "localizeInfos": {
    "title": "Time"
  },
  "additionalFields": {}
}

---

• ملف: أي ملف، على سبيل المثال، مستند، صورة، موسيقى.

{
  "type": "file",
  "value": {},
  "marker": "file",
  "position": 10,
  "listTitles": [],
  "validators": {
    "checkingFilesValidator": {
      "maxUnits": "kb",
      "maxValue": "2000",
      "minUnits": "kb",
      "minValue": 0,
      "extensions": []
    }
  },
  "localizeInfos": {
    "title": "File"
  },
  "additionalFields": {}
}

---

• صورة: صورة، على سبيل المثال، صورة فوتوغرافية أو رسم.

{
  "type": "image",
  "value": {},
  "marker": "image",
  "position": 11,
  "listTitles": [],
  "validators": {
    "sizeInPixelsValidator": {
      "maxX": "500",
      "maxY": "500"
    }
  },
  "localizeInfos": {
    "title": "Image"
  },
  "additionalFields": {}
}

---

• مجموعة من الصور: مجموعة من الصور، على سبيل المثال، ألبوم صور.

{
  "type": "groupOfImages",
  "value": {},
  "marker": "image_group",
  "position": 12,
  "listTitles": [],
  "validators": {},
  "localizeInfos": {
    "title": "Image Group"
  },
  "additionalFields": {}
}

---

• زر راديو: اختيار من بين خيارات يمكن اختيار واحد فقط منها.

{
  "type": "radioButton",
  "value": {},
  "marker": "radio",
  "position": 13,
  "listTitles": [
    {
      "title": "A",
      "value": "a",
      "extended": {
        "type": null,
        "value": null
      },
      "position": 1
    },
    {
      "title": "B",
      "value": "b",
      "extended": {
        "type": null,
        "value": null
      },
      "position": 2
    }
  ],
  "validators": {},
  "localizeInfos": {
    "title": "Radio"
  },
  "additionalFields": {}
}

---

• قائمة: قائمة بالعناصر القابلة للاختيار، على سبيل المثال، منسدلة.

{
  "type": "list",
  "value": {},
  "marker": "list",
  "position": 14,
  "listTitles": [
    {
      "title": "A",
      "value": "a",
      "extended": {
        "type": null,
        "value": null
      },
      "position": 1
    },
    {
      "title": "B",
      "value": "b",
      "extended": {
        "type": null,
        "value": null
      },
      "position": 2
    },
    {
      "title": "C",
      "value": "c",
      "extended": {
        "type": "string",
        "value": "Additional Value"
      },
      "position": 3
    }
  ],
  "validators": {},
  "localizeInfos": {
    "title": "List"
  },
  "additionalFields": {}
}

---

• كيان: رابط إلى كائن آخر (صفحة، منتج، ...).

{
  "type": "entity",
  "value": {},
  "marker": "entity",
  "position": 15,
  "listTitles": [
    {
      "title": "Products",
      "value": {
        "id": 1,
        "depth": 0,
        "parentId": null,
        "isPinned": false,
        "position": 1,
        "selected": true
      }
    },
    {
      "title": "Normal Page",
      "value": {
        "id": 4,
        "depth": 0,
        "parentId": null,
        "isPinned": false,
        "position": 2,
        "selected": true
      }
    },
    {
      "title": "Error",
      "value": {
        "id": 2,
        "depth": 0,
        "parentId": null,
        "isPinned": false,
        "position": 3,
        "selected": true
      }
    }
  ],
  "validators": {},
  "localizeInfos": {
    "title": "Entity"
  },
  "additionalFields": {
    "test_field": {
      "type": "string",
      "value": "Test Field",
      "marker": "test_field"
    }
  }
}

---

• فترة زمنية: تقويم مرن مع واجهة مستخدم سهلة الاستخدام لإدارة بيانات فترات الزمن.

{
  "time_interval": {
    "id": 4,
    "type": "timeInterval",
    "value": [
      // Array of value groups, each linked to a specific interval (via intervalId). This array is formed when Receive values is enabled in CMS
      {
        // Specific time records applicable to the specified dates
        "values": [
          {
            // Unique record identifier
            "id": "1dc1787d-acc3-4315-a45d-52166c72e577",
            // Date range (inclusive) to which this record applies
            "dates": ["2025-11-27T00:00:00.000Z", "2025-11-27T00:00:00.000Z"],
            // Array of time slots in format [[start, end], ...]
            "times": [
              [
                // Start of time slot (hours and minutes)
                {
                  "hours": 19,
                  "minutes": 18
                },
                // End of time slot
                {
                  "hours": 21,
                  "minutes": 19
                }
              ]
            ],
            // Reserved (not used in current implementation)
            "intervals": [],
            // Exceptions — time segments excluded from the schedule on the specified date
            "exceptions": [
              {
                // Exception date
                "date": "2025-12-17T17:00:00.000Z",
                // Array of excluded time segments
                "externalTimes": [
                  ["2025-12-17T17:25:00.000Z", "2025-12-17T17:27:00.000Z"]
                ]
              }
            ],
            // Reference to interval from the `intervals` array
            "intervalId": "0da61a19-49cb-40b1-88e6-1fa3c93a1fa6",
            // Flag for weekly recurrence (on the corresponding day of the week)
            "inEveryWeek": true
          },
          {
            "id": "cfa187d3-0284-4e0d-8206-7b353cf47110",
            "dates": ["2025-12-18T00:00:00.000Z", "2025-12-18T00:00:00.000Z"],
            // Array of time slots in format [[start, end], ...]
            "times": [
              [
                {
                  "hours": 0,
                  "minutes": 25
                },
                {
                  "hours": 0,
                  "minutes": 27
                }
              ],
              [
                {
                  "hours": 19,
                  "minutes": 18
                },
                {
                  "hours": 21,
                  "minutes": 19
                }
              ]
            ],
            "intervals": [],
            "exceptions": [
              {
                "date": "2025-12-17T17:00:00.000Z",
                "externalTimes": [
                  ["2025-12-17T17:25:00.000Z", "2025-12-17T17:27:00.000Z"]
                ]
              }
            ],
            "intervalId": "0da61a19-49cb-40b1-88e6-1fa3c93a1fa6"
          },
          {
            "id": "474de0f7-595f-49a5-aaa7-65617203ae69",
            "dates": ["2025-12-25T00:00:00.000Z", "2025-12-25T00:00:00.000Z"],
            // No time slots
            "times": [],
            // Dynamic rules for schedule expansion
            "external": [
              {
                // Base date for calculating recurring event
                "date": "2026-01-15T00:00:00.000Z",
                // Event repeats every month on this day
                "inEveryMonth": true
              }
            ],
            "intervals": [],
            "exceptions": [
              {
                "date": "2025-12-17T17:00:00.000Z",
                "externalTimes": [
                  ["2025-12-17T17:25:00.000Z", "2025-12-17T17:27:00.000Z"]
                ]
              }
            ],
            "intervalId": "0da61a19-49cb-40b1-88e6-1fa3c93a1fa6",
            // Flag for weekly recurrence
            "inEveryWeek": true,
            // Flag for monthly recurrence
            "inEveryMonth": true,
            // Flag for yearly recurrence
            "inEveryYears": true
          }
        ],
        // Reference to interval from the `intervals` array
        "intervalId": "0da61a19-49cb-40b1-88e6-1fa3c93a1fa6"
      },
      {
        "values": [
          {
            "id": "2f80dc18-16da-45cb-82c6-e41e1f6ee084",
            "dates": ["2025-12-22T00:00:00.000Z", "2025-12-23T00:00:00.000Z"],
            "times": [],
            "intervals": [],
            "exceptions": [],
            "intervalId": "918175fd-cc18-4ca5-9bee-c78c61c9415a",
            "inEveryWeek": true,
            "inEveryMonth": true
          }
        ],
        "intervalId": "918175fd-cc18-4ca5-9bee-c78c61c9415a"
      }
    ],
    "isPrice": false,
    "original": true,
    "intervals": [
      // Array of time interval templates
      {
        // Unique identifier of interval template
        "id": "0da61a19-49cb-40b1-88e6-1fa3c93a1fa6",
        "range": [
          // Main range of interval applicability
          "2025-11-26T17:00:00.000Z",
          "2025-11-26T17:00:00.000Z"
        ],
        // Exceptions at the entire interval level
        "external": [
          {
            "date": "2025-12-17T17:00:00.000Z",
            "externalTimes": [
              ["2025-12-17T17:25:00.000Z", "2025-12-17T17:27:00.000Z"]
            ]
          }
        ],
        // Internal time slots (working/active periods)
        "intervals": [
          {
            "id": "01fea594-9933-47ac-af0a-ec0e0884f618",
            // End of time slot
            "end": {
              "hours": 21,
              "minutes": 19
            },
            // Start of time slot
            "start": {
              "hours": 19,
              "minutes": 18
            },
            // Duration of repeating block (in minutes); null — no periodicity
            "period": null
          },
          {
            "id": "22ba24af-1fae-4422-8c92-0635b684a306",
            "end": {
              "hours": 0,
              "minutes": 29
            },
            "start": {
              "hours": 0,
              "minutes": 25
            },
            // Periodicity: time slots repeat with 2-minute step
            "period": 2,
            // Exception inside periodic slot
            "external": {
              // Flag for displaying exception in the interface
              "show": false,
              // Duration of excluded fragment (in minutes)
              "value": 2
            }
          }
        ],
        "inEveryWeek": true,
        "inEveryMonth": true,
        "inEveryYears": true
      },
      {
        "id": "918175fd-cc18-4ca5-9bee-c78c61c9415a",
        "range": ["2026-01-18T17:00:00.000Z", "2026-01-20T17:00:00.000Z"],
        // No exceptions
        "external": [],
        // No internal time slots
        "intervals": [],
        "inEveryWeek": true,
        "inEveryMonth": true,
        "inEveryYears": true
      }
    ],
    // Flag for attribute visibility in the interface
    "isVisible": true,
    "identifier": "time_interval",
    "localizeInfos": {
      "title": "Time interval"
    },
    "receiveValues": true
  }
}

---

تتوافق واجهة ملء المحتوى في لوحة الإدارة مع نوع البيانات المحدد لكل حقل سمة.

---

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

ما الفرق بين النص و النص الطويل؟

• نص - نص قصير، سطر واحد (حد أقصى ~255 حرف). استخدمه للأسماء، العناوين، البريد الإلكتروني.
• نص طويل - نص طويل، عدة فقرات، يدعم التنسيق وHTML. استخدمه للوصف، المقالات.

---

متى يجب أن أستخدم عدد صحيح، عائم، أو حقيقي؟

• عدد صحيح - أعداد صحيحة فقط (1، 2، 100، -5). استخدمه للكميات، العد، الأعمار.
• عائم - أرقام عشرية (19.99، 4.5). استخدمه للأسعار، التقييمات، القياسات.
• حقيقي - مثل العائم ولكن بدقة أعلى. استخدمه للحسابات العلمية.

---

هل يمكنني إعادة استخدام نفس السمة في مجموعات سمات مختلفة؟

تُعرف السمات ضمن مخطط مجموعة السمات (حسب العلامة). لإعادة استخدام حقل في مكان آخر، إما أن تنشئ سمات مشابهة بعلامات مختلفة، أو تعيد استخدام مجموعة السمات بالكامل عبر عدة كيانات.

---

ما هي "العلامة" ولماذا هي مهمة؟

العلامة هي المعرف الفني الذي تستخدمه في الكود (مثل product.attributeValues.product_name)، على عكس العنوان القابل للقراءة البشرية المعروض في لوحة الإدارة. يجب أن تكون العلامات فريدة، ولا تحتوي على مسافات (استخدم _)، ولا تبدأ برقم، وعادة ما تكون بحروف صغيرة.

---

هل يمكنني الحصول على سمات متداخلة؟

نعم - استخدم Additional Fields (يتم إرجاعها تحت additionalFields).

---

كيف أضيف قواعد التحقق؟

في لوحة إدارة OneEntry: افتح مجموعة السمات الخاصة بك، انقر على سمة، أضف المدققين (مطلوب، حد أدنى/حد أقصى، إلخ)، واحفظ. تعلم المزيد: Validators.

---

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

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

---

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

• وحدة المنتجات - تستخدم مجموعات السمات لبيانات المنتج
• وحدة الصفحات - تستخدم مجموعات السمات لمحتوى الصفحة
• وحدة الكتل - تستخدم مجموعات السمات للكتل القابلة لإعادة الاستخدام
• وحدة النماذج - إنشاء نماذج مع حقول مخصصة

---