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

المقدمة

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

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

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

تتيح لك وحدة Forms استرجاع النماذج - نماذج الاتصال، الاستطلاعات، التسجيلات، نماذج التعليقات - حتى تتمكن من عرضها في تطبيقك. تقوم بإنشاء النماذج في لوحة تحكم OneEntry؛ يقوم SDK باسترجاع هيكلها (الحقول، المدققون، التسميات المحلية) ديناميكيًا. يتم التعامل مع جمع التقديمات الفعلية بواسطة وحدة FormsData.

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

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


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

استرجع نموذجًا واحدًا بواسطة علامته واقرأ حقوله:

// Fetch the "contact_form" form structure.
const form = await Forms.getFormByMarker("contact_form", "en_US");

console.log(form.identifier, form.localizeInfos.title);

// Render each field from the form's attributes.
form.attributes.forEach((field) => {
  console.log(field.marker, field.type, field.localizeInfos.title);
});

لإدراج كل نموذج (مقيد الصفحات) استخدم getAllForms(langCode, offset, limit)، والذي يعيد كائنًا { total, items }.

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

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

النموذج (form) (IFormsEntity) هو وسيلة منظمة لجمع المعلومات من المستخدمين:

  • الحقول (attributes) - عناصر الإدخال، كل منها سمة مع type (string, text, file, list, …)
  • المدققون (validators) - قواعد لكل حقل (مطلوب، طول السلسلة، تنسيق البريد الإلكتروني)
  • الهيكل - التخطيط والتسميات المحلية المحددة في لوحة تحكم OneEntry
  • التقديمات - ردود المستخدمين، المقدمة والمسترجعة عبر وحدة FormsData

أنواع حقول النموذج​

كل حقل له type هو AttributeType. القيم الشائعة:

النوع (AttributeType)الوصفمثال على الاستخدام
stringنص قصير في سطر واحدالاسم، العنوان، المدينة
text / textWithHeaderنص متعدد الأسطرالرسالة، التعليقات، السيرة الذاتية
integer / real / floatإدخال رقميالعمر، الكمية، السعر
date / dateTime / timeمختارات التاريخ والوقتتاريخ الميلاد، تاريخ الحدث
listقائمة منسدلة / اختيار متعدد من الخياراتالدولة، الفئة
radioButtonاختيار واحد من الخياراتالحجم، الخطة
file / imageتحميل ملف / صورةالسيرة الذاتية، الصورة، الوثيقة
groupOfImagesصور متعددةالمعرض
entityمرجع إلى كيان آخرمنتج أو صفحة مرتبطة

ملاحظة: البريد الإلكتروني هو حقل string مع emailInspectionValidator مفعل - لا يوجد نوع حقل منفصل للبريد الإلكتروني.

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

هيكل النموذج​

كل نموذج (IFormsEntity) يحمل id، وidentifier (علامة)، وtype اختياري ('order' | 'sing_in_up' | 'collection' | 'data' | 'rating' | null)، وlocalizeInfos (العنوان، رسالة النجاح، …) ومصفوفة attributes من الحقول. كل حقل له marker، وtype، وlocalizeInfos، وكائن validators:

{
  "marker": "email",
  "type": "string",
  "localizeInfos": { "title": "Email" },
  "validators": {
    "requiredValidator": { "strict": true },
    "emailInspectionValidator": true,
    "stringInspectionValidator": { "stringMin": 5, "stringMax": 100, "stringLength": 0 }
  }
}

المدققون الشائعون:

  • requiredValidator — { strict: boolean }، يجب ملء الحقل
  • stringInspectionValidator — { stringMin, stringMax, stringLength }، قيود طول النص
  • emailInspectionValidator — boolean، فرض تنسيق البريد الإلكتروني
  • defaultValueValidator — القيمة الافتراضية بالإضافة إلى نص خطأ مخصص اختياري

مجموعة المدققين قابلة للتوسيع - قد تعيد واجهة برمجة التطبيقات أنواع مدققين إضافية.

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

الـ SDK مخصص لـ استرجاع النماذج (وعبر وحدة FormsData، تقديم البيانات) - وليس لإنشاء أو تعديل النماذج. لبناء أو تغيير نموذج، استخدم لوحة تحكم OneEntry: افتح قسم النماذج، أضف الحقول، قم بتكوين قواعد التحقق، وفعّل النموذج.

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

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

كلا الطريقتين عامتان - لا حاجة لتفويض المستخدم.

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

كيف يمكنني إنشاء أو تعديل النماذج؟​

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

هل يمكنني تحميل الملفات مع النماذج؟​

نعم. أضف حقل file / image / groupOfImages إلى نموذجك؛ يتم التعامل مع التقديمات التي تحتوي على ملفات بواسطة FormData.postFormsData()، الذي يقوم بتحميلها عبر وحدة FileUploading تلقائيًا. راجع وحدة FormsData.

هل يمكن أن تحتوي النماذج على حقول شرطية (عرض/إخفاء بناءً على حقول أخرى)؟​

ليس مباشرة في الـ SDK - نفذ منطق العرض/الإخفاء في واجهة المستخدم الخاصة بك بناءً على قيم حقول النموذج المسترجعة.

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

  • ارجع إلى النماذج بواسطة identifier (علامة) وليس بواسطة ID رقمي.
  • قم بعرض الحقول وحالة المتطلبات من validators لكل حقل بحيث تتطابق واجهة المستخدم الخاصة بك مع التحقق من جانب الخادم.
  • استخدم try/catch حول الاسترجاعات وتعامل مع شكل إرجاع IError.

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

  • وحدة FormsData - تقديم وإدارة تقديمات النماذج
  • وحدة Events - إعداد إشعارات تلقائية عند تقديم النموذج
  • وحدة FileUploading - التعامل مع تحميل الملفات في النماذج
  • وحدة Users - إدارة المستخدمين الذين يقدمون النماذج