跳到主要内容
版本：v7

@capacitor/file-transfer

FileTransfer API 提供下载和上传文件的机制。

安装​

npm install @capacitor/file-transfer@latest-7
npx cap sync

示例​

下载​

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

// 首先使用 Filesystem 获取完整的文件路径
const fileInfo = await Filesystem.getUri({
  directory: Directory.Data,
  path: 'downloaded-file.pdf'
});

try {
    // 然后使用 FileTransfer 插件下载
    await FileTransfer.downloadFile({
        url: 'https://example.com/file.pdf',
        path: fileInfo.uri,
        progress: true
    });
} catch(error) {
    if (error.code === 'OS-PLUG-FLTR-0010') {
      // HTTP 错误 - 参见 `FileTransferError` 了解 `errorData` 中可用字段的详细信息
      let errorData = error.data;
      this.showError('上传失败：' + errorData.httpStatus + '; ' + errorData.body);
    } else {
      // 其他错误 - 使用 `error.code` 和 `error.message` 获取更多信息。
      this.showError('上传失败：' + error.code + '; ' + error.message);
    }
}

// 进度事件
FileTransfer.addListener('progress', (progress) => {
  console.log(`已下载 ${progress.bytes} / ${progress.contentLength}`);
});

上传​

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

// 首先使用 Filesystem 获取完整的文件路径
const fileInfo = await Filesystem.getUri({
  directory: Directory.Cache,
  path: 'image_upload.png'
});

try {
    // 然后使用 FileTransfer 插件上传
    const result = await FileTransfer.uploadFile({
        url: 'https://example.com/upload_api',
        path: fileInfo.uri,
        chunkedMode: true,
        headers: {
            // 上传默认使用 `multipart/form-data`。
            // 如果您想避免这种情况，可以显式设置 'Content-Type' 头。
            'Content-Type': 'application/octet-stream',
        },
        progress: false
    });
    // 从结果中获取服务器响应和其他信息 - 参见 `UploadFileResult` 接口
} catch(error) {
    if (error.code === 'OS-PLUG-FLTR-0010') {
      // HTTP 错误 - 参见 `FileTransferError` 了解 `errorData` 中可用字段的详细信息
      let errorData = error.data;
      this.showError('上传失败：' + errorData.httpStatus + '; ' + errorData.body);
    } else {
      // 其他错误 - 使用 `error.code` 和 `error.message` 获取更多信息。
      this.showError('上传失败：' + error.code + '; ' + error.message);
    }
}

API​

注意：部分输入选项来自 @capacitor/core 中的 HttpOptions，但插件并未使用 HttpOptions 中的所有参数。以下记录的是实际使用的参数。

关于现有错误代码的列表，请参见错误。

downloadFile(...)​

downloadFile(options: DownloadFileOptions) => Promise<DownloadFileResult>

向服务器发送 HTTP 请求并将文件下载到指定目标。

如果服务器返回 HTTP 错误（例如 404、500 等），Promise 将被拒绝。 要在 Android 和 iOS（不适用于 web）上运行时获取关于 HTTP 错误响应的信息，请使用 error.data 属性中可用的 FileTransferError 接口。

参数类型
options
DownloadFileOptions

返回值： 

Promise<DownloadFileResult>

起始版本： 1.0.0

uploadFile(...)​

uploadFile(options: UploadFileOptions) => Promise<UploadFileResult>

向服务器发送 HTTP 请求以上传文件。

如果服务器返回 HTTP 错误（例如 404、500 等），Promise 将被拒绝。 要在 Android 和 iOS（不适用于 web）上运行时获取关于 HTTP 错误响应的信息，请使用 error.data 属性中可用的 FileTransferError 接口。

参数类型
options
UploadFileOptions

返回值： 

Promise<UploadFileResult>

起始版本： 1.0.0

addListener('progress', ...)​

addListener(eventName: "progress", listenerFunc: (progress: ProgressStatus) => void) => Promise<PluginListenerHandle>

为文件传输（下载或上传）进度事件添加监听器。

参数类型
eventName'progress'
listenerFunc
(progress: ProgressStatus) => void

返回值： 

Promise<PluginListenerHandle>

起始版本： 1.0.0

removeAllListeners()​

removeAllListeners() => Promise<void>

移除此插件的所有监听器。

起始版本： 1.0.0

接口​

DownloadFileResult​

属性类型描述起始版本
pathstring文件下载到的路径。1.0.0
blobBlob下载文件的 blob 数据。仅在 web 上可用。1.0.0

DownloadFileOptions​

属性类型描述起始版本
urlstring下载文件的 URL。1.0.0
pathstring下载文件应移动到的完整文件路径。1.0.0
progressboolean如果为 true，将在每个接收到的块上分发进度事件。默认为 false。1.0.0
methodstring要执行的 HTTP 请求方法。（默认是 GET）1.0.0
paramsHttpParams要附加到请求的 URL 参数。1.0.0
headersHttpHeaders随请求发送的 HTTP 请求头。1.0.0
readTimeoutnumber等待读取额外数据的毫秒数。每次收到新数据时重置。默认值为 60000 毫秒（1 分钟）。web 上不支持。1.0.0
connectTimeoutnumber等待初始连接的毫秒数。默认值为 60000 毫秒（1 分钟）。1.0.0
disableRedirectsboolean设置是否禁用自动 HTTP 重定向。1.0.0
shouldEncodeUrlParamsboolean如果您需要在某些情况下保持 URL 不编码，请使用此选项。默认为 true。web 上不支持。1.0.0

UploadFileResult​

属性类型描述起始版本
bytesSentnumber上传的总字节数。1.0.0
responseCodestring上传的 HTTP 响应代码。1.0.0
responsestring上传的 HTTP 响应体（可用时）。1.0.0
headers{ [key: string]: string; }上传响应的 HTTP 头（可用时）。1.0.0

UploadFileOptions​

属性类型描述起始版本
urlstring上传文件的 URL。1.0.0
pathstring要上传文件的完整文件路径。1.0.0
blobBlob要上传的 blob 数据。如果提供，将使用此数据而不是路径。仅在 web 上可用。1.0.0
chunkedModeboolean是否以分块流模式上传数据。web 上不支持。1.0.0
mimeTypestring要上传数据的 MIME 类型。1.0.0
fileKeystring表单元素的类型。默认设置为 "file"。1.0.0
progressboolean如果为 true，将在每个接收到的块上分发进度事件。默认为 false。1.0.0
methodstring要执行的 HTTP 请求方法。（默认是 POST）1.0.0
paramsHttpParams要附加到请求的 URL 参数。1.0.0
headersHttpHeaders随请求发送的 HTTP 请求头。1.0.0
readTimeoutnumber等待读取额外数据的毫秒数。默认值为 60000 毫秒（1 分钟）。web 上不支持。1.0.0
connectTimeoutnumber等待初始连接的毫秒数。默认值为 60000 毫秒（1 分钟）。web 上不支持。1.0.0
disableRedirectsboolean设置是否禁用自动 HTTP 重定向。web 上不支持。1.0.0
shouldEncodeUrlParamsboolean如果您需要在某些情况下保持 URL 不编码，请使用此选项。默认为 true。web 上不支持。1.0.0

PluginListenerHandle​

属性类型
remove() => Promise<void>

ProgressStatus​

属性类型描述起始版本
type'download' | 'upload'传输操作的类型（下载或上传）。1.0.0
urlstring与传输关联的文件的 URL。1.0.0
bytesnumber迄今为止已传输的字节数。1.0.0
contentLengthnumber与文件传输关联的总字节数。1.0.0
lengthComputablebooleancontentLength 值是否相关。1.0.0

FileTransferError​

属性类型描述起始版本
codestring标识错误的代码：OS-PLUG-FLTR-XXXX。1.0.0
messagestring告知出错原因的消息。1.0.0
sourcestring文件传输操作的源（下载的 URL，上传的文件路径）。1.0.0
targetstring文件传输操作的目标（下载的文件路径，上传的 URL）。1.0.0
httpStatusnumber服务器响应的 HTTP 状态码（如果可用）。1.0.0
headers{ [key: string]: string; }来自服务器响应的 HTTP 头（如果可用）。1.0.0
bodystring来自服务器的 HTTP 错误响应体（如果可用）。1.0.0
exceptionstring原生端抛出的异常消息（如果可用）。1.0.0

错误​

插件在 iOS、Android 和 Web 上返回以下带有特定代码的错误：

错误代码平台描述
OS-PLUG-FLTR-0004Android, iOS方法的输入参数无效。
OS-PLUG-FLTR-0005Android, iOS提供的服务器 URL 无效或 URL 为空。
OS-PLUG-FLTR-0006Android, iOS无法执行操作，用户拒绝了权限请求。
OS-PLUG-FLTR-0007Android, iOS操作失败，因为文件不存在。
OS-PLUG-FLTR-0008Android, iOS, Web无法连接到服务器。
OS-PLUG-FLTR-0009Android, iOS服务器响应 HTTP 304 - 未修改。
OS-PLUG-FLTR-0010Android, iOS服务器响应了一个 HTTP 错误状态码。
OS-PLUG-FLTR-0011Android, iOS, Web操作失败并出现错误（通用错误）。

在应用中处理错误时，您可以检查错误代码以确定具体问题。错误对象通常包含额外信息，例如：

  • code：错误代码（如上表所示）
  • message：错误的人类可读描述
  • source：传输的源（文件路径或 URL）
  • target：传输的目标（文件路径或 URL）
  • httpStatus：HTTP 状态码（对于 HTTP 错误）
  • body：响应体（对于 HTTP 错误）
  • headers：响应头（对于 HTTP 错误）

Contents

编辑此页