版本：v8

@capacitor/file-transfer

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

安装

npm install @capacitor/file-transfer
npx cap sync

Example

Download

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

// First get the full file path using Filesystem
const fileInfo = await Filesystem.getUri({
  directory: Directory.Data,
  path: 'downloaded-file.pdf'
});

try {
    // Then use the FileTransfer plugin to download
    await FileTransfer.downloadFile({
        url: 'https://example.com/file.pdf',
        path: fileInfo.uri,
        progress: true
    });
} catch(error) {
    // handle error - see `FileTransferError` interface for what error information is returned
}

// Progress events
FileTransfer.addListener('progress', (progress) => {
  console.log(`Downloaded ${progress.bytes} of ${progress.contentLength}`);
});

Upload

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

// First get the full file path using Filesystem
const fileInfo = await Filesystem.getUri({
  directory: Directory.Cache,
  path: 'image_upload.png'
});

try {
    // Then use the FileTransfer plugin to upload
    const result = await FileTransfer.downloadFile({
        url: 'https://example.com/upload_api',
        path: fileInfo.uri,
        chunkedMode: true,
        headers: {
            // Upload uses `multipart/form-data` by default.
            // If you want to avoid that, you can set the 'Content-Type' header explicitly.
            'Content-Type': 'application/octet-stream',
        },
        progress: false
    });
    // get server response and other info from result - see `UploadFileResult` interface
} catch(error) {
    // handle error - see `FileTransferError` interface for what error information is returned
}

API

downloadFile(...)
uploadFile(...)
addListener('progress', ...)
removeAllListeners()
接口

Note: Some of the input options come from HttpOptions in @capacitor/core, but the plugin does not use all parameters from HttpOptions. The ones that are used are documented below.

For list of existing error codes, see Errors.

downloadFile(...)

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

向服务器发起 HTTP 请求并将文件下载到指定位置。

参数	类型
`options`	`DownloadFileOptions`

返回值：

Promise<DownloadFileResult>

自版本： 1.0.0

uploadFile(...)

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

执行 HTTP 请求将文件上传到服务器

参数	类型
`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

Interfaces

DownloadFileResult

属性	类型	描述	自版本
`path`	`string`	文件下载到的路径。	1.0.0
`blob`	`Blob`	下载文件的 blob 数据。此属性仅在 Web 平台可用。	1.0.0

DownloadFileOptions

属性（Prop）	类型（Type）	描述（Description）	起始版本（Since）
`url`	`string`（字符串）	用于下载文件的统一资源定位符（URL）。	1.0.0
`path`	`string`（字符串）	下载文件应移动至的完整文件路径。你可使用 `@capacitor/filesystem` 这类插件获取完整文件路径。	1.0.0
`progress`	`boolean`（布尔值）	若为 `true`，则每接收到一个数据块（chunk）时都会派发进度事件（progress event）。更多信息可参考 `addListener()` 方法。在 Android/iOS 平台上，为避免性能下降，数据块的派发频率会限制为每 100 毫秒一次。默认值为 `false`。	1.0.0
`method`	`string`（字符串）	要执行的超文本传输协议（HTTP）请求方法。（默认值为 GET）	1.0.0
`params`	`HttpParams`	需附加到请求中的 URL 参数。此 `HttpParams` 接口来源于 `@capacitor/core`。	1.0.0
`headers`	`HttpHeaders`	需随请求一同发送的 HTTP 请求头。此 `HttpHeaders` 接口来源于 `@capacitor/core`。	1.0.0
`readTimeout`	`number`（数字）	等待读取额外数据的时长（单位：毫秒）。每次接收到新数据时，该时长会重置。默认值为 60,000 毫秒（1 分钟）。Web 平台不支持此属性。	1.0.0
`connectTimeout`	`number`（数字）	等待初始连接的时长（单位：毫秒）。默认值为 60,000 毫秒（1 分钟）。在 iOS 平台上，`connectTimeout`（连接超时）与 `readTimeout`（读取超时）并无实质区别：插件会优先尝试使用 `connectTimeout`，若不可用则使用 `readTimeout`，若两者均不可用则使用默认值。	1.0.0
`disableRedirects`	`boolean`（布尔值）	设置是否应禁用 HTTP 自动重定向功能。	1.0.0
`shouldEncodeUrlParams`	`boolean`（布尔值）	若你需在特定场景下保持 URL 不编码（如 URL 已预先编码、进行 Azure/Firebase 测试等），可使用此选项。默认值为 `true`（即默认对 URL 参数进行编码）。Web 平台不支持此属性。	1.0.0

HttpParams

HttpHeaders

UploadFileResult

属性	类型	描述	自版本
`bytesSent`	`number`	已上传的总字节数	1.0.0
`responseCode`	`string`	上传操作的 HTTP 响应码	1.0.0
`response`	`string`	上传操作的 HTTP 响应体（如果可用）	1.0.0
`headers`	`{ [key: string]: string; }`	上传响应的 HTTP 头信息（如果可用）	1.0.0

UploadFileOptions

属性（Prop）	类型（Type）	描述（Description）	起始版本（Since）
`url`	`string`（字符串）	用于上传文件的统一资源定位符（URL）。	1.0.0
`path`	`string`（字符串）	待上传文件的完整文件路径。你可使用 `@capacitor/filesystem` 这类插件获取完整文件路径。	1.0.0
`blob`	`Blob`（二进制大对象）	待上传的二进制大对象（Blob）数据。若提供该参数，将优先使用此 Blob 数据而非文件路径。此属性仅在 Web 平台可用。	1.0.0
`chunkedMode`	`boolean`（布尔值）	是否以分块流模式（chunked streaming mode）上传数据。Web 平台不支持此属性。注意：当 `chunkedMode` 设为 `true`（启用）时，上传请求将使用 `Content-Type: multipart/form-data`（多部分表单数据类型）。根据后端服务器的配置，这可能导致上传失败。若你的服务器期望接收原始流数据（例如 `application/octet-stream`，二进制流类型），则必须在 `headers`（请求头）中显式设置 `Content-Type` 头信息。	1.0.0
`mimeType`	`string`（字符串）	待上传数据的多用途互联网邮件扩展类型（MIME Type）。仅在未提供 "Content-Type"（内容类型）请求头时生效。	1.0.0
`fileKey`	`string`（字符串）	表单元素类型。默认值设为 "file"（文件）。仅在未提供 "Content-Type" 请求头时生效。	1.0.0
`progress`	`boolean`（布尔值）	若设为 `true`（启用），则每接收到一个数据块（chunk）时都会派发进度事件（progress event）。更多详情可参考 `addListener()` 方法。在 Android/iOS 平台上，为避免性能下降，数据块的派发频率会限制为每 100 毫秒一次。默认值为 `false`（禁用）。	1.0.0
`method`	`string`（字符串）	要执行的超文本传输协议（HTTP）请求方法。（默认值为 POST）	1.0.0
`params`	`HttpParams`	需附加到请求中的 URL 参数。此 `HttpParams` 接口来源于 `@capacitor/core`。	1.0.0
`headers`	`HttpHeaders`	需随请求一同发送的 HTTP 请求头。此 `HttpHeaders` 接口来源于 `@capacitor/core`。	1.0.0
`readTimeout`	`number`（数字）	等待读取额外数据的时长（单位：毫秒）。每次接收到新数据时，该时长会重置。默认值为 60,000 毫秒（1 分钟）。Web 平台不支持此属性。	1.0.0
`connectTimeout`	`number`（数字）	等待初始连接的时长（单位：毫秒）。默认值为 60,000 毫秒（1 分钟）。Web 平台不支持此属性。在 iOS 平台上，`connectTimeout`（连接超时）与 `readTimeout`（读取超时）并无实质区别：插件会优先尝试使用 `connectTimeout`，若不可用则使用 `readTimeout`，若两者均不可用则使用默认值。	1.0.0
`disableRedirects`	`boolean`（布尔值）	设置是否应禁用 HTTP 自动重定向功能。Web 平台不支持此属性。	1.0.0
`shouldEncodeUrlParams`	`boolean`（布尔值）	若需在特定场景下保持 URL 不编码（如 URL 已预先编码、进行 Azure/Firebase 测试等），可使用此选项。默认值为 `true`（启用 URL 参数编码）。Web 平台不支持此属性。	1.0.0

PluginListenerHandle

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

ProgressStatus

属性	类型	描述	自版本
`type`	`'download' \| 'upload'`	传输操作的类型（下载或上传）。	1.0.0
`url`	`string`	与传输（下载或上传）关联的文件 URL。	1.0.0
`bytes`	`number`	到目前为止已传输的字节数。	1.0.0
`contentLength`	`number`	与文件传输关联的总字节数。	1.0.0
`lengthComputable`	`boolean`	contentLength 值是否相关。在某些情况下，可能无法确定总字节数。	1.0.0

错误信息

该插件在 iOS、Android 和 Web 平台上会返回以下特定代码的错误：

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

在应用程序中处理错误时，您可以检查错误代码以确定具体问题。错误对象通常包含以下附加信息：

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

安装​

Example​

Download​

Upload​

API​

downloadFile(...)​

uploadFile(...)​

addListener('progress', ...)​

removeAllListeners()​

Interfaces​

DownloadFileResult​

DownloadFileOptions​

HttpParams​

HttpHeaders​

UploadFileResult​

UploadFileOptions​

PluginListenerHandle​

ProgressStatus​

错误信息​

Contents

安装

Example

Download

Upload

API

downloadFile(...)

uploadFile(...)

addListener('progress', ...)

removeAllListeners()

Interfaces

DownloadFileResult

DownloadFileOptions

HttpParams

HttpHeaders

UploadFileResult

UploadFileOptions

PluginListenerHandle

ProgressStatus

错误信息