גרסת המקור לניסיון של 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.
}

איך מפעילים משגיח על מערכת קבצים

כדי לאתחל משתמש מעקב אחר מערכת קבצים, קוראים לפונקציה 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 שמושפע מהשינוי במערכת הקבצים. השדה הזה יהיה 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, קוראים ל-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.