تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

Thomas Steiner

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

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

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

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

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

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

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

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

دعم المتصفح

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

المصدر

رصد الميزات

للتحقّق مما إذا كانت واجهة برمجة التطبيقات 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. يتم وضع عمليات الإطلاق في قائمة الانتظار إلى أن يعالجها المستهلك المحدّد، ويتم استدعاؤها مرة واحدة بالضبط لكل عملية إطلاق. بهذه الطريقة، يتم التعامل مع كل عملية إطلاق، بغض النظر عن وقت تحديد consumer.

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

الأذونات والحفاظ على الأذونات وتحديثات معالج الملفات

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

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

روابط مفيدة

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

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