หน้านี้ได้รับการแปลโดย Cloud Translation API

ช่วงทดลองใช้ 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
แอปที่ต้องแจ้งชุดข้อความหลักเกี่ยวกับการเปลี่ยนแปลงระบบไฟล์จากผู้ปฏิบัติงานหรือแท็บอื่น
แอปที่ตรวจสอบไดเรกทอรีทรัพยากร เช่น เพื่อเพิ่มประสิทธิภาพรูปภาพโดยอัตโนมัติ
ประสบการณ์ที่ใช้ประโยชน์จากการโหลดซ้ำแบบ Hot เช่น สไลด์เด็คที่ใช้ 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});

ฟังก์ชัน Callback

เมื่อระบบไฟล์มีการเปลี่ยนแปลง ระบบจะเรียกใช้ฟังก์ชันการเรียกกลับพร้อมการเปลี่ยนแปลงระบบไฟล์ 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": บ่งบอกว่ามีการพลาดเหตุการณ์ตั้งแต่ 0 รายการขึ้นไป นักพัฒนาแอปควรตรวจสอบไดเรกทอรีที่ดูอยู่เพื่อตอบสนองต่อเหตุการณ์นี้
- "errored": การสังเกตการณ์ไม่ถูกต้องแล้ว ในกรณีนี้ คุณอาจต้องหยุดสังเกตการณ์ระบบไฟล์ ระบบจะส่งค่านี้ด้วยเมื่อถึงขีดจํากัดสูงสุดของการสังเกตการณ์ต่อต้นทาง ซึ่งขีดจำกัดนี้ขึ้นอยู่กับระบบปฏิบัติการและไม่ทราบล่วงหน้า หากเกิดกรณีนี้ขึ้น เว็บไซต์อาจตัดสินใจลองอีกครั้ง แต่ไม่มีการรับประกันว่าระบบปฏิบัติการจะเพิ่มพื้นที่ว่างในทรัพยากรได้มากพอ อีกกรณีที่ระบบจะส่งค่านี้คือเมื่อมีการลบหรือย้ายแฮนเดิลที่สังเกต (นั่นคือรูทของการสังเกต) ในกรณีนี้ ระบบจะส่งเหตุการณ์ "disappeared" ก่อน ตามด้วยเหตุการณ์ "errored" ซึ่งบ่งบอกว่าการสังเกตการณ์ไม่ถูกต้องอีกต่อไป สุดท้าย ระบบจะส่งเหตุการณ์นี้เมื่อมีการนำสิทธิ์เข้าถึงไดเรกทอรีหรือแฮนเดิลไฟล์ออก
relativePathMovedFrom (Array ไม่บังคับ): ตำแหน่งเดิมของแฮนเดิลที่ย้าย ใช้ได้เมื่อ type เป็น "moved" เท่านั้น

หมายเหตุ: ระบบอาจรายงานเหตุการณ์การเปลี่ยนแปลงบางรายการโดยละเอียดไม่เท่ากัน ทั้งนี้ขึ้นอยู่กับระบบปฏิบัติการ เช่น เมื่อเนื้อหาของไดเรกทอรีมีการเปลี่ยนแปลงแบบซ้ำ ในกรณีที่ดีที่สุด เว็บไซต์จะได้รับบันทึกการเปลี่ยนแปลงโดยละเอียดซึ่งมีประเภทการเปลี่ยนแปลงและตัวแฮนเดิลของเส้นทางที่ได้รับผลกระทบ ในกรณีที่แย่ที่สุด เว็บไซต์จะได้รับระเบียนการเปลี่ยนแปลงที่ทั่วไปมากขึ้น (นั่นคือ type ที่มีค่าเป็น "unknown") ซึ่งยังคงกำหนดให้เว็บไซต์ต้องแจกแจงไดเรกทอรีเพื่อดูว่ารายการย่อยใดมีการเปลี่ยนแปลง ซึ่งยังคงเป็นการปรับปรุงที่ดีกว่าการโหวต เนื่องจากสามารถเริ่มการแจกแจงไดเรกทอรีได้ตามต้องการจากฟังก์ชันการเรียกกลับ แทนที่จะต้องโหวตเพื่อหาการเปลี่ยนแปลงเป็นระยะ

หยุดสังเกตไฟล์หรือไดเรกทอรี

หากต้องการหยุดสังเกต FileSystemHandle ให้เรียกใช้เมธอด unobserve() โดยส่งแฮนเดิลเป็นอาร์กิวเมนต์

observer.unobserve(fileHandle);

หยุดสังเกตการณ์ระบบไฟล์

หากต้องการหยุดสังเกตการณ์ระบบไฟล์ ให้ยกเลิกการเชื่อมต่ออินสแตนซ์ FileSystemObserver ดังนี้

observer.disconnect();

ลองใช้ API

หากต้องการทดสอบ File System Observer API ในเครื่อง ให้ตั้งค่า Flag #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