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

Thomas Steiner

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

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

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

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

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

كيفية استخدام واجهة برمجة التطبيقات 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 (أ 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. سيتم بدء مرحلة التجربة والتقييم من Chrome 129 (في 11 أيلول/سبتمبر 2024) إلى Chrome 134 (في 26 شباط/فبراير 2025).

عرض توضيحي

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

ملاحظات

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

شكر وتقدير

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