גרסת המקור לניסיון של 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 הראשי על שינויים במערכת הקבצים מ-worker או מכרטיסייה אחרת.
  • אפליקציות שעוקבות אחרי ספרייה של משאבים, למשל כדי לבצע אופטימיזציה אוטומטית של תמונות.
  • חוויות שמועילות מטעינה מחדש מהירה, כמו מצגות מבוססות 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);

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

כדי להתחיל לעקוב אחרי קובץ או ספרייה, קוראים ל-method האסינכרוני 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".

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

כדי להפסיק את המעקב אחרי 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).

הדגמה (דמו)

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

משוב

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

תודות

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