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

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

Artık web uygulamaları dosya okuma ve yazma özelliğine sahip olduğundan bir sonraki mantıksal adım, geliştiricilerin bu web uygulamalarını, uygulamalarının oluşturup işleyebilecekleri dosyalar için dosya işleyici olarak tanımlamalarına izin vermektir. File Handling API tam da 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ı varsayılan olarak her zaman bu uygulamayla açması gerektiğini bildirebilirsiniz.

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 seviye düzenleyici araçları.

File Handling API'yi kullanma

Progresif geliştirme

File Handling API'ye çoklu dolgu yapılamaz. Ancak, dosyaları bir web uygulamasıyla açma işlevi, iki başka yöntemle de gerçekleştirilebilir:

  • Web Paylaşım Hedefi API, geliştiricilerin uygulamalarını paylaşım hedefi olarak belirtmesine olanak tanır. Böylece, dosyalar işletim sisteminin paylaşım sayfasından açılabilir.
  • File System Access API, dosya sürükle ve bırak özelliğiyle entegre edilebilir. Böylece geliştiriciler, açılmış uygulamada bırakılan dosyaları işleyebilir.

Tarayıcı desteği

Tarayıcı desteği

  • Chrome: 102.
  • Edge: 102.
  • Firefox: Desteklenmez.
  • Safari: desteklenmez.

Kaynak

Ö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 açıklayıcı kısmı

İlk adım olarak web uygulamalarının, web uygulaması manifest dosyalarında hangi tür dosyaları işleyebileceklerini açık bir şekilde belirtmesi gerekir. File Handling API, web uygulaması manifestini bir dosya işleyici dizisi kabul eden "file_handlers" adlı yeni bir mülkle genişletir. Dosya işleyici, aşağıdaki özelliklere sahip bir nesnedir:

  • Değeri olarak uygulamanın kapsamındaki bir URL'yi işaret eden bir "action" mülkü.
  • Anahtar olarak MIME türleri nesnesini ve değerleri olarak dosya uzantılarının listelerini içeren bir "accept" mülkü.
  • ImageResource simge dizisi içeren bir "icons" mülkü. Bazı işletim sistemleri, dosya türü ilişkilendirmesinin yalnızca ilişkili uygulama simgesini değil, aynı zamanda bu dosya türünün uygulamayla kullanımıyla ilgili ö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" mülkü. Varsayılan değer: "single-client". Kullanıcı birden fazla dosya açarsa ve dosya işleyici, "launch_type" olarak "multiple-clients" ile ek açıklama eklenmişse birden fazla uygulama başlatılır ve her başlatma için LaunchParams.files dizisi (aşağıya bakın) yalnızca bir öğe içerir.

Aşağıdaki örnekte, web uygulaması manifestinin yalnızca alakalı kısmı gösterilmektedir.

{
 
"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 örnek, /open-csv alanında virgül ile ayrılmış değer (.csv) dosyalarını, /open-svg alanında ölçeklenebilir vektör grafik (.svg) dosyalarını ve /open-graf alanında uzantısı .grafr, .graf veya .graph olan kurgusal bir Grafr dosya biçimini işleyen varsayımsal bir uygulama içindir. İlk ikisi tek bir istemcide, sonuncusu ise birden fazla dosya işleniyorsa birden çok istemcide açılır.

File Handling API'nin zorunlu kısmı

Uygulama, hangi dosyaları hangi kapsam içi URL'de işleyebileceğini teorik olarak beyan ettiğine göre, pratikte gelen dosyalarla mutlaka bir işlem yapması gerekir. Bu noktada launchQueue devreye girer. Lansmanı yapılan dosyalara erişmek için sitenin window.launchQueue nesnesi için bir tüketici belirtmesi gerekir. Lansman işlemleri, 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üketicinin ne zaman belirtildiğine bakılmaksızın her lansman işlenir.

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

DevTools desteği

Bu makalenin yazıldığı sırada DevTools desteği yok ancak desteğin eklenmesi için bir özellik isteği gönderdim.

Demo

Karikatür tarzı bir ç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 şablonla bir dosya oluşturup dosya sisteminizde bir yere kaydettiğinizde dosyayı çift tıklayarak veya sağ tıklayıp bağlam menüsünden "Excalidraw"ı seçerek açabilirsiniz. Kaynak kodundaki uygulamaya göz atabilirsiniz.

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, Aç... Excalidraw öğesi vurgulanmış olarak görünen içerik menüsü.
Excalidraw, .excalidraw dosyaları için varsayılan dosya işleyicisidir.

Güvenlik

Chrome ekibi, File Handling API'yi tasarlarken ve uygularken Güçlü Web Platformu Özelliklerine Erişimi Kontrol Etme başlıklı makalede belirtilen temel ilkeleri (kullanıcı kontrolü, şeffaflık ve ergonomi gibi) temel almıştır.

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

Kullanıcı güvenini ve kullanıcı dosyalarının güvenliğini sağlamak için File Handling API bir dosyayı açtığında, PWA'nın dosyayı görüntüleyebilmesi için bir 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 kullanarak dosya açma işlemine sıkı bir şekilde bağlanır. Böylece daha anlaşılır ve alakalı hale gelir.

Kullanıcı site için dosya işleme işlemine İzin ver veya Engelle'yi tıklayana ya da istemi üç kez yoksayana kadar bu izin her seferinde gösterilir (bu durumda Chromium bu izni ambargoya alır ve engeller). Seçilen ayar, PWA kapatıldığında ve yeniden açıldığında korunur.

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

Web sitelerinin dosyalara erişmesine izin verilerek açılan çok sayıda saldırı yolu vardır. Bunlar File System Access API'deki makalede açıklanmıştır. File Handling API'nin File System Access API'ye kıyasla güvenlikle ilgili ek özelliği, web uygulaması tarafından gösterilen bir 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, dosyayı açarak bir web uygulamasına istemeden dosya erişimi vermesi riski yine de vardır. Bununla birlikte, genellikle bir dosyayı açmak, dosyanın birlikte açıldığı uygulamanın o dosyayı okumasına ve/veya değiştirmesine izin verir. Bu nedenle, kullanıcının bir dosyayı yüklü bir uygulamada açma konusundaki açık seçimi (ör. "Birlikte aç..." bağlam menüsü aracılığıyla) uygulamaya güven konusunda yeterli bir sinyal olarak okunabilir.

Varsayılan işleyici zorlukları

Bunun istisnası, belirli bir dosya türü için ana makine sisteminde hiç uygulama olmamasıdır. Bu durumda bazı ana makine işletim sistemleri, yeni kaydedilen işleyiciyi söz konusu dosya türünün varsayılan işleyicisine otomatik olarak, sessiz bir şekilde ve kullanıcının müdahale etmesine gerek kalmadan yükseltebilir. Bu, kullanıcı bu tür bir dosyayı çift tıkladığında dosyanın otomatik olarak kayıtlı web uygulamasında açılacağı anlamına gelir. Bu tür ana makine işletim sistemlerinde, kullanıcı aracısı dosya türü için varsayılan bir işleyici olmadığını belirlediğinde, dosyanın 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 gösterilmesi gerekebilir.

Kullanıcı denetimi

Bu spesifikasyonda, tarayıcıların, dosyaları dosya işleyici olarak işleyebilen her siteyi kaydetmemesi gerektiği belirtilmektedir. Bunun yerine, dosya işleme kaydı yükleme işleminin ardından yapılmalıdır ve özellikle bir sitenin varsayılan işleyici olması gerekiyorsa hiçbir zaman açık bir kullanıcı onayı olmadan yapılmamalıdır. Siteler, kullanıcının muhtemelen zaten varsayılan işleyicisi olan .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 izin verir. Bu, tarayıcının kapsamı dışındadır.

Geri bildirim

Chrome ekibi, File handling API ile ilgili deneyiminiz hakkında bilgi almak istiyor.

API tasarımı hakkında bilgi verin

API ile ilgili olarak beklediğiniz gibi çalışmayan bir şey var mı? Yoksa fikrinizi uygulamak için ihtiyaç duyduğunuz yöntemler veya özellikler eksik mi? Güvenlik modeliyle ilgili sorunuz veya yorumunuz mu var?

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

Uygulamayla ilgili sorunları 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ı ekleyin, yeniden oluşturmayla ilgili basit talimatlar verin ve Bileşenler kutusuna UI>Browser>WebAppInstalls>FileHandling yazın. Glitch, hızlı ve kolay yeniden oluşturma işlemleri paylaşmak için mükemmel bir araçtır.

API'yi destekleme

File Handling API'yi kullanmayı planlıyor musunuz? Herkese açık desteğiniz, Chrome ekibinin özelliklere öncelik vermesine yardımcı olur ve diğer tarayıcı tedarikçi firmalarına bu özellikleri desteklemenin ne kadar önemli olduğunu gösterir.

Faydalı bağlantılar

Teşekkür ederiz

File Handling API, Eric Willigers, Jay Harris ve Raymes Khoury tarafından tanımlanmıştır. Bu makale Joe Medley tarafından incelendi.