پرش به مطلب اصلی

بگذارید بازدیدکنندگان فایل پیوست کنند

هدف​

بگذارید کسی در درگاه شما سندی پیوست کند — یک رسید، یک عکس، یک فرم امضاشده — به رکوردی که دارد می‌سازد.

پیش از شروع​

  • درگاهی که چه کسی می‌تواند باز کند در آن روی کسانی که وارد می‌شوند است، چون پیوست‌کردن فایل بخشی از یک نوشتن است و نوشتن به کسی نیاز دارد که به او نسبت داده شود. ببینید از بازدیدکنندگان بخواهید وارد شوند.
  • جدولی که ستون فایل یا تصویر داشته باشد.
  • سطر ساختن که از پیش در فهرست مجاز درگاه هست، از بگذارید بازدیدکنندگان تغییرات را ذخیره کنند. برای فایل چیزی اضافه نمی‌شود — فایل در بدنهٔ همان نوشتن سفر می‌کند.

گام‌ها​

  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» باید یک ستون متنی ساده بخواند، نه اینکه هر فایل را بیاورد تا نامش را بفهمد.
  • پیام رد را غریبه‌ها می‌خوانند. اگر پیوستی را رد می‌کنید — مثلاً نوع نادرست فایل — جمله را برای عموم بنویسید: کنار همان دکمه‌ای که فشرده‌اند ظاهر می‌شود.

تأیید کنید که کار کرده​

در درگاه فایلی پیوست کنید، دکمه را بزنید، بعد رکورد را در پلتفرم باز کنید. سند روی فیلد فایل آن است، با نامی که ذخیره کرده‌اید در کنارش — و درگاه هرگز نقطهٔ پایانی رکوردی ندید.