中文版 | English Version

Http 插件

用于在 Cloak 应用中发起原生 HTTP 请求。请求不经过 WebView，因此不受 CORS 限制，也不携带 WebView 的 cookie。

• 安装
• 使用方法
• API
  • request
  • get · delete · head
  • post · put
• 类型
  • HttpMethod
  • HttpParam
  • HttpBody
  • HttpConfig
  • HttpOptions
  • HttpResponse
  • HttpError
  • HttpErrorCode

安装

ohpm install @wisdomgarden/cloak-plugin-http
npm install @wisdomgarden/cloak-plugin-http # 可选，用于 TypeScript 类型

在 entry/src/main/module.json5 中声明网络权限：

"requestPermissions": [
  {
    "name": "ohos.permission.INTERNET",
    "reason": "$string:permission_internet_reason",
    "usedScene": { "abilities": ["EntryAbility"], "when": "inuse" }
  }
]

使用方法

// GET，params 拼到 URL 查询串上
const res = await Cloak.plugins.Http.get(url, { params: { page: 1 } });
const list = JSON.parse(res.data); // data 恒为原始字符串，解析在 JS 层

// POST JSON，未声明 Content-Type 时按 JSON 编码
await Cloak.plugins.Http.post(url, { username: 'account', password: 'password' });

// POST 表单
await Cloak.plugins.Http.post(url, { username: 'account' }, {
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
});

// 4xx / 5xx 不会 reject，只有传输层失败才会
try {
  const res = await Cloak.plugins.Http.get(url, { timeout: 10000 });
  if (res.status >= 400) {
    console.error(res.status, res.statusText);
  }
} catch (e) {
  console.error(e.code, e.message); // e 为 HttpError
}

API

request

request(config: HttpOptions): Promise<HttpResponse>;

发起请求，唯一读取 config.method 的方法。

| 参数 | 类型 | 必填 | 说明 | |---|---|---|---| | config | HttpOptions | 是 | 请求配置，须含 url |

返回值：Promise<HttpResponse>

get · delete · head

get(url: string, config?: HttpConfig): Promise<HttpResponse>;
delete(url: string, config?: HttpConfig): Promise<HttpResponse>;
head(url: string, config?: HttpConfig): Promise<HttpResponse>;

| 参数 | 类型 | 必填 | 说明 | |---|---|---|---| | url | string | 是 | 请求地址 | | config | HttpConfig | 否 | 请求配置，method 会被忽略 |

返回值：Promise<HttpResponse>

post · put

post(url: string, data?: HttpBody, config?: HttpConfig): Promise<HttpResponse>;
put(url: string, data?: HttpBody, config?: HttpConfig): Promise<HttpResponse>;

| 参数 | 类型 | 必填 | 说明 | |---|---|---|---| | url | string | 是 | 请求地址 | | data | HttpBody | 否 | 请求体，优先于 config.data | | config | HttpConfig | 否 | 请求配置，method 会被忽略 |

返回值：Promise<HttpResponse>

类型

HttpMethod

type HttpMethod = 'get' | 'post' | 'put' | 'delete' | 'head' | 'options'; // 大小写均可

HttpParam

type HttpParamValue = string | number | boolean;
type HttpParam = HttpParamValue | HttpParamValue[];

HttpBody

type HttpBody = string | object; // 不支持二进制，值以字符串跨桥

HttpConfig

| 字段 | 类型 | 必填 | 默认值 | 说明 | |---|---|---|---|---| | method | HttpMethod | 否 | 'get' | 仅 request() 读取 | | params | Record<string, HttpParam> | 否 | — | 拼到 URL 查询串，数组值展开成重复的 key | | data | HttpBody | 否 | — | 请求体，GET / HEAD 忽略。字符串原样发送；对象按 Content-Type 编码，x-www-form-urlencoded 走表单，其余走 JSON | | headers | Record<string, string> | 否 | — | 有请求体但未声明 Content-Type 时补 application/json | | timeout | number | 否 | 0 | 毫秒，总耗时上限。0 表示连接和读取各用系统默认的 60s，那不是总耗时上限 | | usingCache | boolean | 否 | false | 是否允许网络库的 HTTP 缓存，与 WebView 缓存无关 | | usingProxy | boolean | 否 | true | 是否走系统代理，关掉后 Charles 等抓包代理也会失效 |

HttpOptions

继承 HttpConfig，另加：

| 字段 | 类型 | 必填 | 默认值 | 说明 | |---|---|---|---|---| | url | string | 是 | — | 为空时不发起请求，直接以 NETWORK_ERROR 拒绝 |

HttpResponse

以下字段恒有值。

| 字段 | 类型 | 说明 | |---|---|---| | status | number | HTTP 状态码，4xx / 5xx 也会正常 resolve | | statusText | string | 仅供展示，由固定码表生成，未收录的状态码返回空串 | | headers | Record<string, string> | key 统一小写，同名多值头用 ', ' 拼成单条 | | url | string | 实际请求的地址，含生成的查询串 | | data | string | 原始响应体，原生侧不解析 |

HttpError

仅在传输层失败时 reject，以下字段恒有值。

| 字段 | 类型 | 说明 | |---|---|---| | code | HttpErrorCode | 失败原因 | | message | string | 形如 [2300028] Timeout was reached，方括号内为 HarmonyOS 原始错误码 |

HttpErrorCode

| 值 | 说明 | |---|---| | TIMEOUT | 超过 timeout 仍未完成 | | SSL_ERROR | 证书校验或 TLS 握手失败 | | UNKNOWN_HOST | 域名解析失败 | | CONNECTION_ERROR | 建立连接失败 | | RESPONSE_TOO_LARGE | 响应体超过 5 MiB | | UNSUPPORTED_METHOD | method 不受支持（如 PATCH），请求未发出 | | NETWORK_ERROR | 其余传输层失败 |

关于 Cloak

Cloak 是专为 HarmonyOS 设计的混合开发框架，类似 Cordova 和 Capacitor，但具备 更轻量、更高性能 的特性。

该框架可将 Web 应用快速转换为原生应用，同时通过插件机制访问 HarmonyOS 原生能力。

核心特性

• 快速打包：将 H5 应用快速编译为 HarmonyOS 应用。
• 原生能力访问：通过插件机制调用原生接口。
• WebView 支持：提供高性能 WebView 容器，确保 H5 应用流畅运行。
• 插件开发：支持开发者自定义插件以扩展原生功能。

更多关于 Cloak 框架信息，请查看: https://github.com/WisdomGardenInc/Cloak