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
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 ikonImageResource
. 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, arrayLaunchParams.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.
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.
Tantangan terkait file
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.
- Bagikan rencana Anda untuk menggunakannya di thread Discourse WICG.
- Kirim tweet ke @ChromiumDev menggunakan hashtag
#FileHandling
dan beri tahu kami tempat dan cara Anda menggunakannya.
Link bermanfaat
- Penjelasan publik
- Demo File Handling API | Sumber demo File Handling API
- Bug pelacakan Chromium
- Entri ChromeStatus.com
- Komponen Blink:
UI>Browser>WebAppInstalls>FileHandling
- Peninjauan TAG
- Posisi Standar Mozilla
Ucapan terima kasih
File Handling API ditentukan oleh Eric Willigers, Jay Harris, dan Raymes Khoury. Artikel ini ditinjau oleh Joe Medley.