Panduan Memulai
Salin prompt setup yang berisi langkah install dan panduan markdown lengkap untuk plugin ini.
Set up this Capacitor plugin in the project.
Use the package manager already used by the project.
Install these package(s): `@capgo/capacitor-uploader`
Run the required Capacitor sync/update step after installation.
Read this markdown guide for the full setup steps: https://raw.githubusercontent.com/Cap-go/website/refs/heads/main/apps/docs/src/content/docs/docs/plugins/uploader/getting-started.mdx
Use that guide for platform-specific steps, native file edits, permissions, config changes, imports, and usage setup.
If that guide references other docs pages, read them too.
Anda bisa menggunakan AI-Assisted Setup kami untuk menginstal plugin ini. Tambahkan skill Capgo ke tool AI Anda dengan command berikut:
npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-pluginsLalu gunakan prompt berikut:
Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-uploader` plugin in my project.Jika Anda lebih memilih Manual Setup, instal plugin dengan menjalankan perintah berikut dan ikuti petunjuk khusus platform di bawah ini:
bun add @capgo/capacitor-uploaderbunx cap syncimport { Uploader } from '@capgo/capacitor-uploader';Mulai cepat
Bagian berjudul “Mulai cepat”Mulai upload, subscribe ke events, dan lacak upload yang dikembalikan id.
import { Uploader } from '@capgo/capacitor-uploader';
let uploadId = '';
const listener = await Uploader.addListener('events', async (event) => { if (event.id !== uploadId) return;
if (event.name === 'uploading') { console.log(event.payload.percent); }
if (event.name === 'completed' || event.name === 'failed') { if (event.eventId) { await Uploader.acknowledgeEvent({ eventId: event.eventId }); } await listener.remove(); }});
const { id } = await Uploader.startUpload({ filePath: 'file:///data/user/0/.../scan.jpg', serverUrl: 'https://api.example.com/v1/assets', method: 'POST', headers: { Authorization: 'Bearer token' }, maxRetries: 3,});uploadId = id;Contoh: presigned S3 PUT
Bagian berjudul “Contoh: presigned S3 PUT”PUT uploads mendukung satu file. Gunakan presigned URL sebagai serverUrl dan atur method: 'PUT'.
await Uploader.startUpload({ filePath: capturedUri, serverUrl: presignedUrl, method: 'PUT', headers: { 'Content-Type': 'image/jpeg' },});Contoh: multipart form dengan field tambahan
Bagian berjudul “Contoh: multipart form dengan field tambahan”await Uploader.uploadMultipart({ url: 'https://api.example.com/upload', filePath: localPath, fieldName: 'file', fields: { userId: '42', kind: 'receipt' }, headers: { Authorization: 'Bearer token' },});Kesalahan umum
Bagian berjudul “Kesalahan umum”- Berkas multiple: gunakan
filesarray distartUploaduntuk satu permintaan multipart.PUTtidak dapat mengirim beberapa body. - Latar belakang Web: upload berhenti jika pengguna menutup tab. Gunakan platform native jika penyelesaian harus bertahan saat aplikasi di-background.
- Batal: panggil
removeUpload({ id })dengan id daristartUpload. - Progres: selalu lampirkan
eventslistener sebelum memulai, atau Anda bisa melewatkan progres awal.
Ringkasan API
Bagian berjudul “Ikhtisar API”startUpload
Bagian berjudul “startUpload”Mulai upload file ke server.
Upload akan terus berjalan di latar belakang meskipun aplikasi ditutup atau di-background. Dengarkan event upload untuk melacak progres, penyelesaian, atau kegagalan.
import { Uploader } from '@capgo/capacitor-uploader';
const { id } = await Uploader.startUpload({ filePath: 'file:///path/to/file.jpg', serverUrl: 'https://example.com/upload', headers: { 'Authorization': 'Bearer token' }, method: 'POST', uploadType: 'multipart', fileField: 'photo'});console.log('Upload started with ID:', id);removeUpload
Bagian berjudul “removeUpload”Batalkan dan hapus upload yang sedang berjalan.
Ini akan menghentikan upload jika sedang berlangsung dan membersihkan sumber daya.
import { Uploader } from '@capgo/capacitor-uploader';
await Uploader.removeUpload({ id: 'upload-123' });Referensi Tipe
Bagian berjudul “Referensi Tipe”uploadOption
Bagian berjudul “uploadOption”Opsi konfigurasi untuk mengunggah file.
export interface uploadOption { /** * The local file path of the file to upload. * Can be a file:// URL or an absolute path. * * @since 0.0.1 */ filePath: string;
/** * The server URL endpoint where the file should be uploaded. * * @since 0.0.1 */ serverUrl: string;
/** * The title of the upload notification shown to the user. * Android only. * * @default 'Uploading' * @since 0.0.1 */ notificationTitle?: string;
/** * HTTP headers to send with the upload request. * Useful for authentication tokens, content types, etc. * * @since 0.0.1 * @example * ```typescript * headers: { * 'Authorization': 'Bearer token123', * 'X-Custom-Header': 'value' * } * ``` */ headers: { [key: string]: string; };
/** * The HTTP method to use for the upload request. * * @default 'POST' * @since 0.0.1 */ method?: 'PUT' | 'POST';
/** * The MIME type of the file being uploaded. * If not specified, the plugin will attempt to determine it automatically. * * @since 0.0.1 * @example 'image/jpeg', 'application/pdf', 'video/mp4' */ mimeType?: string;
/** * Additional form parameters to send with the upload request. * These will be included as form data in multipart uploads. * * @since 0.0.1 */ parameters?: { [key: string]: string };
/** * The maximum number of times to retry the upload if it fails. * * @since 0.0.1 * @default 0 */ maxRetries?: number;
/** * The type of upload to perform. * - 'binary': Uploads the file as raw binary data in the request body * - 'multipart': Uploads the file as multipart/form-data * * @default 'binary' * @since 0.0.2 */ uploadType?: 'binary' | 'multipart';
/** * The form field name for the file when using multipart upload type. * Only used when uploadType is 'multipart'. * * @default 'file' * @since 0.0.2 */ fileField?: string;}UploadEvent
Bagian berjudul “UploadEvent”Event yang dipancarkan selama siklus hidup upload.
export interface UploadEvent { /** * The current status of the upload. * - 'uploading': Upload is in progress * - 'completed': Upload finished successfully * - 'failed': Upload encountered an error * * @since 0.0.1 */ name: 'uploading' | 'completed' | 'failed';
/** * Additional data about the upload event. * * @since 0.0.1 */ payload: { /** * Upload progress percentage from 0 to 100. * Only present during 'uploading' events. * * @since 0.0.1 */ percent?: number;
/** * Error message if the upload failed. * Only present during 'failed' events. * * @since 0.0.1 */ error?: string;
/** * HTTP status code returned by the server. * Present during 'completed' and 'failed' events. * * @since 0.0.1 */ statusCode?: number; };
/** * Unique identifier for this upload task. * * @since 0.0.1 */ id: string;}Sumber Kebenaran
Bagian berjudul “Sumber Kebenaran”Halaman ini dibuat dari plugin src/definitions.ts. Jalankan ulang sync saat API publik berubah di upstream.
Lanjutkan dari Getting Started
Bagian berjudul “Lanjutkan dari Getting Started”Jika Anda menggunakan Panduan Memulai untuk merencanakan operasi dashboard dan API, hubungkan dengan Menggunakan @capgo/capacitor-uploader untuk kapabilitas native di Using @capgo/capacitor-uploader, Ringkasan API untuk detail implementasi di API Overview, Pendahuluan untuk detail implementasi di Introduction, Kunci API untuk detail implementasi di API Keys, dan Perangkat untuk detail implementasi di Devices.