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

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

הפסקת הצפייה בקובץ או בספרייה

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

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.