ช่วงทดลองใช้ File System Observer API จากต้นทาง

Thomas Steiner

ทั้ง File System Access API และ Origin Private File System API อนุญาตให้นักพัฒนาแอปเข้าถึงไฟล์และไดเรกทอรีในอุปกรณ์ของผู้ใช้ โดยตัวเลือกแรกช่วยให้นักพัฒนาแอปอ่านและเขียนไปยังระบบไฟล์ปกติที่ผู้ใช้มองเห็นได้ ส่วนตัวเลือกที่ 2 จะเปิดระบบไฟล์พิเศษที่ซ่อนจากผู้ใช้ซึ่งเป็นแบบส่วนตัวสำหรับต้นทางของแต่ละเว็บไซต์ และมาพร้อมกับข้อดีด้านประสิทธิภาพบางอย่าง ในทั้ง 2 กรณี นักพัฒนาแอปจะโต้ตอบกับไฟล์และไดเรกทอรีผ่านออบเจ็กต์ FileSystemHandle โดยเฉพาะอย่างยิ่ง FileSystemFileHandle สำหรับไฟล์ และ FileSystemDirectoryHandle สำหรับไดเรกทอรี ก่อนหน้านี้ การรับทราบการเปลี่ยนแปลงไฟล์หรือไดเรกทอรีในระบบไฟล์ใดระบบหนึ่งต้องมีการสำรวจและเปรียบเทียบรูปแบบใดรูปแบบหนึ่งของlastModifiedการประทับเวลาหรือแม้แต่เนื้อหาของไฟล์เอง

File System Observer API ซึ่งอยู่ในช่วงทดลองใช้จากต้นทางตั้งแต่ Chrome 129 จะเปลี่ยนแปลงสิ่งนี้ และช่วยให้นักพัฒนาแอปได้รับการแจ้งเตือนโดยอัตโนมัติเมื่อมีการเปลี่ยนแปลง คู่มือนี้จะอธิบายวิธีการทำงานและวิธีลองใช้ฟีเจอร์นี้

กรณีการใช้งาน

ใช้ File System Observer API ในแอปที่ต้องรับทราบการเปลี่ยนแปลงที่เป็นไปได้ในระบบไฟล์ทันทีที่เกิดขึ้น

  • สภาพแวดล้อมการพัฒนาแบบรวม (IDE) บนเว็บที่แสดงการแทนโครงสร้างระบบไฟล์ของโปรเจ็กต์
  • แอปที่ซิงโครไนซ์การเปลี่ยนแปลงระบบไฟล์กับเซิร์ฟเวอร์ เช่น ไฟล์ฐานข้อมูล SQLite
  • แอปที่ต้องแจ้งให้เทรดหลักทราบถึงการเปลี่ยนแปลงระบบไฟล์จาก 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);

เริ่มสังเกตการณ์ไฟล์หรือไดเรกทอรี

หากต้องการเริ่มสังเกตการณ์ไฟล์หรือไดเรกทอรี ให้เรียกใช้เมธอด 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});

ฟังก์ชัน Callback

เมื่อมีการเปลี่ยนแปลงระบบไฟล์ ระบบจะเรียกใช้ฟังก์ชันเรียกกลับพร้อมกับการเปลี่ยนแปลงระบบไฟล์recordsและobserverเองเป็นอาร์กิวเมนต์ คุณสามารถใช้อาร์กิวเมนต์ observer เพื่อยกเลิกการเชื่อมต่อ Observer (ดูหยุดสังเกตการณ์ระบบไฟล์) เมื่อระบบลบไฟล์ทั้งหมดที่คุณสนใจแล้ว เป็นต้น

const callback = (records, observer) => {
  for (const record of records) {
    console.log('Change detected', record);
  }
};

บันทึกการเปลี่ยนแปลงระบบไฟล์

บันทึกการเปลี่ยนแปลงระบบไฟล์แต่ละรายการมีโครงสร้างดังนี้ ช่องทั้งหมดเป็นแบบอ่านอย่างเดียว

  • root (FileSystemHandle): แฮนเดิลที่ส่งไปยังฟังก์ชัน FileSystemObserver.observe()
  • changedHandle (FileSystemHandle): แฮนเดิลที่ได้รับผลกระทบจากการเปลี่ยนแปลงระบบไฟล์ ฟิลด์นี้จะเป็น null สำหรับเหตุการณ์ประเภท "errored", "unknown" และ "disappeared" หากต้องการดูว่าไฟล์หรือไดเรกทอรีใดหายไป ให้ใช้ relativePathComponents
  • relativePathComponents (Array): เส้นทางของ changedHandle ที่สัมพันธ์กับ root
  • type (String): ประเภทของการเปลี่ยนแปลง ประเภทที่เป็นไปได้มีดังนี้
    • "appeared": มีการสร้างไฟล์หรือไดเรกทอรีหรือย้ายไฟล์หรือไดเรกทอรีไปยัง root
    • "disappeared": ระบบได้ลบไฟล์หรือไดเรกทอรี หรือย้ายออกจาก root แล้ว
    • "modified": มีการแก้ไขไฟล์หรือไดเรกทอรี
    • "moved": มีการย้ายไฟล์หรือไดเรกทอรีภายใน root
    • "unknown": ซึ่งหมายความว่าพลาดเหตุการณ์ไป 0 รายการขึ้นไป นักพัฒนาแอปควรสำรวจไดเรกทอรีที่ดูเพื่อตอบสนองต่อเหตุการณ์นี้
    • "errored": การสังเกตการณ์นี้ใช้ไม่ได้อีกต่อไป ในกรณีนี้ คุณอาจต้องหยุดสังเกตการณ์ระบบไฟล์ ระบบจะส่งค่านี้เมื่อถึงขีดจำกัดสูงสุดของการสังเกตการณ์ต่อต้นทางด้วย ขีดจำกัดนี้ขึ้นอยู่กับระบบปฏิบัติการและไม่สามารถทราบล่วงหน้าได้ หากเกิดกรณีนี้ขึ้น เว็บไซต์อาจตัดสินใจลองอีกครั้ง แต่ไม่มีการรับประกันว่าระบบปฏิบัติการจะเพิ่มพื้นที่ว่างของทรัพยากรได้เพียงพอ อีกกรณีหนึ่งที่ระบบจะส่งค่านี้คือเมื่อมีการลบหรือย้ายแฮนเดิลที่สังเกต (นั่นคือรูทของการสังเกต) ในกรณีนี้ ระบบจะส่งเหตุการณ์ "disappeared" ก่อน ตามด้วยเหตุการณ์ "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 ได้ในเดโมที่ฝังไว้ ดูซอร์สโค้ด โดยการสาธิตจะสร้าง ลบ หรือแก้ไขไฟล์ในไดเรกทอรีที่สังเกตการณ์แบบสุ่ม และบันทึกกิจกรรมไว้ที่ส่วนบนของหน้าต่างแอป จากนั้นจะบันทึกการเปลี่ยนแปลงเมื่อเกิดขึ้นในส่วนล่างของหน้าต่างแอป หากคุณอ่านข้อความนี้ในเบราว์เซอร์ที่ไม่รองรับ File System Observer API โปรดดูภาพหน้าจอของเดโม

ความคิดเห็น

หากมีข้อเสนอแนะเกี่ยวกับรูปแบบของ File System Observer API โปรดแสดงความคิดเห็นในปัญหา #123 ในที่เก็บ WHATWG/fs

คำขอบคุณ

เอกสารนี้ได้รับการตรวจสอบโดย Daseul Lee, Nathan Memmott, Etienne Noël และ Rachel Andrew