גם 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
(aFileSystemHandle
): הכינוי שהושפע מהשינוי במערכת הקבצים.relativePathComponents
(Array
): הנתיב שלchangedHandle
ביחס ל-root
.type
(aString
): סוג השינוי. אלה הסוגים האפשריים:"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.