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

تسجيل التطبيق كمعالج ملفات من خلال نظام التشغيل

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

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

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

  • تطبيقات Office، مثل برامج تحرير النصوص وتطبيقات جداول البيانات وتطبيقات إنشاء عروض الشرائح
  • برامج تحرير الرسومات وأدوات الرسم
  • أدوات تعديل مستويات ألعاب الفيديو

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

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

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

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

دعم المتصفح

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

  • Chrome: 102.
  • Edge: 102.
  • Firefox: غير متوافق
  • Safari: غير متوافق

المصدر

رصد الميزات

للتحقّق مما إذا كانت واجهة برمجة التطبيقات 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" في قائمة السياقات. يمكنك الاطّلاع على التنفيذ في رمز المصدر.

نافذة الباحث في نظام التشغيل macOS مع ملف Excalidraw
انقر مرّتين أو انقر بزر الماوس الأيمن على ملف في مستكشف الملفات في نظام التشغيل.
قائمة السياقات التي تظهر عند النقر بزر الماوس الأيمن على ملف مع تمييز عنصر "الفتح باستخدام…" Excalidraw
Excalidraw هو معالِج الملفات التلقائي لملفات .excalidraw.

الأمان

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

الأذونات واستمرارية الأذونات وتعديلات معالِج الملفات

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

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

عند تعديل ملف البيان ورصد التغييرات في قسم "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 في تحديد الميزات التي يجب أن تحظى بالأولوية، ويُظهر لموفّري المتصفّحات الآخرين مدى أهمية توفير هذه الميزات.

روابط مفيدة

الشكر والتقدير

تم تحديد واجهة برمجة التطبيقات File Handling API من قِبل إيريك ويليجرز، جاي هاريس، راميس خوري. تمت مراجعة هذه المقالة من قِبل Joe Medley.