Halaman ini diterjemahkan oleh Cloud Translation API.

Mengizinkan aplikasi web terinstal menjadi pengendali file

Mendaftarkan aplikasi sebagai pengendali file dengan sistem operasi.

Thomas Steiner

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 memberi tahu OS bahwa aplikasi harus selalu membuka file .txt dengan aplikasi ini sebagai default.

Kasus penggunaan yang disarankan untuk File Handling API

Contoh situs yang dapat menggunakan API ini antara lain:

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

Cara menggunakan File Handling API

{i>Progressive enhancement <i}

File Handling API per se 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 dibuka.

Dukungan browser

Dukungan Browser

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 harus menjelaskan secara deklaratif dalam manifes aplikasi web-nya jenis file yang dapat ditangani. File Handling API memperluas manifes aplikasi web dengan properti baru bernama "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 mengizinkan pengaitan jenis file untuk menampilkan ikon yang bukan hanya ikon aplikasi terkait, melainkan juga ikon khusus yang terkait dengan penggunaan jenis file tersebut dengan aplikasi.
Properti "launch_type" yang menentukan apakah beberapa file harus dibuka di satu klien atau di beberapa klien. Defaultnya adalah "single-client". Jika pengguna membuka beberapa file dan jika pengendali file telah dianotasi dengan "multiple-clients" sebagai "launch_type", akan terjadi lebih dari satu peluncuran aplikasi, dan untuk setiap peluncuran, array LaunchParams.files (lihat lebih lanjut ke bawah) hanya akan memiliki satu elemen.

Contoh di bawah, yang hanya menampilkan kutipan yang relevan dari manifes aplikasi web, 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 penting dari File Handling API

Setelah aplikasi mendeklarasikan file apa yang dapat ditangani pada URL dalam cakupan secara teori, aplikasi harus melakukan sesuatu dengan file masuk dalam praktiknya. Di sinilah launchQueue akan berperan. Untuk mengakses file yang diluncurkan, situs perlu 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 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

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

Demo

Saya telah menambahkan dukungan penanganan file ke Excalidraw, aplikasi menggambar bergaya kartun. Untuk mengujinya, Anda harus menginstal Excalidraw terlebih dahulu. Saat Anda kemudian membuat file dan menyimpannya di suatu tempat pada sistem file, Anda dapat membuka file dengan klik dua kali, atau klik kanan, lalu memilih "Excalidraw" di menu konteks. Anda dapat melihat implementasi 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 merancang dan menerapkan File Handling API menggunakan prinsip inti yang didefinisikan dalam Mengontrol Akses ke Fitur Platform Web yang Canggih, termasuk kontrol pengguna, transparansi, dan ergonomi.

Izin, persistensi izin, dan update 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 tersebut terkait erat dengan tindakan membuka file menggunakan PWA, sehingga lebih mudah dipahami dan relevan.

Izin ini akan ditampilkan setiap kali 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 saat PWA ditutup dan dibuka kembali.

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

Verifikasi login terkait file

Ada kategori besar vektor serangan yang terbuka dengan mengizinkan {i>website<i} mengakses file. Hal ini diuraikan dalam artikel tentang File System Access API. Kemampuan terkait keamanan tambahan 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, secara umum dipahami bahwa membuka file memungkinkan aplikasi membuka file untuk membaca dan/atau memanipulasi file tersebut. Oleh karena itu, pilihan eksplisit pengguna untuk membuka file dalam aplikasi yang diinstal, seperti melalui menu konteks "Buka dengan...", dapat dibaca sebagai sinyal kepercayaan yang memadai pada aplikasi.

Verifikasi pengendali default

Pengecualian untuk hal ini adalah bila tidak ada aplikasi pada sistem host untuk jenis file tertentu. Dalam hal ini, beberapa sistem operasi host dapat secara otomatis mempromosikan pengendali yang baru didaftarkan ke pengendali default untuk jenis file tersebut secara otomatis 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 untuk jenis file tersebut, prompt izin eksplisit mungkin diperlukan untuk menghindari pengiriman konten file secara tidak sengaja ke aplikasi web tanpa persetujuan pengguna.

Kontrol pengguna

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

Transparansi

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

Masukan

Tim Chrome ingin mengetahui 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 hilang yang Anda butuhkan untuk menerapkan ide Anda? Punya pertanyaan atau komentar tentang model keamanan?

Laporkan 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 implementasi Chrome? Atau apakah implementasinya berbeda dari spesifikasi?

Laporkan bug di new.crbug.com. Pastikan Anda menyertakan detail sebanyak mungkin, petunjuk sederhana untuk mereproduksi, dan masukkan UI>Browser>WebAppInstalls>FileHandling di kotak Components. Glitch berfungsi dengan baik untuk berbagi repro yang cepat dan mudah.

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 mendukung fitur tersebut.

Bagikan rencana Anda untuk menggunakannya di rangkaian pesan Discourse WiCG.
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.