快速入门
复制包含安装步骤和该插件完整 Markdown 指南的配置 prompt。
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.
安装
“安装”章节你可以使用我们的 AI 辅助设置来安装插件。使用以下命令将 Capgo skills 添加到你的 AI 工具中:
npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins然后使用以下 prompt:
Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-uploader` plugin in my project.如果你更想手动设置,请运行以下命令安装插件,并按照下方各平台的说明操作:
bun add @capgo/capacitor-uploaderbunx cap sync导入
“导入”章节import { Uploader } from '@capgo/capacitor-uploader';快速入门
章节标题为“快速入门”开始上传,订阅 events,并跟踪返回的上传 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;示例:S3 预签名 PUT
标题为“示例:预签名 S3 PUT”的章节PUT 上传支持单个文件。将预签名 URL 用作 serverUrl 并设置 method: 'PUT'.
await Uploader.startUpload({ filePath: capturedUri, serverUrl: presignedUrl, method: 'PUT', headers: { 'Content-Type': 'image/jpeg' },});示例:包含额外字段的 multipart 表单
标题为“示例:带额外字段的多部分表单”的章节await Uploader.uploadMultipart({ url: 'https://api.example.com/upload', filePath: localPath, fieldName: 'file', fields: { userId: '42', kind: 'receipt' }, headers: { Authorization: 'Bearer token' },});常见坑点
章节标题为“常见陷阱”- 多个文件:使用
files数组在startUpload中发送一个 multipart 请求。PUT无法发送多个 body。 - Web 后台:如果用户关闭标签页,上传将停止。当需要确保应用进入后台后上传仍能完成时,请使用原生平台。
- 取消: 调用
removeUpload({ id }),使用来自startUpload. - 进度:始终附加
events在启动前注册监听器,否则可能会错过早期的进度更新。
API 概览
章节标题:“API 概览”startUpload
标题为 “startUpload” 的章节开始向服务器上传文件。
即使应用关闭或进入后台,上传仍会在后台继续。 监听上传事件以跟踪进度、完成或失败状态。
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
标题为 “removeUpload” 的章节取消并移除正在进行的上传。
如果上传正在进行,这将停止上传并清理资源。
import { Uploader } from '@capgo/capacitor-uploader';
await Uploader.removeUpload({ id: 'upload-123' });类型参考
“类型参考” 章节uploadOption
“uploadOption” 章节文件上传的配置选项。
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
“UploadEvent” 章节上传生命周期中触发的事件。
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;}单一事实来源
标题为“单一事实来源”的部分本页面由插件的 src/definitions.ts生成。当上游的公共 API 发生变化时,请重新运行 sync。
从入门指南继续
“从入门指南继续”章节如果你正在使用 快速入门 要规划 dashboard 和 API 操作,请将其连接到 使用 @capgo/capacitor-uploader 用于《使用 @capgo/capacitor-uploader》中的原生能力, API 概览 关于 API Overview 中的实现细节, 简介 关于 Introduction 中的实现细节, API 密钥 有关 API Keys 的实现细节,以及 设备 有关 Devices 的实现细节。