اجازه دهید برنامه های کاربردی وب نصب شده، کنترل کننده فایل باشند

یک برنامه را به عنوان یک مدیریت کننده فایل در سیستم عامل ثبت کنید.

توماس اشتاینر

حالا که برنامه‌های وب قادر به خواندن و نوشتن فایل‌ها هستند، گام منطقی بعدی این است که به توسعه‌دهندگان اجازه دهیم همین برنامه‌های وب را به عنوان کنترل‌کننده‌های فایل برای فایل‌هایی که برنامه‌هایشان می‌توانند ایجاد و پردازش کنند، اعلام کنند. رابط برنامه‌نویسی کاربردی مدیریت فایل (File Handling API) به شما امکان می‌دهد دقیقاً همین کار را انجام دهید. پس از ثبت یک برنامه ویرایشگر متن به عنوان کنترل‌کننده فایل و پس از نصب آن، می‌توانید روی یک فایل .txt در macOS کلیک راست کرده و گزینه «دریافت اطلاعات» را انتخاب کنید تا به سیستم عامل دستور دهید که همیشه فایل‌های .txt را با این برنامه به عنوان پیش‌فرض باز کند.

موارد استفاده پیشنهادی برای API مدیریت فایل

نمونه‌هایی از سایت‌هایی که ممکن است از این API استفاده کنند عبارتند از:

  • برنامه‌های آفیس مانند ویرایشگرهای متن، برنامه‌های صفحه گسترده و سازندگان اسلایدشو.
  • ویرایشگرهای گرافیکی و ابزارهای طراحی.
  • ابزارهای ویرایشگر مراحل بازی‌های ویدیویی

نحوه استفاده از API مدیریت فایل

بهبود تدریجی

API مدیریت فایل به خودی خود نمی‌تواند polyfill شود. با این حال، قابلیت باز کردن فایل‌ها با یک برنامه وب از دو طریق دیگر قابل دستیابی است:

  • API هدف اشتراک‌گذاری وب به توسعه‌دهندگان اجازه می‌دهد تا برنامه خود را به عنوان یک هدف اشتراک‌گذاری مشخص کنند تا فایل‌ها بتوانند از صفحه اشتراک‌گذاری سیستم عامل باز شوند.
  • API دسترسی به سیستم فایل می‌تواند با کشیدن و رها کردن فایل ادغام شود، بنابراین توسعه‌دهندگان می‌توانند فایل‌های رها شده را در برنامه‌ای که از قبل باز شده است، مدیریت کنند.

پشتیبانی مرورگر

Browser Support

  • کروم: ۱۰۲.
  • لبه: ۱۰۲.
  • فایرفاکس: پشتیبانی نمی‌شود.
  • سافاری: پشتیبانی نمی‌شود.

Source

تشخیص ویژگی

برای بررسی اینکه آیا API مدیریت فایل پشتیبانی می‌شود، از دستور زیر استفاده کنید:

if ('launchQueue' in window && 'files' in LaunchParams.prototype) {
  // The File Handling API is supported.
}

بخش اعلانی API مدیریت فایل

در اولین قدم، برنامه‌های وب باید به صورت اعلانی در مانیفست برنامه وب خود توضیح دهند که چه نوع فایل‌هایی را می‌توانند مدیریت کنند. API مدیریت فایل، مانیفست برنامه وب را با یک ویژگی جدید به نام "file_handlers" گسترش می‌دهد که آرایه‌ای از، خب، مدیریت‌کننده‌های فایل را می‌پذیرد. یک مدیریت‌کننده فایل، شیء‌ای با این ویژگی‌ها است:

  • یک ویژگی "action" که به عنوان مقدار خود به یک URL در محدوده برنامه اشاره می‌کند.
  • یک ویژگی "accept" با یک شیء از نوع MIME به عنوان کلید و فهرست‌هایی از پسوندهای فایل به عنوان مقادیر آنها.
  • یک ویژگی "icons" با آرایه‌ای از آیکون‌های ImageResource . برخی از سیستم‌عامل‌ها به یک نوع فایل اجازه می‌دهند تا آیکونی را نمایش دهد که نه تنها آیکون برنامه مرتبط است، بلکه یک آیکون ویژه مربوط به استفاده از آن نوع فایل با برنامه است.
  • یک ویژگی "launch_type" که مشخص می‌کند آیا چندین فایل باید در یک کلاینت واحد یا در چندین کلاینت باز شوند. مقدار پیش‌فرض "single-client" است. اگر کاربر چندین فایل را باز کند و اگر کنترل‌کننده فایل با "multiple-clients" به عنوان "launch_type" خود حاشیه‌نویسی شده باشد، بیش از یک اجرای برنامه رخ می‌دهد و برای هر اجرا، آرایه LaunchParams.files ( به ادامه مطلب مراجعه کنید) فقط یک عنصر خواهد داشت.

مثال زیر، که فقط گزیده‌ای از مانیفست برنامه وب مربوط را نشان می‌دهد، باید موضوع را روشن‌تر کند:

{
  "file_handlers": [
    {
      "action": "/open-csv",
      "accept": {
        "text/csv": [".csv"]
      },
      "icons": [
        {
          "src": "csv-icon.png",
          "sizes": "256x256",
          "type": "image/png"
        }
      ],
      "launch_type": "single-client"
    },
    {
      "action": "/open-svg",
      "accept": {
        "image/svg+xml": ".svg"
      },
      "icons": [
        {
          "src": "svg-icon.png",
          "sizes": "256x256",
          "type": "image/png"
        }
      ],
      "launch_type": "single-client"
    },
    {
      "action": "/open-graf",
      "accept": {
        "application/vnd.grafr.graph": [".grafr", ".graf"],
        "application/vnd.alternative-graph-app.graph": ".graph"
      },
      "icons": [
        {
          "src": "graf-icon.png",
          "sizes": "256x256",
          "type": "image/png"
        }
      ],
      "launch_type": "multiple-clients"
    }
  ]
}

این برای یک برنامه فرضی است که فایل‌های مقادیر جدا شده با کاما ( .csv ) را در /open-csv ، فایل‌های گرافیک برداری مقیاس‌پذیر ( .svg ) را در /open-svg و یک فرمت فایل Grafr ساختگی با هر یک از پسوندهای .grafr ، .graf یا .graph را در /open-graf مدیریت می‌کند. دو مورد اول در یک کلاینت واحد باز می‌شوند، و مورد آخر در صورت مدیریت چندین فایل در چندین کلاینت.

بخش ضروری API مدیریت فایل

حالا که برنامه از نظر تئوری اعلام کرده است که چه فایل‌هایی را می‌تواند در کدام URL درون-دامنه مدیریت کند، باید در عمل کاری را با فایل‌های ورودی انجام دهد. اینجاست که launchQueue وارد عمل می‌شود. برای دسترسی به فایل‌های راه‌اندازی شده، یک سایت باید یک مصرف‌کننده برای شیء window.launchQueue مشخص کند. راه‌اندازی‌ها تا زمانی که توسط مصرف‌کننده مشخص شده مدیریت شوند، در صف قرار می‌گیرند، که دقیقاً یک بار برای هر راه‌اندازی فراخوانی می‌شود. به این ترتیب، هر راه‌اندازی، صرف نظر از زمان مشخص شدن مصرف‌کننده، مدیریت می‌شود.

if ('launchQueue' in window && 'files' in LaunchParams.prototype) {
  launchQueue.setConsumer((launchParams) => {
    // Nothing to do when the queue is empty.
    if (!launchParams.files.length) {
      return;
    }
    for (const fileHandle of launchParams.files) {
      // Handle the file.
    }
  });
}

پشتیبانی از ابزارهای توسعه (DevTools)

در زمان نگارش این مطلب، پشتیبانی DevTools وجود ندارد، اما من درخواست اضافه شدن این پشتیبانی را ثبت کرده‌ام.

نسخه آزمایشی

من پشتیبانی از مدیریت فایل را به Excalidraw ، یک برنامه طراحی به سبک کارتونی، اضافه کرده‌ام. برای آزمایش آن، ابتدا باید Excalidraw را نصب کنید. وقتی فایلی را با آن ایجاد کردید و آن را در جایی در سیستم فایل خود ذخیره کردید، می‌توانید فایل را با دوبار کلیک یا کلیک راست باز کنید و سپس "Excalidraw" را در منوی زمینه انتخاب کنید. می‌توانید پیاده‌سازی آن را در کد منبع بررسی کنید.

پنجره‌ی جستجوگر macOS با فایل Excalidraw.
روی یک فایل در فایل اکسپلورر سیستم عامل خود دوبار کلیک کنید یا راست کلیک کنید.
منوی زمینه‌ای که هنگام کلیک راست روی فایلی که گزینه‌ی «باز کردن با…» در آن هایلایت شده است، ظاهر می‌شود.
Excalidraw مدیریت‌کننده‌ی پیش‌فرض فایل‌ها برای فایل‌های .excalidraw است.

امنیت

تیم کروم، رابط برنامه‌نویسی کاربردی مدیریت فایل (File Handling API) را با استفاده از اصول اصلی تعریف‌شده در «کنترل دسترسی به ویژگی‌های قدرتمند پلتفرم وب» ، شامل کنترل کاربر، شفافیت و ارگونومی، طراحی و پیاده‌سازی کرده است.

مجوزها، تداوم مجوزها و به‌روزرسانی‌های مدیریت‌کننده فایل

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

این مجوز هر بار نشان داده می‌شود تا زمانی که کاربر روی «مجاز» یا «مسدود کردن» مدیریت فایل برای سایت کلیک کند، یا سه بار درخواست را نادیده بگیرد (پس از آن کرومیوم این مجوز را ممنوع و مسدود می‌کند). تنظیم انتخاب شده در طول بسته شدن و بازگشایی PWA ادامه خواهد داشت.

هنگامی که به‌روزرسانی‌های مانیفست و تغییرات در بخش "file_handlers" شناسایی شوند، مجوزها بازنشانی می‌شوند.

دسته بزرگی از مسیرهای حمله وجود دارد که با اجازه دادن به وب‌سایت‌ها برای دسترسی به فایل‌ها باز می‌شوند. این موارد در مقاله مربوط به API دسترسی به سیستم فایل شرح داده شده‌اند. قابلیت امنیتی اضافی که API مدیریت فایل نسبت به API دسترسی به سیستم فایل ارائه می‌دهد، امکان اعطای دسترسی به فایل‌های خاص از طریق رابط کاربری داخلی سیستم عامل است، برخلاف انتخابگر فایل که توسط یک برنامه وب نشان داده می‌شود.

هنوز این خطر وجود دارد که کاربران با باز کردن یک فایل، ناخواسته به یک برنامه وب دسترسی به آن را بدهند. با این حال، به طور کلی درک می‌شود که باز کردن یک فایل به برنامه‌ای که با آن باز شده است اجازه می‌دهد تا آن فایل را بخواند و/یا دستکاری کند. بنابراین، انتخاب صریح کاربر برای باز کردن یک فایل در یک برنامه نصب شده، مانند از طریق منوی زمینه "باز کردن با..."، می‌تواند به عنوان یک سیگنال کافی از اعتماد به برنامه تلقی شود.

چالش‌های مدیریت‌کننده پیش‌فرض

استثنا در این مورد زمانی است که هیچ برنامه‌ای روی سیستم میزبان برای یک نوع فایل خاص وجود نداشته باشد. در این حالت، برخی از سیستم عامل‌های میزبان ممکن است به طور خودکار و بدون هیچ گونه دخالتی از سوی کاربر، کنترل‌کننده‌ی تازه ثبت شده را به کنترل‌کننده‌ی پیش‌فرض برای آن نوع فایل ارتقا دهند. این بدان معناست که اگر کاربر روی فایلی از آن نوع دوبار کلیک کند، آن فایل به طور خودکار در برنامه‌ی وب ثبت شده باز می‌شود. در چنین سیستم عامل‌های میزبانی، هنگامی که عامل کاربر تشخیص می‌دهد که هیچ کنترل‌کننده‌ی پیش‌فرضی برای آن نوع فایل وجود ندارد، ممکن است برای جلوگیری از ارسال تصادفی محتوای یک فایل به یک برنامه‌ی وب بدون رضایت کاربر، یک درخواست مجوز صریح لازم باشد.

کنترل کاربر

این مشخصات بیان می‌کند که مرورگرها نباید هر سایتی را که می‌تواند فایل‌ها را مدیریت کند، به عنوان یک کنترل‌کننده فایل ثبت کنند. در عوض، ثبت کنترل‌کننده فایل باید پشت نصب باشد و هرگز بدون تأیید صریح کاربر انجام نشود، به خصوص اگر قرار است سایتی به کنترل‌کننده پیش‌فرض تبدیل شود. به جای ربودن پسوندهای موجود مانند .json که احتمالاً کاربر از قبل یک کنترل‌کننده پیش‌فرض برای آن ثبت کرده است، سایت‌ها باید ساخت پسوندهای خودشان را در نظر بگیرند.

شفافیت

همه سیستم عامل‌ها به کاربران اجازه می‌دهند تا پیوندهای فایل فعلی را تغییر دهند. این خارج از محدوده مرورگر است.

بازخورد

تیم کروم می‌خواهد از تجربیات شما در مورد رابط برنامه‌نویسی کاربردی مدیریت فایل (File Handling API) مطلع شود.

در مورد طراحی API به ما بگویید

آیا چیزی در مورد API وجود دارد که آنطور که انتظار داشتید کار نمی‌کند؟ یا متدها یا ویژگی‌هایی که برای پیاده‌سازی ایده‌تان به آنها نیاز دارید، وجود ندارند؟ در مورد مدل امنیتی سؤال یا نظری دارید؟

  • یک مشکل خاص را در مخزن گیت‌هاب مربوطه ثبت کنید، یا نظرات خود را به یک مشکل موجود اضافه کنید.

گزارش مشکل در پیاده‌سازی

آیا در پیاده‌سازی کروم اشکالی پیدا کردید؟ یا پیاده‌سازی با مشخصات متفاوت است؟

  • یک اشکال را در new.crbug.com ثبت کنید. حتماً تا حد امکان جزئیات، دستورالعمل‌های ساده برای بازتولید را ذکر کنید و در کادر Components UI>Browser>WebAppInstalls>FileHandling وارد کنید.

نمایش پشتیبانی از API

آیا قصد دارید از API مدیریت فایل استفاده کنید؟ پشتیبانی عمومی شما به تیم کروم کمک می‌کند تا ویژگی‌ها را اولویت‌بندی کنند و به سایر فروشندگان مرورگر نشان می‌دهد که پشتیبانی از آنها چقدر حیاتی است.

  • نحوه‌ی استفاده از آن را در تاپیک گفتمان WICG به اشتراک بگذارید.
  • با استفاده از هشتگ #FileHandling یک توییت به @ChromiumDev ارسال کنید و به ما بگویید که کجا و چگونه از آن استفاده می‌کنید.

لینک‌های مفید

تقدیرنامه‌ها

رابط برنامه‌نویسی کاربردی مدیریت فایل (File Handling API) توسط اریک ویلیگرز ، جی هریس و ریمز خوری مشخص شده است. این مقاله توسط جو مدلی بررسی شده است.