Mengizinkan aplikasi web terinstal menjadi pengendali file

Mendaftarkan aplikasi sebagai pengendali file dengan sistem operasi.

Thomas Steiner

Sekarang, karena aplikasi web dapat membaca dan menulis file, langkah logis berikutnya adalah mengizinkan developer mendeklarasikan aplikasi web ini sebagai handler 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 handler file dan setelah menginstalnya, Anda dapat mengklik kanan file .txt di macOS dan memilih "Dapatkan Info" untuk 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 Office seperti editor teks, aplikasi spreadsheet, dan pembuat slide.
Editor grafis dan alat gambar.
Alat editor level video game.

Cara menggunakan File Handling API

{i>Progressive enhancement <i}

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

Web Share Target API memungkinkan developer menetapkan aplikasi mereka sebagai target berbagi sehingga file dapat dibuka dari panel 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 dibuka.

Dukungan browser

Browser Support

Source

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 File Handling API

Sebagai langkah pertama, aplikasi web perlu menjelaskan secara deklaratif dalam manifes aplikasi web jenis file yang dapat ditanganinya. File Handling API memperluas manifes aplikasi web dengan properti baru bernama "file_handlers" yang menerima array, yaitu, handler file. Handler file adalah objek dengan properti berikut:

Properti "action" yang menunjuk 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 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 di beberapa klien. Defaultnya adalah "single-client". Jika pengguna membuka beberapa file dan pengendali file telah diberi anotasi dengan "multiple-clients" sebagai "launch_type"-nya, lebih dari satu peluncuran aplikasi akan terjadi, dan untuk setiap peluncuran, array LaunchParams.files (lihat lebih lanjut 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 hipotetis yang menangani file nilai yang dipisahkan koma (.csv) di /open-csv, file grafik vektor yang dapat diskalakan (.svg) di /open-svg, dan format file Grafr fiktif 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

Sekarang setelah aplikasi mendeklarasikan file yang dapat ditanganinya di URL dalam cakupan mana secara teoretis, aplikasi perlu melakukan sesuatu secara imperatif dengan file yang masuk dalam praktiknya. Di sinilah launchQueue berperan. Untuk mengakses file yang diluncurkan, situs harus menentukan konsumen untuk objek window.launchQueue. Peluncuran diantrekan hingga ditangani oleh konsumen yang ditentukan, yang dipanggil tepat satu kali untuk setiap peluncuran. Dengan cara ini, setiap peluncuran 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

Saat penulisan ini, tidak ada dukungan DevTools, tetapi saya telah mengajukan permintaan fitur agar dukungan ditambahkan.

Demo

Saya telah menambahkan dukungan penanganan file ke Excalidraw, aplikasi menggambar gaya 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 dengan mengklik dua kali, atau mengklik kanan lalu memilih "Excalidraw" di menu konteks. Anda dapat melihat penerapan di kode sumber.

Jendela finder 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 Buka dengan… Excalidraw ditandai. — Excalidraw adalah handler 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 Canggih, termasuk kontrol pengguna, transparansi, dan ergonomi.

Izin, persistensi izin, dan pembaruan handler file

Untuk memastikan kepercayaan pengguna dan keamanan file pengguna, saat File Handling API membuka file, perintah izin akan ditampilkan sebelum PWA dapat melihat file. Dialog izin ini akan ditampilkan tepat setelah pengguna memilih PWA untuk membuka file, sehingga izin tersebut terkait 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 melarang dan memblokir izin ini). Setelan yang dipilih akan tetap ada saat PWA ditutup dan dibuka kembali.

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

Tantangan terkait file

Ada kategori besar vektor serangan yang terbuka dengan mengizinkan situs mengakses file. Hal ini diuraikan dalam artikel tentang File System Access API. Kemampuan tambahan yang relevan dengan keamanan yang disediakan File Handling API dibandingkan 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 digunakan untuk membukanya 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 terhadap aplikasi tersebut.

Masalah pengendali default

Pengecualian untuk hal ini adalah jika tidak ada aplikasi di sistem host untuk jenis file tertentu. Dalam kasus ini, beberapa sistem operasi host dapat secara otomatis mempromosikan handler yang baru terdaftar menjadi handler default untuk jenis file tersebut secara diam-diam dan tanpa intervensi apa pun dari pengguna. Artinya, jika pengguna mengklik dua kali file jenis tersebut, file akan otomatis terbuka di aplikasi web yang terdaftar. Pada sistem operasi host tersebut, saat agen pengguna menentukan bahwa tidak ada pengendali default yang ada 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 balik penginstalan dan tidak pernah terjadi tanpa konfirmasi eksplisit dari pengguna, terutama jika situs akan menjadi pengendali default. Daripada membajak ekstensi yang ada seperti .json yang mungkin sudah memiliki handler default yang terdaftar untuk pengguna, situs harus mempertimbangkan untuk membuat ekstensi sendiri.

Transparansi

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

Masukan

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

Beri tahu 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 dan perlu Anda terapkan untuk mewujudkan ide Anda? Ada pertanyaan atau komentar tentang model keamanan?

Laporkan masalah spesifikasi di repo GitHub yang sesuai, atau tambahkan pendapat Anda ke masalah yang 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 Komponen.

Menunjukkan dukungan untuk API

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

Bagikan rencana penggunaan Anda di thread WICG Discourse.
Kirim tweet ke @ChromiumDev menggunakan hashtag #FileHandling dan beri tahu kami di mana dan bagaimana Anda menggunakannya.

Link bermanfaat

Ucapan terima kasih

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