{"_id":"@cordova-ohos/cordova-plugin-advanced-http","_rev":"5-fa708c1089a147688c15c15384a3a0ab","name":"@cordova-ohos/cordova-plugin-advanced-http","dist-tags":{"latest":"3.3.2"},"versions":{"3.3.1":{"name":"@cordova-ohos/cordova-plugin-advanced-http","version":"3.3.1","keywords":["cordova","advanced-http","ecosystem:cordova","cordova-openharmony"],"author":{"name":"Huawei Device, Inc. Ltd. and","email":"马弓手"},"license":"Apache-2.0","_id":"@cordova-ohos/cordova-plugin-advanced-http@3.3.1","maintainers":[{"name":"luqi_tan","email":"295099422@qq.com"}],"bugs":{"url":"https://gitcode.com/OpenHarmony-Cordova/cordova-plugin-advanced-http/issues"},"dist":{"shasum":"b261678ce0e71a1a8641360c212bb4d8922247aa","tarball":"https://registry.npmjs.org/@cordova-ohos/cordova-plugin-advanced-http/-/cordova-plugin-advanced-http-3.3.1.tgz","fileCount":22,"integrity":"sha512-11Th3i2RJiJVVtXIGISz5oTCLKfM4E7QRprhHUnwomlg9jB8mMqVD/i0LB3LPKIw7yS+jSswLuw4y6ZYa/j21w==","signatures":[{"sig":"MEYCIQDYTxke6PZVu/aJjvNDF5mpNks4cEGUIjzGij3iBKuBXgIhAKyOcCPMarINwX7LBc5Au7UxgegE30jvvImwkh3X2+r5","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":450041},"cordova":{"id":"cordova-plugin-advanced-http","platforms":["ohos"]},"engines":{"cordovaDependencies":{"3.3.1":{"hcordova":">=1.0.0","@cordova-ohos/ohos":">=2.0.0"}}},"gitHead":"ffb9b094cc326baf053373b55abda2d07a19f02a","_npmUser":{"name":"luqi_tan","email":"295099422@qq.com"},"repository":{"url":"gitcode:OpenHarmony-Cordova/cordova-plugin-advanced-http","type":"git"},"_npmVersion":"10.5.1","description":"Cordova Advanced Http Plugin","directories":{},"_nodeVersion":"22.0.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/cordova-plugin-advanced-http_3.3.1_1773926992529_0.9187882793947879","host":"s3://npm-registry-packages-npm-production"}},"3.3.2":{"name":"@cordova-ohos/cordova-plugin-advanced-http","version":"3.3.2","description":"Cordova Advanced Http Plugin","cordova":{"id":"cordova-plugin-advanced-http","platforms":["ohos"]},"repository":{"type":"git","url":"gitcode:CPF-Cordova/cordova-plugin-advanced-http"},"bugs":{"url":"https://gitcode.com/CPF-Cordova/cordova-plugin-advanced-http/issues"},"keywords":["cordova","advanced-http","ecosystem:cordova","cordova-openharmony"],"engines":{"cordovaDependencies":{"3.3.2":{"@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-advanced-http@3.3.2","gitHead":"4dd0cf4bff0bf22ee80e7aca0ab3b4bb8efacd55","_nodeVersion":"22.0.0","_npmVersion":"10.5.1","dist":{"integrity":"sha512-pVFDP5V9IudfAHhpY6aGvJf8PZu0PM+uWCPbuX7hE+LiMLM/tCgjwXs9rIga5ox85HrS3IYiiYSvzATxY8zhQQ==","shasum":"a6cf8dc03e0d8391e33d2b31f6911467408dd18f","tarball":"https://registry.npmjs.org/@cordova-ohos/cordova-plugin-advanced-http/-/cordova-plugin-advanced-http-3.3.2.tgz","fileCount":23,"unpackedSize":481574,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCdrCkKRbJOj4xPwLRzMRd+KhlyceqsyMePkVp+JQfzwwIgGaHuL8OFPtmnBbRxjvilO1N3c1dK/j3E6+OfzLR+kt0="}]},"_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-advanced-http_3.3.2_1785150441944_0.6015520466488393"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-19T13:29:52.425Z","modified":"2026-07-27T11:07:22.413Z","3.3.1":"2026-03-19T13:29:52.711Z","3.3.2":"2026-07-27T11:07:22.119Z"},"bugs":{"url":"https://gitcode.com/CPF-Cordova/cordova-plugin-advanced-http/issues"},"author":{"name":"Huawei Device, Inc. Ltd. and","email":"马弓手"},"license":"Apache-2.0","keywords":["cordova","advanced-http","ecosystem:cordova","cordova-openharmony"],"repository":{"type":"git","url":"gitcode:CPF-Cordova/cordova-plugin-advanced-http"},"description":"Cordova Advanced Http 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-advanced-http\r\n\r\n[](README.md)\r\n[](README.en.md)\r\n\r\n本项目基于 [cordova-plugin-advanced-http@3.3.1](https://www.npmjs.com/package/cordova-plugin-advanced-http/v/3.3.1) 开发，本文档重点阐述其在 OpenHarmony（OHOS）系统中的具体应用。\r\n\r\n- [cordova-plugin-advanced-http](#cordova-plugin-advanced-http)\r\n - [简介](#简介)\r\n - [支持平台](#支持平台)\r\n - [下载安装](#下载安装)\r\n - [从 npm 安装（推荐）](#从-npm-安装推荐)\r\n - [从 GitCode 仓库安装](#从-gitcode-仓库安装)\r\n - [离线安装（本地包）](#离线安装本地包)\r\n - [安装后验证](#安装后验证)\r\n - [卸载](#卸载)\r\n - [约束与限制](#约束与限制)\r\n - [兼容性](#兼容性)\r\n - [权限要求](#权限要求)\r\n - [使用示例](#使用示例)\r\n - [示例 1：基础 GET/POST 请求](#示例-1基础-getpost-请求)\r\n - [示例 2：文件上传与下载](#示例-2文件上传与下载)\r\n - [示例 3：SSL 认证配置](#示例-3ssl-认证配置)\r\n - [使用说明](#使用说明)\r\n - [核心 API](#核心-api)\r\n - [1. 请求 API 说明](#1-请求-api-说明)\r\n - [success 回调响应对象](#success-回调响应对象)\r\n - [error 回调响应对象](#error-回调响应对象)\r\n - [sendRequest options 配置](#sendrequest-options-配置)\r\n - [2. 文件 API](#2-文件-api)\r\n - [上传文件（支持多文件上传）](#上传文件支持多文件上传)\r\n - [下载文件](#下载文件)\r\n - [取消上传/下载](#取消上传下载)\r\n - [3. 配置方法 API](#3-配置方法-api)\r\n - [4. Cookie 管理 API](#4-cookie-管理-api)\r\n - [5. 安全配置 API](#5-安全配置-api)\r\n - [单向认证（客户端验证服务端）](#单向认证客户端验证服务端)\r\n - [双向认证（客户端与服务端互相验证）](#双向认证客户端与服务端互相验证)\r\n - [6. 数据序列化说明](#6-数据序列化说明)\r\n - [核心配置](#核心配置)\r\n - [新增特性](#新增特性)\r\n - [目录结构](#目录结构)\r\n - [贡献代码](#贡献代码)\r\n - [许可证](#许可证)\r\n - [官方资源](#官方资源)\r\n\r\n\r\n## 简介\r\n\r\ncordova-plugin-advanced-http 是 Harmony Cordova 生态系统中一款高级 HTTP 网络请求插件，在原生 `XMLHttpRequest` 基础上进行功能增强与性能优化。支持 SSL 证书 pinning、请求/响应拦截、文件上传下载、cookie 管理等核心能力，解决传统网络请求在安全性、稳定性和功能扩展性上的痛点，适用于对网络请求有高阶需求的企业级应用开发，兼容 Android、iOS、Browser 及 OHOS 平台，本文档主要说明在 OHOS 系统中的应用。\r\n\r\n- 安全增强：支持 SSL 证书 pinning 防止中间人攻击，可配置信任自定义 CA 证书\r\n\r\n- 功能全面：覆盖 GET/POST/PUT/DELETE 等请求方法，支持表单提交、JSON 数据、文件上传下载\r\n\r\n- 拦截可控：提供请求/响应拦截器，可统一处理请求头、参数加密、响应解密等逻辑\r\n\r\n- Cookie 管理：支持手动设置、获取、清除 Cookie，适配需要登录状态保持的场景\r\n\r\n- 离线支持：可配置请求超时重试、网络状态检测，提升弱网环境下的请求稳定性\r\n\r\n- 跨平台兼容：统一 Android、iOS、Browser 平台 API 调用方式，减少平台适配成本\r\n\r\n该插件广泛应用于金融、电商、医疗等对网络安全和稳定性要求较高的领域，经过大量生产环境验证，性能与可靠性均处于行业领先水平。\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- **Browser**：主流现代浏览器（Chrome、Firefox、Safari 等）\r\n\r\n## 下载安装\r\n\r\n通过 hcordova CLI 即可快速安装插件，支持从 npm 仓库、GitCode 仓库安装，也可指定版本安装，仅需针对 OHOS 平台安装时添加对应参数。\r\n\r\n### 从 npm 安装（推荐）\r\n\r\n使用 hcordova 命令化工具安装，支持全平台或仅 OHOS 平台安装：\r\n\r\n```bash\r\n# 安装 hcordova 命令化工具\r\nnpm install -g hcordova\r\n\r\n# 全平台安装插件（最新稳定版）\r\nhcordova plugin add cordova-plugin-advanced-http\r\n\r\n# 仅安装到 OHOS 平台\r\nhcordova plugin add cordova-plugin-advanced-http --platform ohos\r\n\r\n# 安装指定版本（仅 OHOS 平台）\r\nhcordova plugin add cordova-plugin-advanced-http@1.0.0 --platform ohos\r\n```\r\n\r\n### 从 GitCode 仓库安装\r\n\r\n如需测试最新开发功能，可从 GitCode 仓库安装（仅 OHOS 平台）：\r\n\r\n```bash\r\n# 仅安装到 OHOS 平台\r\nhcordova plugin add https://gitcode.com/CPF-Cordova/cordova-plugin-advanced-http.git --platform ohos\r\n\r\n# 指定标签/分支安装\r\nhcordova plugin add https://gitcode.com/CPF-Cordova/cordova-plugin-advanced-http.git@develop --platform ohos\r\n```\r\n\r\n### 离线安装（本地包）\r\n\r\n适用于无网络环境，先下载插件包到本地，再执行离线安装：\r\n\r\n```bash\r\n# 下载插件包到本地（示例路径：~/Downloads/cordova-plugin-advanced-http）\r\n# 执行离线安装\r\nhcordova plugin add ~/Downloads/cordova-plugin-advanced-http --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\r\n```bash\r\n# Cordova CLI 全平台卸载\r\nhcordova plugin remove cordova-plugin-advanced-http \r\n\r\n# 指定 OHOS 平台卸载\r\nhcordova plugin remove cordova-plugin-advanced-http --platform ohos\r\n```\r\n\r\n## 约束与限制\r\n\r\n* SSL 认证：OHOS 平台下，插件使用 openssl 进行 SSL 校验，不依赖系统 CA 证书，需手动配置 CA 根证书（存放于 rawfile/certificates 目录，.cer 结尾）。\r\n\r\n* 双向认证：使用双向认证时，需使用 openssl 3.0 以上版本制作 p12 证书，避免因加密算法过时导致的报错。\r\n\r\n* 文件路径：文件上传下载需使用原生路径，可通过 cordova.file 相关 API 获取合法路径。\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需授予应用网络访问权限（用于与远程服务器通信）、文件读写权限（用于文件上传下载），插件自动适配各平台基础权限，无需额外手动配置。\r\n\r\n## 使用示例\r\n\r\n### 示例 1：基础 GET/POST 请求\r\n\r\n实现简单的 GET 请求获取数据、POST 请求提交数据功能。\r\n\r\n```javascript\r\n// GET 请求\r\nfunction sendHttpGet() {\r\n cordova.plugin.http.get('http://www.tongecn.com/update/server.xml', {\r\n id: '12',\r\n message: 'test'\r\n }, { Authorization: 'OAuth2: token' }, function(response) {\r\n document.getElementById(\"getInfo\").innerHTML = response.status;\r\n console.log('成功:', response.data);\r\n }, function(response) {\r\n document.getElementById(\"getInfo\").innerHTML = response.error;\r\n console.log('错误:', response.status, response.error);\r\n });\r\n}\r\n\r\n// POST 请求\r\nfunction sendHttpPost() {\r\n cordova.plugin.http.setHeader('ceshi.tongecn.com', 'Header', 'Value');\r\n cordova.plugin.http.setCookie('https://ceshi.tongecn.com', \"auth=12345;SameSite=none\");\r\n const options = {\r\n method: 'POST',\r\n data: {\r\n bookname: \"《cordova编程》\",\r\n author: \"马弓手\"\r\n },\r\n serializer:\"json\"\r\n };\r\n\r\n cordova.plugin.http.sendRequest('https://ceshi.tongecn.com/member/test.jsp', options, function(response) {\r\n document.getElementById(\"postInfo\").innerHTML = response.status;\r\n }, function(response) {\r\n document.getElementById(\"postInfo\").innerHTML = response.error;\r\n });\r\n}\r\n```\r\n\r\n### 示例 2：文件上传与下载\r\n\r\n实现文件下载、上传及取消操作，适配 OHOS 平台文件路径规范。\r\n\r\n```javascript\r\n// 下载文件\r\nfunction downloadHttpFile() {\r\n var uri = \"https://cordova.apache.org/static/img/cordova_bot.png\";\r\n window.resolveLocalFileSystemURL(cordova.file.externalDataDirectory, function(dirEntry) {\r\n document.getElementById(\"downloadInfo\").innerHTML = \"正在下载...\";\r\n var targetPath = dirEntry.toURL() + \"cordova_bot.png\";\r\n cordova.plugin.http.downloadFile(\r\n uri,\r\n { id: '12', message: 'test' },\r\n { Authorization: 'OAuth2: token' },\r\n targetPath,\r\n function(entry, response) {\r\n document.getElementById(\"downloadInfo\").innerHTML = entry.name;\r\n console.log(entry.fullPath);\r\n },\r\n function(response) {\r\n document.getElementById(\"downloadInfo\").innerHTML = response.error;\r\n }\r\n );\r\n });\r\n}\r\n\r\n// 上传文件\r\nfunction uploadHttpFile() {\r\n window.resolveLocalFileSystemURL(cordova.file.externalDataDirectory, function(dirEntry) {\r\n var targetPath = dirEntry.toURL() + \"cordova_bot.png\";\r\n const filePath = [targetPath, dirEntry.toURL() + \"cordova_bot.png\"];\r\n const name = ['picture', 'document'];\r\n\r\n cordova.plugin.http.uploadFile(\"https://ceshi.tongecn.com/servlet/ImageTempUpload\", {\r\n id: '12',\r\n message: 'test'\r\n }, { Authorization: 'OAuth2: token' }, filePath, name, function (response) {\r\n document.getElementById(\"uploadInfo\").innerHTML = response.status;\r\n }, function (response) {\r\n document.getElementById(\"uploadInfo\").innerHTML = response.error;\r\n });\r\n });\r\n}\r\n\r\n// 取消上传\r\nfunction cancelUploadHttpFile() {\r\n window.resolveLocalFileSystemURL(cordova.file.externalDataDirectory, function(dirEntry) {\r\n var targetPath = dirEntry.toURL() + \"cordova_bot.png\";\r\n const filePath = [targetPath];\r\n const name = ['picture'];\r\n\r\n var reqId = cordova.plugin.http.uploadFile(\"https://ceshi.tongecn.com/servlet/ImageTempUpload\", {\r\n id: '12',\r\n message: 'test'\r\n }, { Authorization: 'OAuth2: token' }, filePath, name, function (response) {\r\n console.log(response.status);\r\n }, function (response) {\r\n console.log(response.error);\r\n });\r\n\r\n // 取消上传\r\n cordova.plugin.http.abort(reqId, function(result) {\r\n document.getElementById(\"cancelUploadInfo\").innerHTML = result.aborted;\r\n }, function(response) {\r\n document.getElementById(\"cancelUploadInfo\").innerHTML = response.error;\r\n });\r\n });\r\n}\r\n```\r\n\r\n### 示例 3：SSL 认证配置\r\n\r\n实现单向认证和双向认证配置，保障请求安全。\r\n\r\n```javascript\r\n// 单向认证（SSL 证书锁定）\r\nfunction setServerTrustMode() {\r\n cordova.plugin.http.setServerTrustMode('pinned', function() {\r\n document.getElementById(\"serverTrustInfo\").innerHTML = \"设置成功\";\r\n }, function(errorInfo) {\r\n document.getElementById(\"serverTrustInfo\").innerHTML = errorInfo;\r\n });\r\n}\r\n\r\n// 双向认证\r\nfunction setClientTrustMode() {\r\n // 将 base64 格式的 p12 证书转换为 ArrayBuffer\r\n function base64ToArrayBuffer(base64) {\r\n const binaryString = atob(base64);\r\n const bytes = new Uint8Array(binaryString.length);\r\n for (let i = 0; i < binaryString.length; i++) {\r\n bytes[i] = binaryString.charCodeAt(i);\r\n }\r\n return bytes.buffer;\r\n }\r\n\r\n var p12base64 = \"MIIRvwIBAzCCEXUGCSqGSIb3DQEHAaC.....=\"; // 完整 base64 格式 p12 证书\r\n const myPkcs12ArrayBuffer = base64ToArrayBuffer(p12base64);\r\n cordova.plugin.http.setClientAuthMode('buffer', {\r\n rawPkcs: myPkcs12ArrayBuffer,\r\n pkcsPassword: 'your_cert_password'\r\n }, function(){\r\n document.getElementById(\"clientTrustInfo\").innerHTML = \"设置成功\";\r\n }, function(errorInfo){\r\n document.getElementById(\"clientTrustInfo\").innerHTML = \"设置失败\";\r\n });\r\n}\r\n```\r\n\r\n## 使用说明\r\n\r\n### 核心 API\r\n\r\n#### 1. 请求 API 说明\r\n\r\n支持多种 HTTP 请求方法，统一接收 URL、参数/数据、请求头、成功回调、失败回调五个参数，其中 sendRequest 方法支持更灵活的配置。\r\n\r\n```javascript\r\n/*\r\n* url (String): 请求 URL\r\n* params/data (Object): 请求参数或数据（params 适用于 GET/HEAD 等，data 适用于 POST/PUT 等）\r\n* headers (Object): 请求头对象\r\n* success (Function): 成功回调函数，接收响应对象\r\n* error (Function): 失败回调函数，接收错误响应对象\r\n*/\r\n\r\n// GET 请求\r\ncordova.plugin.http.get(url, params, headers, success, error);\r\n\r\n// POST 请求\r\ncordova.plugin.http.post(url, data, headers, success, error);\r\n\r\n// PUT 请求\r\ncordova.plugin.http.put(url, data, headers, success, error);\r\n\r\n// DELETE 请求\r\ncordova.plugin.http.delete(url, params, headers, success, error);\r\n\r\n// PATCH 请求\r\ncordova.plugin.http.patch(url, data, headers, success, error);\r\n\r\n// HEAD 请求\r\ncordova.plugin.http.head(url, params, headers, success, error);\r\n\r\n// 通用请求方法（支持更多配置）\r\ncordova.plugin.http.sendRequest(url, options, success, error);\r\n```\r\n\r\n##### success 回调响应对象\r\n\r\n```javascript\r\n{\r\n status: 200, // HTTP 响应码（数值型）\r\n data: '{\"id\": 12, \"message\": \"test\"}', // 服务器响应数据（字符串）\r\n url: 'http://example.net/rest', // 最终请求 URL（含重定向后）\r\n headers: { // 响应头（键值对，全小写）\r\n 'content-length': '247'\r\n }\r\n}\r\n```\r\n\r\n##### error 回调响应对象\r\n\r\n```javascript\r\n{\r\n status: 403, // HTTP 响应码或内部错误码（正值为 HTTP 码，负值为内部错误）\r\n error: 'Permission denied', // 错误信息（字符串）\r\n url: 'http://example.net/noperm', // 最终请求 URL（可选）\r\n headers: { // 响应头（可选）\r\n 'content-length': '247'\r\n }\r\n}\r\n```\r\n\r\n##### sendRequest options 配置\r\n\r\noptions 对象用于配置请求相关参数，支持以下键值：\r\n\r\n- method：HTTP 请求方法（默认 get），可选值：get、post、put、patch、head、delete、options、upload、download\r\n\r\n- data：请求负载数据（适用于 post、put、patch 方法）\r\n\r\n- params：URL 查询参数（适用于 get、head、delete、upload、download 方法）\r\n\r\n- serializer：数据序列化器（适用于 post、put、patch 方法），可选值：json、urlencoded、utf8、multipart、raw\r\n\r\n- responseType：预期响应类型（默认 text），可选值：text、json、arraybuffer、blob\r\n\r\n- timeout：请求超时时间（单位：秒，默认使用全局超时）\r\n\r\n- followRedirect：是否自动跟随重定向（默认 true）\r\n\r\n- headers：请求头对象（与全局请求头合并）\r\n\r\n- filePath：文件上传/下载的文件路径（适用于 upload、download 方法）\r\n\r\n- name：文件上传时的文件名称（可指定多个，适用于多文件上传）\r\n\r\n#### 2. 文件 API\r\n\r\n##### 上传文件（支持多文件上传）\r\n\r\n```javascript\r\n// 单个文件上传\r\nconst filePath = '/data/storage/el2/base/somepicture.jpg'; // 原生路径\r\nconst name = 'picture';\r\n\r\n// 多个文件上传\r\nconst filePath = ['/data/storage/el2/base/somepicture.jpg', '/data/storage/el2/base/somedocument.doc'];\r\nconst name = ['picture', 'document'];\r\n\r\ncordova.plugin.http.uploadFile(url, params, headers, filePath, name, success, error);\r\n```\r\n\r\n##### 下载文件\r\n\r\n```javascript\r\nconst targetPath = '/data/storage/el2/base/somepicture.jpg'; // 下载后保存的原生路径\r\ncordova.plugin.http.downloadFile(url, params, headers, targetPath, success, error);\r\n```\r\n\r\n##### 取消上传/下载\r\n\r\n```javascript\r\n// requestId 是 uploadFile/downloadFile 方法返回的 ID\r\ncordova.plugin.http.abort(requestId, success, error);\r\n```\r\n\r\n#### 3. 配置方法 API\r\n\r\n```javascript\r\n// 设置数据序列化器（全局）\r\ncordova.plugin.http.setDataSerializer('json'); // 可选：json、urlencoded、utf8、multipart、raw\r\n\r\n// 设置请求超时时间（单位：秒）\r\ncordova.plugin.http.setRequestTimeout(30);\r\n\r\n// 设置全局请求头\r\ncordova.plugin.http.setHeader('*', 'Authorization', 'Bearer token123'); // 所有域名\r\ncordova.plugin.http.setHeader('*.example.com', 'X-Custom-Header', 'value'); // 指定域名\r\n\r\n// 设置是否自动跟随重定向（全局）\r\ncordova.plugin.http.setFollowRedirect(true);\r\n```\r\n\r\n#### 4. Cookie 管理 API\r\n\r\n```javascript\r\n// 设置 Cookie\r\ncordova.plugin.http.setCookie('https://example.com', 'token=abc123');\r\n\r\n// 获取指定 URL 的 Cookie\r\ncordova.plugin.http.getCookies('https://example.com', success, error);\r\n\r\n// 清除所有 Cookie\r\ncordova.plugin.http.clearCookies();\r\n```\r\n\r\n#### 5. 安全配置 API\r\n\r\n##### 单向认证（客户端验证服务端）\r\n\r\n```javascript\r\n/*\r\n* SSL 模式选项：\r\n* 'default': 不验证服务端 SSL 证书（Android 默认使用系统 CA 证书，OHOS 不使用系统 CA 证书）\r\n* 'pinned': 校验服务端 SSL 证书（需提供 CA 根证书，存放于 rawfile/certificates 目录，.cer 结尾）\r\n* 'nocheck': 不验证服务端 SSL 证书\r\n* 'legacy': 与 pinned 一致\r\n*/\r\ncordova.plugin.http.setServerTrustMode('pinned', success, error);\r\n```\r\n\r\n##### 双向认证（客户端与服务端互相验证）\r\n\r\n```javascript\r\n/*\r\n* 模式选项：\r\n* 'buffer': 使用 p12 格式证书（需传入 ArrayBuffer 类型证书数据和密码）\r\n* 'systemstore': 与 none 一致，不开启双向认证\r\n* 'none': 不开启双向认证\r\n*/\r\ncordova.plugin.http.setClientAuthMode('buffer', {\r\n rawPkcs: myPkcs12ArrayBuffer, // p12 证书的 ArrayBuffer 格式\r\n pkcsPassword: 'your_cert_password' // 证书密码\r\n}, success, error);\r\n```\r\n\r\n### 6. 数据序列化说明\r\n\r\n插件支持 5 种数据序列化格式，可通过 setDataSerializer 方法全局设置，也可在 sendRequest 的 options 中单独配置：\r\n\r\n- json：默认格式，Content-Type 为 application/json，数据为对象或数组\r\n\r\n- urlencoded：Content-Type 为 application/x-www-form-urlencoded，数据为键值对对象\r\n\r\n- utf8：Content-Type 为 text/plain，数据为字符串\r\n\r\n- multipart：Content-Type 为 multipart/form-data，数据为 FormData 对象\r\n\r\n- raw：Content-Type 为 application/octet-stream，数据为 ArrayBuffer 或 Uint8Array\r\n\r\n### 核心配置\r\n\r\n可在项目 config.xml 中预设全局配置，如最低 TLS 版本：\r\n\r\n```xml\r\n\r\n\r\n\r\n```\r\n\r\n## 新增特性\r\n\r\n这里结合插件 API 对 SSL/TLS 网络通讯简要说明一下\r\n\r\n- （1）使用函数 setServerTrustMode 设置客户端验证服务端模式，服务端在 SSL/TLS 捂手阶段，服务端发送证书到客户端，客户端通过本地根证书对服务端提供的证书进行校验，以确认服务端身份，也就是单向认证，即客户端验证服务端身份，服务端不验证客户端身份，浏览器上网通常采用此机制，使用浏览器上网，根证书库维护有操作系统维护或者浏览器本身维护，根证书有 CA 提供，不能使用自签名证书，但是使用此插件和服务器通讯，可以使用自签名证书，根证书有自己的 APP 维护，同样可以实现加密通讯。\r\n\r\n - nocheck：不验证服务端 SSL 证书\r\n\r\n - default：不验证服务端 SSL 证书，Android 默认使用系统提供的 CA 证书，OHOS 插件不使用系统 CA 证书\r\n\r\n - pinned：校验服务端的 SSL 证书，需提供 CA 根证书，CA 根证书可以在申请证书的服务商直接下载，下载后存在在 rawfile/certificates 目录下，必须 .cer 结尾\r\n\r\n - legacy：和 pinned 一致。\r\n\r\n 说明：客户端验证服务端，cordova-ohos 提供了两种方式，第一个是不校验，第二个是有 APP 提供 CA 根证书，不使用系统提供的 CA 证书，主要原因在于 cordova 内部使用 openssl 校验，因 openssl 对 CA 证书的存放要求所致，也为提高校验效率，因此 cordova-ohos 使用 APP 提供的 CA 根证书校验。根证书在服务商申请证书时可直接下载 CA 根证书，CA 的根证书是全网公开的。\r\n\r\n- （2）使用函数 setClientAuthMode 设置服务端验证客户端模式，服务端在 SSL/TLS 捂手阶段，服务端会要求客户端发送客户端证书，客户端提供证书后，服务端通过服务端预存的根证书对客户端证书进行校验，以确认客户端的身份，也就是双向认证，即客户端验证服务端，服务端也验证客户端，服务端验证客户端，可以使用自签名证书，因为根证书的维护在服务端。使用双向认证，不仅要配置客户端证书，也需要服务端配置和支持，大部分金融级安全多采用此模式。\r\n\r\n - buffer：使用给定的 p12 格式的证书，一般情况下，可以直接下载 pfx 就是 p12 证书的二进制格式，但是直接下载 pfx 证书，一般采用是已经废弃的加密算法加密的，不能正确提取证书和 key，所以可以自行制作 p12 证书，使用 openssl 3.0 以上版本制作 p12 证书参考如下：\r\n\r\n ```bash\r\n # fullchain.crt 包含证书链和根证书，证书链在上，根证书在下。\r\n openssl pkcs12 -export -out server.p12 -inkey server.key -in server.crt -chain -CAfile fullchain.crt -password pass:yourpassword\r\n # 该命令不检验证书链，可不包含根证书，p12 证书建议包含根证书\r\n openssl pkcs12 -export -out server.p12 -inkey server.key -in server.crt -certfile chain.crt -password pass:yourpassword\r\n ```\r\n\r\n - none：不提供证书，不开启不开启双向认证\r\n \r\n - systemstore：和 none 保持一致，不开启双向认证\r\n \r\n - 说明：\r\n\r\n - 1，默认不开启双向认证\r\n - 2，设置双向认证时报错：error:0308010C:digital envelope routines::unsupported，是因为使用了传统的老的加密算法合并 p12 文件，如果使用 openssl 将密码、证书和证书链合并为 p12，请使用 openssl 3.0 以上版本。直接下载的 pfx 格式的证书一般会这个错误。\r\n\r\n- (3) 此插件上传和下载文件不支持进度通知，如果要显示进度通知的，请使用 [cordova-plugin-file-transfer](https://gitcode.com/CPF-Cordova/cordova-plugin-file-transfer) 插件，参考原文档即可，这里不再详细说明\r\n- (4) 在 config.xml 文件中配置支持的最低 TLS 协议版本，不再支持 TLS 的黑名单配置 AndroidBlacklistSecureSocketProtocols 参数\r\n\r\n\r\n## 目录结构\r\n\r\n```\r\ncordova-plugin-advanced-http/\r\n├── src/ # 源代码目录\r\n│ └── main/ # 主要源代码\r\n│ └── cpp/ # C++ 原生代码\r\n│ └── Http/ # HTTP 请求模块\r\n│ ├── CordovaHttpPlugin.cpp # HTTP 插件 C++ 实现\r\n│ └── CordovaHttpPlugin.h # HTTP 插件头文件\r\n├── www/ # Web 资源目录\r\n│ ├── advanced-http.js # 高级 HTTP 请求主入口文件\r\n│ ├── cookie-handler.js # Cookie 处理模块\r\n│ ├── dependency-validator.js # 依赖验证模块\r\n│ ├── error-codes.js # 错误码定义\r\n│ ├── global-configs.js # 全局配置管理\r\n│ ├── helpers.js # 辅助函数工具集\r\n│ ├── js-util.js # JavaScript 工具函数\r\n│ ├── local-storage-store.js # 本地存储管理\r\n│ ├── lodash.js # Lodash 工具库（或子集）\r\n│ ├── messages.js # 消息提示定义\r\n│ ├── ponyfills.js # Polyfill 填充库\r\n│ ├── public-interface.js # 公共接口暴露\r\n│ ├── umd-tough-cookie.js # Tough-Cookie 的 UMD 打包版本\r\n│ ├── url-util.js # URL 工具函数\r\n│ └── LICENSE # Web 资源的许可证文件\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-advanced-http/issues) ，当然也非常欢迎发 [PR](https://gitcode.com/CPF-Cordova/cordova-plugin-advanced-http/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-advanced-http 官方指南](https://www.npmjs.com/package/cordova-plugin-advanced-http)\r\n\r\n- GitCode 仓库：[CPF-Cordova/cordova-plugin-advanced-http](https://gitcode.com/CPF-Cordova/cordova-plugin-advanced-http)\r\n","readmeFilename":"README.md"}