انتخاب فایل در ویجت Flutter

با app.pickFile و app.pickFiles می‌توانید از کاربر نهایی فایل بگیرید؛ مثلاً برای خواندن متن یا ارسال یک سند به سرویس خودتان. انتخاب از دستگاه با فایل‌های ویجت در پنل فرق دارد: فایل انتخاب‌شده خودکار در سرور اپ‌ادیتور بارگذاری یا به فایل‌های آفلاین اپ اضافه نمی‌شود.

استفاده از نمونهٔ آماده

1. یک ویجت Flutter سفارشی اضافه کنید و تنظیمات آن را باز کنید.
2. روی نمونه انتخاب فایل بزنید؛ این کار کد نمونه را در ویرایشگر قرار می‌دهد.
3. برای انتخاب چند سند با حداکثر حجم ۱۰ مگابایت برای هر فایل، پارامترهای زیر را وارد کنید:

{
  "allowedExtensions": ["pdf", "txt", "csv"],
  "maxBytes": 10485760,
  "multiple": true
}

4. در صورت نیاز، در فهرست عملکردهای ویجت شناسهٔ onSelected تعریف کنید تا بعد از انتخاب موفق اجرا شود.
5. آیتم و صفحه را ذخیره کنید، آنالیز کد بگیرید و خروجی جدید بسازید. پیش‌نمایش پنل کد Flutter سفارشی را اجرا نمی‌کند.

پارامتر نمونه	رفتار
allowedExtensions	پسوندهای مجاز مانند pdf؛ حذف آن همهٔ نوع‌های فایل را مجاز می‌کند
maxBytes	سقف حجم هر فایل برحسب بایت؛ پیش‌فرض نمونه ۱۰ مگابایت است
multiple	با true چند فایل انتخاب می‌شود؛ پیش‌فرض انتخاب یک فایل است

نمونه، نام اولین فایل را در selected_file_name، اندازهٔ آن را در selected_file_size و فهرست نام‌ها را در selected_file_names می‌نویسد. این متغیرها موقت‌اند و فقط مشخصات فایل را دارند. برای خواندن یا ارسال محتوا، کد نمونه را گسترش دهید؛ نام فایل به‌تنهایی دسترسی به محتوای آن نمی‌دهد. انصراف، انتخاب قبلی نمونه را پاک نمی‌کند.

استفاده در کد خودتان

این تابع را از رویداد لمس دکمه، مانند onPressed، فراخوانی کنید. نوع‌های لازم با import معمول AppEditorWidgetContext.dart در دسترس‌اند:

Future<void> readSelectedText(AppEditorWidgetContext app) async {
  try {
    final file = await app.pickFile(
      allowedExtensions: ['txt', 'csv'],
      maxBytes: 1024 * 1024,
    );
    if (file == null || !app.mounted) return;
    final text = await file.readText();
    if (!app.mounted) return;
    await app.addVar(
      name: 'imported_text',
      value: text,
      overwrite: true,
    );
    app.showMessage('فایل خوانده شد');
  } on AppEditorFilePickerException catch (error) {
    if (app.mounted) app.showMessage(error.message);
  } catch (_) {
    if (app.mounted) app.showMessage('خواندن فایل انجام نشد');
  }
}

API	کاربرد
await app.pickFile(...)	انتخاب یک فایل؛ انصراف null برمی‌گرداند
await app.pickFiles(...)	انتخاب چند فایل؛ انصراف فهرست خالی برمی‌گرداند
file.name، file.extension، file.size	نام، پسوند و حجم گزارش‌شده برحسب بایت؛ حجم نامشخص ممکن است صفر باشد
await file.readBytes()	خواندن محتوای باینری؛ مناسب تصویر، PDF یا آپلود
await file.readText()	خواندن متن UTF-8؛ مناسب TXT و CSV، نه استخراج متن PDF
file.readStream()	خواندن تدریجی محتوا؛ مناسب فایل‌های بزرگ
file.path	مسیر موقت در خروجی بومی؛ در وب null است

برای آپلود می‌توانید بایت‌های فایل را با MultipartFile و FormData به درخواست شبکهٔ ویجت بدهید. دادهٔ باینری را در متغیرهای ذخیره‌شدهٔ دستگاه قرار ندهید.

محدودیت‌ها و خطاها

• انتخابگر را مستقیم از لمس کاربر باز کنید؛ اجرای آن در build یا تایمر، به‌خصوص در وب، مناسب نیست.
• پسوندها را مانند pdf بنویسید. فهرست خالی معتبر نیست. فیلتر پسوند، محتوای واقعی فایل را تأیید نمی‌کند؛ سرویس دریافت‌کننده باید نوع و حجم فایل را هم بررسی کند.
• maxBytes در API اختیاری است و باید مثبت باشد؛ حذف آن از فراخوانی API یعنی سقف تعیین نشده است. سقف هنگام انتخاب و خواندن محتوا بررسی می‌شود. در انتخاب چند فایل، نامعتبر بودن یک فایل کل درخواست را ناموفق می‌کند.
• کدهای خطا شامل invalidExtension، fileTooLarge، pickerBusy، unavailable و pickerFailed است. انصراف خطا نیست. هم‌زمان فقط یک انتخابگر فایل در اپ باز می‌شود.
• در اندروید، انتخاب فایل از مسیر انتخابگر سند سیستم انجام می‌شود و به مجوز دسترسی عمومی حافظه نیاز ندارد. مسیر موقت و دسترسی فایل را برای اجرای بعدی اپ دائمی فرض نکنید.
• در یک StatefulWidget، پس از await و پیش از setState، علاوه بر app.mounted، مقدار mounted خود ویجت را هم بررسی کنید.