cordova-plugin-file-transfer Alternative pour Capacitor

The best cordova-plugin-file-transfer alternative for a Capacitor app depends on one question: does the transfer need to survive the app going to the background? For normal uploads and downloads with progress, use the official @capacitor/file-transfer plugin. For large files, flaky networks, or transfers that must keep going when the user switches apps, use @capgo/capacitor-uploader et @capgo/capacitor-downloaderCe guide compare et mappe tous les plugins de transfert de fichiers. FileTransfer appel.

Est-ce que cordova-plugin-file-transfer est toujours obsolète ?

L'histoire est confuse, voici les faits :

• En 2017, l'équipe Apache Cordova a annoncé qu'elle prévoyait déprécier le plugin et a orienté les développeurs vers XMLHttpRequest Niveau 2.
• Le plugin n'a jamais été signalé comme obsolète sur npm. La version 2.0.0 a été livrée en septembre 2023, et 2.0.1 en août 2026. Le GitHub repository est actif.

Ainsi, il n'est pas mort. Mais dans une Capacitor application, il s'agit toujours d'un plugin Cordova :

• qui repose sur cordova-plugin-file et ses cdvfile:// et file:// modèle de chemin,
• ne convient pas à Capacitor’s Filesystem répertoires et conversions URI,
• Pas de support de transfert de fond d'écran.
• utilise des API de style de rappel.

Si vous migrez de Cordova, la remplacement par des plugins natifs Capacitor supprime l'un des derniers motifs pour conserver cordova-plugin-file.

Why “just use fetch” breaks on large files

La suggestion d'Apache, XHR, fonctionne pour les petits JSON et images. Elle échoue pour les transferts de fichiers réels dans une application hybride :

• La mémoire. fetch et XHR vous donnent un Blob ou ArrayBuffer in the WebView. A 500 MB video means 500 MB in WebView memory, then a copy to write it through the bridge. On mid-range Android devices that crashes the renderer.
• Suspendu. Quand l'utilisateur bascule entre les applications, iOS suspend la vue Web. Les requêtes en cours s'arrêtent ou échouent.
• Aucune intégration du système. Aucune notification de téléchargement du système, aucune option Wi-Fi uniquement, aucune reprise après une connexion interrompue.

Les plugins natifs transmettent directement entre le disque et le réseau et gardent le JavaScript hors du chemin des données.

Les options comparées

La plupart des applications se retrouvent avec @capacitor/file-transfer for small, user-visible transfers and the Capgo plugins for media upload queues and offline content downloads.

Option 1 : @capacitor/file-transfer

bun add @capacitor/file-transfer @capacitor/filesystem
bunx cap sync

The plugin nécessite un chemin natif complet. Obtenez-l’à partir de @capacitor/filesystem.

Télécharger

import { FileTransfer } from '@capacitor/file-transfer';
import { Filesystem, Directory } from '@capacitor/filesystem';

export async function downloadReport(url: string) {
  const { uri } = await Filesystem.getUri({
    directory: Directory.Data,
    path: 'reports/latest.pdf',
  });

  const progress = await FileTransfer.addListener('progress', (p) => {
    if (p.type === 'download' && p.lengthComputable) {
      console.log(`Downloaded ${Math.round((p.bytes / p.contentLength) * 100)}%`);
    }
  });

  try {
    const result = await FileTransfer.downloadFile({
      url,
      path: uri,
      progress: true,
      headers: { Authorization: 'Bearer <token>' },
    });
    return result.path;
  } catch (error: any) {
    if (error.code === 'OS-PLUG-FLTR-0010') {
      console.error('HTTP error', error.data?.httpStatus, error.data?.body);
    }
    throw error;
  } finally {
    await progress.remove();
  }
}

Envoyer

export async function uploadAvatar(path: string) {
  const result = await FileTransfer.uploadFile({
    url: 'https://api.example.com/v1/avatar',
    path,
    fileKey: 'avatar',
    mimeType: 'image/jpeg',
    headers: { Authorization: 'Bearer <token>' },
    progress: true,
  });
  console.log(result.responseCode, result.response);
}

Les téléchargements sont par défaut en plusieurs parties. Pour un flux brut, par exemple vers une URL S3 presignée, définissez method: 'PUT' et un en-tête explicite Content-Type un en-tête comme application/octet-stream.

Les codes d'erreur suivent le OS-PLUG-FLTR-XXXX format. Les plus utiles sont : 0007 le fichier non trouvé, 0008 la connexion échouée, 0010 l'état HTTP d'erreur avec httpStatus et body In error.data.

Option 2 : téléchargements en arrière-plan avec @capgo/capacitor-uploader

bun add @capgo/capacitor-uploader
bunx cap sync

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

await Uploader.addListener('events', async (event) => {
  switch (event.name) {
    case 'uploading':
      console.log(event.id, `${event.payload.percent}%`);
      break;
    case 'completed':
      console.log(event.id, 'done', event.payload.statusCode);
      break;
    case 'failed':
      console.error(event.id, event.payload.error);
      break;
  }
  // Completed and failed events are cached natively until acknowledged
  if (event.eventId) {
    await Uploader.acknowledgeEvent({ eventId: event.eventId });
  }
});

const { id } = await Uploader.startUpload({
  filePath: 'file:///path/to/video.mp4',
  serverUrl: 'https://api.example.com/v1/videos',
  method: 'POST',
  uploadType: 'multipart',
  fileField: 'video',
  parameters: { albumId: '7' },
  headers: { Authorization: 'Bearer <token>' },
  maxRetries: 3,
  notificationTitle: 'Uploading video', // Android only
});

Pour les URL presignées, utilisez method: 'PUT', qui se définit par un corps binaire :

await Uploader.startUpload({
  filePath,
  serverUrl: presignedUrl,
  method: 'PUT',
  headers: { 'Content-Type': 'video/mp4' },
  mimeType: 'video/mp4',
});

Plusieurs fichiers dans une demande multipart :

await Uploader.startUpload({
  serverUrl: 'https://api.example.com/v1/photos',
  method: 'POST',
  uploadType: 'multipart',
  files: [
    { filePath: photo1, fieldName: 'images[]', mimeType: 'image/jpeg' },
    { filePath: photo2, fieldName: 'images[]', mimeType: 'image/jpeg' },
  ],
  headers: { Authorization: 'Bearer <token>' },
});

Annuler avec Uploader.removeUpload({ id }).

Pourquoi reconnaître les événements ? Les événements terminés et échoués sont stockés dans une cache native persistante, ils peuvent donc être réexpédiés si l'application était fermée ou en arrière-plan avant qu'elle ne les traite. La reconnaissance supprime l'événement afin qu'il ne soit pas rebroadcast la prochaine fois que le plugin s'initialise.

Configuration iOS. L'uploader utilise un arrière-plan URLSession. Many apps need no extra setup. If uploads must continue after the app is suspended, add fetch Vers UIBackgroundModes. Ne pas ajouter processing sauf si une autre fonction utilise BGTaskScheduler, car App Store Connect rejette les builds qui déclarent cela sans BGTaskSchedulerPermittedIdentifiers.

Option 3 : téléchargements en arrière-plan avec @capgo/capacitor-téléchargeur

bun add @capgo/capacitor-downloader
bunx cap sync

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

await CapacitorDownloader.addListener('downloadProgress', ({ id, progress }) => {
  console.log(id, `${progress}%`);
});
await CapacitorDownloader.addListener('downloadCompleted', ({ id }) => {
  console.log(id, 'completed');
});
await CapacitorDownloader.addListener('downloadFailed', ({ id, error }) => {
  console.error(id, error);
});

await CapacitorDownloader.download({
  id: 'course-42',
  url: 'https://cdn.example.com/courses/42.zip',
  destination: 'courses/42.zip',
  headers: { Authorization: 'Bearer <token>' },
  network: 'wifi-only',
  priority: 'normal',
  notification: 'progress', // Android: remove the system notification when done
});

// Later
await CapacitorDownloader.pause({ id: 'course-42' });
await CapacitorDownloader.resume({ id: 'course-42' });
const status = await CapacitorDownloader.checkStatus({ id: 'course-42' });
console.log(status.state, status.progress);

Un chemin relatif destination se réfère au répertoire Documents de l'application sur iOS et au répertoire de fichiers externes spécifiques à l'application sur Android. Vous pouvez également passer un chemin absolu ou une file:// Utilisez getFileInfo({ path }) pour lire la taille et le type MIME après le téléchargement, et stop({ id }) pour annuler et supprimer les données partielles.

Migrer depuis cordova-plugin-file-transfer

Télécharger

// Before
const ft = new FileTransfer();
ft.onprogress = (e) => e.lengthComputable && setProgress(e.loaded / e.total);
ft.download(
  encodeURI(url),
  cordova.file.dataDirectory + 'report.pdf',
  (entry) => console.log(entry.toURL()),
  (err) => console.error(err.code, err.http_status),
  false,
  { headers: { Authorization: 'Bearer <token>' } },
);

// After
const { uri } = await Filesystem.getUri({ directory: Directory.Data, path: 'report.pdf' });
await FileTransfer.downloadFile({
  url,
  path: uri,
  progress: true,
  headers: { Authorization: 'Bearer <token>' },
});

Télécharger

// Before
const options = new FileUploadOptions();
options.fileKey = 'file';
options.fileName = 'photo.jpg';
options.mimeType = 'image/jpeg';
options.params = { albumId: '7' };
options.headers = { Authorization: 'Bearer <token>' };
new FileTransfer().upload(fileUrl, encodeURI(serverUrl), onSuccess, onError, options);

// After, foreground
await FileTransfer.uploadFile({
  url: serverUrl,
  path: fileUrl,
  fileKey: 'file',
  mimeType: 'image/jpeg',
  params: { albumId: '7' },
  headers: { Authorization: 'Bearer <token>' },
});

// After, background
await Uploader.startUpload({
  filePath: fileUrl,
  serverUrl,
  uploadType: 'multipart',
  fileField: 'file',
  parameters: { albumId: '7' },
  headers: { Authorization: 'Bearer <token>' },
});

Notez que params en @capacitor/file-transfer sont des paramètres de requête URL. Si votre serveur attend des champs de formulaire, utilisez l'uploader Capgo parametersqui sont envoyés sous forme de champs de formulaire multipart.

Tableau de correspondance

Chemins : la partie qui casse les migrations

Cordova code passe cdvfile:// ou cordova.file.* chemins partout. Dans Capacitor :

• Obtenez des chemins natifs de Filesystem.getUri() ou depuis le plugin qui a créé le fichier (caméra, sélection de fichier, enregistreur).
• Pour afficher une image téléchargée dans le WebView, convertissez le chemin natif avec Capacitor.convertFileSrc(path).
• Capgo a plugin de fichier et un pick de fichier si @capacitor/filesystem ce cas ne vous est pas couvert.

Troubleshooting

L'upload fonctionne sur Android mais échoue sur iOS avec une erreur de fichier non trouvé. Vous avez passé un capacitor:// URL de la vue Web au lieu d'une native file:// URL de WebView au lieu d'une Filesystem.getUri().

chemin natif. Utilisez le chemin depuis Multipart vs raw body mismatch. For presigned URLs use PUT avec une explication explicite Content-Type.

Les téléchargements en arrière-plan s'arrêtent sur iOS. L’utilisateur a fermé l'application, ce qui annule les sessions en arrière-plan, ou fetch le mode en arrière-plan est manquant lorsqu'il est nécessaire.

Android affiche une notification de téléchargement bloqué. Configurez notification: 'progress' or 'hidden' sur le téléchargeur.

Crash de mémoire lors de téléchargements importants. sur le téléchargeur. fetch ouvrir le fichier en base64 à travers le pont. Passer à un téléchargement natif sur le disque.

Expédiez la migration

Remplacez les plugins natifs par des nouveaux ensembles de build, ce qui Capgo Construction peut s'exécuter en nuage pour iOS et Android. Après cela, le JavaScript qui gère les téléchargements et les téléchargements peut être corrigé et amélioré avec Capgo mises à jour en direct. Pour le reste du Cordova à Capacitor déplacer, voir notre guide de migration, et pour les autres SDKs natives payantes ou légendaires, les alternatives de plugins Ionic Enterprise.