Halaman ini diterjemahkan oleh Cloud Translation API.

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 pengguna yang bersifat pribadi untuk origin setiap situs dan memiliki keuntungan performa tertentu. Cara developer berinteraksi dengan file dan direktori dalam kedua kasus tersebut adalah melalui objek FileSystemHandle, lebih konkretnya, FileSystemFileHandle untuk file, dan FileSystemDirectoryHandle untuk direktori. Hingga saat ini, untuk mengetahui 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, mengubah hal tersebut, dan memungkinkan developer diberi tahu 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.

Lingkungan pengembangan terintegrasi (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 diuntungkan dari hot-reloading, seperti slide presentasi berbasis HTML yang pemuatan ulang dipicu oleh perubahan file.

Cara menggunakan File System Observer API

Deteksi fitur

Untuk melihat apakah File System Observer API didukung, jalankan uji fitur seperti dalam contoh berikut.

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

Melakukan inisialisasi pengamat sistem file

Lakukan inisialisasi 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 FileSystemHandle file atau direktori yang dipilih sebagai argumen ke metode ini. 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 subdirektori dan file yang ada di dalamnya). Opsi default adalah hanya mengamati direktori itu sendiri dan file yang ada di dalamnya 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 perubahan pada sistem file terjadi, fungsi callback dipanggil dengan perubahan sistem file records dan observer itu sendiri sebagai argumennya. Anda dapat menggunakan argumen observer untuk, misalnya, menghentikan koneksi pengamat (lihat Menghentikan pengamatan 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 catatan perubahan sistem file memiliki struktur berikut. Semua kolom bersifat hanya baca.

root (FileSystemHandle): Handle yang diteruskan ke fungsi FileSystemObserver.observe().
changedHandle (FileSystemHandle): Handle yang terpengaruh oleh perubahan sistem file. Kolom ini akan berupa null untuk peristiwa jenis "errored", "unknown", dan "disappeared". Untuk melihat file atau direktori mana 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 lebih banyak 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 membebaskan cukup banyak resource. Kasus lain saat nilai ini akan dikirim adalah saat handle yang diamati (yaitu, root pengamatan) dihapus atau dipindahkan. Dalam hal ini, peristiwa "disappeared" dikirim terlebih dahulu, diikuti dengan peristiwa "errored", yang menunjukkan bahwa pengamatan tidak lagi valid. Terakhir, peristiwa ini dikirim saat izin ke direktori atau penanganan file dihapus.
relativePathMovedFrom (Array, opsional): Lokasi sebelumnya dari handle 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 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 ke 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 yang disematkan. Lihat kode sumber. Demo ini secara acak membuat, menghapus, atau mengubah file dalam direktori yang diamati dan mencatat aktivitasnya di bagian atas jendela aplikasi. Kemudian, perubahan akan dicatat 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 Issue #123 di repositori WHATWG/fs.

Link yang relevan

Ucapan terima kasih

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