Langsung ke konten utama

Panduan Penanganan File Capacitor: Baca, Tulis, Pilih, Bagikan

Panduan penanganan file Capacitor: baca dan tulis file, pilih direktori, pilih, tampilkan, buka, bagikan, unduh, dan unggah file di iOS dan Android.

Membaca, menulis, dan berbagi file di aplikasi mobile Capacitor

Penanganan file Capacitor bergantung pada beberapa blok bangunan: @capacitor/filesystem untuk membaca dan menulis file di direktori aplikasi, Capacitor.convertFileSrc untuk menampilkannya, picker untuk mengimpor file pengguna, dan plugin native untuk download, upload, membuka, dan berbagi. Panduan ini menunjukkan masing-masing dengan Capacitor 8 code, menjelaskan direktori mana yang harus digunakan di iOS dan Android, serta membahas jebakan memori dan izin yang menyebabkan sebagian besar bug file.

Kotak perkakas penanganan file

Tugas Plugin
Baca, tulis, daftar, salin, hapus di penyimpanan aplikasi @capacitor/filesystem
Tampilkan file lokal di <img>, <video>, <iframe> Capacitor.convertFileSrc (inti)
Biarkan pengguna memilih file atau folder @capgo/capacitor-file-picker
Download dengan progres @capacitor/file-transfer atau @capgo/capacitor-downloader untuk download latar belakang yang bisa dijeda
Upload dengan progres @capacitor/file-transfer atau @capgo/capacitor-uploader untuk upload di background
Bagikan file atau simpan ke Downloads @capgo/capacitor-file-sharer atau @capacitor/share
Buka file di aplikasi lain @capacitor-community/file-opener
Kompres gambar @capgo/capacitor-file-compressor
Zip dan unzip @capgo/capacitor-zip

Install plugin core terlebih dahulu:

bun add @capacitor/filesystem
bunx cap sync

Pilih direktori yang tepat

Setiap panggilan Filesystem memerlukan directory. Memilih yang salah adalah penyebab paling umum file hilang dan aplikasi ditolak.

Directory Lokasi iOS Lokasi Android Backed up Gunakan untuk
Data Documents Dir file aplikasi (/data/data/<pkg>/files) iCloud iOS, Auto Backup Android Data pengguna yang dimiliki aplikasi
Documents Documents (sama dengan Data) Publik Documents folder Ya Hindari di Android 11+, lihat di bawah
Library Library Dir file aplikasi iOS ya File dukungan aplikasi, database
LibraryNoCloud Library/NoCloud Dir file aplikasi Tidak Konten besar, dapat diunduh ulang
Cache Library/Caches Dir cache aplikasi Tidak File sementara, dapat dihapus oleh OS
External Documents Dir file eksternal aplikasi Tidak File aplikasi besar di Android, dihapus saat uninstall
ExternalStorage Documents Akar penyimpanan bersama n/a Hanya legacy, tidak dapat diakses di Android 11+

Aturan praktis:

  • Media besar yang bisa diunduh ulang (video offline, tile peta) disimpan di LibraryNoCloud. Apple menolak aplikasi yang menyimpan konten besar yang bisa diunduh ulang di folder berbasis iCloud, sebagaimana dijelaskan dalam Panduan Penyimpanan Data iOS-nya.
  • File sementara (ekspor yang dibagikan sekali, thumbnail) disimpan di Cache. Jangan simpan satu-satunya salinan data pengguna di sana.
  • File yang harus ditemukan pengguna kemudian di luar aplikasi Anda tidak boleh disimpan di direktori aplikasi sama sekali. Simpan melalui share sheet, MediaStore Downloads, atau file picker sistem. Lihat panduan kami tentang scoped storage Android di Capacitor.

Menulis file

import { Filesystem, Directory, Encoding } from '@capacitor/filesystem';

// Text file
await Filesystem.writeFile({
  path: 'notes/today.txt',
  data: 'Hello from Capacitor',
  directory: Directory.Data,
  encoding: Encoding.UTF8,
  recursive: true, // create notes/ if missing
});

// JSON
await Filesystem.writeFile({
  path: 'settings.json',
  data: JSON.stringify({ theme: 'dark' }),
  directory: Directory.Data,
  encoding: Encoding.UTF8,
});

// Binary file: pass base64 and no encoding
await Filesystem.writeFile({
  path: 'images/logo.png',
  data: base64Png,
  directory: Directory.Data,
  recursive: true,
});

Panduan encoding opsi menentukan bagaimana data diinterpretasikan. Dengan Encoding.UTF8, string ditulis sebagai teks. Tanpa itu, platform native men-decode data sebagai base64 dan menulis byte mentah. Lupa hal ini adalah bug klasik “PDF saya corrupt”.

Untuk menambahkan ke file yang sudah ada, seperti log, gunakan appendFile dengan opsi yang sama.

Membaca file

const { data } = await Filesystem.readFile({
  path: 'settings.json',
  directory: Directory.Data,
  encoding: Encoding.UTF8,
});
const settings = JSON.parse(data as string);

// Binary: returns base64 on native, a Blob on web
const image = await Filesystem.readFile({
  path: 'images/logo.png',
  directory: Directory.Data,
});

Cek apakah file ada dengan stat, yang akan menolak jika file tidak ditemukan:

async function exists(path: string) {
  try {
    await Filesystem.stat({ path, directory: Directory.Data });
    return true;
  } catch {
    return false;
  }
}

Baca file besar dalam chunk

readFile mengembalikan seluruh file sebagai satu string base64. Untuk video berukuran 200 MB, ini berarti penggunaan memori JS sebesar ratusan MB untuk string tersebut. readFileInChunks gunakan stream sebagai gantinya:

await Filesystem.readFileInChunks(
  { path: 'videos/clip.mp4', directory: Directory.Data, chunkSize: 1024 * 1024 },
  (chunk, err) => {
    if (err) return console.error(err);
    if (chunk === null) return console.log('done');
    processChunk(chunk.data); // base64 chunk
  },
);

Lebih baik lagi, hindari memindahkan byte melalui JS sama sekali. Kebanyakan tugas "baca file besar" sebenarnya adalah "upload" atau "tampilkan", dan keduanya punya jalur native di bawah ini.

Daftar, salin, pindah, dan hapus

const { files } = await Filesystem.readdir({ path: 'notes', directory: Directory.Data });
for (const f of files) console.log(f.name, f.type, f.size, f.mtime);

await Filesystem.mkdir({ path: 'archive', directory: Directory.Data, recursive: true });

await Filesystem.copy({
  from: 'notes/today.txt',
  to: 'archive/today.txt',
  directory: Directory.Data,
});

await Filesystem.rename({
  from: 'archive/today.txt',
  to: 'archive/2026-10-01.txt',
  directory: Directory.Data,
});

await Filesystem.deleteFile({ path: 'notes/today.txt', directory: Directory.Data });
await Filesystem.rmdir({ path: 'notes', directory: Directory.Data, recursive: true });

copy dan rename menerima toDirectory untuk pindah antar direktori, contohnya dari Cache ke Data setelah download selesai. Keduanya juga menerima file:// path absolut saat Anda tidak mengisinya directory, yang merupakan cara mengimpor file yang dikembalikan plugin lain.

Tampilkan file di WebView

Jangan pernah memuat gambar atau video sebagai base64 data URL jika bisa dihindari. Konversi path native menjadi URL yang disajikan server lokal Capacitor:

import { Capacitor } from '@capacitor/core';

const { uri } = await Filesystem.getUri({ path: 'images/logo.png', directory: Directory.Data });
img.src = Capacitor.convertFileSrc(uri);

Di iOS, hasilnya terlihat seperti capacitor://localhost/_capacitor_file_/..., di Android https://localhost/_capacitor_file_/.... Ini berfungsi untuk <img>, <video>, <audio>, dan fetch(), yang berarti Anda juga bisa membaca file sebagai ArrayBuffer tanpa base64:

const buffer = await fetch(Capacitor.convertFileSrc(uri)).then((r) => r.arrayBuffer());

Simpan path, bukan URL yang sudah dikonversi. Bentuk konversi hanya valid untuk sesi aplikasi saat ini.

Pilih file dari perangkat

System picker memberi pengguna kontrol dan tidak memerlukan izin penyimpanan di Android 13+ atau iOS:

bun add @capgo/capacitor-file-picker
bunx cap sync
import { CapgoFilePicker } from '@capgo/capacitor-file-picker';

const { files } = await CapgoFilePicker.pickFiles({
  types: ['application/pdf', 'image/*'],
  limit: 5,
  readData: false, // keep false for anything bigger than a few MB
});

for (const file of files) {
  console.log(file.name, file.mimeType, file.size, file.path);
}

There are also pickImages, pickVideos, pickMedia dan pickDirectory, serta convertHeicToJpeg di iOS. Di iOS, types hanya menerima tipe MIME, bukan ekstensi.

File yang dipilih mungkin berada di lokasi sementara atau di balik content:// URI yang hanya bisa dibaca untuk sementara. Jika Anda butuh file tersebut nanti, salin ke direktori Anda sendiri segera dengan Filesystem.copy.

Unduh file

Dengan progres: @capacitor/file-transfer

Filesystem.downloadFile tidak didukung lagi di Filesystem 8. Penggantinya mengalirkan respons langsung ke disk:

bun add @capacitor/file-transfer
bunx cap sync
import { FileTransfer } from '@capacitor/file-transfer';
import { Directory, Filesystem } from '@capacitor/filesystem';

const { uri } = await Filesystem.getUri({ path: 'downloads/report.pdf', directory: Directory.Data });

const listener = await FileTransfer.addListener('progress', (p) => {
  if (p.lengthComputable) setProgress(p.bytes / p.contentLength);
});

await FileTransfer.downloadFile({
  url: 'https://example.com/report.pdf',
  path: uri,
  progress: true,
  headers: { Authorization: `Bearer ${token}` },
});

await listener.remove();

Di latar belakang: @capgo/capacitor-downloader

Untuk file besar yang harus terus diunduh saat pengguna keluar dari aplikasi, dan yang bisa dijeda serta dilanjutkan, gunakan downloader Capgo, yang bergantung pada DownloadManager di Android dan background URLSession di iOS:

import { CapacitorDownloader } from '@capgo/capacitor-downloader';

await CapacitorDownloader.addListener('downloadProgress', ({ id, progress }) => {
  console.log(id, progress);
});
await CapacitorDownloader.addListener('downloadCompleted', ({ id }) => {
  console.log('done', id);
});

await CapacitorDownloader.download({
  id: 'course-video-12',
  url: 'https://cdn.example.com/course/12.mp4',
  destination: 'videos/12.mp4',
  network: 'wifi-only',
  notification: 'progress', // Android
});

Path relatif destination mengarah ke direktori file eksternal aplikasi di Android dan Documents direktori di iOS, lokasi yang sama dengan Directory.External.

Upload file

Jangan membaca file ke base64 hanya untuk mengirimnya. Kedua opsi upload membaca langsung dari disk secara native:

import { FileTransfer } from '@capacitor/file-transfer';

const result = await FileTransfer.uploadFile({
  url: 'https://api.example.com/upload',
  path: uri,          // full file:// path
  fileKey: 'file',
  mimeType: 'application/pdf',
  headers: { Authorization: `Bearer ${token}` },
  progress: true,
});
console.log(result.responseCode, result.bytesSent);

Untuk upload yang harus tetap berjalan saat aplikasi masuk ke background (video, batch upload foto), gunakan @capgo/capacitor-uploader, yang berjalan di background URLSession pada iOS dan layanan upload dengan notifikasi progres di Android:

import { Uploader } from '@capgo/capacitor-uploader';

const { id } = await Uploader.startUpload({
  filePath: uri,
  serverUrl: 'https://api.example.com/upload',
  method: 'PUT', // binary body, ideal for presigned S3 or R2 URLs
  mimeType: 'video/mp4',
});

Presigned PUT URL ke object storage adalah pola paling andal untuk file besar: API Anda menandatangani URL tersebut, dan perangkat langsung upload ke storage.

Bagikan atau ekspor file

Agar pengguna bisa mengirim file ke aplikasi lain atau menyimpannya di tempat yang mudah ditemukan:

import { FileSharer } from '@capgo/capacitor-file-sharer';

await FileSharer.share({
  filename: 'report.pdf',
  path: uri,
  contentType: 'application/pdf',
});

// Android: write to Downloads via MediaStore. iOS: opens the share sheet ("Save to Files")
await FileSharer.save({
  filename: 'report.pdf',
  path: uri,
  contentType: 'application/pdf',
});

Capgo file sharer menyalin file ke folder cache sendiri dan menyajikannya melalui FileProvider, jadi Anda tidak perlu mengedit file_paths.xml. Dengan plugin resmi @capacitor/share, Android hanya bisa berbagi dari folder cache kecuali Anda menambahkan folder lain ke android/app/src/main/res/xml/file_paths.xml.

Buka file di aplikasi lain

bun add @capacitor-community/file-opener
bunx cap sync
import { FileOpener } from '@capacitor-community/file-opener';

await FileOpener.open({ filePath: uri, contentType: 'application/pdf' });

Di iOS, ini membuka pratinjau Quick Look. Di Android, ini membuka aplikasi default untuk MIME type atau menampilkan chooser. Jika tidak ada aplikasi yang bisa menangani tipe itu, pemanggilan akan reject, jadi tangkap error-nya dan tawarkan opsi berbagi sebagai gantinya.

Resep file umum

Generate PDF: render HTML dengan @capgo/capacitor-pdf-generator atau build di JS dengan pdf-lib, lalu tulis output base64 dengan writeFile. Kami tutorial scan ke PDF menunjukkan alur lengkapnya.

Hapus GPS dari foto sebelum upload: @capgo/capacitor-file-compressor menghapus metadata EXIF di semua platform saat resize.

Resize atau konversi gambar: kompresor yang sama menangani lebar, tinggi, kualitas, dan format output, termasuk HEIC ke JPEG.

Bundle banyak file: zip folder dengan @capgo/capacitor-zip dan upload satu arsip alih-alih ratusan request.

Dukungan Web

@capacitor/filesystem berjalan di web menggunakan IndexedDB, jadi code Anda berjalan di browser selama development. Perbedaan yang perlu diperhatikan: baca biner mengembalikan Blob, file hanya ada di profil browser, dan kuota penyimpanan jauh lebih rendah. Untuk build web, lebih baik gunakan URL.createObjectURL(blob) untuk tampilan.

Pemecahan Masalah

“File tidak ada”: Anda mencampur direktori, atau meneruskan path absolut bersama dengan directory. Gunakan salah satu saja.

File biner rusak: Anda menulis base64 dengan Encoding.UTF8. Hapus encoding-nya.

Aplikasi crash dengan file besar: base64 melalui bridge. Gunakan chunks, file-transfer, atau fetch(convertFileSrc(uri)).

Gambar tidak tampil di Android: Anda menggunakan file:// URL secara langsung. Konversi dengan Capacitor.convertFileSrc.

Failed to find configured root saat berbagi di Android: file berada di luar path dalam file_paths.xml. Gunakan Capgo file sharer atau salin ke Cache pertama.

File hilang di iOS: file tersebut ada di Cache, yang iOS bersihkan saat tekanan penyimpanan.

Penolakan App Store karena penyimpanan iCloud: konten unduhan besar di Data atau Documents. Pindahkan ke LibraryNoCloud.

Langkah berikutnya

Sebagian besar logika file, seperti tempat penyimpanan, aturan retry, dan penamaan, ada di JavaScript dan dapat disesuaikan dengan Live updates Capgo setelah rilis. Untuk sisi Android terkait penyimpanan bersama dan izin, lanjutkan dengan panduan scoped storage kami, dan lihat dokumentasi file picker untuk semua opsi picker.

Live updates untuk aplikasi Capacitor

Saat bug web-layer sudah live, kirim perbaikannya lewat Capgo alih-alih menunggu berhari-hari untuk persetujuan app store. Pengguna mendapat update di background, sementara perubahan native tetap mengikuti jalur review normal.

Terbaru dari Blog kami

Capgo memberikan insight terbaik yang Anda butuhkan untuk membuat aplikasi mobile yang benar-benar profesional.