{"_id":"@cordova-ohos/cordova-plugin-file-transfer","_rev":"3-40e9d9b5d7610dae2a49b0d49486805e","name":"@cordova-ohos/cordova-plugin-file-transfer","dist-tags":{"latest":"2.0.1"},"versions":{"2.0.0":{"name":"@cordova-ohos/cordova-plugin-file-transfer","version":"2.0.0","keywords":["cordova","file-transfer","ecosystem:cordova","cordova-openharmony"],"author":{"name":"Huawei Device, Inc. Ltd. and","email":"马弓手"},"license":"Apache-2.0","_id":"@cordova-ohos/cordova-plugin-file-transfer@2.0.0","maintainers":[{"name":"luqi_tan","email":"295099422@qq.com"},{"name":"wanpengsz","email":"wanpengsz@163.com"},{"name":"xkh111","email":"xukaihui11@163.com"}],"bugs":{"url":"https://gitcode.com/OpenHarmony-Cordova/cordova-plugin-file-transfer/issues"},"dist":{"shasum":"7367bad4e7966b23a4752b39c6ab6b89260e9e48","tarball":"https://registry.npmjs.org/@cordova-ohos/cordova-plugin-file-transfer/-/cordova-plugin-file-transfer-2.0.0.tgz","fileCount":9,"integrity":"sha512-bShHzfH1jzHXB4z4eP2QFQoMqmSh/7OyP1edcu8d9WeBJ0o260MXFt7b/g3jxICDnYU74+V8XsQh1/ShJlEfMw==","signatures":[{"sig":"MEQCIAI0OpjYDTiTNmQYg8iu6gBobST69CH0AchwPM+ap5XYAiAW0nHHKu1ePhwEBq1aQg9B8AvxGagN8qUtwI7lTgCWzQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":76734},"cordova":{"id":"cordova-plugin-file-transfer","platforms":["ohos"]},"engines":{"cordovaDependencies":{"2.0.0":{"hcordova":">=1.0.0","@cordova-ohos/ohos":">=2.0.0"}}},"gitHead":"15c19025fc27c9c1550d7690622229d513f021d4","_npmUser":{"name":"wanpengsz","email":"wanpengsz@163.com"},"repository":{"url":"gitcode:OpenHarmony-Cordova/cordova-plugin-file-transfer","type":"git"},"_npmVersion":"9.6.2","description":"Cordova File Transfer Plugin","directories":{},"_nodeVersion":"20.16.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/cordova-plugin-file-transfer_2.0.0_1773991787570_0.27118062705668056","host":"s3://npm-registry-packages-npm-production"}},"2.0.1":{"name":"@cordova-ohos/cordova-plugin-file-transfer","version":"2.0.1","description":"Cordova File Transfer Plugin","cordova":{"id":"cordova-plugin-file-transfer","platforms":["ohos"]},"repository":{"type":"git","url":"gitcode:CPF-Cordova/cordova-plugin-file-transfer"},"bugs":{"url":"https://gitcode.com/CPF-Cordova/cordova-plugin-file-transfer/issues"},"keywords":["cordova","file-transfer","ecosystem:cordova","cordova-openharmony"],"engines":{"cordovaDependencies":{"2.0.1":{"@cordova-ohos/ohos":">=2.0.0","hcordova":">=1.0.0"}}},"author":{"name":"Huawei Device, Inc. Ltd. and","email":"马弓手"},"license":"Apache-2.0","_id":"@cordova-ohos/cordova-plugin-file-transfer@2.0.1","gitHead":"dbab76bbc31f578b5f3836ab11b62079354c99ee","_nodeVersion":"22.0.0","_npmVersion":"10.5.1","dist":{"integrity":"sha512-aeQxvmrouFxYcvGZjmr/YDKIPpBVmaYtbjL1Bmor2s09zA09Vynm6PMjcX4h5gsFki+NuV/63xCyQ1GKvOhHRw==","shasum":"9652b24b1a2959b345978ebbf88012e6c3d73714","tarball":"https://registry.npmjs.org/@cordova-ohos/cordova-plugin-file-transfer/-/cordova-plugin-file-transfer-2.0.1.tgz","fileCount":10,"unpackedSize":102868,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDMDBLzDJcaIs8Yx0YP5aTDHyZR2Jsq49Mutsq9qbPduwIgSKmjO0piFdfkGOQMz2VQae00SV5WcMnqC+FNlWvAxjQ="}]},"_npmUser":{"name":"luqi_tan","email":"295099422@qq.com"},"directories":{},"maintainers":[{"name":"luqi_tan","email":"295099422@qq.com"},{"name":"wanpengsz","email":"wanpengsz@163.com"},{"name":"xkh111","email":"xukaihui11@163.com"},{"name":"hcordova","email":"chenlihuiabc@163.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/cordova-plugin-file-transfer_2.0.1_1785144676775_0.32001165363877626"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-20T07:29:47.461Z","modified":"2026-07-27T09:31:17.143Z","2.0.0":"2026-03-20T07:29:47.703Z","2.0.1":"2026-07-27T09:31:16.901Z"},"bugs":{"url":"https://gitcode.com/CPF-Cordova/cordova-plugin-file-transfer/issues"},"author":{"name":"Huawei Device, Inc. Ltd. and","email":"马弓手"},"license":"Apache-2.0","keywords":["cordova","file-transfer","ecosystem:cordova","cordova-openharmony"],"repository":{"type":"git","url":"gitcode:CPF-Cordova/cordova-plugin-file-transfer"},"description":"Cordova File Transfer Plugin","maintainers":[{"name":"luqi_tan","email":"295099422@qq.com"},{"name":"wanpengsz","email":"wanpengsz@163.com"},{"name":"xkh111","email":"xukaihui11@163.com"},{"name":"hcordova","email":"chenlihuiabc@163.com"}],"readme":"# cordova-plugin-file-transfer\r\n\r\n[](README.md)\r\n[](README.en.md)\r\n\r\n本项目基于 [cordova-plugin-file-transfer@2.0.0](https://www.npmjs.com/package/cordova-plugin-file-transfer/v/2.0.0) 开发，本文档重点阐述其在 OpenHarmony（OHOS）系统中的具体应用。\r\n\r\n- [cordova-plugin-file-transfer](#cordova-plugin-file-transfer)\r\n - [简介](#简介)\r\n - [支持平台](#支持平台)\r\n - [下载安装](#下载安装)\r\n - [从 npm 安装（推荐）](#从-npm-安装推荐)\r\n - [指定平台安装 ohos](#指定平台安装-ohos)\r\n - [从 GitCode 仓库安装](#从-gitcode-仓库安装)\r\n - [离线安装（本地包）](#离线安装本地包)\r\n - [安装后验证](#安装后验证)\r\n - [卸载](#卸载)\r\n - [约束与限制](#约束与限制)\r\n - [兼容性](#兼容性)\r\n - [使用示例](#使用示例)\r\n - [示例 1：上传图片](#示例-1上传图片)\r\n - [示例 2：下载图片](#示例-2下载图片)\r\n - [使用说明](#使用说明)\r\n - [核心 API 说明](#核心-api-说明)\r\n - [1. 构造函数：创建文件传输对象](#1-构造函数创建文件传输对象)\r\n - [2. 核心方法：上传文件](#2-核心方法上传文件)\r\n - [3. 核心方法：下载文件](#3-核心方法下载文件)\r\n - [4. 事件：进度监听](#4-事件进度监听)\r\n - [5. 方法：取消传输](#5-方法取消传输)\r\n - [参数配置详解](#参数配置详解)\r\n - [1. 上传配置（FileUploadOptions）](#1-上传配置fileuploadoptions)\r\n - [2. 下载配置（FileDownloadOptions）](#2-下载配置filedownloadoptions)\r\n - [错误码与处理方案](#错误码与处理方案)\r\n - [目录结构](#目录结构)\r\n - [贡献代码](#贡献代码)\r\n - [许可证](#许可证)\r\n - [官方资源](#官方资源)\r\n\r\n\r\n## 简介\r\n\r\ncordova-plugin-file-transfer 是 Cordova 官方生态核心插件，专注于跨平台文件传输场景，为 Cordova 应用提供统一的文件上传与下载接口，无需关注不同平台底层传输实现差异。插件支持 HTTP/HTTPS 协议，适配 `cordova-plugin-file` 插件实现本地文件操作，具备大文件断点传输、实时进度监听、灵活参数配置、完善错误处理及安全传输等核心能力，广泛应用于图片上传、资源下载、日志同步等移动应用常见场景，本文档重点说明其在 OHOS 系统中的应用方法。核心特性包括：\r\n\r\n- 跨平台统一接口：一套代码适配 Android、iOS、OHOS 等平台，无需关注底层传输实现差异\r\n\r\n- 完整文件传输能力：支持文件上传（multipart/form-data 格式）与下载（断点续传）\r\n\r\n- 实时进度监听：提供上传/下载进度回调，支持显示进度条\r\n\r\n- 灵活参数配置：支持自定义请求头、超时时间、文件 MIME 类型、表单字段等\r\n\r\n- 错误处理机制：提供明确的错误码与描述，覆盖网络异常、文件不存在、权限不足等场景\r\n\r\n- 安全传输支持：兼容 HTTPS 协议\r\n\r\n## 支持平台\r\n\r\n- **Android**：API 19 及以上（Android 4.4+）\r\n\r\n- **iOS**：10.0 及以上\r\n\r\n- **OHOS**：5.0+\r\n\r\n## 下载安装\r\n\r\n通过 hcordova CLI 即可快速安装插件，支持从 npm 仓库或 GitCode 仓库获取。\r\n\r\n### 从 npm 安装（推荐）\r\n\r\n```bash\r\n# 使用 hcordova CLI 安装\r\n# 安装 hcordova 命令化工具\r\nnpm install -g hcordova\r\n\r\n# 全平台安装插件（自动安装依赖的 cordova-plugin-file）\r\nhcordova plugin add cordova-plugin-file-transfer\r\n\r\n```\r\n\r\n### 指定平台安装 ohos\r\n\r\n仅为 OHOS 平台安装插件：\r\n\r\n```bash\r\n# 仅安装到 OHOS 平台\r\nhcordova plugin add cordova-plugin-file-transfer --platform ohos\r\n\r\n# 仅安装到 OHOS 平台（指定版本示例）\r\nhcordova plugin add cordova-plugin-file-transfer@1.0.0 --platform ohos\r\n```\r\n\r\n### 从 GitCode 仓库安装\r\n\r\n仅为 OHOS 平台安装插件：\r\n\r\n```bash\r\n# 仅安装到 OHOS 平台\r\n# 默认分支安装\r\nhcordova plugin add https://gitcode.com/CPF-Cordova/cordova-plugin-file-transfer.git --platform ohos\r\n\r\n# 指定标签/分支安装\r\nhcordova plugin add https://gitcode.com/CPF-Cordova/cordova-plugin-file-transfer.git@develop --platform ohos\r\n```\r\n\r\n### 离线安装（本地包）\r\n\r\n适用于无网络环境，先下载插件包到本地，再执行离线安装：\r\n\r\n```bash\r\n# 下载插件包到本地（示例路径：~/Downloads/cordova-plugin-file-transfer）\r\n# 执行离线安装\r\nhcordova plugin add ~/Downloads/cordova-plugin-file-transfer --platform ohos\r\n```\r\n\r\n### 安装后验证\r\n\r\n安装完成后，可通过以下命令验证插件是否成功添加到项目中：\r\n\r\n```bash\r\n# 查看已安装的插件列表，若包含本插件 ID 则表示插件已成功安装\r\nhcordova plugin list\r\n```\r\n\r\n### 卸载\r\n\r\n```bash\r\n# Cordova CLI 全平台卸载\r\nhcordova plugin remove cordova-plugin-file-transfer \r\n\r\n# 指定平台卸载\r\nhcordova plugin remove cordova-plugin-file-transfer --platform ohos\r\n\r\n```\r\n\r\n## 约束与限制\r\n\r\n- 依赖插件：依赖 cordova-plugin-file 插件实现本地文件操作，安装时会自动关联依赖，无需手动安装\r\n\r\n- 传输限制：不建议直接使用大文件上传或下载，如果应用进入后台，会被操作系统中断传输\r\n\r\n- 网络要求：计算远程文件传输时，需确保网络通畅，且服务端接口可正常访问（无跨域、权限限制）\r\n\r\n- URL 规范：服务端 URL 需符合 HTTP/HTTPS 格式，建议开启 encodeURI 编码特殊字符（默认开启）\r\n\r\n### 兼容性\r\n\r\n支持：\r\n\r\n| 项目 | 版本/信息 |\r\n|-----|--------|\r\n| SDK | API12+ |\r\n| IDE | DevEco Studio: 5.0+ |\r\n| ROM | 5.1+ |\r\n| Emulator | OpenHarmony 6.0+ |\r\n\r\n在以下版本中已测试通过：\r\n\r\n| 项目 | 版本/信息 |\r\n|-----|--------|\r\n| @cordova-ohos/ohos | 14.0.1-ohos-14.0.1 |\r\n| SDK | 5.0.0(12) |\r\n| IDE | DevEco Studio: 6.0.13.200 |\r\n| ROM | 5.1.0.120 SP3 |\r\n| Emulator | OpenHarmony 6.0.1(21) |\r\n\r\n## 使用示例\r\n\r\n以下提供两种常用场景的使用示例，适配 OHOS 平台，可直接复制到项目中调试使用，所有示例均需在 `deviceready` 事件触发后执行。\r\n\r\n### 示例 1：上传图片\r\n\r\n结合 cordova-plugin-camera 插件选择图片，实现图片上传功能，包含进度监听、异常处理，可根据服务端要求调整配置。\r\n\r\n```javascript\r\n// 上传一张图片\r\nfunction uploadPicture(imageUri) {\r\n function win(r) {\r\n console.log(\"Code = \" + r.responseCode);\r\n console.log(\"Response = \" + r.response);\r\n console.log(\"Sent = \" + r.bytesSent);\r\n if(r.response == \"MAX\") { // 服务端检测图片太大返回，具体以您的服务器返回修改\r\n alert(\"图片太大超过 4M，请剪裁小一点\");\r\n }\r\n }\r\n\r\n function fail(error) {\r\n console.log(\"An error has occurred: Code = \" + error.code);\r\n console.log(\"upload error source \" + error.source);\r\n console.log(\"upload error target \" + error.target);\r\n // alert('图片上传失败。');\r\n }\r\n\r\n // 显示上传进度\r\n function progressFun(progressEvent) {\r\n var progress = progressEvent.loaded / progressEvent.total * 100;\r\n document.getElementById(\"progress\").innerHTML = \"上传进度:\"+progress+\"%100\";\r\n }\r\n\r\n // 上传参数配置，具体您的服务器要求配置\r\n var options = new FileUploadOptions();\r\n options.fileKey = \"picture\";\r\n options.fileName = imageUri.substr(imageUri.lastIndexOf('/')+1);\r\n options.mimeType = \"image/pjpeg\";\r\n var headers={'oss-token':'YOUR_OSS_TOKEN_HERE'};\r\n options.headers = headers;\r\n var ft = new FileTransfer();\r\n ft.onprogress = progressFun;\r\n ft.upload(imageUri, \"https://your-server-domain/ImageTempUpload\", win, fail, options);\r\n // ft.abort(); // 如需取消上传，可调用此方法\r\n}\r\n\r\nfunction upload() {\r\n var options = {\r\n // Some common settings are 20, 50, and 100\r\n quality: 50,\r\n destinationType: Camera.DestinationType.FILE_URI,\r\n // In this app, dynamically set the picture source, Camera or photo gallery\r\n sourceType: Camera.PictureSourceType.CAMERA,\r\n encodingType: Camera.EncodingType.JPEG,\r\n mediaType: Camera.MediaType.PICTURE,\r\n allowEdit: false,\r\n correctOrientation: true // Corrects Android orientation quirks\r\n }\r\n\r\n // 使用 cordova-plugin-camera 插件选择一个照片上传\r\n navigator.camera.getPicture(function cameraSuccess(imageUri) {\r\n var elem = document.getElementById('imageFile');\r\n elem.src = imageUri;\r\n window.resolveLocalFileSystemURL(imageUri, function (fileEntry) {\r\n console.log(fileEntry.toURL());\r\n uploadPicture(fileEntry.toURL());\r\n });\r\n }, function cameraError(error) {\r\n console.debug(\"Unable to obtain picture: \" + error, \"app\");\r\n }, options);\r\n\r\n}\r\n\r\n```\r\n\r\n### 示例 2：下载图片\r\n\r\n实现远程图片下载至本地指定目录，包含进度监听、文件读取及显示功能，适配 OHOS 本地文件系统规范。\r\n\r\n```javascript\r\nfunction download() {\r\n function onErrorReadFile(error) {\r\n\r\n }\r\n function displayImage(blob) {\r\n // Displays image if result is a valid DOM string for an image.\r\n var elem = document.getElementById('imageFile2');\r\n // Note: Use window.URL.revokeObjectURL when finished with image.\r\n elem.src = window.URL.createObjectURL(blob);\r\n }\r\n\r\n function readBinaryFile(fileEntry) {\r\n fileEntry.file(function (file) {\r\n var reader = new FileReader();\r\n reader.onloadend = function() {\r\n console.log(\"Successful file write: \" + this.result);\r\n // displayFileData(fileEntry.fullPath + \": \" + this.result);\r\n var blob = new Blob([new Uint8Array(this.result)], { type: \"image/png\" });\r\n displayImage(blob);\r\n // displayImage2(this.result);\r\n };\r\n reader.readAsArrayBuffer(file);\r\n // reader.readAsDataURL(file);\r\n // reader.readAsBinaryString(file);\r\n }, onErrorReadFile);\r\n }\r\n\r\n function successFun(fileEntry) {\r\n console.log(\"download complete: \" + fileEntry.toURL());\r\n readBinaryFile(fileEntry);\r\n // document.getElementById(\"imageFile2\").src = \"https://localhost/\"+fileEntry.toURL();\r\n }\r\n\r\n function failFun(error) {\r\n console.log(\"An error has occurred: Code = \" + error.code);\r\n console.log(\"upload error source \" + error.source);\r\n console.log(\"upload error target \" + error.target);\r\n alert('图片下载失败。');\r\n }\r\n\r\n function progressFun(progressEvent) {\r\n var progress = progressEvent.loaded / progressEvent.total * 100;\r\n document.getElementById(\"progress\").innerHTML = \"下载进度:\"+progress+\"%100\";\r\n }\r\n\r\n var uri = \"https://cordova.apache.org/static/img/cordova_bot.png\";\r\n window.resolveLocalFileSystemURL(cordova.file.externalDataDirectory, function(dirEntry) {\r\n var targetPath = dirEntry.toURL() + \"中文.png\";\r\n console.log(\"targetPath:\" + targetPath);\r\n var fileTransfer = new FileTransfer();\r\n fileTransfer.onprogress = progressFun;\r\n fileTransfer.download(\r\n uri,\r\n targetPath,\r\n successFun,\r\n failFun,\r\n false,\r\n {}\r\n );\r\n // fileTransfer.abort(); // 如需取消下载，可调用此方法\r\n });\r\n}\r\n\r\n```\r\n\r\n## 使用说明\r\n\r\n本插件核心功能为跨平台文件上传与下载，支持 HTTP/HTTPS 协议，所有操作需在 `deviceready` 事件触发后执行，核心 API、参数配置及错误处理说明如下。\r\n\r\n### 核心 API 说明\r\n\r\n插件核心通过 `FileTransfer` 对象实现文件传输功能，包含构造函数、上传、下载、进度监听、取消传输等核心方法，适配 OHOS 平台特性。\r\n\r\n#### 1. 构造函数：创建文件传输对象\r\n\r\n```javascript\r\n// 初始化文件传输对象\r\nconst fileTransfer = new FileTransfer();\r\n\r\n```\r\n\r\n#### 2. 核心方法：上传文件\r\n\r\n```javascript\r\ninterface FileUploadOptions {\r\n fileKey?: string; // 表单字段名，默认 \"file\"\r\n fileName?: string; // 上传后的文件名，默认 \"image.jpg\"\r\n mimeType?: string; // 文件 MIME 类型，默认 \"image/jpeg\"\r\n params?: { [key: string]: string | number }; // 额外表单参数\r\n chunkedMode?: boolean; // 是否分片传输，OHOS 默认 true\r\n headers?: { [key: string]: string }; // 自定义请求头\r\n httpMethod?: \"POST\" | \"PUT\"; // HTTP 方法，默认 \"POST\"\r\n encodeURI?: boolean; // 是否自动编码 URL，默认 true\r\n trustAllHosts?: boolean; // OHOS 不校验域名\r\n}\r\n\r\ninterface FileUploadResult {\r\n bytesSent: number; // 已上传字节数\r\n responseCode: number; // HTTP 响应码\r\n response: string; // 服务端响应数据（字符串）\r\n objectId: string; // 任务 ID\r\n}\r\n\r\nfileTransfer.upload(\r\n localFilePath: string | Blob, // 本地文件路径\r\n serverUrl: string, // 服务端上传接口 URL\r\n successCallback: (result: FileUploadResult) => void, // 成功回调\r\n errorCallback: (error: FileTransferError) => void, // 失败回调\r\n options?: FileUploadOptions, // 上传配置\r\n trustAllHosts?: boolean // OHOS 不校验域名\r\n): void;\r\n\r\n```\r\n\r\n#### 3. 核心方法：下载文件\r\n\r\n```javascript\r\ninterface FileDownloadOptions {\r\n headers?: { [key: string]: string }; // 自定义请求头\r\n}\r\n\r\n// 下载结果是 fileEntry 对象\r\nfileTransfer.download(\r\n serverUrl: string, // 服务端文件 URL\r\n localFilePath: string, // 本地保存路径\r\n successCallback: (result: FileDownloadResult) => void, // 成功回调\r\n errorCallback: (error: FileTransferError) => void, // 失败回调\r\n trustAllHosts?: boolean, // 是否信任所有主机（SSL），默认 false\r\n options?: FileDownloadOptions // 下载配置\r\n): void;\r\n\r\n```\r\n\r\n#### 4. 事件：进度监听\r\n\r\n```javascript\r\n// 上传/下载进度回调（共用同一个事件）\r\nfileTransfer.onprogress = function(progressEvent: ProgressEvent) {\r\n /**\r\n * progressEvent 属性说明：\r\n * - loaded：已传输字节数\r\n * - total：总字节数（仅当服务端返回 Content-Length 时有效）\r\n * - lengthComputable：是否可计算总进度（布尔值）\r\n * - timeStamp：事件触发时间戳（毫秒）\r\n */\r\n\r\n if (progressEvent.lengthComputable) {\r\n const progress = (progressEvent.loaded / progressEvent.total) * 100;\r\n console.log(`当前进度：${progress.toFixed(2)}%`);\r\n } else {\r\n console.log(`已传输：${(progressEvent.loaded / 1024 / 1024).toFixed(2)} MB`);\r\n }\r\n};\r\n\r\n```\r\n\r\n#### 5. 方法：取消传输\r\n\r\n```javascript\r\n// 取消正在进行的上传/下载\r\nfileTransfer.abort();\r\n\r\n```\r\n\r\n### 参数配置详解\r\n\r\n#### 1. 上传配置（FileUploadOptions）\r\n\r\n| **参数名** | **类型** | **默认值** | **说明** |\r\n|---|---|---|---|\r\n| fileKey | string | \"file\" | 服务端接收文件的表单字段名（如 PHP 中 `$_FILES['file']`） |\r\n| fileName | string | \"image.jpg\" | 上传到服务端后的文件名，支持自定义扩展名（如 \"video.mp4\"） |\r\n| mimeType | string | \"image/jpeg\" | 文件的 MIME 类型，需与文件实际类型匹配（如 \"application/pdf\"） |\r\n| params | 对象 | {} | 额外的表单参数，服务端可通过请求体获取（如用户 ID、文件类型） |\r\n| chunkedMode | boolean | true（移动平台） | 是否分片传输：
大文件（>10MB）建议开启
减少内存占用，小文件可关闭，提升效率 |\r\n| headers | 对象 | {} | 自定义 HTTP 请求头 |\r\n| httpMethod | \"POST\" / \"PUT\" | \"POST\" | 上传使用的 HTTP 方法，需与服务端接口匹配 |\r\n| encodeURI | boolean | true | 是否自动编码服务端 URL 中的特殊字符（如空格、中文） |\r\n#### 2. 下载配置（FileDownloadOptions）\r\n\r\n| **参数名** | **类型** | **默认值** | **说明** |\r\n|---|---|---|---|\r\n| headers | 对象 | {} | 自定义 HTTP 请求头（如 Accept、Cookie） |\r\n### 错误码与处理方案\r\n\r\n插件定义了标准化的错误码（`FileTransferError`），便于定位问题，常见错误码及处理方案如下：\r\n\r\n| **错误码** | **常量名** | **说明** | **常见原因与解决方案** |\r\n|---|---|---|---|\r\n| 1 | FILE_NOT_FOUND_ERR | 本地文件不存在 | 1. 检查文件路径是否正确 2. 确保应用有文件读取权限 |\r\n| 2 | INVALID_URL_ERR | 服务端 URL 无效 | 1. 检查 URL 格式（如是否遗漏 http://）2. 使用 `encodeURI` 编码 URL |\r\n| 3 | CONNECTION_ERR | 网络连接错误 | 1. 检查设备网络状态（WiFi/4G）2. 确认服务端接口可访问 3. 处理超时（增大超时时间） |\r\n| 4 | ABORT_ERR | 传输被主动取消 | 调用了 `fileTransfer.abort()`，属于正常流程，无需特殊处理 |\r\n| 5 | NOT_MODIFIED_ERR | 文件未修改（HTTP 304） | 服务端返回 304 响应，说明本地文件已是最新版本，可停止下载 |\r\n\r\n## 目录结构\r\n\r\n```\r\ncordova-plugin-file-transfer/\r\n├── src/ # 源代码目录\r\n│ └── main/ # 主要源代码\r\n│ └── cpp/ # C++ 原生代码\r\n│ └── FileTransfer/ # 文件传输模块\r\n│ ├── FileTransfer.cpp # 文件传输功能的 C++ 实现\r\n│ └── FileTransfer.h # 文件传输功能的头文件\r\n├── www/ # Web 资源目录\r\n│ ├── FileTransfer.js # JavaScript 文件传输接口（Cordova 桥接层）\r\n│ └── FileTransferError.js # 文件传输错误码定义\r\n├── .gitignore # Git 忽略文件配置\r\n├── LICENSE # 项目开源许可证\r\n├── OAT.xml # OpenHarmony 审核配置文件\r\n├── package.json # Node.js 包配置\r\n├── plugin.xml # Cordova 插件描述文件（核心配置）\r\n└── README.md # 项目说明文档\r\n```\r\n\r\n## 贡献代码\r\n\r\n使用过程中发现任何问题都可以提 [Issue](https://gitcode.com/CPF-Cordova/cordova-plugin-file-transfer/issues) ，当然也非常欢迎发 [PR](https://gitcode.com/CPF-Cordova/cordova-plugin-file-transfer/pulls) 共建。\r\n\r\n## 许可证\r\n\r\n本插件基于 **Apache License 2.0** 开源，详见 [LICENSE](LICENSE) 文件。\r\n\r\n## 官方资源\r\n\r\n- Android 和 iOS：[cordova-plugin-file-transfer 官方指南](https://www.npmjs.com/package/cordova-plugin-file-transfer)\r\n\r\n- GitCode 仓库：[CPF-Cordova/cordova-plugin-file-transfer](https://gitcode.com/CPF-Cordova/cordova-plugin-file-transfer)\r\n","readmeFilename":"README.md"}