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

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.
}

ملاحظة: يُرجى الاطّلاع على الشرح للاطّلاع على الأساليب العامة لإضافة polyfill إلى سلوك واجهة برمجة التطبيقات File System Observer API من خلال الاستطلاع.

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

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

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

ملاحظة: في نظام التشغيل Windows، لا تكون أحداث "moved" متاحة بين الأدلة. ويتم إدراجها على أنّها "disappeared" من دليل المصدر و"appeared" في دليل الوجهة. ويتم إدراجها على أنّها "moved" عندما يكون المصدر والوجهة في الدليل نفسه.

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

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

observer.unobserve(fileHandle);

ملاحظة: لا تتوفّر طريقة unobserve(). استخدِم طريقة disconnect() كحل بديل. إذا كنت مهتمًا بمعرفة مستوى التقدّم في هذه الميزة، يمكنك وضع علامة على خطأ الميزة.

إيقاف مراقبة نظام الملفات

لإيقاف مراقبة نظام الملفات، عليك إلغاء ربط مثيل 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.

روابط ذات صلة

• الشرح
• مراجعة علامة Google
• موقف Mozilla بشأن المعايير
• موضع معايير WebKit
• ChromeStatus
• خطأ في Chromium

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

راجع هذا المستند كلّ من داسول لي وناثان ميمو وإتيان نويل وراشيل أندرو.