Mengizinkan aplikasi web terinstal menjadi pengendali file

Daftarkan aplikasi sebagai pengendali file dengan sistem operasi.

Setelah aplikasi web mampu membaca dan menulis file, langkah logis berikutnya adalah mengizinkan developer mendeklarasikan aplikasi web ini sebagai pengendali file untuk file yang dapat dibuat dan diproses oleh aplikasi mereka. File Handling API memungkinkan Anda melakukan hal ini. Setelah mendaftarkan aplikasi editor teks sebagai pengendali file dan setelah menginstalnya, Anda dapat mengklik kanan file .txt di macOS dan memilih "Get Info" untuk kemudian menginstruksikan OS agar selalu membuka file .txt dengan aplikasi ini sebagai default.

Kasus penggunaan yang disarankan untuk File Handling API

Contoh situs yang dapat menggunakan API ini meliputi:

  • Aplikasi kantor seperti editor teks, aplikasi spreadsheet, dan pembuat slideshow.
  • Editor grafis dan alat gambar.
  • Alat editor level game video.

Cara menggunakan File Handling API

Peningkatan progresif

File Handling API itu sendiri tidak dapat di-polyfill. Namun, fungsi membuka file dengan aplikasi web dapat dicapai melalui dua cara lain:

  • Web Share Target API memungkinkan developer menentukan aplikasi mereka sebagai target berbagi sehingga file dapat dibuka dari sheet berbagi sistem operasi.
  • File System Access API dapat diintegrasikan dengan tarik lalu lepas file, sehingga developer dapat menangani file yang dilepas di aplikasi yang sudah terbuka.

Dukungan browser

Dukungan Browser

  • Chrome: 102.
  • Edge: 102.
  • Firefox: tidak didukung.
  • Safari: tidak didukung.

Sumber

Deteksi fitur

Untuk memeriksa apakah File Handling API didukung, gunakan:

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

Bagian deklaratif dari File Handling API

Sebagai langkah pertama, aplikasi web perlu mendeskripsikan secara deklaratif dalam manifes aplikasi web jenis file yang dapat ditanganinya. File Handling API memperluas manifes aplikasi web dengan properti baru yang disebut "file_handlers" yang menerima array pengendali file. Pengendali file adalah objek dengan properti berikut:

  • Properti "action" yang mengarah ke URL dalam cakupan aplikasi sebagai nilainya.
  • Properti "accept" dengan objek jenis MIME sebagai kunci dan daftar ekstensi file sebagai nilainya.
  • Properti "icons" dengan array ikon ImageResource. Beberapa sistem operasi memungkinkan asosiasi jenis file untuk menampilkan ikon yang bukan hanya ikon aplikasi terkait, tetapi ikon khusus yang terkait dengan penggunaan jenis file tersebut dengan aplikasi.
  • Properti "launch_type" yang menentukan apakah beberapa file harus dibuka dalam satu klien atau dalam beberapa klien. Defaultnya adalah "single-client". Jika pengguna membuka beberapa file dan jika pengendali file telah dianotasi dengan "multiple-clients" sebagai "launch_type"-nya, lebih dari satu peluncuran aplikasi akan terjadi, dan untuk setiap peluncuran, array LaunchParams.files (lihat di bawah) hanya akan memiliki satu elemen.

Contoh di bawah, yang hanya menampilkan kutipan manifes aplikasi web yang relevan, akan membuatnya lebih jelas:

{
 
"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"
   
}
 
]
}

Ini untuk aplikasi fiktif yang menangani file nilai yang dipisahkan koma (.csv) di /open-csv, file grafik vektor skalabel (.svg) di /open-svg, dan format file Grafr yang dibuat-buat dengan .grafr, .graf, atau .graph sebagai ekstensi di /open-graf. Dua yang pertama akan terbuka di satu klien, yang terakhir di beberapa klien jika beberapa file sedang ditangani.

Bagian imperatif dari File Handling API

Setelah mendeklarasikan file apa yang dapat ditangani URL dalam cakupan secara teori, aplikasi harus harus melakukan sesuatu dengan file yang masuk secara imperatif. Di sinilah launchQueue berperan. Untuk mengakses file yang diluncurkan, situs harus menentukan konsumen untuk objek window.launchQueue. Peluncuran diantrekan sampai ditangani oleh konsumen yang ditentukan, yang dipanggil tepat satu kali untuk setiap peluncuran. Dengan cara ini, setiap peluncuran akan ditangani, terlepas dari kapan konsumen ditentukan.

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

Dukungan DevTools

Tidak ada dukungan DevTools pada saat penulisan ini, tetapi saya telah mengajukan permintaan fitur agar dukungan ditambahkan.

Demo

Saya telah menambahkan dukungan penanganan file ke Excalidraw, aplikasi gambar bergaya kartun. Untuk mengujinya, Anda harus menginstal Excalidraw terlebih dahulu. Saat Anda membuat file dengannya dan menyimpannya di suatu tempat di sistem file, Anda dapat membuka file tersebut dengan mengklik dua kali, atau mengklik kanan, lalu memilih "Excalidraw" di menu konteks. Anda dapat melihat penerapan dalam kode sumber.

Jendela pencari macOS dengan file Excalidraw.
Klik dua kali atau klik kanan file di file explorer sistem operasi Anda.
Menu konteks yang muncul saat mengklik kanan file dengan item Open with... Excalidraw ditandai.
Excalidraw adalah pengendali file default untuk file .excalidraw.

Keamanan

Tim Chrome telah mendesain dan menerapkan File Handling API menggunakan prinsip inti yang ditentukan dalam Mengontrol Akses ke Fitur Platform Web yang Efisien, termasuk kontrol pengguna, transparansi, dan ergonomi.

Izin, persistensi izin, dan pembaruan pengendali file

Untuk memastikan kepercayaan pengguna dan keamanan file pengguna, saat File Handling API membuka file, permintaan izin akan ditampilkan sebelum PWA dapat melihat file. Permintaan izin ini akan ditampilkan tepat setelah pengguna memilih PWA untuk membuka file, sehingga izin terikat erat dengan tindakan membuka file menggunakan PWA, sehingga lebih mudah dipahami dan relevan.

Izin ini akan ditampilkan setiap kali hingga pengguna mengklik Izinkan atau Blokir penanganan file untuk situs, atau mengabaikan perintah tiga kali (setelah itu Chromium akan melakukan embargo dan memblokir izin ini). Setelan yang dipilih akan tetap ada di seluruh PWA yang ditutup dan dibuka kembali.

Saat manifes diperbarui dan perubahan di bagian "file_handlers" terdeteksi, izin akan direset.

Ada kategori besar vektor serangan yang dibuka dengan mengizinkan {i>website<i} mengakses file. Hal ini diuraikan dalam artikel tentang File System Access API. Kemampuan tambahan terkait keamanan yang disediakan File Handling API melalui File System Access API adalah kemampuan untuk memberikan akses ke file tertentu melalui UI bawaan sistem operasi, bukan melalui pemilih file yang ditampilkan oleh aplikasi web.

Masih ada risiko bahwa pengguna dapat secara tidak sengaja memberikan akses aplikasi web ke file dengan membukanya. Namun, umumnya dipahami bahwa membuka file memungkinkan aplikasi yang membuka file tersebut untuk membaca dan/atau memanipulasi file tersebut. Oleh karena itu, pilihan eksplisit pengguna untuk membuka file di aplikasi yang diinstal, seperti melalui menu konteks "Buka dengan…", dapat dibaca sebagai sinyal kepercayaan yang memadai dalam aplikasi.

Tantangan pengendali default

Pengecualian untuk hal ini adalah ketika tidak ada aplikasi pada sistem {i>host<i} untuk jenis file tertentu. Dalam hal ini, beberapa sistem operasi host dapat otomatis mempromosikan pengendali yang baru terdaftar ke pengendali default untuk jenis file tersebut secara diam-diam dan tanpa intervensi apa pun oleh pengguna. Artinya, jika pengguna mengklik dua kali file jenis tersebut, file akan otomatis terbuka di aplikasi web terdaftar. Pada sistem operasi host tersebut, saat agen pengguna menentukan bahwa tidak ada pengendali default untuk jenis file, perintah izin eksplisit mungkin diperlukan untuk menghindari pengiriman konten file secara tidak sengaja ke aplikasi web tanpa izin pengguna.

Kontrol pengguna

Spesifikasi menyatakan bahwa browser tidak boleh mendaftarkan setiap situs yang dapat menangani file sebagai pengendali file. Sebagai gantinya, pendaftaran penanganan file harus dibatasi di belakang penginstalan dan jangan pernah terjadi tanpa konfirmasi pengguna secara eksplisit, terutama jika suatu situs akan menjadi pengendali default. Daripada membajak ekstensi yang sudah ada seperti .json yang mungkin sudah memiliki pengendali default yang terdaftar, situs sebaiknya mempertimbangkan untuk membuat ekstensinya sendiri.

Transparansi

Semua sistem operasi memungkinkan pengguna mengubah pengaitan file saat ini. Hal ini berada di luar cakupan browser.

Masukan

Tim Chrome ingin mengetahui pengalaman Anda saat menggunakan File Handling API.

Ceritakan kepada kami tentang desain API

Apakah ada sesuatu tentang API yang tidak berfungsi seperti yang Anda harapkan? Atau apakah ada metode atau properti yang tidak ada yang Anda perlukan untuk menerapkan ide Anda? Ada pertanyaan atau komentar tentang model keamanan?

  • Ajukan masalah spesifikasi di repo GitHub yang sesuai, atau tambahkan pendapat Anda ke masalah yang sudah ada.

Melaporkan masalah terkait penerapan

Apakah Anda menemukan bug pada penerapan Chrome? Atau apakah implementasinya berbeda dengan spesifikasi?

  • Laporkan bug di new.crbug.com. Pastikan untuk menyertakan detail sebanyak mungkin, petunjuk sederhana untuk mereproduksi, dan masukkan UI>Browser>WebAppInstalls>FileHandling di kotak Components. Glitch sangat cocok untuk membagikan reproduksi yang cepat dan mudah.

Menampilkan dukungan untuk API

Anda berencana menggunakan File Handling API? Dukungan publik Anda membantu tim Chrome untuk memprioritaskan fitur dan menunjukkan kepada vendor browser lain betapa pentingnya mendukung fitur tersebut.

Link bermanfaat

Ucapan terima kasih

File Handling API ditentukan oleh Eric Willigers, Jay Harris, dan Raymes Khoury. Artikel ini ditinjau oleh Joe Medley.