Bu sayfa, Cloud Translation API ile çevrilmiştir.

File System Observer API kaynak denemesi

Thomas Steiner

Hem File System Access API hem de Origin Private File System API, geliştiricilerin kullanıcının cihazındaki dosya ve dizinlere erişmesine olanak tanır. Birincisi, geliştiricilerin normal, kullanıcı tarafından görülebilen dosya sisteminde okuma ve yazma işlemlerini yapmasına olanak tanır. İkincisi ise her sitenin kaynağına özel olan ve belirli performans avantajları sunan, kullanıcıdan gizli özel bir dosya sistemi açar. Geliştiricilerin her iki durumda da dosyalar ve dizinlerle etkileşim kurma şekli FileSystemHandle nesneler aracılığıyla olur. Daha somut olarak, dosyalar için FileSystemFileHandle, dizinler için ise FileSystemDirectoryHandle kullanılır. Şimdiye kadar, dosya sistemlerinden birindeki bir dosya veya dizinde yapılan değişikliklerden haberdar olmak için bir tür yoklama yapılması ve lastModified zaman damgasının, hatta dosya içeriklerinin kendisinin karşılaştırılması gerekiyordu.

Chrome 129'dan itibaren kaynak denemesi olarak sunulan File System Observer API, bu durumu değiştirerek geliştiricilerin değişiklikler olduğunda otomatik olarak uyarılmasını sağlar. Bu kılavuzda, özelliğin işleyiş şekli ve nasıl deneneceği açıklanmaktadır.

Kullanım alanları

Olası dosya sistemi değişikliklerinden anında haberdar olması gereken uygulamalarda File System Observer API'yi kullanın.

Bir projenin dosya sistemi ağacının gösterimini sunan web tabanlı entegre geliştirme ortamları (IDE'ler).
Dosya sistemi değişikliklerini bir sunucuyla senkronize eden uygulamalar. Örneğin, SQLite veritabanı dosyası.
Bir çalışan veya başka bir sekmeden dosya sistemi değişiklikleri hakkında ana iş parçacığını bilgilendirmesi gereken uygulamalar.
Örneğin, resimleri otomatik olarak optimize etmek için kaynak dizinini gözlemleyen uygulamalar.
Yeniden yüklemenin dosya değişikliğiyle tetiklendiği HTML tabanlı slayt desteleri gibi, anında yeniden yüklemeden yararlanan deneyimler.

File System Observer API nasıl kullanılır?

Özellik algılama

File System Observer API'nin desteklenip desteklenmediğini görmek için aşağıdaki örnekteki gibi bir özellik testi çalıştırın.

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

Dosya sistemi gözlemcisini başlatma

new FileSystemObserver() işlevini çağırarak bir Dosya Sistemi Gözlemcisi başlatın ve bağımsız değişken olarak callback işlevini sağlayın.

const observer = new FileSystemObserver(callback);

Dosya veya dizini izlemeye başlama

Bir dosyayı veya dizini izlemeye başlamak için FileSystemObserver örneğinin eşzamansız observe() yöntemini çağırın. Bu yönteme, seçili dosyanın veya dizinin FileSystemHandle değerini bağımsız değişken olarak sağlayın. Bir dizini gözlemlerken, dizinde yapılan değişikliklerden yinelemeli olarak (yani dizinin kendisi ve içerdiği tüm alt dizinler ve dosyalar için) haberdar olmak isteyip istemediğinizi seçmenize olanak tanıyan isteğe bağlı bir options bağımsız değişkeni vardır. Varsayılan seçenek, yalnızca dizinin kendisini ve doğrudan içerdiği dosyaları gözlemlemektir.

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

Geri çağırma işlevi

Dosya sisteminde değişiklikler olduğunda, dosya sistemi değişikliği records ve observer'ün kendisi bağımsız değişken olarak kullanılarak bir geri çağırma işlevi çağrılır. Örneğin, ilgilendiğiniz tüm dosyalar silindiğinde gözlemciyi devre dışı bırakmak için observer bağımsız değişkenini kullanabilirsiniz (bkz. Dosya sistemini gözlemlemeyi durdurma).

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

Dosya sistemi değişiklik kaydı

Her dosya sistemi değişikliği kaydı aşağıdaki yapıya sahiptir. Tüm alanlar salt okunurdur.

root (bir FileSystemHandle): FileSystemObserver.observe() işlevine iletilen tutma yeri.
changedHandle (FileSystemHandle): Dosya sistemi değişikliğinden etkilenen tutma yeri. Bu alan, "errored", "unknown" ve "disappeared" türü etkinlikler için null olur. Hangi dosyanın veya dizinin kaybolduğunu görmek için relativePathComponents simgesini kullanın.
relativePathComponents (bir Array): changedHandle öğesinin root öğesine göre yolu.
type (a String): Değişikliğin türü. Aşağıdaki türler mümkündür:
- "appeared": Dosya veya dizin, root içinde oluşturuldu ya da root içine taşındı.
- "disappeared": Dosya veya dizin silindi ya da root dışına taşındı.
- "modified": Dosya veya dizin değiştirildi.
- "moved": Dosya veya dizin, root içinde taşındı.
- "unknown": Bu, sıfır veya daha fazla etkinliğin kaçırıldığını gösterir. Geliştiriciler, buna yanıt olarak izlenen dizini yoklamalıdır.
- "errored": Gözlem artık geçerli değil. Bu durumda, dosya sistemini izlemeyi durdurmak isteyebilirsiniz. Bu değer, kaynak başına gözlem sayısı maksimum sınırına ulaşıldığında da gönderilir. Bu sınır, işletim sistemine bağlıdır ve önceden bilinmez. Bu durumda site, yeniden denemeye karar verebilir ancak işletim sisteminin yeterli kaynağı boşalttığı garanti edilmez. Bu değerin gönderileceği başka bir durum da gözlemlenen tutma yeri (yani gözlemin kökü) silindiğinde veya taşındığında ortaya çıkar. Bu durumda önce "disappeared" etkinliği, ardından gözlemin artık geçerli olmadığını belirten bir "errored" etkinliği gönderilir. Son olarak, bu etkinlik, dizin veya dosya işleyicisi için izin kaldırıldığında gönderilir.
relativePathMovedFrom (Array, isteğe bağlı): Taşınan bir herkese açık kullanıcı adının önceki konumu. Yalnızca type "moved" olduğunda kullanılabilir.

Dosya veya dizini izlemeyi durdurma

Bir FileSystemHandle izlemeyi durdurmak için unobserve() yöntemini çağırın ve işleyiciyi bağımsız değişken olarak iletin.

observer.unobserve(fileHandle);

Dosya sistemini gözlemlemeyi durdurma

Dosya sistemini izlemeyi durdurmak için FileSystemObserver örneğinin bağlantısını aşağıdaki şekilde kesin.

observer.disconnect();

API'yi deneyin

File System Observer API'yi yerel olarak test etmek için about:flags içinde #file-system-observer işaretini ayarlayın. API'yi gerçek kullanıcılarla test etmek için kaynak denemesine kaydolun ve Chrome Kaynak Denemeleri kılavuzundaki talimatları uygulayın. Kaynak denemesi, Chrome 129 (11 Eylül 2024) ile Chrome 134 (26 Şubat 2025) arasında geçerli olacaktır.

Demo

Dosya Sistemi Gözlemcisi API'sinin nasıl çalıştığını yerleştirilmiş demoda görebilirsiniz. Kaynak koduna göz atın. Demoda, izlenen bir dizindeki dosyalar rastgele oluşturulur, silinir veya değiştirilir ve etkinlikleri uygulama penceresinin üst kısmına kaydedilir. Ardından, değişiklikler gerçekleştiği sırada uygulama penceresinin alt kısmına kaydedilir. Bu sayfayı, File System Observer API'yi desteklemeyen bir tarayıcıda okuyorsanız demoya ait ekran görüntüsünü inceleyin.

Geri bildirim

File System Observer API'nin şekli hakkında geri bildiriminiz varsa WHATWG/fs deposundaki 123 numaralı soruna yorum yapın.

İlgili bağlantılar

Teşekkür

Bu belge Daseul Lee, Nathan Memmott, Etienne Noël ve Rachel Andrew tarafından incelenmiştir.