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

postFormsData

إرسال بيانات النموذج إلى منصة OneEntry.

🎯 ماذا تفعل هذه الطريقة؟​

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

حالات الاستخدام:

  • 📝 نماذج الاتصال
  • 📋 نماذج التسجيل
  • 💬 نماذج التعليقات
  • 📤 تحميل الملفات
  • 🎫 تذاكر الدعم

📖 شرح بسيط​

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

فكر في الأمر كالتالي:

User fills form → Your code calls postFormsData() → Data saved in OneEntry ✅

🚀 مثال بسيط جداً (ابدأ هنا!)​

السيناريو: لديك نموذج اتصال يحتوي فقط على حقل الاسم.

// Step 1: User fills the form (e.g., enters "John Doe")
// Step 2: Send it to OneEntry

const response = await FormData.postFormsData({
  formIdentifier: "contact_us",        // 👈 Your form's name
  formModuleConfigId: 2,               // 👈 Form config ID (from OneEntry admin)
  moduleEntityIdentifier: "blog",      // 👈 Where to save it (from OneEntry)
  replayTo: null,                      // 👈 Reply email (optional)
  status: "sent",                      // 👈 "sent" or "draft"
  formData: [                          // 👈 The actual form data
    {
      marker: "name",                  // 👈 Field name
      type: "string",                  // 👈 Field type
      value: "John Doe"                // 👈 User's input
    }
  ]
});

// ✅ Done! Form submitted successfully
console.log("Form submitted, ID:", response.formData.id);

هذا كل شيء! الآن دعنا نرى كيف نتعامل مع أنواع الحقول المختلفة...

📋 ما تحتاج لمعرفته قبل الاستخدام​

قبل استدعاء هذه الطريقة، تحتاج إلى هذه الأشياء الثلاثة من لوحة إدارة OneEntry:

  1. formIdentifier - الاسم الفريد لنموذجك (مثل "contact_us")
  2. formModuleConfigId - معرف تكوين النموذج (رقم، مثل 2)
  3. moduleEntityIdentifier - المكان الذي سيتم تخزين البيانات فيه (مثل "blog"، "contacts")

كيف تجد هذه المعلومات؟

  • تسجيل الدخول إلى OneEntry Admin
  • الانتقال إلى قسم النماذج
  • نسخ القيم من تكوين النموذج الخاص بك

🔧 توقيع الطريقة​

.postFormsData(

,

);

مخطط المعلمات​

المخطط (body)

body(required): IBodyPostFormData
جسم الطلب
مثال:

{
  "formIdentifier": "test-form",
  "formModuleConfigId": 2,
  "moduleEntityIdentifier": "blog",
  "replayTo": null,
  "status": "sent",
  "formData": [
    {
      "marker": "name",
      "type": "string",
      "value": "Test"
    }
  ]
}

body.formIdentifier(required): string
معرف نصي (علامة) للنموذج.
مثال: "form"

body.formModuleConfigId(required): number
المعرف الفريد لتكوين وحدة النموذج.
مثال: 2

body.moduleEntityIdentifier(required): string
معرف نصي (علامة) للكيان في الوحدة.
مثال: "blog"

body.replayTo(required): string | null
البريد الإلكتروني للرد عليه.
مثال: "some@email.com"

body.status(required): string
حالة النموذج.
مثال: "sent"

body.formData(required): FormDataPostType[]
مصفوفة من كائنات بيانات النموذج. تختلف قيم التقديم عن أشكال القراءة — انظر FormDataPostType.
مثال:

[
  {
    "marker": "name",
    "type": "string",
    "value": "Jack"
  }
]

body.fileQuery: IUploadingQuery
استعلام ملف اختياري لتحميل الملفات. محفوظ للتوافق: تقرأ SDK fileQuery من حقل الملف نفسه (انظر IBodyTypeFile)، وليس من الجسم، لذا فإن مجموعة واحدة هنا لا تغير مكان تحميل الملف.
مثال:

{
  "type": "page",
  "entity": "editor",
  "id": 3787
}

fileQuery.type(required): string
النوع، يحدد اسم المجلد في التخزين.
مثال: "page"

fileQuery.entity(required): string
اسم الكيان الذي يتم تحميل الملف منه، يحدد اسم المجلد في التخزين.
مثال: "editor"

fileQuery.id(required): number
معرف الكائن الذي يتم تحميل الملف منه، يحدد اسم المجلد في التخزين.
مثال: 3787

fileQuery.width: number
معامل العرض.
مثال: 0

fileQuery.height: number
معامل الارتفاع.
مثال: 0

fileQuery.compress: boolean
علامة التحسين (الضغط) للصور.
مثال: true

langCode: string
رمز اللغة. الافتراضي: "en_US"
مثال: "en_US"

أمثلة​

مثال بسيط​


const body = {
  ,
  ,
  ,
  ,
  ,
  
    {
      ,
      ,
      
    }
  ]
};

const response = await FormData.postFormsData(body);

مثال مع نوع بسيط من السمة "string"، "number"، "float"​


const body = {
  ,
  ,
  ,
  ,
  ,
  
    {
      ,
      ,
      
    },
    {
      ,
      ,
      
    },
    {
      ,
      ,
      
    }
  ]
};

const response = await FormData.postFormsData(body);

مثال مع نوع بسيط من السمة "date"، "dateTime"، "time"​


const body = {
  ,
  ,
  ,
  ,
  ,
  
    {
      ,
      ,
      
        "fullDate": "2024-05-07T21:02:00.000Z",
        "formattedValue": "08-05-2024 00:02",
        "formatString": "DD-MM-YYYY HH:mm"
      }
    }
  ]
};

const response = await FormData.postFormsData(body);

مثال مع نوع بسيط من السمة "text" (يمكن تقديم واحدة فقط من htmlValue أو plainValue أو mdValue)​


const body = {
  ,
  ,
  ,
  ,
  ,
  
    {
      ,
      ,
      
        {
          "htmlValue": "<p>Hello world</p>",
          
            "isImageCompressed": true,
            "editorMode": "html"
          }
        }
      ]
    }
  ]
};

const response = await FormData.postFormsData(body);

مثال مع نوع بسيط من السمة "textWithHeader" (يمكن تقديم واحدة فقط من htmlValue أو plainValue أو mdValue)​


const body = {
  ,
  ,
  ,
  ,
  ,
  
    {
      marker: ,
      type: ,
      : [
        {
          "header": "Headline",
          "htmlValue": "<p>Hello World</p>",
          
            "isImageCompressed": true,
            "editorMode": "html"
          }
        }
      ]
    }
  ]
};

const response = await FormData.postFormsData(body);

ثلاث طرق لإرفاق ملف

قيمة file / image / groupOfImages تقبل أي من هذه، ويمكن أن تكون مختلطة داخل مصفوفة واحدة:

  1. الملف نفسه — File، Blob أو FileList. تقوم SDK بتحميله أولاً وترسل ما تم إرجاعه من التحميل. أضف fileQuery إلى الحقل لاختيار مكان تخزينه؛ بدونها، تقوم SDK بتحميله إلى page / editor تحت معرف تم إنشاؤه.
  2. ملف موجود بالفعل في التخزين — الكائن FileUploading.upload() الذي تم إرجاعه. مرره كما هو: منذ 1.0.171، تقوم SDK بإرساله دون تغيير (باستثناء contentType، الذي يرفضه نقطة النهاية) بدلاً من تحميله مرة أخرى.
  3. قيمة مبنية يدويًا — IFileValue (filename، downloadLink، size) أو IImageValue (نفس الشيء بالإضافة إلى previewLink، params).

شيئان تصر عليهما نقطة النهاية:

  • القيمة تذهب في مصفوفة. كائن وحيد — وصف أو IFileValue — يتم الرد عليه بـ 400 formData's marker '…' value must be an array. كائن File وحيد مقبول: نتيجة التحميل هي بالفعل مصفوفة.
  • مجموعة الصور هي groupOfImages، جمع. groupOfImage يتم الرد عليه بـ 400 formData's marker '…' type must be one of […].

قبل 1.0.171، لم تعمل الطريقة الثانية: وصف وحيد ألقى fd.value.map is not a function داخل الحزمة، وتم تحميل مصفوفة من الأوصاف مرة أخرى كما لو كانت الأوصاف ملفات، وهو ما رفضته نقطة النهاية بـ value[0].filename is required. إذا كنت تستخدم إصدارًا أقدم، أرسل الملفات نفسها أو قيمة مبنية يدويًا.

مثال مع ملف موجود بالفعل في التخزين​


const uploaded = await FileUploading.(file, {
  type: 'page',
  entity: 'editor',
  id: 3492
});
const stored = Array.isArray(uploaded) ? uploaded[0] : uploaded;

const body = {
  ,
  ,
  ,
  ,
  ,
  
    {
      ,
      ,
      ]
    }
  ]
};

const response = await FormData.postFormsData(body);

مثال مع نوع السمة "image"​


const testImageUrl = ;
const filename = 'test-image.png';

/* في سيناريو العالم الحقيقي، يجب عليك استخدام واجهة برمجة التطبيقات File لإنشاء ملف من عنوان URL، ولكن من أجل البساطة، سنستخدم عنوان URL للملف المحدد مسبقًا ونستخدم طريقة createFileFromUrl لهذا المثال */
const file = await FileUploading.createFileFromUrl(testImageUrl, filename);

const body = {
  ,
  ,
  ,
  ,
  ,
  
    {
      marker: ,
      type: ,
      : [
        file
      ]
    }
  ]
};

const response = await FormData.postFormsData(body);

مثال مع نوع السمة "groupOfImages"​


const testImageUrl = ;
const filename = 'test-image.png';

/* في سيناريو العالم الحقيقي، يجب عليك استخدام واجهة برمجة التطبيقات File لإنشاء ملف من عنوان URL، ولكن من أجل البساطة، سنستخدم عنوان URL للملف المحدد مسبقًا ونستخدم طريقة createFileFromUrl لهذا المثال */
const file = await FileUploading.createFileFromUrl(testImageUrl, filename);

const body = {
  ,
  ,
  ,
  ,
  ,
  
    {
      marker: ,
      type: ,
      : [
        file
      ]
    }
  ]
};

const response = await FormData.postFormsData(body);

مثال مع نوع السمة "files"​


const testImageUrl = ;
const filename = 'test-image.png';

/* في سيناريو العالم الحقيقي، يجب عليك استخدام واجهة برمجة التطبيقات File لإنشاء ملف من عنوان URL، ولكن من أجل البساطة، سنستخدم عنوان URL للملف المحدد مسبقًا ونستخدم طريقة createFileFromUrl لهذا المثال */
const file = await FileUploading.createFileFromUrl(testImageUrl, filename);

const body = {
  ,
  ,
  ,
  ,
  ,
  
    {
      ,
      ,
      
        {
          "filename": "files/project/page/10/image/Screenshot-from-2024-05-02-15-23-14.png",
          "downloadLink": "http://my-site.com/cloud-static/files/project/page/10/image/Screenshot-from-2024-05-02-15-23-14.png",
          "size": 392585
        }
      ]
    }
  ]
};

const response = await FormData.postFormsData(body);

مثال مع نوع السمة "radioButton" أو "list"​


const body = {
  ,
  ,
  ,
  ,
  ,
  
    {
      ,
      ,
      ]
    }
  ]
};

const response = await FormData.postFormsData(body);

⚠️ يقوم التقديم بإرسال الخيارات المختارة كـ سلاسل نصية. الشكل [{ title, value }] الذي يخزنه سمة الصفحة يتم رفضه هنا بـ 400 formData's marker '<marker>' value[0] must be a string.

مثال مع نوع السمة "spam" (captcha)​

تقوم المنصة بإنشاء مفاتيح Google reCAPTCHA v3 — لا توجد خانة اختيار ولا لغز صورة. لا يُطلب من الزائر أي شيء: يتم الحصول على الرمز في المتصفح عند تقديم النموذج، ويتم تقييم النتيجة على الخادم.

اقرأ مفتاح الموقع من النموذج نفسه: يحمل حقل spam ذلك في settings.captcha.key، بجوار domainNames — النطاق الذي تم إصدار المفتاح له. احصل عليه من getFormByMarker بدلاً من ترميزه بشكل ثابت، وكن واعيًا أن المفتاح الذي تم إصداره لـ localhost لن يمر على نطاق الإنتاج.

<script src="https://www.google.com/recaptcha/api.js?render=YOUR_SITE_KEY"></script>

const siteKey = form..find((a) => a.type === 'spam').settings.captcha.key;

const token = await window..execute(siteKey, { action: 'submit' });

const body = {
  "formIdentifier": "contact_us",
  "formModuleConfigId": 2,
  "moduleEntityIdentifier": "contact-us",
  "replayTo": null,
  "status": "sent",
  "formData": [
    { "marker": "your_name", "type": "string", "value": "John Doe" },
    {
      ,
      ,
      , "siteKey": siteKey } }
    }
  ]
};

const response = await FormData.postFormsData(body);

⚠️ القيمة هي كائن الحدث، وليس سلسلة الرمز. يتم رفض الرمز العاري، أو القيمة الفارغة، أو الشكل الخاطئ بنفس الجملة — 400 Captcha Validation Failed, captcha type is: google — لذا فإن الطلب غير الصحيح لا يمكن تمييزه عن الروبوت. تحقق من الشكل قبل إلقاء اللوم على النتيجة.

يتم رفض نموذج تم تكوين حقل spam الخاص به ولكن لم يتم إرساله بـ 400 formData doesn't have spam attribute.

مثال مع نوع السمة "entity" (قائمة متداخلة)​


const body = {
  ,
  ,
  ,
  ,
  ,
  
    {
      ,
      ,
      , 32, 24]
    }
  ]
};

const response = await FormData.postFormsData(body);

القيمة - معرفات عددية للصفحات ومعرفات نصية للمنتجات. يجب أن تتضمن معرفات المنتجات البادئة 'p-'، على سبيل المثال، 'p-1-'، 'p-2-'، إلخ. p-[parentId]-[productId]

مثال مع نوع السمة "timeInterval"​


const body = {
  ,
  ,
  ,
  ,
  ,
  
    {
      marker: ,
      type: ,
      : [
        [
          "2025-02-11T16:00:00.000Z",
          "2025-02-13T16:00:00.000Z"
        ]
      ]
    },
  ]
};

const response = await FormData.postFormsData(body);

القيمة — مصفوفة من مصفوفات الفترات بتنسيق ISO 8601. على سبيل المثال 2025-02-11T16:00:00:000Z

2025 — السنة؛ 02 — الشهر؛ 11 — يوم الشهر؛ T — الفاصل بين التاريخ والوقت؛ 16:00:00 — الوقت بتنسيق الساعات:الدقائق:الثواني؛ 000Z — الميلي ثانية وإشارة المنطقة الزمنية. Z تعني أن الوقت محدد بتنسيق UTC.

مثال على الاستجابة:​

{
  "formData": {
    "formIdentifier": "test-form",
    "time": "2026-10-08T10:08:17.069Z",
    "formData": [
      {
        "marker": "name",
        "type": "string",
        "value": "Test"
      }
    ],
    "userIdentifier": "test@test.ru",
    "entityIdentifier": "blog",
    "fingerprint": "UQ_6e681661-9a58-4c18-9e94-ede07ecfd132",
    "isUserAdmin": false,
    "formModuleId": 2,
    "parentId": null,
    "id": 9087
  },
  "actionMessage": ""
}

مخطط الاستجابة​

المخطط: IPostFormResponse

formData: object
بيانات النموذج.
مثال:

{
  "id": 42,
  "formIdentifier": "contact_form",
  "time": "2023-10-01T12:00:00Z",
  "entityIdentifier": "blog",
  "isUserAdmin": false,
  "formModuleId": 2,
  "parentId": null,
  "userIdentifier": null,
  "formData": [
    {
      "marker": "name",
      "type": "string",
      "value": "Jack"
    }
  ]
}

formData.id: number
المعرف الفريد لصفحة النموذج.
مثال: 12345

formData.formIdentifier: string
معرف النموذج.
مثال: "contact_form"

formData.time: string
وقت تقديم النموذج.
مثال: "2023-10-01T12:00:00Z"

formData.entityIdentifier: string
معرف الكيان.
مثال: "blog"

formData.isUserAdmin: boolean
هل المستخدم هو المسؤول.
مثال: false

formData.formModuleId: number
معرف وحدة النموذج.
مثال: 2

formData.userIdentifier: string | null
معرف المستخدم.
مثال: null

formData.parentId: number | null
معرف الوالد.
مثال: null

formData.formData: FormDataType[]
بيانات حقول النموذج.
مثال:

[
  {
    "marker": "name",
    "type": "string",
    "value": "Jack"
  }
]

actionMessage: string
رسالة الإجراء لبيانات النموذج (يمكن أن تكون محلية).
مثال: "تم تقديم النموذج بنجاح"

أمثلة الاستخدام​

خطوات تفصيلية في الوثائق:

  • تقديم نموذج — جمع مدخلات نموذج الاتصال وإرسالها مرة أخرى إلى OneEntry.
  • نموذج الكيان — تقديم نموذج مع حقول من نوع الكيان (صفحات أو منتجات).

جربها مباشرة​

قم بتشغيل هذه الطريقة بشكل تفاعلي في JS SDK sandbox — قم بتوصيل عنوان URL لمشروعك ورمز التطبيق عند الزيارة الأولى، ثم افتح أي سيناريو أدناه لرؤية تقديمات النموذج الحقيقية: