@ capgo/ 电容器加载器

从您的 Capacitor app 上传文件, 并带有本地背景上传, 程序关闭后继续运行, 并进行进度事件和重试 .

🤖 建筑与AI编码代理? 安装 Capgo 技能 所以克劳德代码,代码,光标,副驾驶,或双子座CLI知道如何安装和使用 @capgo/capacitor-uploader 在您的电容应用程序中: npx skills add Cap-go/capgo-skills。然后问你的经纪人: 添加@capgo/电容-uploader到我的电容软件上并把它接上 代理设置指南 • 妇女 主机磁共振

主要特点

• 上传数字 : startUpload() 发送文件与 PUT 或者说 POST,自定义标题和参数.
• 多块数字 : uploadMultipart() 发送文件为 multipart/form-data。 。 。 .
• 进展活动页:1 events 听者报告进展、完成和出错.
• 控制权数字 : removeUpload() 取消上传, maxRetries 重复失败.
• 背景情况: 背景情况 URLSession 在iOS和上传服务 并通知Android.
• 平台: iOS,Android和Web. 互联网档案馆的存檔,存档日期2013-12-02. 网络上传 fetch() 在页面打开时,没有本地背景上传.

上传插件

这个插件提供了一个灵活的方法,可以将本地文件上传到各种服务器上,包括带有预先签名的URL的S3.

可用于与 电容相机预览 以可靠的方式上传文件,而不是在网络视图的缓冲器中阅读,然后在JS中上传.

在网络上,文件路径支持使用以下格式的索引DB(IDB)语义路径:
idb://[database-name]/[collection-name]/[key]
这允许与索引DB进行无缝集成,用于存储和检索文件.

文档

这里有最完整的医生: 页:1

兼容性

说明: 此插件的主要版本沿用了Capacitor的主要版本. 使用匹配您的 Capacitor 安装的版本( 如 Capacitor 8 的插件 v8) 。 只有最新的主要版本得到积极维护.

安装

您可以使用我们的 AI 辅助设置安装插件 。 使用以下命令将 Capgo 技能添加到您的 AI 工具 :

npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins

然后使用下列提示:

Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-uploader` plugin in my project.

如果您更喜欢手动设置,请通过运行以下命令来安装插件,并遵循下面的平台特定指令:

npm install @capgo/capacitor-uploader
npx cap sync

机器人

在您的 AndroidManifest.xml 文件 :

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

iOS系统

在iOS上,插件通过背景上传 URLSession 使用标识符 CapacitorUploaderBackgroundSession。 。 。 .

上传工作往往没有额外内容 Info.plist 键。 为了让系统在背景传输完成时唤醒您的应用,请添加 fetch 背景模式 :

<key>UIBackgroundModes</key>
<array>
  <string>fetch</string>
</array>

执行 没有 添加 processing 仅此插件的背景模式。 需要 App Store 连接 BGTaskSchedulerPermittedIdentifiers 任何时候 processing 声明,此插件不注册 BGTaskScheduler 任务。 如果您的应用程序已经包含 processing (例如,来自旧文件)和验证失败,加上:

<key>BGTaskSchedulerPermittedIdentifiers</key>
<array>
  <string>CapacitorUploaderBackgroundSession</string>
</array>

见 问题115 用于上下文.

示例 S3 上传

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

async function uploadToS3(filePath: string, presignedUrl: string, fields: Record<string, string>) {
  try {
    const { id } = await Uploader.startUpload({
      filePath: filePath,
      serverUrl: presignedUrl,
      method: 'PUT',
      parameters: fields,
      notificationTitle: 'Uploading to S3'
    });

    console.log('Upload started with ID:', id);

    // Listen for upload events
    Uploader.addListener('events', (event: UploadEvent) => {
      if (event.name === 'uploading') {
        console.log(`Upload progress: ${event.payload.percent}%`);
      } else if (event.name === 'completed') {
        console.log('Upload completed successfully');
      } else if (event.name === 'failed') {
        console.error('Upload failed:', event.payload.error);
      }
    });

  } catch (error) {
    console.error('Failed to start upload:', error);
  }
}

上传到自定义服务器的示例

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

async function uploadToCustomServer(filePath: string, serverUrl: string) {
  try {
    // Start the upload
    const { id } = await Uploader.startUpload({
      filePath: filePath,
      serverUrl: serverUrl,
      method: 'POST',
      headers: {
        'Authorization': 'Bearer your-auth-token-here'
      },
      parameters: {
        'user_id': '12345',
        'file_type': 'image'
      },
      notificationTitle: 'Uploading to Custom Server',
      maxRetries: 3
    });

    console.log('Upload started with ID:', id);

    // Listen for upload events
    Uploader.addListener('events', (event) => {
      switch (event.name) {
        case 'uploading':
          console.log(`Upload progress: ${event.payload.percent}%`);
          break;
        case 'completed':
          console.log('Upload completed successfully');
          console.log('Server response status code:', event.payload.statusCode);
          break;
        case 'failed':
          console.error('Upload failed:', event.payload.error);
          break;
      }
    });

    // Optional: Remove the upload if needed
    // await Uploader.removeUpload({ id: id });

  } catch (error) {
    console.error('Failed to start upload:', error);
  }
}

// Usage
const filePath = 'file:///path/to/your/file.jpg';
const serverUrl = 'https://your-custom-server.com/upload';
uploadToCustomServer(filePath, serverUrl);

示例多文件多部分上传

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

const { id } = await Uploader.startUpload({
  serverUrl: 'https://api.example.com/upload',
  method: 'POST',
  uploadType: 'multipart',
  files: [
    { filePath: 'file:///...photo1.jpg', fieldName: 'images[]', mimeType: 'image/jpeg' },
    { filePath: 'file:///...photo2.jpg', fieldName: 'images[]', mimeType: 'image/jpeg' },
  ],
  parameters: { albumId: '7' },
  headers: { Authorization: 'Bearer token' },
});
console.log('Upload started with ID:', id);

带有相机相机预览的示例

联合国文件 电容相机预览

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


  async function record() {
    await CameraPreview.startRecordVideo({ storeToFile: true })
    await new Promise(resolve => setTimeout(resolve, 5000))
    const fileUrl = await CameraPreview.stopRecordVideo()
    console.log(fileUrl.videoFilePath)
    await uploadVideo(fileUrl.videoFilePath)
  }

  async function uploadVideo(filePath: string) {
    Uploader.addListener('events', (event) => {
      switch (event.name) {
        case 'uploading':
          console.log(`Upload progress: ${event.payload.percent}%`);
          break;
        case 'completed':
          console.log('Upload completed successfully');
          console.log('Server response status code:', event.payload.statusCode);
          break;
        case 'failed':
          console.error('Upload failed:', event.payload.error);
          break;
      }
    });
    try {
      const result = await Uploader.startUpload({
        filePath,
        serverUrl: 'S#_PRESIGNED_URL',
        method: 'PUT',
        headers: {
          'Content-Type': 'video/mp4',
        },
        mimeType: 'video/mp4',
      });
      console.log('Video uploaded successfully:', result.id);
    } catch (error) {
      console.error('Error uploading video:', error);
      throw error;
    }
  }

API 密码

• startUpload(...)
• uploadMultipart(...)
• removeUpload(...)
• addListener('events', ...)
• acknowledgeEvent(...)
• getPluginVersion()
• 接口

用于上传带有背景支持和进度跟踪的文件的电容上传插件 .

iOS 设置

在iOS上,原生地层使用背景 URLSession 带有标识符 CapacitorUploaderBackgroundSession。许多应用程序可以在不添加的情况下上传 UIBackgroundModes; 添加 fetch 应用程序后需要上传时继续 暂停.

App Store 连接拒绝构建声明 UIBackgroundModes → processing 无 BGTaskSchedulerPermittedIdentifiers。此插件没有排程 BGTaskScheduler 工作,所以避开 processing 除非其他特性需要它. 若为 processing 存在(例如,来自旧的设置指南),包括 CapacitorUploaderBackgroundSession 内 BGTaskSchedulerPermittedIdentifiers 在你的应用软件 Info.plist。 。 。 .

启动装入(...)

startUpload(options: uploadOption) => Promise<{ id: string; }>

开始上传文件到服务器 .

即使应用程序关闭或背景化,上传也会在背景中继续. 听上传事件跟踪进度,完成或失败.

回返情况: Promise<{ id: string; }>

自: 0.0.1 资源

上传多部分(...)

uploadMultipart(options: UploadMultipartOptions) => Promise<{ id: string; }>

开始上传单个文件为多段/窗体-数据.

这是一个方便的 API,用于后端,期望一个命名的文件字段和 额外的窗体字段。 现有 startUpload 二进制上传不变.

回返情况: Promise<{ id: string; }>

自: 8.3.2 国家

删除上载(...)

removeUpload(options: { id: string; }) => Promise<void>

取消并删除正在进行的上传 .

这将停止上传,如果它正在进行,并清理资源.

自: 0.0.1 资源

添加倾听者( 事件,...)

addListener(eventName: 'events', listenerFunc: (state: UploadEvent) => void) => Promise<PluginListenerHandle>

听上传进度和状态事件.

活动为:

• 上传进度更新( 含百分比)
• 上传完成( 有状态代码)
• 上传失败( 有错误和状态代码)

回返情况: Promise<PluginListenerHandle>

自: 0.0.1 资源

确认Event(...)

acknowledgeEvent(options: { eventId: string; }) => Promise<void>

确认收到上传事件, 从插件缓存中删除 .

已完成和失败的事件被存储在插件的持久缓存中, 以便它们成为 如果应用程序在事件处理前关闭或背景化,则重新交付. 在成功处理“ 完成的” 或“ 失败的” 事件后调用此方法以预防 它从下次插件时重播开始.

进步( “ 上载 ” ) 事件没有事件标识, 不需要承认 .

自: 0.0.2 (中文(简体) )

获取 PluginVersion ()

getPluginVersion() => Promise<{ version: string; }>

获取本地 Capacitor 插件版本 .

回返情况: Promise<{ version: string; }>

自: 0.0.1 资源

接口

上传选项

上传文件选项

上传文件的配置选项 .

上传多部分选项

启动单文件多段上传的选项 .

插件听筒

上传事件

上传生命周期中排放出的事件 .

功劳:

Ios上的灵感和代码: https://github.com/Vydia/ react-native-background-upload/tree/master 页面存档备份,存于互联网档案馆 API定义: https://www.npmjs.com/package/cordova-plugin-background-upload-put-s3 互联网档案馆的存檔,存档日期2014-12-21