跳到主要内容
版本：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 错误 - 有关 `errorData` 中可用字段的详细信息，请参阅 `FileTransferError`
      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 错误 - 有关 `errorData` 中可用字段的详细信息，请参阅 `FileTransferError`
      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
属性类型说明始版
urlstring要下载文件的 URL。1.0.0
pathstring下载文件应移动到的完整文件路径。你可以使用像 @capacitor/filesystem 这样的插件来获取完整的文件路径。1.0.0
progressboolean如果为 true，每次接收到数据块时都会分派进度事件。更多信息请参阅 addListener()。在 Android/iOS 上，为了避免速度下降，数据块会被节流到每 100ms 一次。默认值为 false。1.0.0
methodstring要运行的 HTTP 请求方法。（默认为 GET）1.0.0
params
HttpParams
要附加到请求的 URL 参数。此 HttpParams 接口来自 @capacitor/core。1.0.0
headers
HttpHeaders
要随请求发送的 HTTP 请求头。此 HttpHeaders 接口来自 @capacitor/core。1.0.0
readTimeoutnumber等待读取额外数据的时长（毫秒）。每次接收到新数据时重置。默认为 60,000 毫秒（1 分钟）。Web 平台不支持。1.0.0
connectTimeoutnumber等待初始连接的时长（毫秒）。默认为 60,000 毫秒（1 分钟）。在 iOS 上，connectTimeout 和 readTimeout 没有真正的区别。插件会尝试使用 connectTimeout，如果没有则使用 readTimeout，如果都没有则使用默认值。1.0.0
disableRedirectsboolean设置是否应禁用自动 HTTP 重定向。1.0.0
shouldEncodeUrlParamsboolean如果你需要在某些情况下（已经编码、Azure/Firebase 测试等）保持 URL 未编码，请使用此选项。默认值为 true。Web 平台不支持。1.0.0

HttpParams​

HttpHeaders​

上传文件结果​

属性类型说明始版
bytesSentnumber上传的总字节数1.0.0
responseCodestring上传的 HTTP 响应码1.0.0
responsestring上传的 HTTP 响应体（如果可用）1.0.0
headers{ [key: string]: string; }上传响应的 HTTP 头信息（如果可用）1.0.0
属性类型说明版本
urlstring文件上传的目标 URL。1.0.0
pathstring要上传文件的完整路径。可以使用 @capacitor/filesystem 等插件来获取完整的文件路径。1.0.0
blobBlob要上传的 Blob 数据。如果提供了此参数，将优先使用 blob 而不是 path。此选项仅在 Web 平台上可用。1.0.0
chunkedModeboolean是否以分块流模式上传数据。Web 平台不支持。注意：当 chunkedMode 为 true 时，上传会使用 Content-Type: multipart/form-data。根据后端服务器的不同，这可能导致上传失败。如果服务器期望接收原始数据流（例如 application/octet-stream），则必须在 headers 中显式设置 Content-Type 请求头。1.0.0
mimeTypestring要上传数据的 MIME 类型。仅在未提供 "Content-Type" 请求头时使用。1.0.0
fileKeystring表单元素的类型。默认为 "file"。仅在未提供 "Content-Type" 请求头时使用。1.0.0
progressboolean如果设为 true，则每收到一个数据块都会触发进度事件。更多信息请参考 addListener()。在 Android/iOS 上，为避免性能下降，事件触发频率被限制为每 100 毫秒一次。默认为 false。1.0.0
methodstring要执行的 HTTP 请求方法。（默认为 POST）1.0.0
params
HttpParams
要附加到请求的 URL 参数。此 HttpParams 接口来自 @capacitor/core。1.0.0
headers
HttpHeaders
要与请求一起发送的 HTTP 请求头。此 HttpHeaders 接口来自 @capacitor/core。1.0.0
readTimeoutnumber等待读取额外数据的超时时间（毫秒）。每次收到新数据时重置。默认为 60,000 毫秒（1 分钟）。Web 平台不支持。1.0.0
connectTimeoutnumber等待初始连接的超时时间（毫秒）。默认为 60,000 毫秒（1 分钟）。Web 平台不支持。在 iOS 上，connectTimeout 和 readTimeout 没有实质区别。插件会尝试使用 connectTimeout，如果没有则使用 readTimeout，如果都没有则使用默认值。1.0.0
disableRedirectsboolean设置是否禁用自动 HTTP 重定向。Web 平台不支持。1.0.0
shouldEncodeUrlParamsboolean在特定情况下（例如 URL 已编码、Azure/Firebase 测试等），如果需要保持 URL 不编码，请使用此选项。默认为 true。Web 平台不支持。1.0.0

PluginListenerHandle​

属性类型
remove() => Promise<void>
属性类型描述始于版本
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-XXXX1.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 无效或为空。
OS-PLUG-FLTR-0006Android, iOS操作失败，用户拒绝了权限请求。
OS-PLUG-FLTR-0007Android, iOS操作失败，因为文件不存在。
OS-PLUG-FLTR-0008Android, iOS, Web连接服务器失败。
OS-PLUG-FLTR-0009Android, iOS服务器返回 HTTP 304 – 未修改。如需避免此错误，请检查与 HTTP 缓存相关的头部信息。
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

编辑此页