@heybox/hb-sdk API Reference - v0.9.5
    正在准备搜索索引...
    • 发起网络请求。

      注意:在移动端访问官方域名时,JSON 请求体或自定义请求头不会自动附加客户端签名。

      类型参数

      • T = unknown

        调用方期望的响应 data 类型;只影响 TypeScript,不做运行时 schema 校验。

      参数

      返回 Promise<MiniProgramNetworkResponse<T>>

      通过 validateStatus 的标准化 MiniProgramNetworkResponse;默认仅 2xx resolve。响应包含安全 Header 与公开 config 快照。

      HbMiniProgramNetworkError Host 已完成 HTTP 响应,但状态未通过 validateStatus 时抛出;错误的 status、data、安全 headers、config 与 response 可用于业务分支。它不表示权限、bridge 或网络不可达。

      HbMiniProgramSDKError 配置/数据/Header 非法时返回 INVALID_PARAMS;当前运行快照 缺少 network 时返回 PERMISSION_NOT_IN_SNAPSHOT;权限未启用或未获官方域名批准时返回 PERMISSION_DENIED;Host 不支持请求形态时返回 REQUEST_UNSUPPORTED,Host/transport 失败返回 REQUEST_FAILED,Host 能力关闭或旧 Runtime 不认识 method 时可返回 METHOD_FORBIDDEN / METHOD_NOT_FOUND,响应结构无效返回 INVALID_NETWORK_RESPONSE; 其他握手、bridge 或 Host 错误保留对应 SDK 错误码。

      移动端访问官方域名时,当前 API 不支持同时使用 JSON/自定义请求头和自动附加的 客户端签名,也没有强制启用签名的配置项。依赖客户端签名的接口应使用服务端支持的 GET 或兼容表单 POST,并避免自定义请求头。接口同时要求两者时,应先与服务端约定 兼容的请求格式或鉴权方式。访问权限已获批、Cookie 可用或请求成功均不代表已签名, 具体编码与兼容规则见 MiniProgramNetworkRequestConfig.data。

      该 API 需要在 package.json#heybox.permissions 声明并启用 network,且取得平台批准; 不需要 filesystem 或可信用户手势。useOfficialDomain 只有开发者声明与平台批准都为 true 时生效,并且不会绕过 HTTPS、敏感路径、Header、body、timeout 或响应策略。

      公开请求使用 no-follow redirect policy。3xx 不会自动访问 Location;它作为已完成响应 返回到 SDK,默认触发 HbMiniProgramNetworkError,只有自定义 validateStatus 接受时才 resolve。平台保留的 Runtime auth/OpenAPI 路径始终不能通过该能力访问。

      自正式版 0.8.1 起公开 config 不再支持 withCredentials;JavaScript 仍传入时会被 SDK 忽略且不报错,也不会把凭据开关传给 Host。原生 Cookie 是否随请求发送由 Host 按目标 域名决定,iframe Cookie 不会由 SDK 自动读取;响应中的 Set-Cookie 与认证 Header 不会 暴露给页面。应用显式 Header 仍必须遵守敏感信息边界。

      Browser Dev Host 与真实 App Host 都拒绝 multipart,并执行相同的 no-follow、官方域名和 敏感路径策略;本地代理另有 5 MiB 响应体上限,真机 Host 仍可能有不同的响应限制。

      Host 的 config.timeout 与 SDK 等待 bridge 响应的超时彼此独立;默认 SDK 实例从请求 发出后最多等待 10 秒。因此即使传 timeout: 30000,也可能先以 REQUEST_TIMEOUT 拒绝。 SDK 等待超时不会主动取消 Host 请求,也不能证明服务端未处理请求;写请求重试应使用 幂等键或先核实业务结果,避免重复执行。

      import hbSDK from '@heybox/hb-sdk'

      type ItemsResult = { items: string[] } | { message: string }

      const response = await hbSDK.network.request<ItemsResult>({
      url: 'https://api.example.com/items',
      method: 'POST',
      params: { page: 1, locale: 'zh-CN' },
      data: { filters: ['owned'] },
      headers: { 'content-type': 'application/json', 'x-request-id': 'request-1' },
      timeout: 10_000,
      validateStatus: (status) => (status >= 200 && status < 300) || status === 404,
      })

      if (response.status === 404) console.log('暂无数据')
      else if ('items' in response.data) console.log(response.data.items)

      0.3.1

      android

      ios

      ohos

      windows

      macos

      android none

      ios none

      ohos none

      windows none

      macos none