גרסת המקור לניסיון של 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.
  • אפליקציות שצריכות להודיע ל-thread הראשי על שינויים במערכת הקבצים מעובד או מכרטיסייה אחרת.
  • אפליקציות ששומרות על ספריית משאבים, למשל, כדי לבצע אופטימיזציה אוטומטית של תמונות.
  • חוויות שמפיקות תועלת מהטעינה מחדש בזמן אמת, כמו חבילות שקופיות מבוססות-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): ה-handle שהוענק לפונקציה FileSystemObserver.observe().
  • changedHandle (FileSystemHandle): ה-handle שמושפע מהשינוי במערכת הקבצים.
  • relativePathComponents (Array): הנתיב של changedHandle ביחס ל-root.
  • type (a String): סוג השינוי. אלה הסוגים האפשריים:
    • "appeared": הקובץ או הספרייה נוצרו או הועברו אל root.
    • "disappeared": הקובץ או הספרייה נמחקו או הועברו מ-root.
    • "modified": הקובץ או הספרייה השתנו.
    • "moved": הקובץ או הספרייה הועברו בתוך root.
    • "unknown": המשמעות היא שהתרחשו אפס אירועים או יותר שלא תועדו. בתגובה לכך, המפתחים צריכים לבצע סקירה של הספרייה שנמצאת במעקב.
    • "errored": התצפית כבר לא תקפה. במקרה כזה, מומלץ להפסיק את המעקב אחרי מערכת הקבצים.
  • relativePathMovedFrom (Array, אופציונלי): המיקום הקודם של הכינוי שהועתק. האפשרות הזו זמינה רק כשהערך של type הוא "moved".

הפסקת מעקב אחרי קובץ או ספרייה

כדי להפסיק את המעקב אחרי FileSystemHandle, קוראים ל-method‏ unobserve() ומעבירים לו את ה-handle כארגומנט.

observer.unobserve(fileHandle);

הפסקת הצפייה במערכת הקבצים

כדי להפסיק את המעקב אחרי מערכת הקבצים, מנתקים את המכונה FileSystemObserver באופן הבא.

observer.disconnect();

התנסות ב-API

כדי לבדוק את File System Observer API באופן מקומי, צריך להגדיר את הדגל #file-system-observer ב-about:flags. כדי לבדוק את ה-API עם משתמשים אמיתיים, נרשמים לגרסת המקור לניסיון ופועלים לפי ההוראות במדריך גרסת המקור לניסיון ב-Chrome. גרסת המקור לניסיון תפעל מ-Chrome 129 (11 בספטמבר 2024) עד Chrome 134 (26 בפברואר 2025).

הדגמה (דמו)

אתם יכולים לראות את File System Observer API בפעולה בדמו המוטמע. אפשר לעיין בקוד המקור או ליצור רמיקס של קוד הדגמה ב-Glitch. ההדגמה יוצרת, מוחקת או משנה קבצים באופן אקראי בספרייה שנשמרה, ומתעדת את הפעילות שלה בחלק העליון של חלון האפליקציה. לאחר מכן, השינויים מתועדים ביומן בחלק התחתון של חלון האפליקציה. אם קראת את המידע הזה בדפדפן שאינו תומך ב-File System Observer API, יש לעיין בצילום מסך של ההדגמה.

משוב

אם יש לכם משוב לגבי הצורה של File System Observer API, תוכלו לכתוב תגובה בבעיה מס' 123 במאגר WHATWG/fs.

תודות

המסמך הזה נבדק על ידי Daseul Lee,‏ Nathan Memmott,‏ Etienne Noël ו-Rachel Andrew.