مرحلة التجربة والتقييم في File System Observer API

Thomas Steiner
Thomas Steiner

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

تعمل واجهة برمجة التطبيقات File System Observer API، التي تم طرحها في مرحلة التجربة والتقييم من الإصدار 129 من Chrome، على تغيير ذلك، وتتيح للمطوّرين تلقّي تنبيهات تلقائيًا عند حدوث تغييرات. يشرح هذا الدليل طريقة عمل الميزة وكيفية تجربتها.

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

استخدِم واجهة برمجة التطبيقات File System Observer API في التطبيقات التي تحتاج إلى تلقّي إشعارات بشأن التغييرات المحتملة في نظام الملفات فور حدوثها.

  • بيئات التطوير المتكاملة المستندة إلى الويب (IDE) التي تعرض تمثيلاً لشجرة نظام ملفات المشروع.
  • التطبيقات التي تُزامن تغييرات نظام الملفات مع خادم على سبيل المثال، ملف قاعدة بيانات SQLite.
  • التطبيقات التي تحتاج إلى إبلاغ سلسلة التعليمات الرئيسية بتغييرات نظام الملفات من عامل أو علامة تبويب أخرى
  • التطبيقات التي تتتبّع دليلاً للموارد، على سبيل المثال، لتحسين الصور تلقائيًا
  • التجارب التي تستفيد من ميزة "إعادة التحميل السريع"، مثل عروض الشرائح المستندة إلى HTML التي يتم فيها ب��ء إعادة التحميل عند تغيير ملف

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

رصد الميزات

لمعرفة ما إذا كانت واجهة برمجة التطبيقات File System Observer API متوافقة، يمكنك إجراء اختبار ميزة كما في المثال التالي.

if ('FileSystemObserver' in self) {
  // The File System Observer API is supported.
}

بدء مراقب نظام الملفات

لإعداد مراقب نظام الملفات من خلال استدعاء new FileSystemObserver()، مع توفير دالة callback له كوسيطة.

const observer = new FileSystemObserver(callback);

بدء مراقبة ملف أو دليل

لبدء مراقبة ملف أو دليل، يمكنك استدعاء الطريقة غير المتزامنة observe() مثيل FileSystemObserver. قدِّم لهذه الطريقة FileSystemHandle للملف أو الدليل المحدَّد كوسيطة. عند مراقبة دليل، تتوفّر وسيطة options اختيارية تتيح لك اختيار ما إذا كنت تريد أن يتم إعلامك بالتغييرات التي تطرأ على الدليل بشكل متكرّر (أي للدليل نفسه وجميع الأدلة الفرعية والملفات المضمّنة). الخيار التلقائي هو مراقبة الدليل نفسه والملفات المضمّنة فيه مباشرةً فقط.

// Observe a file.
await observer.observe(fileHandle);
// Observe a directory.
await observer.observe(directoryHandle);
// Observe a directory recursively.
await observer.observe(directoryHandle, {recursive: true});

دالة ردّ الاتصال

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

const callback = (records, observer) => {
  for (const record of records) {
    console.log('Change detected', record);
  }
};

سجلّ تغيير نظام الملفات

يحتوي كل سجل تغيير نظام ملفات على البنية التالية. جميع الحقول للقراءة فقط.

  • root (FileSystemHandle): الاسم المعرِّف الذي تم تمريره إلى الدالة FileSystemObserver.observe()
  • changedHandle (a FileSystemHandle): الاسم المعرِّف المتأثّر بتغيير نظام الملفات.
  • relativePathComponents (Array): مسار changedHandle بالنسبة إلى root.
  • type (a String): نوع التغيير. في ما يلي الأنواع المحتمَلة:
    • "appeared": تم إنشاء الملف أو الدليل أو تم نقلهما إلى root.
    • "disappeared": تم حذف الملف أو الدليل أو نقلهما خارج root.
    • "modified": تم تعديل الملف أو الدليل.
    • "moved": تم نقل الملف أو الدليل ضمن root.
    • "unknown": يشير ذلك إلى عدم تسجيل أيّ أحداث أو أكثر. على المطوّرين إجراء استطلاع للدليل الذي تمّت مراقبته استجابةً لذلك.
    • "errored": لم تعُد الملاحظة صالحة. في هذه الحالة، قد تحتاج إلى إيقاف مراقبة نظام الملفات.
  • relativePathMovedFrom (Array، اختياري): الموقع الجغرافي السابق للاسم المعرِّف الذي تم نقله. لا يتوفّر إلا عندما يكون type هو "moved".

إيقاف مراقبة ملف أو دليل

لإيقاف مراقبة FileSystemHandle، يمكنك استدعاء طريقة unobserve() مع تمرير الاسم المعرِّف لها كوسيطة.

observer.unobserve(fileHandle);

التوقف عن مراقبة نظام الملفات

لإيقاف مراقبة نظام الملفات، عليك إلغاء ربط مثيل FileSystemObserver على النحو التالي.

observer.disconnect();

تجربة واجهة برمجة التطبيقات

لاختبار واجهة برمجة التطبيقات File System Observer API محليًا، اضبط العلامة #file-system-observer في about:flags. لاختبار واجهة برمجة التطبيقات مع مستخدمين حقيقيين، عليك الاشتراك في الفترة التجريبية للإصدار الأول واتّباع التعليمات الواردة في دليل فترات Chrome التجريبية للإصدار الأول. ستتم تجربة وتقييم Topics من Chrome ابتداءً من الإصدار 129 (11 أيلول/سبتمبر 2024) إلى الإصدار 134 (26 شباط/فبراير 2025).

عرض توضيحي

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

ملاحظات

إذا كانت لديك ملاحظات حول شكل واجهة برمجة التطبيقات File System Observer API، يُرجى التعليق على المشكلة رقم 123 في مستودع WHATWG/fs.

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

تمت مراجعة هذا المستند من قِبل داسول لي وناثان ميموت وإتيان نويل وراشيل أندرو.