{"_id":"@capacitor-ohos/file-transfer","_rev":"2-8feff411a45ed4f6fd85601e107c24d5","name":"@capacitor-ohos/file-transfer","dist-tags":{"latest":"2.0.1"},"versions":{"2.0.0":{"name":"@capacitor-ohos/file-transfer","version":"2.0.0","keywords":["capacitor","plugin","native"],"author":{"url":"Group","name":"Huawei Device Co., Ltd and iSoftStone Information Technology"},"license":"MIT","_id":"@capacitor-ohos/file-transfer@2.0.0","maintainers":[{"name":"luqi_tan","email":"295099422@qq.com"}],"bugs":{"url":"https://gitcode.com/CPF-Ionic/capacitor-file-transfer/issues"},"dist":{"shasum":"63c278bfc5d6eea5d752ee4a98253872f75876c5","tarball":"https://registry.npmjs.org/@capacitor-ohos/file-transfer/-/file-transfer-2.0.0.tgz","fileCount":10,"integrity":"sha512-VGDqBnV+9i/rG5LFkzB5ZyNLR9jng0nzLIPr2twRMhu4wPB+51i+Ra3cRNmaDkA93zARrBBk6fHe7VBgU9zeHg==","signatures":[{"sig":"MEUCIQCB9++6vyIYOXIIKpXoZwvh4jIq9FWmBQ0yWtTfKVRkrQIgXziC0CHcQq76wP/G9Xm4VtQz5ERA2tuDpVrvLiekd5I=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":95197},"gitHead":"fe61dab86bc4b416a1ebb726b464b4239f96e450","_npmUser":{"name":"luqi_tan","email":"295099422@qq.com"},"capacitor":{"id":"@capacitor/file-transfer","platforms":["openharmony"]},"repository":{"url":"gitcode:CPF-Ionic/capacitor-file-transfer","type":"git"},"_npmVersion":"10.5.1","description":"The FileTransfer API provides mechanisms for downloading and uploading files.","directories":{},"_nodeVersion":"22.0.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/file-transfer_2.0.0_1777545113421_0.796541511613611","host":"s3://npm-registry-packages-npm-production"}},"2.0.1":{"name":"@capacitor-ohos/file-transfer","version":"2.0.1","description":"The FileTransfer API provides mechanisms for downloading and uploading files.","capacitor":{"id":"@capacitor/file-transfer","platforms":["openharmony"]},"repository":{"type":"git","url":"gitcode:CPF-Ionic/capacitor-file-transfer"},"bugs":{"url":"https://gitcode.com/CPF-Ionic/capacitor-file-transfer/issues"},"keywords":["capacitor","plugin","native"],"author":{"name":"Huawei Device Co., Ltd and iSoftStone Information Technology","url":"Group"},"license":"MIT","_id":"@capacitor-ohos/file-transfer@2.0.1","gitHead":"10c317473a192b40da9eaab2cee635cc227bc9bf","_nodeVersion":"22.0.0","_npmVersion":"10.5.1","dist":{"integrity":"sha512-EeGWcpkK/t+TOVTdV+dKv2n0AEH0H8M7DoycbUT65/oBJjGs3mxinRfsYlQNsD5qYF+dZ8BRUsyHPkukJwYtlA==","shasum":"d74ac423edd15a0cb9d628a76e8b5d6307500734","tarball":"https://registry.npmjs.org/@capacitor-ohos/file-transfer/-/file-transfer-2.0.1.tgz","fileCount":10,"unpackedSize":95268,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIACxBrkIKQkTdXNmtWddaXB4sxGfZh/GdDhUVqpHX5MSAiAOYDfefM4P/VGjAAbmuxgnSoMpnv5pkTcpj6MaxZa0kw=="}]},"_npmUser":{"name":"luqi_tan","email":"295099422@qq.com"},"directories":{},"maintainers":[{"name":"luqi_tan","email":"295099422@qq.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/file-transfer_2.0.1_1784795083033_0.9923788579152795"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-30T10:31:53.238Z","modified":"2026-07-23T08:24:43.315Z","2.0.0":"2026-04-30T10:31:53.550Z","2.0.1":"2026-07-23T08:24:43.175Z"},"bugs":{"url":"https://gitcode.com/CPF-Ionic/capacitor-file-transfer/issues"},"author":{"name":"Huawei Device Co., Ltd and iSoftStone Information Technology","url":"Group"},"license":"MIT","keywords":["capacitor","plugin","native"],"repository":{"type":"git","url":"gitcode:CPF-Ionic/capacitor-file-transfer"},"description":"The FileTransfer API provides mechanisms for downloading and uploading files.","maintainers":[{"name":"luqi_tan","email":"295099422@qq.com"}],"readme":"# <center>@capacitor/file-transfer</center>\r\n[![zh-CN](https://img.shields.io/badge/lang-中文-blue.svg)](README.md)\r\n[![en](https://img.shields.io/badge/lang-English-blue.svg)](README.en.md)\r\n\r\n本项目基于 [@capacitor/file-transfer@2.0.0](https://www.npmjs.com/package/@capacitor/file-transfer/v/2.0.0) 开发。\r\n\r\n## 简介\r\n\r\n@capacitor/file-transfer是capacitor生态系统中的核心插件，提供文件上传与下载功能，可实现进度监听、请求头自定义等能力，为跨平台应用开发提供设备差异化适配能力，兼容capacitor的Android、iOS等主流移动平台及浏览器环境，本文档只说明在OpenHarmony系统中的使用。\r\n\r\nAPI提供完善的文件上传与下载功能，支持进度监听、请求参数自定义等核心能力，适配OpenHarmony系统的文件传输场景，调用便捷、适配性强。\r\n\r\n## 支持平台\r\n\r\n- **OpenHarmony**：5.0+\r\n\r\n## 下载安装\r\n\r\n通过命令行或手动引入即可快速安装插件，支持从npm仓库获取。\r\n\r\n### 命令行安装（推荐）\r\n\r\n安装hionic CLI：\r\n\r\n```bash\r\nnpm install -g hionic\r\n```\r\n\r\n以下两种方式中**任选其一**即可，无需重复操作：\r\n\r\nnpm安装：\r\n\r\n```bash\r\n# 安装插件\r\nnpm install @capacitor/file-transfer\r\n\r\n# 同步插件\r\nhionic sync openharmony\r\n```\r\n\r\nhionic CLI安装：\r\n\r\n```bash\r\nhionic plugin add @capacitor/file-transfer\r\n```\r\n\r\n### 手动引入安装\r\n\r\n根据插件源码中 `plugin.xml` 配置在项目中引入插件，步骤如下：\r\n\r\n#### 1. 添加插件配置\r\n\r\n根据 `plugin.xml` 的 `config-json` 项，通过 `target` 字段找到 `entry` 模块中 `capacitor.plugins.json` 文件，并根据 `param`\r\n标签添加配置如下：\r\n\r\n```json\r\n{\r\n  \"pkg\": \"@capacitor/file-transfer\",\r\n  \"classpath\": \"FileTransfer\"\r\n}\r\n```\r\n\r\n#### 2. 修改 CMake 配置\r\n\r\n根据 `plugin.xml` 的 `CMakeLists` 项，通过 `modules-name` 字段找到模块 `capacitor`，路径为 `target` 字段的\r\n`CMakeLists.txt` 文件，并添加 `add_subdirectory` 和 `target_link_libraries` 如下：\r\n\r\n```cmake\r\n#START_ADD_SUBDIRECTORY\r\n// ...\r\nadd_subdirectory(FileTransfer)\r\n// ...\r\n#END_ADD_SUBDIRECTORY\r\n\r\n// ...\r\n\r\ntarget_link_libraries(capacitor PUBLIC\r\n  // ...\r\n  \"-Wl,--whole-archive\"\r\n  // ...\r\n  FileTransfer\r\n  // ...\r\n  \"-Wl,--no-whole-archive\"\r\n)\r\n```\r\n\r\n#### 3. 复制源码文件\r\n\r\n根据 `plugin.xml` 的 `source-file` 项，根据 `src` 字段找到需要复制的文件，并根据 `modules-name` 字段和 `target-dir`\r\n字段找到文件复制的具体模块和目录，具体操作如下：\r\n\r\n将源码中src/main/cpp/FileTransfer目录下的FileTransfer.h、FileTransfer.cpp、CMakeLists.txt文件引入到capacitor模块中src/main/cpp/FileTransfer目录下。\r\n\r\n将源码中src/main/ets/components/FileTransfer目录下的FileTransferAction.ets文件引入到capacitor模块中src/main/ets/components/FileTransfer目录下。\r\n\r\n#### 4. 添加 ArkTS 配置\r\n\r\n在 `capacitor` 模块的 `build-profile.json5` 文件中，`buildOption/arkOptions/runtimeOnly/sources`\r\n配置项数组中加入步骤3中拷贝的ets文件路径，具体配置如下：\r\n\r\n```json\r\n{\r\n  \"buildOption\": {\r\n    // ...\r\n    \"arkOptions\": {\r\n      \"runtimeOnly\": {\r\n        \"sources\": [\r\n          // ...\r\n          \"./src/main/ets/components/FileTransfer/FileTransferAction.ets\"\r\n          // ...\r\n        ]\r\n      }\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n## 卸载\r\n\r\n```bash\r\n# 卸载 file-transfer 插件\r\nhionic plugin remove @capacitor/file-transfer\r\n```\r\n\r\n## 约束与限制\r\n\r\n### 兼容性\r\n\r\n在以下版本中已测试通过：\r\n\r\n1. capacitor: 8.0.0-ohos-8.0.0; SDK: 5.0.5(17); IDE: DevEco Studio: 6.0.0; ROM: 5.1.0.150;\r\n\r\n### 权限要求\r\n\r\n插件依赖OpenHarmony系统 `ohos.permission.INTERNET` 权限，需在应用中提前申请，否则将导致文件上传、下载功能失效。\r\n\r\nOpenHarmony应用权限添加参考[申请应用权限](https://docs.openharmony.cn/pages/v6.0/zh-cn/application-dev/security/AccessToken/declare-permissions.md)\r\n，在主工程的 `module.json5` 的 requestPermissions 中添加 ohos.permission.INTERNET 权限，示例如下：\r\n\r\n```json\r\n{\r\n  \"name\": \"ohos.permission.INTERNET\"\r\n}\r\n```\r\n\r\n## 使用示例\r\n\r\n### 示例1：下载文件\r\n\r\n```typescript\r\nimport { FileTransfer } from '@capacitor/file-transfer';\r\nimport { Filesystem, Directory } from '@capacitor/filesystem';\r\n\r\n// First get the full file path using Filesystem\r\nconst fileInfo = await Filesystem.getUri({\r\n  directory: Directory.Data,\r\n  path: '' // 空字符串获取目录路径\r\n});\r\n\r\ntry {\r\n  // Then use the FileTransfer plugin to download\r\n  await FileTransfer.downloadFile({\r\n    url: 'https://example.com/file.pdf',\r\n    path: fileInfo.uri,\r\n    progress: true\r\n  });\r\n} catch (error) {\r\n  const errorMsg = error instanceof Error ? error.message : String(error);\r\n  console.error('下载文件失败:', errorMsg);\r\n}\r\n\r\n// Progress events\r\nFileTransfer.addListener('progress', (progress) => {\r\n  console.log(`Downloaded ${progress.bytes} of ${progress.contentLength}`);\r\n});\r\n```\r\n\r\n### 示例2：上传文件\r\n\r\n```typescript\r\nimport { FileTransfer } from '@capacitor/file-transfer';\r\nimport { Filesystem, Directory } from '@capacitor/filesystem';\r\n\r\n// First get the full file path using Filesystem\r\nconst fileInfo = await Filesystem.getUri({\r\n  directory: Directory.Cache,\r\n  path: 'image_upload.png'\r\n});\r\n\r\ntry {\r\n  // Then use the FileTransfer plugin to upload\r\n  const result = await FileTransfer.uploadFile({\r\n    url: 'https://example.com/upload_api',\r\n    path: fileInfo.uri,\r\n    chunkedMode: false,\r\n    progress: false\r\n  });\r\n} catch (error) {\r\n  const errorMsg = error instanceof Error ? error.message : String(error);\r\n  console.error('上传文件失败:', errorMsg);\r\n}\r\n```\r\n\r\n### 示例3：进度监听（上传/下载通用）\r\n\r\n```typescript\r\nimport { FileTransfer } from '@capacitor/file-transfer';\r\nimport { Filesystem, Directory } from '@capacitor/filesystem';\r\n\r\n// 监听进度事件\r\nconst progressListener = await FileTransfer.addListener('progress', (progress) => {\r\n  // 计算进度百分比\r\n  const progressPercent = progress.contentLength ? Math.round((progress.bytes / progress.contentLength) * 100) : 0;\r\n  console.log(`传输进度：${progressPercent}%，已传输：${progress.bytes}字节，总大小：${progress.contentLength}字节`);\r\n});\r\n\r\n// 下载文件（带进度监听）\r\nconst fileInfo = await Filesystem.getUri({\r\n  directory: Directory.Documents,\r\n  path: 'document.pdf'\r\n});\r\n\r\nawait FileTransfer.downloadFile({\r\n  url: 'https://example.com/document.pdf',\r\n  path: fileInfo.uri,\r\n  progress: true // 必须开启progress，否则不触发进度事件\r\n});\r\n\r\n// 移除监听（无需监听时调用）\r\nawait progressListener.remove();\r\n\r\n// 移除所有监听\r\nawait FileTransfer.removeAllListeners();\r\n```\r\n\r\n## 使用说明\r\n\r\nFileTransfer是插件导出对象，可直接导入使用，导入后即可调用插件提供的所有方法，调用便捷高效，所有API均基于Promise实现，支持异步调用；使用前需确保已申请\r\n`ohos.permission.INTERNET` 权限，适用于各类文件上传、下载及进度监听场景。\r\n\r\n## 核心 API：FileTransfer 对象\r\n\r\nFileTransfer 是插件导出对象，可直接导入使用，导入后即可调用插件提供的所有方法，调用便捷高效。依赖OpenHarmony系统\r\n`ohos.permission.INTERNET` 权限。\r\n\r\n### 方法列表与说明\r\n\r\n| 方法名                                        | 返回类型                                                         | 描述                    |\r\n|--------------------------------------------|--------------------------------------------------------------|-----------------------|\r\n| downloadFile(options: [DownloadFileOptions](#downloadfileoptions)) | Promise&lt;[DownloadFileResult](#downloadfileresult)&gt;     | 将文件下载到指定位置            |\r\n| uploadFile(options: UploadFileOptions)     | Promise&lt;[UploadFileResult](#uploadfileresult)&gt;         | 将文件上传到服务器             |\r\n| addListener('progress', ...)               | Promise&lt;[PluginListenerHandle](#pluginlistenerhandle)&gt; | 添加文件传输（下载或上传）进度事件的监听器 |\r\n| removeAllListeners()                       | Promise&lt;void&gt;                                          | 移除此插件的所有监听器           |\r\n\r\n### 数据结构\r\n\r\n#### DownloadFileResult\r\n\r\ndownloadFile 方法的返回结果对象，包含下载文件的相关信息。\r\n\r\n| 属性   | 类型     | 描述            | 备注                           |\r\n|------|--------|---------------|------------------------------|\r\n| path | string | 文件下载到的路径      | -                            |\r\n| blob | Blob   | 下载文件的 blob 数据 | 仅在 Web 平台可用，OpenHarmony平台不支持 |\r\n\r\n#### DownloadFileOptions\r\n\r\n调用 downloadFile 方法时的入参对象，用于配置文件下载相关参数。\r\n\r\n| 属性                    | 类型          | 描述                                                       | 备注                        |\r\n|-----------------------|-------------|----------------------------------------------------------|---------------------------|\r\n| url                   | string      | 用于下载文件的统一资源定位符（URL）                                      |                           |\r\n| path                  | string      | 下载文件应移动至的完整文件路径。可使用 @capacitor/filesystem 这类插件获取完整文件路径   |                           |\r\n| progress              | boolean     | 是否派发进度事件（progress event）。默认值为 false                      |                           |\r\n| method                | string      | HTTP请求方法。（默认值为 GET）                                      |                           |\r\n| params                | HttpParams  | 需附加到请求中的 URL 参数                                          |                           |\r\n| headers               | HttpHeaders | 需随请求一同发送的 HTTP 请求头                                       |                           |\r\n| readTimeout           | number      | 等待读取额外数据的时长（单位：毫秒）。每次接收到新数据时，该时长会重置。默认值为 60,000 毫秒（1 分钟） | OpenHarmony平台不支持          |\r\n| connectTimeout        | number      | 等待初始连接的时长（单位：毫秒）。默认值为 60,000 毫秒（1 分钟）                    | OpenHarmony平台api20及以上版本支持 |\r\n| disableRedirects      | boolean     | 设置是否应禁用 HTTP 自动重定向功能                                     |                           |\r\n| shouldEncodeUrlParams | boolean     | 是否对URL参数进行编码。默认值为 true（即默认对 URL 参数进行编码）                  |                           |\r\n\r\n#### UploadFileResult\r\n\r\nuploadFile 方法的返回结果对象，包含文件上传的相关信息。\r\n\r\n| 属性           | 类型                         | 描述                   |\r\n|--------------|----------------------------|----------------------|\r\n| bytesSent    | number                     | 已上传的总字节数             |\r\n| responseCode | string                     | 上传操作的 HTTP 响应码       |\r\n| response     | string                     | 上传操作的 HTTP 响应体（如果可用） |\r\n| headers      | { [key: string]: string; } | 上传响应的 HTTP 头信息（如果可用） |\r\n\r\n#### PluginListenerHandle\r\n\r\n| 属性名    | 类型                        |\r\n|--------|---------------------------|\r\n| remove | () => Promise&lt;void&gt; |\r\n\r\n#### UploadFileOptions\r\n\r\n调用 uploadFile 方法时的入参对象，用于配置文件上传相关参数。\r\n\r\n| 属性                    | 类型          | 描述                                                                                                                                                                                                          | 备注                           |\r\n|-----------------------|-------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------|\r\n| url                   | string      | 用于上传文件的统一资源定位符（URL）                                                                                                                                                                                         |                              |\r\n| path                  | string      | 待上传文件的完整文件路径。可使用 @capacitor/filesystem 这类插件获取完整文件路径                                                                                                                                                         |                              |\r\n| blob                  | Blob        | 待上传的二进制大对象（Blob）数据                                                                                                                                                                                          | 仅在 Web 平台可用，OpenHarmony平台不支持 |\r\n| chunkedMode           | boolean     | 是否以分块流模式上传数据。Web 平台不支持此属性。注意：当 chunkedMode 设为 true（启用）时，上传请求将使用 Content-Type: multipart/form-data。根据后端服务器的配置，这可能导致上传失败。若服务器期望接收原始流数据（例如 application/octet-stream，二进制流类型），则必须在 headers中显式设置 Content-Type 头信息 |                              |\r\n| mimeType              | string      | 待上传数据的多用途互联网邮件扩展类型（MIME Type）。仅在未提供 \"Content-Type\"（内容类型）请求头时生效                                                                                                                                              |                              |\r\n| fileKey               | string      | 表单元素类型。默认值设为 \"file\"（文件）。仅在未提供 \"Content-Type\" 请求头时生效                                                                                                                                                         |                              |\r\n| progress              | boolean     | 是否派发进度事件（progress event）。 默认值为 false                                                                                                                                                                        |                              |\r\n| method                | string      | HTTP请求方法。（默认值为 POST）                                                                                                                                                                                        |                              |\r\n| params                | HttpParams  | 需附加到请求中的 URL 参数                                                                                                                                                                                             |                              |\r\n| headers               | HttpHeaders | 需随请求一同发送的 HTTP 请求头                                                                                                                                                                                          |                              |\r\n| readTimeout           | number      | 等待读取额外数据的时长（单位：毫秒）。每次接收到新数据时，该时长会重置。默认值为 60,000 毫秒（1 分钟）                                                                                                                                                    |                              |\r\n| connectTimeout        | number      | 等待初始连接的时长（单位：毫秒）。默认值为 60,000 毫秒（1 分钟）                                                                                                                                                                       |                              |\r\n| disableRedirects      | boolean     | 设置是否应禁用 HTTP 自动重定向功能                                                                                                                                                                                        |                              |\r\n| shouldEncodeUrlParams | boolean     | 是否对URL参数进行编码。默认值为 true（即默认对 URL 参数进行编码）                                                                                                                                                                     |                              |\r\n\r\n## 目录结构\r\n\r\n```plaintext\r\n|---- 目录\r\n|     |---- src/main  # 插件的实现代码\r\n|           |----cpp  # C++ 代码\r\n|           |----ets   # ArkTS 代码\r\n|     |---- README.md          # 说明文档\r\n|     |---- package.json       # 配置文件\r\n|     |---- plugin.xml         # 插件配置文件\r\n```\r\n\r\n## 贡献代码\r\n\r\n使用过程中发现任何问题都可以提 [Issue](https://gitcode.com/CPF-Ionic/capacitor-file-transfer/issues)\r\n，当然，也非常欢迎发[PR](https://gitcode.com/CPF-Ionic/capacitor-file-transfer/pulls) 共建。\r\n\r\n## 许可证\r\n\r\n本插件基于 **MIT License** 开源，详见 [LICENSE](./LICENSE) 文件。","readmeFilename":"README.md"}