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

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

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

Thomas Steiner

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

حالات الاستخدام المقترَحة لواجهة برمجة تطبيقات معالجة الملفات

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

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

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

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

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

تتيح 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_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. سيتم فتح أول اثنين في عميل واحد، أو آخر في عدة عملاء إذا كان يتم التعامل مع ملفات متعددة.

الجزء الأساسي من واجهة برمجة تطبيقات معالجة الملفات

والآن بعد أن أعلن التطبيق عن الملفات التي يمكنه التعامل معها من الناحية النظرية وعنوان 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 — انقر نقرًا مزدوجًا أو انقر بزر الماوس الأيمن على ملف في مستكشف الملفات في نظام التشغيل.

قائمة السياق التي تظهر عند النقر بزر الماوس الأيمن على ملف مع تمييز العنصر "فتح باستخدام... Excali draw". — ExcaliDraw هو معالِج الملفات التلقائي لـ `.excalidraw` ملف.

الأمان

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

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

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

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

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

التحديات المتعلّقة بالملفات

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

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

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

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

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

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

الشفافية

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

ملاحظات

يريد فريق Chrome معرفة رأيك بشأن تجاربك في استخدام واجهة برمجة تطبيقات معالجة الملفات.

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

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

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

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

هل واجهت مشكلة في التنفيذ في Chrome؟ أم أن التنفيذ يختلف عن المواصفات؟

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

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

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

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

روابط مفيدة

شكر وتقدير

تمّ تحديد واجهة برمجة تطبيقات معالجة الملفات من قِبل إريك ويلجر، جاي هاريس، ريمس خوري تمت مراجعة هذه المقالة بواسطة جو ميدلي.