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 dosyalara ve dizinlere erişmesine olanak tanır. İlki, geliştiricilerin normal, kullanıcı tarafından görülebilen dosya sisteminde okuma ve yazma yapmasına olanak tanır. İkincisi ise her sitenin kökenine özel olan ve belirli performans avantajları sunan, kullanıcıdan gizli özel bir dosya sistemi açar. Her iki durumda da geliştiricilerin dosyalar ve dizinlerle etkileşimde bulunma şekli, FileSystemHandle nesneleri (daha somut şekilde, dosyalar için FileSystemFileHandle ve dizinler için FileSystemDirectoryHandle) aracılığıyla gerçekleşir. Şimdiye kadar, dosya sistemlerinden birinde bir dosya veya dizinde yapılan değişikliklerden haberdar olmak için bir tür anket yapılması ve lastModified zaman damgasının ya da dosya içeriğinin karşılaştırılması gerekiyordu.

Chrome 129'dan itibaren kaynak denemesinde olan File System Observer API, bu durumu değiştirir ve değişiklikler olduğunda geliştiricilerin otomatik olarak uyarılmasına olanak tanır. Bu kılavuzda, özelliğin nasıl çalıştığı ve özelliğin nasıl deneyileceği açıklanmaktadır.

Kullanım alanları

Dosya sistemiyle ilgili olası değişikliklerden hemen haberdar edilmesi gereken uygulamalarda File System Observer API'yi kullanın.

  • Bir projenin dosya sistemi ağacının bir temsilini gösteren web tabanlı entegre geliştirme ortamları (IDE'ler).
  • Dosya sistemi değişikliklerini bir sunucuda senkronize eden uygulamalar. Örneğin, bir SQLite veritabanı dosyası.
  • Bir çalışandan veya başka bir sekmeden dosya sistemi değişikliklerini ana iş parçacığına bildirmesi gereken uygulamalar.
  • Görselleri otomatik olarak optimize etmek için bir kaynak dizinini gözlemleyen uygulamalar.
  • Dosya değişikliğinin yeniden yüklemeyi tetiklediği HTML tabanlı slaytlar gibi, anında yeniden yükleme özelliğinden yararlanan deneyimler.

File System Observer API'yi kullanma

Özellik algılama

Dosya Sistemi Gözlemcisi API'sinin desteklenip desteklenmediğini görmek için aşağıdaki örnekte gösterildiği 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 ve bağımsız değişken olarak bir callback işlevi sağlayarak bir dosya sistemi gözlemcisi başlatın.

const observer = new FileSystemObserver(callback);

Bir dosyayı veya dizini gözlemlemeye başlama

Bir dosyayı veya dizini gözlemlemeye başlamak için FileSystemObserver örneğinin asenkron observe() yöntemini çağırın. Bu yönteme, bağımsız değişken olarak seçilen dosyanın veya dizinin FileSystemHandle değerini sağlayın. Bir dizini gözlemlerken, dizine yapılan değişikliklerden yinelemeli olarak (yani dizinin kendisi ve tüm alt dizinleri ve dosyaları için) bilgilendirilmek 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çinde bulunan 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şiklik olduğunda, dosya sistemi değişikliği records ve observer'ın kendisi bağımsız değişken olarak bir geri çağırma işlevi çağrılır. Örneğin, ilgilendiğiniz tüm dosyalar silindiğinde gözlemcinin bağlantısını kesmek için observer bağımsız değişkenini kullanabilirsiniz (Dosya sistemini gözlemlemeyi durdurma bölümüne bakın).

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şiklik kaydı aşağıdaki yapıya sahiptir. Tüm alanlar salt okunur.

  • root (bir FileSystemHandle): FileSystemObserver.observe() işlevine iletilen tutamaç.
  • changedHandle (a FileSystemHandle): Dosya sistemi değişikliğinden etkilenen herkese açık tanımlayıcı.
  • relativePathComponents (Array): changedHandle öğesinin root'e göre yolu.
  • type (a String): Değişikliğin türü. Aşağıdaki türler kullanılabilir:
    • "appeared": Dosya veya dizin oluşturuldu ya da root klasörüne 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, bu yanıta yanıt olarak izlenen dizini yoklamalıdır.
    • "errored": Gözlem artık geçerli değil. Bu durumda, dosya sistemini gözlemlemeyi durdurabilirsiniz.
  • relativePathMovedFrom (bir Array, isteğe bağlı): Taşınan herkese açık kullanıcı adının önceki konumu. Yalnızca type "moved" olduğunda kullanılabilir.

Bir dosyayı veya dizini gözlemlemeyi durdurma

Bir FileSystemHandle'yi gözlemlemeyi durdurmak için unobserve() yöntemini çağırın ve bağımsız değişken olarak herkese açık kimliği iletin.

observer.unobserve(fileHandle);

Dosya sistemini gözlemlemeyi durdurma

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

observer.disconnect();

API'yi deneyin

File System Observer API'yi yerel olarak test etmek için about:flags öğesinde #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

File System Observer API'nin nasıl çalıştığını yerleşik demoda görebilirsiniz. Kaynak koduna göz atın veya Glitch'te demo kodunu remiksleyin. Demo, gözlemlenen bir dizinde rastgele dosya oluşturur, siler veya değiştirir ve etkinliğini uygulama penceresinin üst kısmına kaydeder. Ardından, uygulama penceresinin alt kısmında değişiklikler gerçekleştikçe bunları günlüğe kaydeder. Bu makaleyi File System Observer API'yi desteklemeyen bir tarayıcıda okuyorsanız demonun ekran görüntüsüne bakın.

Geri bildirim

File System Observer API'nin şekliyle ilgili geri bildiriminiz varsa WHATWG/fs deposundaki 123 numaralı soruna yorum ekleyin.

Teşekkür ederiz

Bu doküman Daseul Lee, Nathan Memmott, Etienne Noël ve Rachel Andrew tarafından incelendi.