دع الزوّار يرفقون ملفًا

الهدف

دع أحدهم على بوابتك يرفق مستندًا — إيصالًا أو صورة أو نموذجًا موقّعًا — بالسجل الذي يُنشئه.

قبل أن تبدأ

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

الخطوات

1. ارسم منتقي ملفات واربط قيمته بحقل من حالة الشاشة — state.document.

2. أرسله مع السجل. يسلّم المنتقي شاشتك الملف نفسه لا اسمه، فيذهب في نفس الكائن مع كل شيء آخر:

   createRecord("par_claim", {
     par_name: getState("subject"),
     par_document: getState("document")
   }, "saved");

3. صِفه في مخطط طلب الـ API، ككائن من أربع خصائص:

   "par_document": {
     "type": "object",
     "additionalProperties": false,
     "required": ["fileName", "contentType", "contentBase64"],
     "properties": {
       "fileName":      { "type": "string", "maxLength": 260 },
       "contentType":   { "type": "string", "maxLength": 200 },
       "sizeBytes":     { "type": "integer" },
       "contentBase64": { "type": "string", "maxLength": 5600000 }
     }
   }

4. خزّن السجل أولًا ثم الملف، لأن الملف يخصّ سجلًا ولا يوجد ما يُرفق به قبل أن يوجد الصفّ:

   var file = getInput('par_document');
   
   var id = createRecord('par_claim', {
     par_name: getInput('par_name'),
     par_raised_by_email: portalEmail(),
     par_document_name: isEmpty(file) ? '' : file.fileName
   });
   
   if (!isEmpty(file)) {
     putRecordFile('par_claim', id, 'par_document',
       file.fileName, file.contentType, file.contentBase64);
   }

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

   setState("document", null);

ما هو الملف المُنتقى فعلًا

أربعة حقول، وهي نفس الأربعة التي يعيدها getRecordFile لأي سكربت — فللملف الذاهب والملف العائد شكل واحد:

fileName	اسمه على جهاز الزائر نفسه
contentType	نوع وسائطه كما أبلغ عنه متصفحه
sizeBytes	حجمه — وهو ما يقوله التعليق
contentBase64	البايتات، كنص

التعليق المربوط بالكائن كله يُقرأ اسمَ الملف، فـ text(state.document) يقول contract.pdf لا شيئًا غير مقروء. ولعرض صورة مُنتقاة اربط مصدر img بـ fileUrl(state.document).

لماذا لا يوجد صفّ «إرفاق ملف» في القائمة المسموح بها

قائمة البوابة تسمّي عمليات الجدول — قراءة قائمة، قراءة واحد، إنشاء، تغيير، حذف — والملف ليس واحدًا منها. إنه يسافر في جسم الكتابة، فالبوابة التي يمكنها إنشاء مطالبة يمكنها وضع مستند على المطالبة التي تُنشئها، والتي لا يمكنها، لا يمكنها. لا شيء إضافي تمنحه، ولا شيء إضافي تنسى سحبه.

ولهذا أيضًا لا توجد أي نقطة نهاية للملفات على الإنترنت العام. تذهب البايتات إلى الـ Custom API الخاص بك، ويقرّر سكربتك على أي سجل تحطّ، ويخزّنها putRecordFile بصلاحيات السجل نفسه — فهو يحتاج Update على ذلك الصفّ، تمامًا كنموذج داخل المنصّة.

الإرفاق بسجل موجود من قبل

بالطريقة نفسها، عبر تغيير. أرسل الملف ضمن قيم updateRecord، واجعل Custom API خلف صفّ تغيير سجل يقرأ السجل ويحدّثه ثم يستدعي putRecordFile. في جدول عليه قاعدة تحدد سجلات الزائر يتبع الملف القاعدة أيضًا: لا يستطيع الزائر إرفاق ملف إلا بسجل تمنحه إياه القاعدة.

ما أقصى حجم للملف

٤ ميغابايت، والمنتقي يقول ذلك قبل رفع أي شيء.

وهذا أصغر ممّا تخزّنه المنصّة — فالنشر الذي يملك تخزين كائنات يقبل ملفات أكبر بكثير عبر نقطة نهاية السجل نفسها — والفرق مقصود. هنا يُرمَّز الملف نصًّا داخل جسم JSON ويبقى في متصفح الزائر ريثما يُكمل النموذج. مرفق ضخم على هذا الطريق يعني سلسلة نصية ضخمة في متصفح شخص غريب، وجسمًا لا ينبغي أن يُطلب من أي عقد تحليله.

نفس الشاشة داخل المنصّة

لا شيء يتغيّر. افتح التطبيق نفسه في بارسوير، فيكتب المعالج نفسه على الجدول مباشرة ويذهب الملف إلى عمود ملف في السجل عبر نقطة نهاية المنصّة نفسها. أنت ترسم شاشة واحدة، لا اثنتين.

ثلاثة أمور تُربك الناس

• اكتب السجل قبل الملف. يحتاج putRecordFile إلى معرّف سجل، والسكربت الذي يُرفق أولًا لا يجد ما يُرفق به.
• احتفظ باسم الملف في عمود نصّي بجانبه. القائمة التي تريد أن تقول «📎 invoice.pdf» ينبغي أن تقرأ عمودًا نصيًّا بسيطًا لا أن تجلب كل ملف لتعرف اسمه.
• الرفض يقرأه غرباء. إن رفضت مرفقًا — نوع ملف غير مناسب مثلًا — فاكتب الجملة للعامة: ستظهر بجوار الزر الذي ضغطوه.

تأكّد أنه نجح

أرفق ملفًا على البوابة، اضغط الزر، ثم افتح السجل في المنصّة. المستند على حقل ملف فيه، والاسم الذي خزّنته بجانبه — والبوابة لم ترَ أي نقطة نهاية للسجلات.