cordova-plugin-file-transferの代替 Capacitor

Capacitor アプリのための cordova-plugin-file-transfer の代替は、1 つの質問に依存します: トランスファーがアプリがバックグラウンドに移動しても存続する必要がありますか? 正常なアップロードとダウンロードの場合、進捗状況を表示するには公式のプラグインを使用します。 大きなファイル、不安定なネットワーク、またはユーザーがアプリを切り替えるときにトランスファーが続行される必要がある場合には @capacitor/file-transfer そして @capgo/capacitor-uploader 公式のプラグイン @capgo/capacitor-downloader、nativeバックグラウンド転送APIを実行するものです。このガイドでは、両方を比較し、各の FileTransfer をマップします。

。

cordova-plugin-file-transferはまだ廃止されたままですか?

• 歴史は混乱しているので、以下の事実を示します。 XMLHttpRequest レベル２。
• The plugin was never flagged as deprecated on npm. Version 2.0.0 shipped in September 2023, and 2.0.1 in August 2026. The GitHub repository is active.

So it is not dead. But in a Capacitor app it is still a Cordova plugin that:

• 依存する cordova-plugin-file 依存する cdvfile:// と file:// と
• Capacitor が適合しない Filesystem ディレクトリと URI の変換
• バックグラウンド転送のサポートがなく
• コールバックスタイルの API を使用

Cordova から移行する場合、Capacitor のネイティブ プラグインに置き換えることで、最後の理由の 1 つを取り除くことができます cordova-plugin-file.

「fetch を単に使用する」は、大きなファイルの場合に機能しない

Apache が推奨する代替品である XHR は、小さな JSON と画像の場合に機能しますが、ハイブリッドアプリで実際のファイル転送作業には失敗します

• メモリ fetch または Blob ウェブビュー内で ArrayBuffer 500 MB のビデオは、ウェブビュー内で 500 MB のメモリを占有し、ブリッジを通して書き込むためにコピーする必要があります。中級の Android デバイスではレンダラーがクラッシュします
• 停止 iOSアプリを切り替えると、WebViewは一時停止されます。インフライトの要求は停止または失敗します。
• OS統合なし。 システムダウンロード通知なし、Wi-Fiのみオプションなし、接続が切断されたときに再開しない。

ネイティブプラグインはディスクとネットワーク間で直接ストリーミングし、JavaScriptはデータパスから排除されます。

比較対象のオプション

ほとんどのアプリは @capacitor/file-transfer 小さなユーザーに表示される転送と Capgo プラグインのメディアアップロードキューとオフラインコンテンツダウンロード

オプション 1: @capacitor/file-transfer

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

プラグインにはフルネイティブパスが必要です。 @capacitor/filesystem.

ダウンロード

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();
  }
}

アップロード

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);
}

デフォルトでは、複数ファイルのアップロードになります。RAW ストリームにアップロードする場合、例えば署名済みのS3 URLにアップロードする場合、次のように設定します。 method: 'PUT' と明示的に Content-Type ヘッダーとして application/octet-stream.

エラー コードは次の形式になります。有用なものは: OS-PLUG-FLTR-XXXX ファイルが見つかりません 0007 接続が失敗しました 0008 HTTP エラー ステータスと 0010 そして httpStatus and body in error.data.

オプション 2: @capgo/capacitor-アップローダーでバックグラウンドアップロード

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
});

プレサIGNED URLの場合に使用します method: 'PUT', これはデフォルトでバイナリボディになります

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

1 つの多部品要求に複数のファイルが含まれます

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>' },
});

キャンセルする Uploader.removeUpload({ id }).

イベントを認識する理由 完了したイベントと失敗したイベントは、永続的なネイティブキャッシュに格納され、イベントを再送信するために使用できます。アプリが閉じられまたはバックグラウンドに移動した場合、イベントを再送信するために使用できます。イベントを認識すると、イベントは次回プラグインが初期化されたときに再送信されないように削除されます。

iOSの設定 アップローダーはバックグラウンド URLSession. 多くのアプリには追加の設定が必要ありません。アップロードがアプリが一時停止した後も続行する必要がある場合、 fetch に追加します UIBackgroundModes. 追加しないでください processing の場合、別の機能が使用している BGTaskScheduler, App Store Connect が宣言していることを拒否するため BGTaskSchedulerPermittedIdentifiers.

オプション 3: @capgo/capacitor-downloader を使用したバックグラウンド ダウンロード

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);

相対的な destination iOS ではアプリの Documents ディレクトリ、Android ではアプリ固有の外部ファイル ディレクトリに解決されます。絶対パスまたはURLを渡すこともできます。 file:// URLを使用します。 getFileInfo({ path }) を使用して部分データをキャンセルして削除します。 stop({ id }) cordova-plugin-file-transfer から移行する

ダウンロード

アップロード

// 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>' },
});

のことに注意してください

// 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>' },
});

__CAPGO_KEEP_0__ params in @capacitor/file-transfer はURLクエリパラメータです。サーバーがフォームフィールドを受け入れる場合、Capgo アップローダーの parameters, これらはマルチパートフォームフィールドとして送信されます。

マッピングテーブル

パスの部分がマイグレーションを破壊する

Cordova code がパスを渡す cdvfile:// または cordova.file.* パスがどこでもある。 Capacitor では

• ネイティブのパスを取得する Filesystem.getUri() または、ファイル (カメラ、ファイルピッカー、レコーダー) によって作成されたプラグインから
• ダウンロードした画像をWebViewで表示するには、ネイティブのパスを __CAPGO_KEEP_0__ で変換する Capacitor.convertFileSrc(path).
• Capgo は ファイルプラグイン と ファイル選択 もし @capacitor/filesystem あなたのケースをカバーしていない場合。

トラブルシューティング

アップロードはAndroidで正常に動作しますが、iOSではファイルが見つからないエラーで失敗します。 アップロードはAndroidで動作しますが、iOSではファイルが見つからないエラーで失敗します。 capacitor:// あなたは file:// ウェブビューのURLを代わりに Filesystem.getUri().

ネイティブ パスを使用してください。 PUT サーバーはパスを使用してアップロードを拒否します。415です。 Content-Type.

iOSでバックグラウンドアップロードは停止します。 ユーザーがアプリを強制終了したため、バックグラウンドセッションがキャンセルされたり、 fetch バックグラウンドモードが必要なときに欠けている場合

Androidではダウンロードの通知がストック状態になります。 設定 notification: 'progress' または 'hidden' ダウンローダー

メモリリークが大きなダウンロードで発生します。 まだ fetch またはファイルをbase64形式で読み込んでいます。ブリッジを通じて。native download to diskに切り替えてください。

移行を配信

ネイティブプラグインを交換するには、新しいストアビルドが必要です、 Capgo ビルド iOSとAndroidでクラウドで実行できます。 その後、アップロードとダウンロードを制御するJavaScriptを修正して改善することができます。 Capgo ライブアップデートCordova から Capacitor への移行については、以下を参照してください。 移行ガイド、その他の有料またはレガシーコアネイティブSDKについては、 Ionicエンタープライズプラグイン代替.