入门

1. 安装软件包

   npm

   npm i @capgo/capacitor-uploader

   pnpm

   pnpm add @capgo/capacitor-uploader

   yarn

   yarn add @capgo/capacitor-uploader

   bun

   bun add @capgo/capacitor-uploader

2. 与原生项目同步

   npm

   npx cap sync

   pnpm

   pnpm cap sync

   yarn

   yarn cap sync

   bun

   bunx cap sync

3. 配置权限

   iOS

   将背景模式添加到您的 Info.plist 中：

   <key>UIBackgroundModes</key>
   <array>
     <string>processing</string>
   </array>

   Android

   向您的 AndroidManifest.xml 添加权限：

   <uses-permission android:name="android.permission.INTERNET" />
   <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
   <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />

用法

导入插件并使用其方法上传文件：

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

// Start an upload
const startUpload = async () => {
  const upload = await Uploader.startUpload({
    filePath: 'file:///path/to/your/file.jpg',
    serverUrl: 'https://your-server.com/upload',
    method: 'POST',
    headers: {
      'Authorization': 'Bearer your-token'
    },
    parameters: {
      'userId': '12345',
      'type': 'profile'
    },
    notificationTitle: 'Uploading Photo'
  });

  console.log('Upload ID:', upload.id);
};

// Listen for upload events
const listener = await Uploader.addListener('events', (event) => {
  switch (event.name) {
    case 'uploading':
      console.log(`Upload ${event.payload.id}: ${event.payload.percent}%`);
      break;
    case 'completed':
      console.log('Upload completed:', event.payload.id);
      console.log('Status code:', event.payload.statusCode);
      break;
    case 'failed':
      console.error('Upload failed:', event.payload.id);
      console.error('Error:', event.payload.error);
      break;
  }
});

// Remember to remove listener when done
// listener.remove();

// Cancel an upload
const cancelUpload = async (uploadId: string) => {
  await Uploader.cancelUpload({ id: uploadId });
};

// Get all active uploads
const getActiveUploads = async () => {
  const uploads = await Uploader.getUploads();
  console.log('Active uploads:', uploads);
};

API 参考

开始上传（选项）

开始新文件上传。

interface UploadOptions {
  filePath: string;
  serverUrl: string;
  method?: 'POST' | 'PUT';
  headers?: { [key: string]: string };
  parameters?: { [key: string]: string };
  notificationTitle?: string;
  notificationBody?: string;
  useUtf8Charset?: boolean;
  maxRetries?: number;
}

取消上传（选项）

取消正在进行的上传。

interface CancelOptions {
  id: string;
}

获取上传()

返回所有活动上传。

删除上传（选项）

从队列中删除上传。

interface RemoveOptions {
  id: string;
}

活动

活动

所有上传事件均通过单个 events 侦听器传递。该事件包含一个 name 字段来标识类型：

Uploader.addListener('events', (event: UploadEvent) => {
  switch (event.name) {
    case 'uploading':
      // Upload in progress
      console.log(`Progress: ${event.payload.percent}%`);
      console.log(`ID: ${event.payload.id}`);
      break;

    case 'completed':
      // Upload finished successfully
      console.log(`Completed: ${event.payload.id}`);
      console.log(`Status code: ${event.payload.statusCode}`);
      break;

    case 'failed':
      // Upload failed
      console.error(`Failed: ${event.payload.id}`);
      console.error(`Error: ${event.payload.error}`);
      break;
  }
});

事件类型：

• uploading - percent 和 id 的进度更新
• completed - 使用 id 和 statusCode 完成上传
• failed - 上传失败，并显示 id 和 error 消息

高级功能

多部分表单上传

const uploadWithFormData = async () => {
  const upload = await Uploader.startUpload({
    filePath: 'file:///path/to/photo.jpg',
    serverUrl: 'https://api.example.com/upload',
    method: 'POST',
    parameters: {
      'name': 'profile-photo',
      'description': 'User profile photo'
    },
    headers: {
      'X-API-Key': 'your-api-key'
    }
  });
};

二进制上传

const uploadBinary = async () => {
  const upload = await Uploader.startUpload({
    filePath: 'file:///path/to/data.bin',
    serverUrl: 'https://api.example.com/binary',
    method: 'PUT',
    headers: {
      'Content-Type': 'application/octet-stream'
    }
  });
};

网络感知上传

import { Network } from '@capacitor/network';

const smartUpload = async () => {
  const status = await Network.getStatus();

  if (status.connectionType === 'wifi') {
    // Start large file uploads on WiFi
    await startLargeUpload();
  } else if (status.connectionType === 'cellular') {
    // Queue for later or warn user
    console.log('Using cellular data');
  }
};

最佳实践

1. 处理所有事件类型

   const setupUploadHandlers = () => {
     Uploader.addListener('events', (event) => {
       switch (event.name) {
         case 'uploading':
           handleProgress(event.payload);
           break;
         case 'completed':
           handleCompleted(event.payload);
           break;
         case 'failed':
           handleError(event.payload);
           break;
       }
     });
   };

2. 清理监听器

   // Add listener
   const listener = await Uploader.addListener('events', handleEvent);
   
   // Clean up when done
   listener.remove();

3. 重试失败的上传

   const retryUpload = async (filePath: string, serverUrl: string) => {
     try {
       await Uploader.startUpload({
         filePath,
         serverUrl,
         maxRetries: 3
       });
     } catch (error) {
       console.error('Upload failed after retries:', error);
     }
   };

4. 显示上传通知

   await Uploader.startUpload({
     filePath: 'file:///path/to/file',
     serverUrl: 'https://server.com/upload',
     notificationTitle: 'Uploading File',
     notificationBody: 'Your file is being uploaded...'
   });

平台说明

iOS

• 使用 URLSession 进行后台上传
• 需要后台处理能力
• 应用程序暂停时继续上传

Android

• 使用 WorkManager 进行可靠的上传
• 上传期间显示前台服务通知
• 尊重电池优化设置