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

سجِّل تطبيقًا كمعالج ملفات في نظام التشغيل.

Thomas Steiner

بما أنّ تطبيقات الويب أصبحت قادرة على قراءة الملفات وكتابتها، فإنّ الخطوة المنطقية التالية هي السماح للمطوّرين بإدراج تطبيقات الويب هذه كمعالِجات للملفات التي يمكن لتطبيقاتهم إنشاؤها ومعالجتها. تتيح لك واجهة برمجة التطبيقات File Handling API تنفيذ ذلك بالضبط. بعد تسجيل تطبيق ملف تحرير نصي كمعالِج ملفات وبعد تثبيته، يمكنك النقر بزر الماوس الأيمن على ملف .txt على نظام التشغيل macOS و selecting "Get Info" (الحصول على معلومات) لتوجيه نظام التشغيل بعد ذلك إلى فتح ملفات .txt دائمًا باستخدام هذا التطبيق بشكلٍ default (تلقائي).

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

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

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

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

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

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

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

دعم المتصفح

Browser Support

  • Chrome: 102.
  • Edge: 102.
  • Firefox: not supported.
  • Safari: not supported.

Source

رصد الميزات

للتحقّق مما إذا كانت واجهة برمجة التطبيقات 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
انقر مرّتين أو انقر بزر الماوس الأيمن على ملف في مستكشف الملفات في نظام التشغيل.
قائمة السياقات التي تظهر عند النقر بزر الماوس الأيمن على ملف مع تمييز عنصر Open with… Excalidraw
Excalidraw هو معالِج الملفات التلقائي لملفات .excalidraw.

الأمان

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

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

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

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

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

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

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

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

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

التحكّم في المستخدم

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

الشفافية

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

الملاحظات

يريد فريق Chrome معرفة تجاربك مع واجهة برمجة التطبيقات File Handling API.

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

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

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

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

هل رصدت خطأ في عملية تنفيذ Chrome؟ أم أنّ عملية التنفيذ مختلفة عن المواصفات؟

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

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

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

روابط مفيدة

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

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