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 reguler 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 dilengkapi dengan keunggulan performa tertentu. Cara developer berinteraksi dengan file dan direktori dalam kedua kasus tersebut adalah melalui objek FileSystemHandle, lebih konkret lagi, FileSystemFileHandle untuk file, dan FileSystemDirectoryHandle untuk direktori. Hingga saat ini, untuk mendapatkan informasi tentang perubahan pada file atau direktori di salah satu sistem file, diperlukan beberapa bentuk polling dan perbandingan stempel waktu lastModified atau bahkan konten file itu sendiri.

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

Kasus penggunaan

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

• Integrated development environment (IDE) berbasis web yang menampilkan 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.
• Pengalaman yang mendapatkan manfaat dari hot reload, seperti slide presentasi berbasis HTML yang memicu pemuatan ulang karena perubahan file.

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.
}

Catatan: Lihat Penjelasan untuk mengetahui pendekatan umum guna melakukan polyfill pada perilaku File System Observer API melalui polling.

Melakukan inisialisasi pada observer sistem file

Lakukan inisialisasi File System Observer 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 FileSystemHandle file atau direktori yang dipilih sebagai argumen ke metode ini. Saat mengamati direktori, ada argumen options opsional yang memungkinkan Anda memilih apakah ingin diberi tahu tentang perubahan pada direktori secara berulang (yaitu, untuk direktori itu sendiri dan semua subdirektori dan file yang ada). Opsi defaultnya adalah hanya mengamati direktori itu sendiri dan file yang langsung dimuat.

// 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 perubahan pada sistem file terjadi, fungsi callback akan 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 telah dihapus.

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

Data perubahan sistem file

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

• root (FileSystemHandle): Nama sebutan yang diteruskan ke fungsi FileSystemObserver.observe().
• changedHandle (FileSystemHandle): Nama sebutan yang terpengaruh oleh perubahan sistem file. Kolom ini akan menjadi null untuk peristiwa jenis "errored", "unknown", dan "disappeared". Untuk melihat file atau direktori yang telah hilang, gunakan relativePathComponents.
• relativePathComponents (Array): Jalur changedHandle relatif terhadap root.
• type (String): Jenis perubahan. Jenis berikut mungkin muncul:
  • "appeared": File atau direktori dibuat atau dipindahkan ke root.
  • "disappeared": File atau direktori dihapus atau dipindahkan dari root.
  • "modified": File atau direktori telah diubah.
  • "moved": File atau direktori dipindahkan dalam root.
  • "unknown": Hal ini menunjukkan bahwa nol atau beberapa peristiwa terlewat. Developer harus melakukan polling pada direktori yang dipantau sebagai respons terhadap hal ini.
  • "errored": Pengamatan tidak lagi valid. Dalam hal ini, Anda dapat berhenti mengamati sistem file. Nilai ini juga akan dikirim saat batas maksimum pengamatan per asal tercapai. Batas ini bergantung pada sistem operasi dan tidak diketahui sebelumnya. Jika hal ini terjadi, situs dapat memutuskan untuk mencoba lagi, meskipun tidak ada jaminan bahwa sistem operasi telah mengosongkan resource yang cukup. Kasus lain saat nilai ini akan dikirim adalah saat nama sebutan yang diamati (yaitu, root pengamatan) dihapus atau dipindahkan. Dalam hal ini, pertama-tama, peristiwa "disappeared" dikirim, diikuti dengan peristiwa "errored", yang menunjukkan bahwa pengamatan tidak lagi valid. Terakhir, peristiwa ini dikirim saat izin ke direktori atau pengendali file dihapus.
• relativePathMovedFrom (Array, opsional): Lokasi sebelumnya dari handle yang dipindahkan. Hanya tersedia jika type adalah "moved".

Catatan: Bergantung pada sistem operasi, tidak semua peristiwa perubahan dapat dilaporkan dengan tingkat detail yang sama, misalnya, saat konten direktori berubah secara rekursif. Paling-paling, situs akan menerima catatan perubahan mendetail yang berisi jenis perubahan dan nama sebutan untuk jalur yang terpengaruh. Terburuknya, situs menerima data perubahan yang lebih umum (yaitu, type dengan nilai "unknown") yang masih mengharuskan situs untuk menguraikan direktori guna mengetahui turunan mana yang berubah. Ini masih merupakan peningkatan dibandingkan polling, karena enumerasi direktori dapat dimulai sesuai permintaan dari fungsi callback, bukan perlu melakukan polling untuk perubahan dalam interval.

Catatan: Di Windows, peristiwa "moved" tidak didukung di antara direktori. File tersebut dilaporkan sebagai "disappeared" dari direktori sumber dan "appeared" di direktori tujuan. Nilai ini dilaporkan sebagai "moved" jika sumber dan tujuan berada di direktori yang sama.

Berhenti mengamati file atau direktori

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

observer.unobserve(fileHandle);

Catatan: Metode unobserve() tidak didukung. Gunakan metode disconnect() sebagai solusi. Jika Anda tertarik dengan progres fitur ini, beri bintang pada bug fitur.

Berhenti mengamati sistem file

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

observer.disconnect();

Coba API

Untuk menguji File System Observer API secara lokal, tetapkan tanda #file-system-observer di about:flags. Untuk menguji API dengan pengguna sungguhan, daftar untuk uji coba origin dan ikuti petunjuk sesuai panduan Uji Coba Origin Chrome. Uji coba origin akan berjalan dari Chrome 129 (11 September 2024) hingga 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 tersebut 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, berikan komentar di Masalah #123 di repositori WHATWG/fs.

Link yang relevan

• Penjelas
• Peninjauan TAG
• Posisi Standar Mozilla
• Posisi Standar WebKit
• ChromeStatus
• Bug Chromium

Ucapan terima kasih

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