السماح لتطبيقات الويب المثبتة بأن تكون معالجات للملفات

سجّل أحد التطبيقات كمعالج ملفات في نظام التشغيل.

Thomas Steiner

والآن بعد أن أصبحت تطبيقات الويب قادرة على قراءة الملفات وكتابتها، تتمثل الخطوة المنطقية التالية في السماح للمطورين بالتعريف عن تطبيقات الويب هذه نفسها كمعالجات للملفات التي يمكن لتطبيقاتهم إنشاؤها ومعالجتها. تتيح لك واجهة برمجة تطبيقات معالجة الملفات إجراء ذلك بالضبط. بعد تسجيل تطبيق محرّر نصوص كمعالج ملفات، وبعد تثبيته، يمكنك النقر بزر الماوس الأيمن على ملف .txt على نظام التشغيل macOS واختيار "الحصول على معلومات" لتوجيه طلب إلى نظام التشغيل بعد ذلك أن يفتح دائمًا ملفات .txt باستخدام هذا التطبيق كإعداد تلقائي.

حالات الاستخدام المقترَحة لواجهة File Handling API

في ما يلي أمثلة على المواقع الإلكترونية التي قد تستخدم واجهة برمجة التطبيقات هذه:

• التطبيقات المكتبية مثل أدوات تحرير النصوص وتطبيقات جداول البيانات وصنّاع عرض الشرائح.
• برامج تحرير الرسومات وأدوات الرسم.
• أدوات تعديل مستويات ألعاب الفيديو

كيفية استخدام واجهة برمجة التطبيقات File Handling API

التحسين التدريجي

لا يمكن تعويض واجهة برمجة التطبيقات File Handling API في حد ذاته. ومع ذلك، يمكن تحقيق وظيفة فتح الملفات باستخدام تطبيق الويب من خلال طريقتين أخريين:

• تتيح Web Share API للمطوّرين تحديد تطبيقاتهم كهدف للمشاركة ليتمكّن المستخدمون من فتح الملفات من صفحة المشاركة الخاصة بنظام التشغيل.
• يمكن دمج File System Access API مع سحب الملفات وإفلاتها، ليتمكّن المطوّرون من التعامل مع الملفات التي تم إسقاطها في التطبيق المفتوح مسبقًا.

المتصفحات المتوافقة

التوافق مع المتصفح

• 102
• 102
• x
• x

المصدر

رصد الميزات

للتحقّق من توفُّر واجهة برمجة التطبيقات File Handling API، يمكنك استخدام:

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

ملاحظة: تقتصر معالجة الملفات حاليًا على أنظمة تشغيل أجهزة الكمبيوتر المكتبي.

الجزء التعريفي من File Handling API

كخطوة أولى، يجب أن تحدّد تطبيقات الويب في بيان تطبيق الويب نوع الملفات التي يمكنها التعامل معها بشكل واضح. تعمل واجهة File Handling 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. سيتم فتح أول اثنين في برنامج واحد، الأخير في عملاء متعددين إذا تمت معالجة ملفات متعددة.

ملاحظة: يجب تثبيت التطبيق كي يكون لهذا البيان أي تأثير. يمكنك الاطّلاع على المزيد من المعلومات في سلسلة مقالات على هذا الموقع الإلكتروني بالتحديد حول جعل تطبيقك قابلاً للتثبيت.

الجزء الضروري من File Handling 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.
    }
  });
}

دعم أدوات مطوّري البرامج

لا تتوفّر إمكانية استخدام "أدوات مطوري البرامج" حتى الآن، ولكنني قدّمتُ طلب ميزة للحصول على الدعم.

الخصائص الديموغرافية

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

انقر مرّتين أو انقر بزر الماوس الأيمن على ملف في مستكشف الملفات بنظام التشغيل.

ExcaliDraw هو معالج الملفات التلقائي لملفات .excalidraw.

الأمان

لقد صمّم فريق Chrome واجهة برمجة التطبيقات File Handling API وطبّقها باستخدام المبادئ الأساسية المحدّدة في التحكّم في الوصول إلى الميزات الفعّالة للنظام الأساسي للويب، بما في ذلك التحكّم في المستخدم والشفافية وهندسة العمل.

الأذونات واستمرار الأذونات وتحديثات معالج الملفات

لضمان ثقة المستخدم وأمان ملفات المستخدمين، عندما تفتح واجهة برمجة تطبيقات معالجة الملفات ملفًا، سيظهر طلب الإذن قبل أن يتمكن تطبيق الويب التقدّمي من عرض ملف. ستظهر رسالة طلب الإذن هذه مباشرةً بعد أن يختار المستخدم تطبيق الويب التقدّمي (PWA) لفتح ملف، بحيث يكون الإذن مقترنًا إلى حدّ كبير بإجراء فتح ملف باستخدام تطبيق الويب التقدّمي (PWA)، ما يجعله أكثر وضوحًا وملاءمةً.

وسيظهر هذا الإذن في كل مرة إلى أن ينقر المستخدم على السماح أو الحظر بمعالجة الملف في الموقع الإلكتروني، أو يتجاهل الإشعار ثلاث مرات (بعدها سيحظر Chromium هذا الإذن). سيستمر الإعداد المحدَّد في إغلاق تطبيق الويب التقدّمي (PWA) وإعادة فتحه.

عند اكتشاف تعديلات وتغييرات البيان في القسم "file_handlers"، ستتم إعادة ضبط الأذونات.

الاختبارات المتعلقة بالملف

هناك فئة كبيرة من متجهات الهجوم التي يتم فتحها من خلال السماح للمواقع الإلكترونية بالوصول إلى الملفات. ويمكنك الاطّلاع على هذه التفاصيل في المقالة حول File System Access API. إنّ القدرة الإضافية المرتبطة بالأمان التي توفّرها واجهة File Handling API على واجهة برمجة التطبيقات File System Access API هي القدرة على منح إمكانية الوصول إلى ملفات معيَّنة من خلال واجهة المستخدم المدمجة في نظام التشغيل، بدلاً من استخدام منتقي الملفات المعروض في أحد تطبيقات الويب.

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

اختبارات المعالج التلقائي

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

تحكُّم المستخدم

تنص المواصفات على أنّه يجب على المتصفّحات عدم تسجيل كل موقع إلكتروني يمكنه التعامل مع الملفات كمعالج ملفات. بدلاً من ذلك، يجب أن يكون تسجيل معالجة الملفات محدودًا بعد التثبيت ولا يحدث أبدًا بدون تأكيد صريح من المستخدم، خاصةً إذا كان الموقع الإلكتروني سيصبح المعالج التلقائي. بدلاً من اختراق الإضافات الحالية، مثل .json التي قد يكون لدى المستخدم معالِج تلقائي مُسجَّل لها حاليًا، على المواقع الإلكترونية التفكير في تصميم الإضافات الخاصة بها.

الشفافية

تتيح جميع أنظمة التشغيل للمستخدمين تغيير ارتباطات الملفات الحالية. هذا خارج نطاق المتصفح.

إضافة ملاحظات

يرغب فريق Chrome في معرفة رأيك بتجاربك مع File Handling API.

أخبرنا عن تصميم واجهة برمجة التطبيقات

هل هناك مشكلة في واجهة برمجة التطبيقات لا تعمل على النحو المتوقَّع؟ أو هل هناك طرق أو خصائص مفقودة تحتاج إلى تنفيذ فكرتك؟ هل لديك سؤال أو تعليق على نموذج الأمان؟

• عليك الإبلاغ عن مشكلة في المواصفات على مستودع GitHub المقابل، أو إضافة أفكارك إلى مشكلة حالية.

الإبلاغ عن مشكلة في التنفيذ

هل واجهت خطأً في تنفيذ Chrome؟ أم أنّ التنفيذ مختلف عن المواصفات؟

• عليك الإبلاغ عن خطأ على new.crbug.com. واحرص على تضمين أكبر قدر ممكن من التفاصيل وتعليمات بسيطة لإعادة الإنتاج، وأدخِل UI>Browser>WebAppInstalls>FileHandling في مربّع المكوّنات. تعمل ميزة Glitch بشكل رائع لمشاركة عمليات إعادة الإنشاء بسرعة وسهولة.

إظهار الدعم لواجهة برمجة التطبيقات

هل تخطّط لاستخدام واجهة برمجة التطبيقات File Handling API؟ يساعد الدعم العام فريق Chrome في تحديد أولويات الميزات ويوضح لمورّدي المتصفِّح الآخرين مدى أهمية دعمهم.

• شارِك كيف تنوي استخدامها في سلسلة محادثات WICG Discourse.
• يمكنك إرسال تغريدة إلى @ChromiumDev باستخدام الهاشتاغ #FileHandling وإعلامنا بمكان استخدامك لها وطريقة استخدامك لها.

روابط مفيدة

• شرح علني
• عرض توضيحي لواجهة برمجة تطبيقات معالجة الملفات | مصدر العرض التوضيحي لواجهة برمجة تطبيقات معالجة الملفات
• خطأ في تتبُّع Chromium
• إدخال ChromeStatus.com
• مكوّن Blink: UI>Browser>WebAppInstalls>FileHandling
• مراجعة TAG
• موضع معايير Mozilla

شكر وتقدير

تم تحديد واجهة برمجة التطبيقات File Handling API من قِبل Eric Willigers وJay Harris وRaymes Khoury. راجعت هذه المقالة جو ميدلي.