Uji coba origin File System Observer API

Thomas Steiner

File System Access API dan Origin Private File System API memungkinkan developer mengakses file dan direktori di perangkat pengguna. Yang pertama memungkinkan developer membaca dan menulis ke sistem file biasa yang terlihat oleh pengguna, dan yang kedua membuka sistem file khusus yang tersembunyi dari sistem file pengguna yang bersifat pribadi untuk asal setiap situs, dan yang memberikan keunggulan performa tertentu. Cara developer berinteraksi dengan file dan direktori dalam kedua kasus ini adalah melalui objek FileSystemHandle, yang lebih konkret, FileSystemFileHandle untuk file, dan FileSystemDirectoryHandle untuk direktori. Hingga saat ini, mendapatkan informasi tentang perubahan pada file atau direktori di salah satu sistem file memerlukan beberapa bentuk polling dan membandingkan stempel waktu lastModified atau bahkan konten file itu sendiri.

File System Observer API, dalam uji coba origin dari Chrome 129, mengubah hal tersebut, dan memungkinkan developer diberi tahu secara otomatis saat terjadi perubahan. Panduan ini menjelaskan cara kerjanya dan cara mencoba fitur tersebut.

Kasus penggunaan

Gunakan File System Observer API dalam aplikasi yang perlu diberi tahu tentang kemungkinan perubahan sistem file segera setelah hal itu terjadi.

  • Integrated Development Environment (IDE) berbasis web yang menunjukkan representasi hierarki sistem file project.
  • Aplikasi yang menyinkronkan perubahan sistem file dengan server. Misalnya, file database SQLite.
  • Aplikasi yang perlu memberi tahu thread utama tentang perubahan sistem file dari pekerja atau tab lain.
  • Aplikasi yang mengamati direktori resource, misalnya, untuk mengoptimalkan gambar secara otomatis.

Cara menggunakan File System Observer API

Deteksi fitur

Untuk melihat apakah File System Observer API didukung, jalankan pengujian fitur seperti pada contoh berikut.

if ('FileSystemObserver' in self) {
  // The File System Observer API is supported.
}

Melakukan inisialisasi observer sistem file

Lakukan inisialisasi pada Pengamat Sistem File dengan memanggil new FileSystemObserver(), yang menyediakan fungsi callback sebagai argumen.

const observer = new FileSystemObserver(callback);

Mulai mengamati file atau direktori

Untuk mulai mengamati file atau direktori, panggil metode observe() asinkron dari instance FileSystemObserver. Berikan metode ini FileSystemHandle dari file atau direktori yang dipilih sebagai argumen. Saat mengamati direktori, ada argumen options opsional yang memungkinkan Anda memilih apakah Anda ingin diberi tahu tentang perubahan pada direktori secara rekursif (yaitu, untuk direktori itu sendiri dan semua yang berisi subdirektori dan file). Opsi {i>default<i} adalah untuk hanya mengamati direktori itu sendiri dan file yang terdapat secara langsung.

// Observe a file.
await observer.observe(fileHandle);
// Observe a directory.
await observer.observe(directoryHandle);
// Observe a directory recursively.
await observer.observe(directoryHandle, {recursive: true});

Fungsi callback

Saat terjadi perubahan pada sistem file, fungsi callback dipanggil dengan perubahan sistem file records dan observer itu sendiri sebagai argumennya. Anda dapat menggunakan argumen observer untuk, misalnya, memutuskan koneksi observer (lihat Berhenti mengamati sistem file) saat semua file yang Anda minati dihapus.

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

Catatan perubahan sistem file

Setiap data perubahan sistem file memiliki struktur berikut. Semua kolom bersifat hanya baca.

  • root (FileSystemHandle): Nama sebutan channel yang diteruskan ke fungsi FileSystemObserver.observe().
  • changedHandle (FileSystemHandle): Nama sebutan channel yang terpengaruh oleh perubahan sistem file.
  • relativePathComponents (Array): Jalur changedHandle relatif terhadap root.
  • type (String): Jenis perubahan. Jenis-jenis berikut mungkin ada:
    • "appeared": File atau direktori dibuat atau dipindahkan ke root.
    • "disappeared": File atau direktori dihapus atau dipindahkan dari root.
    • "modified": File atau direktori diubah.
    • "moved": File atau direktori dipindahkan di dalam root.
    • "unknown": Hal ini menunjukkan bahwa ada nol peristiwa atau lebih yang terlewat. Developer harus melakukan polling pada direktori yang dipantau sebagai respons terhadap hal ini.
    • "errored": Pengamatan tidak lagi valid. Dalam kasus ini, sebaiknya Anda berhenti mengamati sistem file.
  • relativePathMovedFrom (Array, opsional): Lokasi sebelumnya dari nama sebutan channel yang dipindahkan. Hanya tersedia jika type adalah "moved".

Berhenti mengamati file atau direktori

Untuk berhenti mengamati FileSystemHandle, panggil metode unobserve(), dengan meneruskan handle sebagai argumen.

observer.unobserve(fileHandle);

Berhenti mengamati sistem file

Untuk berhenti mengamati sistem file, putuskan koneksi instance FileSystemObserver seperti berikut.

observer.disconnect();

Coba API

Untuk menguji File System Observer API secara lokal, tetapkan tanda #file-system-observer dalam about:flags. Untuk menguji API dengan pengguna sungguhan, daftar ke uji coba origin dan ikuti petunjuk sesuai panduan Uji Coba Origin Chrome. Uji coba origin akan berjalan dari Chrome 129 (11 September 2024) ke Chrome 134 (26 Februari 2025).

Demo

Anda dapat melihat cara kerja File System Observer API dalam demo tersemat. Lihat kode sumber atau remix kode demo di Glitch. Demo ini secara acak membuat, menghapus, atau mengubah file di direktori yang diamati dan mencatat aktivitasnya di bagian atas jendela aplikasi. Kemudian, perubahan akan dicatat ke dalam log saat terjadi di bagian bawah jendela aplikasi. Jika Anda membaca ini di browser yang tidak mendukung File System Observer API, lihat screenshot demo.

Masukan

Jika Anda memiliki masukan tentang bentuk File System Observer API, beri komentar pada Masalah #123 di repositori WhatWG/fs.

Ucapan terima kasih

Dokumen ini ditinjau oleh Daseul Lee, Nathan Memmott, Etienne Noël, dan Rachel Andrew.