Yüklü web uygulamalarının dosya işleyicisi olmasına izin ver

Bir uygulamayı işletim sistemine dosya işleyici olarak kaydetme.

Thomas Steiner

Web uygulamaları artık dosyaları okuyup yazabildiğine göre, bir sonraki mantıklı adım geliştiricilerin bu web uygulamalarını, uygulamalarının oluşturup işleyebileceği dosyalar için dosya işleyicileri olarak bildirmesine izin vermektir. File Handling API, tam olarak bunu yapmanıza olanak tanır. Bir metin düzenleyici uygulamasını dosya işleyici olarak kaydettikten ve yükledikten sonra macOS'te bir .txt dosyasını sağ tıklayıp "Bilgi Al"ı seçerek işletim sistemine .txt dosyalarını her zaman bu uygulamayla varsayılan olarak açması talimatını verebilirsiniz.

File Handling API için önerilen kullanım alanları

Bu API'yi kullanabilecek sitelere örnek olarak şunlar verilebilir:

Metin düzenleyiciler, e-tablo uygulamaları ve slayt gösterisi oluşturucular gibi Office uygulamaları
Grafik düzenleyiciler ve çizim araçları.
Video oyunu seviyesi düzenleme araçları

File Handling API nasıl kullanılır?

Progresif geliştirme

File Handling API'ye çoklu dolgu yapılamaz. Ancak dosyaları bir web uygulamasıyla açma işlevi iki farklı şekilde kullanılabilir:

Web Share Target API, geliştiricilerin uygulamalarını paylaşım hedefi olarak belirtmelerine olanak tanır. Böylece dosyalar, işletim sisteminin paylaşım sayfasından açılabilir.
File System Access API, dosya sürükleyip bırakma özelliğiyle entegre edilebilir. Böylece geliştiriciler, bırakılan dosyaları halihazırda açık olan uygulamada işleyebilir.

Tarayıcı desteği

Browser Support

Source

Özellik algılama

File Handling API'nin desteklenip desteklenmediğini kontrol etmek için:

if ('launchQueue' in window && 'files' in LaunchParams.prototype) {
  // The File Handling API is supported.
}

File Handling API'nin bildirimsel kısmı

İlk adım olarak, web uygulamalarının web uygulaması manifestlerinde hangi tür dosyaları işleyebileceklerini bildirmeleri gerekir. File Handling API, web uygulaması manifestini "file_handlers" adlı yeni bir özellik ile genişletir. Bu özellik, dosya işleyicilerin dizisini kabul eder. Dosya işleyici, şu özelliklere sahip bir nesnedir:

Değeri olarak uygulamanın kapsamındaki bir URL'yi işaret eden bir "action" özelliği.
Anahtar olarak MIME türlerinin nesnesini ve değer olarak dosya uzantılarının listelerini içeren bir "accept" özelliği.
ImageResource simgeleri dizisine sahip bir "icons" özelliği. Bazı işletim sistemleri, dosya türü ilişkilendirmesinin yalnızca ilişkili uygulama simgesi olmayan, bunun yerine dosya türünün uygulamayla kullanımına ilişkin özel bir simge göstermesine izin verir.
Birden fazla dosyanın tek bir istemcide mi yoksa birden fazla istemcide mi açılacağını tanımlayan bir "launch_type" özelliği. Varsayılan değer "single-client"'dir. Kullanıcı birden fazla dosya açarsa ve dosya işleyici "multiple-clients" ile "launch_type" olarak açıklama eklenmişse birden fazla uygulama başlatılır ve her başlatma için LaunchParams.files dizisinde (daha aşağıda bakın) yalnızca bir öğe bulunur.

Aşağıdaki örnekte, web uygulaması manifestinin yalnızca ilgili alıntısı gösterilmektedir. Bu örnek, durumu daha net bir şekilde açıklayacaktır:

{
  "file_handlers": [
    {
      "action": "/open-csv",
      "accept": {
        "text/csv": [".csv"]
      },
      "icons": [
        {
          "src": "csv-icon.png",
          "sizes": "256x256",
          "type": "image/png"
        }
      ],
      "launch_type": "single-client"
    },
    {
      "action": "/open-svg",
      "accept": {
        "image/svg+xml": ".svg"
      },
      "icons": [
        {
          "src": "svg-icon.png",
          "sizes": "256x256",
          "type": "image/png"
        }
      ],
      "launch_type": "single-client"
    },
    {
      "action": "/open-graf",
      "accept": {
        "application/vnd.grafr.graph": [".grafr", ".graf"],
        "application/vnd.alternative-graph-app.graph": ".graph"
      },
      "icons": [
        {
          "src": "graf-icon.png",
          "sizes": "256x256",
          "type": "image/png"
        }
      ],
      "launch_type": "multiple-clients"
    }
  ]
}

Bu, virgülle ayrılmış değer (.csv) dosyalarını /open-csv, ölçeklenebilir vektör grafikleri (.svg) dosyalarını /open-svg ve .grafr, .graf veya .graph uzantılı uydurma bir Grafr dosya biçimini /open-graf konumunda işleyen varsayımsal bir uygulama içindir. İlk iki dosya tek bir istemcide, son dosya ise birden fazla dosya işleniyorsa birden fazla istemcide açılır.

File Handling API'nin zorunlu kısmı

Uygulama, teoride hangi kapsam içi URL'de hangi dosyaları işleyebileceğini beyan ettiğine göre, pratikte gelen dosyalarla ilgili zorunlu olarak bir işlem yapması gerekir. Bu noktada launchQueue devreye girer. Başlatılan dosyalara erişmek için bir sitenin window.launchQueue nesnesi için bir tüketici belirtmesi gerekir. Lansmanlar, belirtilen tüketici tarafından işlenene kadar sıraya alınır. Tüketici, her lansman için tam olarak bir kez çağrılır. Bu şekilde, tüketici belirtilme zamanından bağımsız olarak her lansman ele alınır.

if ('launchQueue' in window && 'files' in LaunchParams.prototype) {
  launchQueue.setConsumer((launchParams) => {
    // Nothing to do when the queue is empty.
    if (!launchParams.files.length) {
      return;
    }
    for (const fileHandle of launchParams.files) {
      // Handle the file.
    }
  });
}

Geliştirici Araçları desteği

Bu makalenin yazıldığı sırada DevTools desteği yoktu ancak destek eklenmesi için özellik isteğinde bulundum.

Demo

Karikatür tarzında çizim uygulaması olan Excalidraw'a dosya işleme desteği ekledim. Bu özelliği test etmek için önce Excalidraw'ı yüklemeniz gerekir. Ardından bu uzantıyla bir dosya oluşturup dosya sisteminizde bir yere kaydettiğinizde dosyayı çift tıklayarak veya sağ tıklayıp içerik menüsünde "Excalidraw"u seçerek açabilirsiniz. Uygulamayı kaynak kodunda inceleyebilirsiniz.

Excalidraw dosyası içeren macOS Finder penceresi. — İşletim sisteminizin dosya gezgininde bir dosyayı çift tıklayın veya sağ tıklayın.

Bir dosyayı sağ tıkladığınızda görünen içerik menüsünde "Birlikte aç… Excalidraw" öğesi vurgulanmış. — Excalidraw, `.excalidraw` dosyaları için varsayılan dosya işleyicidir.

Güvenlik

Chrome Ekibi, File Handling API'yi Güçlü Web Platformu Özelliklerine Erişimi Kontrol Etme başlıklı makalede tanımlanan temel ilkeleri (kullanıcı kontrolü, şeffaflık ve ergonomi dahil) kullanarak tasarladı ve uyguladı.

İzinler, izinlerin kalıcılığı ve dosya işleyici güncellemeleri

Kullanıcıların güvenini kazanmak ve dosyalarının güvenliğini sağlamak için Dosya İşleme API'si bir dosyayı açtığında, PWA'nın dosyayı görüntüleyebilmesi için önce izin istemi gösterilir. Bu izin istemi, kullanıcının bir dosyayı açmak için PWA'yı seçmesinden hemen sonra gösterilir. Böylece izin, PWA kullanılarak dosya açma işlemiyle sıkı bir şekilde ilişkilendirilir ve daha anlaşılır ve alakalı hale gelir.

Bu izin, kullanıcı dosya işleme için siteye İzin ver'i veya Engelle'yi tıklayana ya da istemi üç kez yoksayana kadar (üç kez yoksandıktan sonra Chromium bu izni yasaklar ve engeller) her seferinde gösterilir. Seçilen ayar, PWA kapatılıp yeniden açıldığında geçerliliğini korur.

Manifest güncellendiğinde ve "file_handlers" bölümünde değişiklikler algılandığında izinler sıfırlanır.

Dosyalarla ilgili zorluklar

Web sitelerinin dosyalara erişmesine izin verilmesiyle açılan geniş bir saldırı vektörü kategorisi vardır. Bunlar File System Access API ile ilgili makalede açıklanmıştır. File Handling API'nin File System Access API'ye kıyasla sağladığı ek güvenlik özelliği, bir web uygulaması tarafından gösterilen dosya seçici yerine işletim sisteminin yerleşik kullanıcı arayüzü aracılığıyla belirli dosyalara erişim izni verme olanağıdır.

Kullanıcıların bir dosyayı açarak web uygulamasına istemeden erişim izni verme riski devam etmektedir. Ancak, bir dosyanın açılması, genellikle açıldığı uygulamanın bu dosyayı okumasına ve/veya değiştirmesine izin verdiği anlamına gelir. Bu nedenle, kullanıcının bir dosyayı yüklü bir uygulamada açmak için açıkça yaptığı seçim (ör. "Birlikte aç…" bağlam menüsü aracılığıyla) uygulamaya duyulan güvenin yeterli bir sinyali olarak okunabilir.

Varsayılan işleyiciyle ilgili sorunlar

Bunun istisnası, ana makine sisteminde belirli bir dosya türü için uygulama olmamasıdır. Bu durumda, bazı ana makine işletim sistemleri yeni kaydedilen işleyiciyi, kullanıcı müdahalesi olmadan ve sessizce söz konusu dosya türünün varsayılan işleyicisi olarak otomatik olarak yükseltebilir. Bu durumda, kullanıcı bu türdeki bir dosyayı çift tıkladığında dosya otomatik olarak kayıtlı web uygulamasında açılır. Bu tür ana makine işletim sistemlerinde, kullanıcı aracısı dosya türü için mevcut bir varsayılan işleyici olmadığını belirlediğinde, dosya içeriğinin kullanıcının izni olmadan yanlışlıkla bir web uygulamasına gönderilmesini önlemek için açık bir izin istemi gerekebilir.

Kullanıcı denetimi

Spesifikasyonda, dosyaları işleyebilen her sitenin dosya işleyici olarak kaydedilmemesi gerektiği belirtiliyor. Bunun yerine, dosya işleme kaydı yükleme işleminden sonra yapılmalı ve özellikle bir site varsayılan işleyici olacaksa hiçbir zaman açık kullanıcı onayı olmadan gerçekleşmemelidir. Siteler, kullanıcının muhtemelen varsayılan bir işleyiciyi kaydettirdiği .json gibi mevcut uzantıları ele geçirmek yerine kendi uzantılarını oluşturmayı düşünmelidir.

Şeffaflık

Tüm işletim sistemleri, kullanıcıların mevcut dosya ilişkilendirmelerini değiştirmesine olanak tanır. Bu, tarayıcının kapsamı dışındadır.

Geri bildirim

Chrome Ekibi, Dosya İşleme API'si ile ilgili deneyimlerinizi öğrenmek istiyor.

API tasarımı hakkında bilgi verin

API ile ilgili beklentilerinizi karşılamayan bir durum var mı? Yoksa fikrinizi uygulamak için eksik yöntemler veya özellikler mi var? Güvenlik modeliyle ilgili sorunuz veya yorumunuz mu var?

İlgili GitHub deposunda bir spesifikasyon sorunu bildirin veya düşüncelerinizi mevcut bir soruna ekleyin.

Uygulamayla ilgili sorun bildirme

Chrome'un uygulamasında bir hata mı buldunuz? Yoksa uygulama, spesifikasyondan farklı mı?

new.crbug.com adresinden hata kaydı oluşturun. Mümkün olduğunca fazla ayrıntı ve yeniden oluşturmayla ilgili basit talimatlar eklediğinizden emin olun. Ayrıca UI>Browser>WebAppInstalls>FileHandling simgesini Bileşenler kutusuna girin.

API'ye desteğinizi gösterme

File Handling API'yi kullanmayı planlıyor musunuz? Herkese açık desteğiniz, Chrome ekibinin özellikleri önceliklendirmesine yardımcı olur ve diğer tarayıcı satıcılarına bu özelliklerin ne kadar önemli olduğunu gösterir.

Bu özelliği nasıl kullanmayı planladığınızı WICG Discourse iş parçacığında paylaşın.
@ChromiumDev'e #FileHandling hashtag'ini kullanarak tweet gönderin ve nerede, nasıl kullandığınızı bize bildirin.

Faydalı bağlantılar

Teşekkür

File Handling API, Eric Willigers, Jay Harris ve Raymes Khoury tarafından belirtilmiştir. Bu makale Joe Medley tarafından incelendi.