HiAPI Cloud 知识库

Appearance

@hiapi/hiapi-cloud-web-basic ​

源码:hiapi-cloud-web-basic/(仓库根目录)· 当前 0.0.25 · main: src(发的是 TS 源码,不是产物)

它解决什么问题 ​

装修组件要在四种宿主里跑同一份代码:C 端 uniapp 主应用、装修器(浏览器里的 Vue 应用)、 各后台的微前端、本地预览工作台。这些宿主的网络层、路由、上传、弹窗完全不同。

web-basic 的做法是:声明一组接口,由各宿主在启动时把实现塞进去。 组件只 import HiapiUtils,不知道自己跑在哪。

ts
import {HiapiUtils} from '@hiapi/hiapi-cloud-web-basic'

所有方法的默认实现都是 reject

HiapiUtils 的默认实现清一色 Promise.reject(new Error("Method not implemented."))。 宿主没赋值就调 = 一个没人接的 rejection。所以每个调用都要 .catch(), 而不是假定它一定能用。getEnv / getPlatform / getStyleUnit / transformStyleUnit 是例外(纯本地状态,无需宿主)。

网络 ​

ts
get   <T>(url, params?, options?)
post  <T>(url, params?, data?, options?)   // 第二个 query,第三个 body
put   <T>(url, params?, data?, options?)   // 同上
delete<T>(url, params?, options?)

⚠️ post/put 的第二个参数是 query、第三个才是 body。 和 admin-lib 的 useApi().post(url, data, params) 正好相反 —— 见一号陷阱。

只发 body 的常见写法(绝大多数业务接口都是这种):

ts
HiapiUtils.post(`${USER}/cart/add`, {}, {skuId, num})

返回 Promise<ApiResponse<T>>。各宿主的请求层普遍在 code !== 200 时 throw (包括 401 / 403),而且不一定跳登录页,所以未登录用户身上会留下 unhandled rejection。

跳转:href 是全站唯一入口 ​

ts
href(link: Link): Promise<any>                                   // 0.0.25 起
href(url: string, params?, type?: 'redirectTo'|'reLaunch'|'switchTab'|'navigateTo')

业务代码不许直接调 uni.navigateTo / location.href —— 跨端降级(小程序跳 APP、 H5 唤起小程序)散在各处永远补不齐。由 hiapi-chart/ci/check-navigate.sh 静态看守。

传 Link 对象要看版本和宿主

href(link) 这个重载 0.0.22 没有。而且即使在 0.0.25,能不能传对象取决于宿主实现:

  • public-web 的 22 个组件都是 HiapiUtils.href(item.link)(传对象)
  • 但主应用 uniapp/hiapi-cloud-uniapp/src/App.vue 的实现是 href(url, params, type) => router.push({path: url, params}) —— 把第一个参数当字符串用, 并且从不读 link.params

也就是说新链接内核在 web-basic 和装修器两端都就绪了,运行时宿主还没升级。 在 0.0.22 的工程(shop-web / uniapp-design)里,一律自己把参数拼进 url、只传字符串。

Link.params 是和 url 分开存的字段。带参页面(商品分类、商品详情、店铺主页) 只取 url 就会落到默认值 —— 配置像是没生效,页面也不报错。0.0.25 有 resolveUrl(link) 帮你拼;0.0.22 得自己拼。

环境与单位 ​

ts
setHiapiEnv(env: HiapiEnv, platform: Platform, styleUnit?: 'px'|'rpx')
setStyleUnit(unit)
getEnv(): HiapiEnv          // 'DEV' | 'DESIGN' | ...  默认 'DEV'
getPlatform(): Platform     // 'H5' | 'APP' | 'PC' | 'WX' | 'ALIPAY'
getStyleUnit(): 'px'|'rpx'
transformStyleUnit(v)       // number → `12px`/`12rpx`;string → 只留数字

setHiapiEnv 改的是模块级单例

不是"只影响当前页"。装修预览页调一次,整个会话的 getEnv() 都变了。

getEnv() === 'DESIGN' 是装修画布。这时组件应该给假数据 —— 商户拖进来必须有东西可看, 真接口在新租户上往往是空的,一排"暂无数据"等于组件坏了。

其它宿主能力 ​

ts
uploadFile(): Promise<FileRes[]>          // 打开选择器让用户挑
uploadBlob(blob, filename): Promise<FileRes>  // 已有 Blob(canvas 截图等)
selectLink(platform): Promise<Link>      // 打开装修链接选择器
back(delta): Promise<any>
getQuery(): any
showAlert(msg, title?) / showToast(msg, title?) / showConfirm(msg, title?)
buildStyle(styles): Record<string, any>  // 装修 styles → 内联 style
updateUser(info) / userChange(cb) / getUserInfo()
loadRemoteScript(src)                    // 仅 H5,带成功/失败去重
shortId()

showConfirm 在不同宿主里行为不一致

装修宿主有的实现是 uni.showModal().then(() => resolve()) —— 点取消也 resolve; web-basic 的默认实现直接 reject。同一个弹窗一个"取消也执行"、一个"点了没反应"。 面板里的危险操作(删除条目)自己在组件内做两步确认,不要依赖宿主。

back(delta) 在部分工程里根本没实现(默认 reject)。别拿它当"返回上一页"的兜底。

类型(schema.ts) ​

装修 schema 相关:HiapiCloudSchema / HiapiCloudSchemas / HiapiCloudStyles、 Link / LinkType / Platform / HiapiEnv、ApiResponse / FileRes。

0.0.25 追加:LinkKind(page|sub|web|mini|native|tab|action)、 LinkAction、LinkOpenType、MiniProgramTarget、NativeAppTarget。

为什么有 kind 又有 type

type: 'app' 在老数据里指子应用页面,而产品说的"跳 APP"是原生应用。 两个 app 挤一个字段,后面每个组件都要猜。kind 是拆开后的新字段, normalizeLink() 负责把存量 type 归一化过来。

0.0.25 独有的三个模块 ​

normalizeLink(raw)、isExternal(url)、buildUrl(url, params)、resolveUrl(link)、 CAPABILITY / capabilityOf(platform, kind)(端 × 跳转种类 → direct|bridge|unsupported 的数据表,加一个端是加一列)、matchesPlatform(link, platform)。

resolveLink(raw, platform, ctx) → LinkPlan;navigate(link, platform, adapter); LinkAdapter 接口。目前全仓没有任何工程实现 LinkAdapter —— 这套内核还没接上运行时。

theme.ts ​

运行期注入主题令牌。0.0.22 的工程只能在自己工程里放一份静态 --hi-* (shop-web 的 src/styles/widget.scss 就是这么做的,变量名刻意跟 public-web 对齐, 将来升版本可以让运行期注入直接覆盖)。

宿主实现清单(改宿主前先看这张表) ​

宿主文件post 顺序备注
主应用 uniappuniapp/hiapi-cloud-uniapp/src/App.vue✅ (params, data)href 只吃字符串、不读 link.params
shop-webhiapi-cloud-shop/hiapi-cloud-shop-web/src/main.ts✅href 自己修过(支持对象 params / 绝对地址 / 四种 type)
uniapp-designuniapp-design/src/main.ts✅
admin-libhiapi-cloud-admin-lib/src/index.ts HiapiUtilsInit()✅(2026-08-22 修)三个后台都调它
page-designhiapi-cloud-admin-page-design/src/main.ts✅(2026-08-22 修)独立态 + qiankun 两份实现
vem-admin(qiankun)hiapi-cloud-vem/vem-admin/src/main.ts mount()✅(2026-08-22 修)需与 admin-ts 桥接交换