مرحلة التجربة والتقييم في 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.
}

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

ابدأ File System Observer (مراقب نظام الملفات) من خلال استدعاء 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 (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".

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

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

observer.unobserve(fileHandle);

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

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

observer.disconnect();

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

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

عرض توضيحي

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

الملاحظات

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

الإقرارات

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