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

مقدمة

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

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

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

يتيح لك موديل FormData تقديم النماذج المملوءة من قبل المستخدمين (نماذج الاتصال، الاستطلاعات، التسجيلات) إلى OneEntry و استرجاع، تحديث، أو حذف البيانات المقدمة للتحليل، والتقارير، والإدارة.

فكر في الأمر كمدير تقديمات النماذج الخاص بك - يقوم المستخدمون بتقديم النماذج، وأنت تخزنها في OneEntry، وتسترجعها كلما احتجت إلى عرض الردود، أو توليد التقارير، أو تحليل البيانات.

🚀 بدء سريع​

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


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

قم ببناء الجسم من تكوين النموذج وقدمها:

// 1. Fetch the form to read its module config.
const form = await Forms.getFormByMarker("contact_form");
const formModuleConfigId = form.moduleFormConfigs[0].id;
const moduleEntityIdentifier = form.moduleFormConfigs[0].entityIdentifiers[0].id;

// 2. Submit the user's input.
const response = await FormData.postFormsData({
  formIdentifier: "contact_form",
  formModuleConfigId,
  moduleEntityIdentifier,
  replayTo: null,
  status: "sent",
  formData: [
    { marker: "name", type: "string", value: "Jack" },
  ],
});

console.log(response);

لقراءة التقديمات لاحقًا، اتصل بـ getFormsDataByMarker(marker, formModuleConfigId, body?, isExtended?, langCode?, offset?, limit?).

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

ما هي بيانات النموذج؟​

بيانات النموذج هي المعلومات التي يقدمها المستخدمون من خلال نموذج. يتم بناء كل تقديم من مصفوفة formData من كائنات الحقول (marker, type, value) بالإضافة إلى معرفات تكوين النموذج.

هيكل جسم التقديم​

تقبل postFormsData كائن IBodyPostFormData:

const body = {
  formIdentifier: 'contact_form', // Form marker
  formModuleConfigId: 9,          // Module config ID (from the form)
  moduleEntityIdentifier: 'blog', // Module entity identifier (from the form)
  replayTo: null,                 // Email address to reply to (optional)
  status: 'sent',                 // Submission status (optional)
  formData: [                     // Form fields
    { marker: 'name', type: 'string', value: 'Test' },
  ],
};

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

يتطلب التقديم تكوين النموذج​

قبل التقديم، تحتاج إلى ثلاث قيم، جميعها تُقرأ من النموذج نفسه:

  1. علامة النموذج (formIdentifier) — المعرف النصي للنموذج
  2. formModuleConfigId — من moduleFormConfigs للنموذج
  3. moduleEntityIdentifier — من moduleFormConfigs للنموذج
const form = await Forms.getFormByMarker('contact_form');
const formModuleConfigId = form.moduleFormConfigs[0].id;
const moduleEntityIdentifier = form.moduleFormConfigs[0].entityIdentifiers[0].id;

قم بتخزين هذه القيم حتى لا تضطر إلى إعادة جلب النموذج في كل تقديم.

حقول formData​

كل إدخال في مصفوفة formData يصف حقلًا واحدًا:

  • marker — يجب أن يتطابق مع علامة حقل من تعريف النموذج
  • type — نوع الحقل (يستخدم للتحقق من الصحة ومعالجة الملفات)
  • value — إدخال المستخدم

تتم تحميل الحقول من نوع file / image / groupOfImages تلقائيًا من خلال موديل FileUploading عندما تمرر File/FileList/Blob كـ value.

حالة التقديم​

استخدم حقل status لتتبع حالة التقديم. "sent" هي القيمة النموذجية للتقديمات الجديدة؛ يمكنك لاحقًا نقل تقديم إلى حالة تمت مراجعته/أرشفته باستخدام updateFormsDataStatusByid().

تحديث وحذف التقديمات​

التقديمات ليست غير قابلة للتغيير. يمكن للمستخدمين المصرح لهم تغييرها أو إزالتها:

  • updateFormsDataByid(id, body) — تحرير تقديم مخزن بواسطة المعرف 🔐
  • updateFormsDataStatusByid(id, body) — تغيير حالة تقديم فقط بواسطة المعرف 🔐
  • deleteFormsDataByid(id) — حذف تقديم بواسطة المعرف 🔐

قراءة التقديمات​

تُرجع getFormsDataByMarker التقديمات لنموذج. يمكنك التنقل عبر النتائج باستخدام offset / limit، وتضييقها باستخدام جسم الطلب (مثل status, dateFrom, dateTo, userIdentifier).

البحث عن التقديمات حسب المعنى​

تقوم getFormsDataByVectorSearch(body, langCode, offset, limit) بإجراء بحث دلالي (متجهي) على التقديمات: تمرر نص استعلام بلغة طبيعية queryText وتسترجع السجلات التي تتطابق معها في المعنى، وليس بالكلمات الرئيسية الحرفية.

تستخدم سجلاتها نوعًا مختلفًا عن بقية الموديل - IFormDataSearchEntity بدلاً من IFormDataEntity. كلاهما يحمل id, formIdentifier, time و formData، لكن كيان البحث يكشف أيضًا عن حقول الاعتدال والمرسل للسجل الخام:

الحقلالنوعالمعنى
status'sent' | 'banned' | 'deleted' | 'moderation' | 'approved'حالة الاعتدال للسجل
ipstringعنوان IP الذي تم تقديم النموذج منه
fingerprintstringبصمة الجهاز للمرسل
isUserAdminbooleanما إذا كان مسؤولًا قد قدم السجل
userIdentifierstringمن قدم النموذج
entityIdentifierstringالكيان الذي ينتمي إليه السجل
parentIdnumberسجل بيانات النموذج الأب

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

الطريقةالوصفحالة الاستخدام
postFormsData()تقديم بيانات نموذج جديدةيقدم المستخدم نموذج الاتصال
getFormsDataByMarker()الحصول على التقديمات لنموذج معينعرض جميع تقديمات نموذج الاتصال
updateFormsDataByid() 🔐تحديث تقديم نموذج بواسطة المعرفتحرير تقديم مخزن
updateFormsDataStatusByid() 🔐تحديث حالة تقديم بواسطة المعرفوضع علامة كمعالجة/أرشفة
deleteFormsDataByid() 🔐حذف تقديم نموذج بواسطة المعرفإزالة تقديم
getFormsDataByVectorSearch()بحث دلالي (متجهي) لبيانات النموذجالعثور على التقديمات حسب المعنى، وليس الكلمات الرئيسية

🔐 تتطلب الطرق تفويض المستخدم — انظر AuthProvider. postFormsData() و getFormsDataByMarker() هما عامان.

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

كيف أقدم نموذجًا؟​

احصل على النموذج باستخدام Forms.getFormByMarker()، اقرأ formModuleConfigId و moduleEntityIdentifier من moduleFormConfigs الخاصة به، قم ببناء الجسم، ثم اتصل بـ FormData.postFormsData(body). انظر قسم البدء السريع أعلاه.

هل يمكنني تحديث أو حذف بيانات النموذج المقدمة؟​

نعم. يمكن تغيير أو إزالة التقديمات عبر SDK (تتطلب هذه تفويض المستخدم):

  • updateFormsDataByid() — تحرير تقديم مخزن بواسطة المعرف
  • updateFormsDataStatusByid() — تغيير حالة تقديم فقط بواسطة المعرف
  • deleteFormsDataByid() — حذف تقديم بواسطة المعرف

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

مرر File / FileList / Blob كـ value لحقل وسيتولى postFormsData() تحميله لك، أو قم بالتحميل بشكل منفصل باستخدام موديل FileUploading وضمن URLs المعادة في formData.

كيف أفلتر التقديمات حسب التاريخ؟​

مرر dateFrom و dateTo في جسم الطلب لـ getFormsDataByMarker().

كيف أتنقل عبر جميع التقديمات؟​

استخدم معطيات offset و limit لـ getFormsDataByMarker().

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

  • قم بتخزين تكوين النموذج (formModuleConfigId, moduleEntityIdentifier) لتجنب إعادة جلب النموذج في كل تقديم.
  • تحقق من صحة الحقول المطلوبة على جانب العميل قبل التقديم؛ يقوم OneEntry أيضًا بالتحقق من الصحة على جانب الخادم.
  • قم بتقسيم القراءات باستخدام offset / limit بدلاً من جلب كل شيء دفعة واحدة.
  • قم بالإشارة إلى النماذج بواسطة العلامة، وليس بواسطة المعرف الرقمي.
  • استخدم حقل status (و updateFormsDataStatusByid) لتنظيم التقديمات.
  • تعامل مع الأخطاء باستخدام try/catch وتحقق من شكل إرجاع IError.

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