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

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

Thomas Steiner

Web uygulamaları artık dosya okuyup yazabiliyor. Bu nedenle, geliştiricilerin bu web uygulamalarını, uygulamalarının oluşturabileceği ve işleyebileceği dosyalar için dosya işleyici olarak tanımlamasına izin vermek mantıklı bir sonraki adımdır. 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

Dosya işleme API'si kendi başına çoklu doldurulamaz. Ancak, dosyaları bir web uygulamasıyla açma işlevi, iki başka yöntemle de gerçekleştirilebilir:

  • Web Share Target API, geliştiricilerin uygulamalarını bir 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.
  • Kenar: 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"'tir. 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, birden fazla dosya işleniyorsa sonuncusu birden fazla istemcide açılır.

File Handling API'nin zorunlu kısmı

Teoride uygulama hangi kapsam içi URL'de hangi dosyaları işleyebileceğini beyan etti. Şimdi, gelen dosyalarla ilgili pratikte bir şeyler yapması gerekiyor. 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 yazının yazıldığı sırada Geliştirici Araçları desteği yoktur ancak desteğin eklenmesi için özellik isteğinde bulundum.

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 kodunda uygulamayı kontrol edebilirsiniz.

Excalidraw dosyası içeren macOS Finder penceresi.
İşletim sisteminizin dosya gezgininde bir dosyayı çift tıklayın veya sağ tıklayın.
Birlikte aç... Excalidraw öğesi vurgulanmış haldeki bir dosyayı sağ tıkladığınızda görünen içerik menüsü.
Excalidraw, .excalidraw dosyaları için varsayılan dosya işleyicidir.

Güvenlik

Chrome ekibi; kullanıcı denetimi, şeffaflık ve ergonomik dahil olmak üzere Güçlü Web Platformu Özelliklerine Erişimi Kontrol Etme konusunda tanımlanan temel ilkeleri kullanarak File handling API'yi tasarlamış ve uygulamıştır.

İzinler, izinlerin kalıcı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 (progresif web uygulaması) kapatma ve yeniden açma işlemleri boyunca geçerliliğini korur.

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 ile ilgili 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. Ancak, bir dosyanın açılmasının, açıldığı uygulamanın bu dosyayı okumasına ve/veya değiştirmesine izin verdiği genel olarak kabul edilir. 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ı, ana sistemde belirli bir dosya türü için uygulama bulunmamasıdır. Bu durumda, bazı ana makine işletim sistemleri, yeni kayıtlı işleyiciyi otomatik olarak ve kullanıcı müdahalesi olmadan söz konusu dosya türü için varsayılan işleyiciye yükseltebilir. Bu durum, kullanıcı söz konusu türdeki bir dosyayı çift tıkladığında 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, bir 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 gerekebilir.

Kullanıcı denetimi

Spesifikasyonda, tarayıcıların dosyaları işleyebilecek her siteyi dosya işleyici olarak 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. Sitelerin, kullanıcının muhtemelen kayıtlı bir varsayılan işleyicisi olan .json gibi mevcut uzantıları ele geçirmek yerine kendi uzantılarını oluşturmaları önerilir.

Ş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 deneyimlerinizi öğrenmek istiyor.

API tasarımı hakkında bilgi verin

API'de beklediğiniz gibi çalışmayan bir şey mi var? 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 bir spesifikasyon sorunu bildirin veya düşüncelerinizi mevcut bir soruna ekleyin.

Uygulamayla ilgili bir sorunu bildirin

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

  • new.crbug.com adresinde bir hata bildiriminde bulunun. Mümkün olduğunca çok ayrıntıyı, çoğaltmaya ilişkin basit talimatları eklediğinizden ve Bileşenler kutusuna UI>Browser>WebAppInstalls>FileHandling ifadesini girdiğinizden emin olun. 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 özellikleri önceliklendirmesine yardımcı olur ve diğer tarayıcı tedarikçilerine bunları desteklemenin ne kadar kritik olduğunu gösterir.

Faydalı bağlantılar

Teşekkür

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