Lewati ke konten utama

Pendahuluan

Unggah dan kelola file di penyimpanan cloud dengan optimisasi otomatis.

Informasi lebih lanjut tentang antarmuka pengguna modul ini https://doc.oneentry.cloud/docs/attributes/types/#File

🎯 Apa yang dilakukan modul ini?​

Modul FileUploading memungkinkan Anda untuk mengunggah, mengambil, dan menghapus file di penyimpanan cloud OneEntry - gambar, PDF, video, dokumen, jenis file apa pun - dengan optimisasi gambar otomatis dan pengiriman CDN.

Anggap saja ini sebagai manajer penyimpanan cloud Anda - Anda mengunggah file sekali, dan OneEntry menyimpannya, mengoptimalkan gambar secara otomatis, dan menyajikannya dengan cepat melalui CDN.

🚀 Memulai dengan Cepat​

Inisialisasi modul dari defineOneEntry:


const { FileUploading } = defineOneEntry(
  "your-project-url", {
    "token": "your-app-token"
  }
);

Unggah file dan baca tautan unduhan yang dikembalikan:

// upload() returns an ARRAY of uploaded files (IUploadingReturn[]).
const uploaded = await FileUploading.upload(file, {
  entity: "product",
  id: 123,
  type: "image",
  compress: true,
});

const { filename, downloadLink, size } = uploaded[0];
console.log(downloadLink); // use in <img>, <a>, <video>

Kemudian, hapus berdasarkan nama file (entitas/id menyelesaikan folder penyimpanan):

await FileUploading.delete(filename, { entity: "product", id: 123 });

✨ Konsep Utama​

Apa itu Pengunggahan File?​

Pengunggahan file adalah menyimpan file di penyimpanan cloud dan mendapatkan tautan CDN permanen kembali:

  • Unggah - kirim File atau Blob ke cloud OneEntry
  • Penyimpanan - file disimpan, diorganisir berdasarkan entity → id → filename
  • CDN - pengiriman cepat dari server yang dekat dengan pengguna
  • Optimisasi - gambar dapat dikompresi dan diubah ukurannya secara otomatis
  • URL - downloadLink dalam respons adalah tautan permanen

Jenis file yang didukung​

Jenis file apa pun diterima. Hanya gambar yang dioptimalkan secara otomatis; yang lainnya disimpan apa adanya.

KategoriJenis FileOptimisasi Otomatis
GambarJPG, PNG, GIF, WebP, SVGYa (ubah ukuran, kompres)
DokumenPDF, DOC, DOCX, XLS, XLSXTidak (disimpan apa adanya)
VideoMP4, MOV, AVI, WebMTidak (disimpan apa adanya)
ArsipZIP, RAR, TAR, GZTidak (disimpan apa adanya)
LainnyaJenis file apa punTidak (disimpan apa adanya)

📋 Apa yang Perlu Anda Ketahui​

Parameter Unggah​

upload(file, fileQuery?) mengambil file ditambah objek kueri opsional:

await FileUploading.upload(file, {
  entity: 'product',     // Storage folder name (optional, any string)
  id: 123,               // Entity ID (optional)
  type: 'image',         // Folder/type hint (optional, any string)
  width: 1920,           // Max width for images (optional)
  height: 1080,          // Max height for images (optional)
  compress: true,        // Compress images (optional)
});
  • file — File atau Blob yang akan diunggah (dari input atau drag-drop)
  • entity — nama folder bebas dalam penyimpanan (misalnya product, page, user, editor — contoh, bukan enum tetap)
  • id — ID entitas untuk mengaitkan file
  • type — string petunjuk folder/tipe bebas
  • width / height — dimensi maksimum untuk gambar (rasio aspek dipertahankan)
  • compress — aktifkan kompresi gambar

Respons Unggah​

upload() menghasilkan array dari IUploadingReturn. Setiap item memiliki:

{
  filename: "uploads/abc123-photo.jpg",      // Filename with relative path
  downloadLink: "https://cdn.../photo.jpg",  // CDN URL
  size: 204800,                              // File size in bytes
  contentType: "image/png",                  // MIME type
}
  • downloadLink — gunakan URL ini dalam tag <img>, <a>, <video>
  • filename — simpan untuk menghapus file nanti
  • size — ukuran file dalam byte

Optimisasi Gambar​

Untuk gambar, Anda dapat melewatkan width, height, dan compress. Rasio aspek selalu dipertahankan — gambar diubah ukurannya agar sesuai dalam batas yang diberikan, tidak pernah direnggangkan.

Menghapus File​

Kirim nama file terlebih dahulu; entitas/id/tipe berada di objek kueri opsional yang menyelesaikan folder penyimpanan:

await FileUploading.delete('abc123-photo.jpg', {
  entity: 'product',
  id: productId,
});

Mengambil File​

getFile(id, type, entity, filename, template?) mengembalikan objek Response mentah (tidak diparsing JSON) — panggil .blob(), .arrayBuffer(), dll. sesuai kebutuhan.

Membangun File dari URL​

createFileFromUrl(url, filename, mimeType?) mengambil sumber daya jarak jauh dan mengembalikan File browser, berguna untuk mengunggah kembali gambar jarak jauh yang sudah ada.

📊 Tabel Referensi Cepat - Metode​

MetodeApa yang DilakukanKapan Digunakan
upload()Unggah file ke penyimpanan cloudPengguna mengunggah gambar, dokumen
getFile()Ambil file (raw Response)Unduh file yang disimpan
delete()Hapus file dari penyimpananHapus file lama
createFileFromUrl()Bangun File dari URL jarak jauhImpor gambar jarak jauh sebelum diunggah

Semua metode bersifat publik — tidak memerlukan otorisasi pengguna.

❓ Pertanyaan Umum (FAQ)​

Jenis file apa yang bisa saya unggah?​

Jenis file apa pun. Hanya gambar yang dioptimalkan secara otomatis (ubah ukuran/kompres); file lainnya disimpan apa adanya.

Apa ukuran file maksimum?​

Tergantung pada batasan rencana OneEntry Anda. Optimalkan gambar sebelum diunggah untuk menjaga ukuran tetap rendah.

Apakah file disimpan secara permanen?​

Ya — file tetap ada sampai Anda menghapusnya dengan FileUploading.delete(). File tetap di penyimpanan bahkan jika entitas terkait dihapus, jadi bersihkan secara eksplisit.

Bisakah saya mendapatkan daftar semua file yang diunggah untuk suatu entitas?​

Tidak langsung melalui SDK ini. Lacak nilai filename yang Anda dapatkan dari upload() (misalnya simpan di database Anda) untuk mengelola file nanti.

Bisakah saya mengubah ukuran gambar ke dimensi yang tepat?​

Tidak — rasio aspek selalu dipertahankan. width/height mendefinisikan kotak batas di mana gambar disesuaikan, mencegah distorsi.

🎓 Praktik Terbaik​

  • Validasi jenis file dan ukuran sebelum memanggil upload().
  • Kirim entity / id agar file terorganisir berdasarkan entitas di penyimpanan.
  • Aktifkan compress untuk gambar web.
  • Simpan filename yang dikembalikan agar Anda dapat delete() file nanti.
  • Bersihkan file yang tidak terpakai secara eksplisit — mereka bertahan setelah penghapusan entitas.
  • Tangani kesalahan unggah dengan try/catch dan periksa bentuk pengembalian IError.

🔗 Dokumentasi Terkait​