Halaman ini diterjemahkan oleh Cloud Translation API.

Membaca dan menulis file serta direktori dengan library browser-fs-access

Thomas Steiner

Browser telah dapat menangani file dan direktori sejak lama. File API menyediakan fitur untuk merepresentasikan objek file dalam aplikasi web, serta memilihnya secara terprogram dan mengakses datanya. Namun, saat Anda melihat lebih dekat, ternyata tidak semua yang berkilau itu emas.

Cara tradisional untuk menangani file

Membuka file

Sebagai developer, Anda dapat membuka dan membaca file melalui elemen <input type="file">. Dalam bentuk yang paling sederhana, membuka file dapat terlihat seperti contoh kode di bawah. Objek input memberi Anda FileList, yang dalam kasus di bawah ini hanya terdiri dari satu File. File adalah jenis Blob tertentu, dan dapat digunakan dalam konteks apa pun yang dapat digunakan Blob.

const openFile = async () => {
  return new Promise((resolve) => {
    const input = document.createElement('input');
    input.type = 'file';
    input.addEventListener('change', () => {
      resolve(input.files[0]);
    });
    input.click();
  });
};

Membuka direktori

Untuk membuka folder (atau direktori), Anda dapat menetapkan atribut <input webkitdirectory>. Selain itu, semuanya berfungsi sama seperti di atas. Meskipun namanya diawali dengan awalan vendor, webkitdirectory tidak hanya dapat digunakan di browser Chromium dan WebKit, tetapi juga di Edge berbasis EdgeHTML lama serta di Firefox.

Menyimpan (atau: mendownload) file

Untuk menyimpan file, secara tradisional, Anda dibatasi untuk mendownload file, yang berfungsi berkat atribut <a download>. Dengan Blob, Anda dapat menetapkan atribut href anchor ke URL blob: yang dapat Anda dapatkan dari metode URL.createObjectURL().

const saveFile = async (blob) => {
  const a = document.createElement('a');
  a.download = 'my-file.txt';
  a.href = URL.createObjectURL(blob);
  a.addEventListener('click', (e) => {
    setTimeout(() => URL.revokeObjectURL(a.href), 30 * 1000);
  });
  a.click();
};

Permasalahan

Kelemahan besar dari pendekatan download adalah tidak ada cara untuk membuat alur klasik buka→edit→simpan terjadi, yaitu, tidak ada cara untuk menulis ulang file asli. Sebagai gantinya, Anda akan mendapatkan salinan baru dari file asli di folder Download default sistem operasi setiap kali Anda "menyimpan".

File System Access API

File System Access API membuat kedua operasi, membuka dan menyimpan, menjadi jauh lebih sederhana. Hal ini juga memungkinkan penyimpanan sebenarnya, yaitu Anda tidak hanya dapat memilih tempat untuk menyimpan file, tetapi juga menimpa file yang ada.

Membuka file

Dengan File System Access API, membuka file hanya memerlukan satu panggilan ke metode window.showOpenFilePicker(). Panggilan ini menampilkan handle file, tempat Anda bisa mendapatkan File yang sebenarnya melalui metode getFile().

const openFile = async () => {
  try {
    // Always returns an array.
    const [handle] = await window.showOpenFilePicker();
    return handle.getFile();
  } catch (err) {
    console.error(err.name, err.message);
  }
};

Membuka direktori

Buka direktori dengan memanggil window.showDirectoryPicker() yang membuat direktori dapat dipilih di kotak dialog file.

Menyimpan file

Menyimpan file juga sama mudahnya. Dari handle file, Anda membuat aliran yang dapat ditulis melalui createWritable(), lalu menulis data Blob dengan memanggil metode write() aliran, dan terakhir Anda menutup aliran dengan memanggil metode close()-nya.

const saveFile = async (blob) => {
  try {
    const handle = await window.showSaveFilePicker({
      types: [{
        accept: {
          // Omitted
        },
      }],
    });
    const writable = await handle.createWritable();
    await writable.write(blob);
    await writable.close();
    return handle;
  } catch (err) {
    console.error(err.name, err.message);
  }
};

Memperkenalkan browser-fs-access

Meskipun File System Access API sudah sangat baik, API ini belum tersedia secara luas.

Tabel dukungan browser untuk File System Access API. Semua browser ditandai sebagai 'tidak ada dukungan' atau 'di belakang tanda'. — Tabel dukungan browser untuk File System Access API. (Sumber)

Itulah sebabnya saya melihat File System Access API sebagai progressive enhancement. Oleh karena itu, saya ingin menggunakannya jika browser mendukungnya, dan menggunakan pendekatan tradisional jika tidak; sambil tidak pernah menghukum pengguna dengan download kode JavaScript yang tidak didukung yang tidak perlu. Library browser-fs-access adalah jawaban saya untuk tantangan ini.

Filosofi desain

Karena File System Access API masih mungkin berubah di masa mendatang, browser-fs-access API tidak dimodelkan setelahnya. Artinya, library ini bukan polyfill, tetapi ponyfill. Anda dapat (secara statis atau dinamis) mengimpor secara eksklusif fungsi apa pun yang diperlukan agar aplikasi Anda tetap sekecil mungkin. Metode yang tersedia adalah metode yang diberi nama tepat fileOpen(), directoryOpen(), dan fileSave(). Secara internal, fitur library mendeteksi apakah File System Access API didukung, lalu mengimpor jalur kode yang sesuai.

Menggunakan library browser-fs-access

Ketiga metode tersebut intuitif untuk digunakan. Anda dapat menentukan mimeTypes atau file extensions yang diterima aplikasi, dan menetapkan tanda multiple untuk mengizinkan atau melarang pemilihan beberapa file atau direktori. Untuk mengetahui detail selengkapnya, lihat dokumentasi browser-fs-access API. Contoh kode di bawah menunjukkan cara membuka dan menyimpan file gambar.

// The imported methods will use the File
// System Access API or a fallback implementation.
import {
  fileOpen,
  directoryOpen,
  fileSave,
} from 'https://unpkg.com/browser-fs-access';

(async () => {
  // Open an image file.
  const blob = await fileOpen({
    mimeTypes: ['image/*'],
  });

  // Open multiple image files.
  const blobs = await fileOpen({
    mimeTypes: ['image/*'],
    multiple: true,
  });

  // Open all files in a directory,
  // recursively including subdirectories.
  const blobsInDirectory = await directoryOpen({
    recursive: true
  });

  // Save a file.
  await fileSave(blob, {
    fileName: 'Untitled.png',
  });
})();

Demo

Anda dapat melihat cara kerja kode di atas dalam demo di Glitch. Kode sumber-nya juga tersedia di sana. Karena alasan keamanan, subframe lintas origin tidak diizinkan untuk menampilkan pemilih file, demo tidak dapat disematkan dalam artikel ini.

Library browser-fs-access di dunia nyata

Di waktu luang, saya berkontribusi sedikit pada PWA yang dapat diinstal yang disebut Excalidraw, alat papan tulis virtual yang memungkinkan Anda membuat sketsa diagram dengan mudah dengan nuansa gambar tangan. Aplikasi ini sepenuhnya responsif dan berfungsi dengan baik di berbagai perangkat, mulai dari ponsel kecil hingga komputer dengan layar besar. Artinya, aplikasi harus menangani file di berbagai platform baik yang mendukung File System Access API maupun yang tidak. Hal ini menjadikannya kandidat yang tepat untuk library browser-fs-access.

Misalnya, saya dapat memulai gambar di iPhone, menyimpannya (secara teknis: mendownloadnya, karena Safari tidak mendukung File System Access API) ke folder Download iPhone, membuka file di desktop (setelah mentransfernya dari ponsel), mengubah file, dan menimpanya dengan perubahan saya, atau bahkan menyimpannya sebagai file baru.

Gambar Excalidraw di iPhone. — Memulai gambar Excalidraw di iPhone tempat File System Access API tidak didukung, tetapi file dapat disimpan (didownload) ke folder Download.

Gambar Excalidraw yang diubah di Chrome pada desktop. — Membuka dan mengubah gambar Excalidraw di desktop tempat File System Access API didukung sehingga file dapat diakses melalui API.

Mengganti file asli dengan modifikasi. — Menimpa file asli dengan modifikasi pada file gambar Excalidraw asli. Browser menampilkan dialog yang menanyakan apakah saya setuju.

Menyimpan perubahan ke file gambar Excalidraw baru. — Menyimpan modifikasi ke file Excalidraw baru. File asli tetap tidak tersentuh.

Contoh kode dunia nyata

Di bawah ini, Anda dapat melihat contoh browser-fs-access yang sebenarnya seperti yang digunakan di Excalidraw. Cuplikan ini diambil dari /src/data/json.ts. Yang menarik secara khusus adalah cara metode saveAsJSON() meneruskan handle file atau null ke metode browser-fs-access' fileSave(), yang menyebabkannya ditimpa saat handle diberikan, atau disimpan ke file baru jika tidak.

export const saveAsJSON = async (
  elements: readonly ExcalidrawElement[],
  appState: AppState,
  fileHandle: any,
) => {
  const serialized = serializeAsJSON(elements, appState);
  const blob = new Blob([serialized], {
    type: "application/json",
  });
  const name = `${appState.name}.excalidraw`;
  (window as any).handle = await fileSave(
    blob,
    {
      fileName: name,
      description: "Excalidraw file",
      extensions: ["excalidraw"],
    },
    fileHandle || null,
  );
};

export const loadFromJSON = async () => {
  const blob = await fileOpen({
    description: "Excalidraw files",
    extensions: ["json", "excalidraw"],
    mimeTypes: ["application/json"],
  });
  return loadFromBlob(blob);
};

Pertimbangan UI

Baik di Excalidraw maupun aplikasi Anda, UI harus beradaptasi dengan situasi dukungan browser. Jika File System Access API didukung (if ('showOpenFilePicker' in window) {}), Anda dapat menampilkan tombol Save As selain tombol Save. Screenshot di bawah menunjukkan perbedaan antara toolbar aplikasi utama responsif Excalidraw di iPhone dan di desktop Chrome. Perhatikan bahwa di iPhone, tombol Save As tidak ada.

Toolbar aplikasi Excalidraw di iPhone hanya dengan tombol 'Save'. — Toolbar aplikasi Exaclidraw di iPhone hanya dengan tombol **Simpan**.

Toolbar aplikasi Excalidraw di desktop Chrome dengan tombol 'Simpan' dan 'Simpan Sebagai'. — Toolbar aplikasi Exaclidraw di Chrome dengan tombol **Save** dan **Save As** yang difokuskan.

Kesimpulan

Secara teknis, bekerja dengan file sistem berfungsi di semua browser modern. Di browser yang mendukung File System Access API, Anda dapat meningkatkan pengalaman dengan mengizinkan penyimpanan dan penggantian file yang sebenarnya (bukan hanya mendownload) dan dengan mengizinkan pengguna membuat file baru di mana pun mereka mau, sambil tetap berfungsi di browser yang tidak mendukung File System Access API. browser-fs-access mempermudah Anda dengan menangani detail progressive enhancement dan membuat kode Anda sesederhana mungkin.

Ucapan terima kasih

Artikel ini ditinjau oleh Joe Medley dan Kayce Basques. Terima kasih kepada kontributor Excalidraw atas pekerjaan mereka dalam project ini dan telah meninjau Pull Request saya. Banner besar oleh Ilya Pavlov di Unsplash.