企业官网建设流程全解析

JSAPI、NAPI、Biz、Imp：ASCF Demo 如何真正调用系统能力和 C++ 能力

前面讲了 H5 怎么进 ArkTS，也讲了 ArkTS 怎么回调 H5。

但是还有一个关键问题：

ArkTS 收到请求之后，怎么真正调用 OpenHarmony 系统能力，甚至 C++ Native 能力？

在 MyASCF 里，我做了两类能力：

clipboard.writeText / clipboard.readText native.addByNapi / native.getNativeVersion

前者验证 JSAPI / 系统能力。

后者验证 NAPI / C++ Native 能力。

一、为什么要有 Biz / Imp？

如果只做 Demo，可以把所有逻辑写在 handler 里。

比如：

clipboard.writeText handler ↓ 直接调用 pasteboard

但是这不适合框架。

框架要考虑扩展。

所以我把能力拆成两层：

Biz ↓ Imp

Biz负责业务语义：

clipboard.writeText 是写入剪贴板。 native.addByNapi 是通过 NAPI 调 C++ 求和。

Imp负责具体实现：

ClipboardImp 调 pasteboard。 NativeImp 调 C++ native module。

这样拆以后，调用链路变成：

Register ↓ Biz ↓ Imp ↓ 系统 API / NAPI

二、clipboard.writeText：调用 OpenHarmony 系统剪贴板

H5 发起请求：

window.ascf.send('clipboard.writeText',{text:'hello ASCF'})

完整链路是：

H5 ↓ JavaScriptProxy ↓ BridgeController ↓ BridgeDispatcher ↓ HandlerRegister ↓ ClipboardBiz.writeText ↓ ClipboardImp.writeText ↓ OpenHarmony pasteboard API ↓ BridgeResponse ↓ runJavaScript ↓ H5 Promise resolve

这里最关键的是：

ClipboardImp ↓ OpenHarmony pasteboard API

这说明 H5 最终确实通过 ArkTS 调到了系统能力。

但是 H5 没有直接调系统 API。

它只是发了一个 action：

clipboard.writeText

真正接触系统能力的是ClipboardImp。

三、JSAPI 是什么？

在这篇文章里，可以把 JSAPI 先理解成：

ArkTS / JS 调用 OpenHarmony 系统能力的接口。

比如剪贴板、设备信息、文件、位置、网络等能力。

以 pasteboard 为例，它属于系统剪贴板能力。

所以这条线可以写成：

ArkTS ↓ JSAPI ↓ OpenHarmony 系统能力

在 MyASCF 里就是：

ClipboardImp ↓ pasteboard

注意，它不是 H5 的浏览器 Clipboard API。

它是 OpenHarmony / HarmonyOS 提供的系统能力。

四、native.addByNapi：调用 C++ 求和

另一个能力是：

native.addByNapi

H5 发起：

window.ascf.send('native.addByNapi',{a:7,b:5})

完整链路是：

H5 ↓ JavaScriptProxy ↓ BridgeController ↓ BridgeDispatcher ↓ HandlerRegister ↓ NativeBiz.addByNapi ↓ NativeImp.addByNapi ↓ NAPI ↓ C++ add(a, b) ↓ 返回 12 ↓ BridgeResponse ↓ runJavaScript ↓ H5 Promise resolve

这个能力的重点不是加法。

重点是验证：

ArkTS 可以通过 NAPI 调 C++ Native 模块。

五、NAPI 是什么？

NAPI，也叫 Node-API，可以先理解成：

ArkTS / JS 和 C/C++ 之间的桥。

它不是 H5 直接调 C++ 的桥。

这句话很重要：

H5 不能直接调用 NAPI。

正确链路是：

H5 ↓ JavaScriptProxy ↓ ArkTS ↓ NAPI ↓ C++

所以在 MyASCF 里，真正调用 NAPI 的是：

NativeImp

不是 H5。

六、JSAPI 和 NAPI 的区别

这两个词很容易混。

可以这样记：

JSAPI： ArkTS / JS 调 OpenHarmony 系统能力。 NAPI： ArkTS / JS 调 C++ Native 能力。

对应 Demo：

clipboard.writeText ↓ ClipboardImp ↓ JSAPI / pasteboard ↓ OpenHarmony 系统剪贴板 native.addByNapi ↓ NativeImp ↓ NAPI ↓ C++ add(a, b)

一句话：

JSAPI 面向系统能力； NAPI 面向 C/C++ 扩展能力。

七、为什么不让 H5 直接调用 NAPI？

因为 H5 运行在 WebView 页面环境里。

它能执行页面 JS，但不能直接 import HarmonyOS native.so模块。

如果让 H5 直接接触 C++，也会带来安全和边界问题。

所以更合理的链路是：

H5 只发请求 ArkTS 做校验和分发 Biz 解释语义 Imp 调用真实能力

这就是框架的价值。

H5 不需要知道底层到底是 pasteboard，还是 C++，还是别的系统 API。

它只需要知道：

action = clipboard.writeText action = native.addByNapi

八、错误处理也应该在框架层统一

比如 H5 发了错误参数：

window.ascf.send('native.addByNapi',{a:'7',b:5})

NativeBiz应该做参数校验。

如果参数不合法，返回：

{"requestId":"req_001","code":400,"message":"native.addByNapi requires number params.a and params.b","data":{}}

如果 action 没注册，Dispatcher 返回：

{"requestId":"req_001","code":404,"message":"UNKNOWN_ACTION: unknown.action","data":{"action":"unknown.action"}}

如果系统能力调用失败，返回：

{"requestId":"req_001","code":500,"message":"Handler execute failed","data":{"action":"clipboard.readText"}}

这样 H5 只需要处理统一的 response。

九、这套分层带来的好处

拆成 Biz / Imp 之后，有几个好处。

第一，H5 不依赖底层实现。

H5 只知道 action，不关心 pasteboard 或 C++。

第二，Controller 不关心具体能力。

Controller 只解析协议，不写业务。

第三，Register 只维护映射。

action → handler

第四，Biz 负责参数和业务语义。

native.addByNapi 必须有 number 类型的 a 和 b。

第五，Imp 负责真实能力调用。

ClipboardImp 调 pasteboard。 NativeImp 调 NAPI。

这样项目会更像框架，而不是功能堆砌。

十、总结

这一篇主要讲两条能力链路：

clipboard.writeText ↓ JSAPI / pasteboard ↓ OpenHarmony 系统能力

和：

native.addByNapi ↓ NAPI ↓ C++ Native 模块

它们共同说明一件事：

H5 不直接调用系统能力，也不直接调用 C++。 H5 只通过 JavaScriptProxy 把请求交给 ArkTS。 ArkTS 通过 Controller / Dispatcher / Register / Biz / Imp 把请求送到真正的能力实现层。 最后再通过 runJavaScript 把结果回调给 H5。

这就是 MyASCF 目前最核心的学习价值。

参考资料

• ArkWeb 前端页面调用应用侧函数：JavaScriptProxy / registerJavaScriptProxy
  https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/web-in-page-app-function-invoking
• ArkWeb 应用侧调用前端页面函数：runJavaScript / runJavaScriptExt
  https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/web-in-app-frontend-page-function-invoking
• WebviewController API 参考
  https://developer.huawei.com/consumer/en/doc/harmonyos-references/arkts-apis-webview-webviewcontroller
• pasteboard 剪贴板 API
  https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-pasteboard
• Node-API / NAPI
  https://developer.huawei.com/consumer/en/doc/harmonyos-references-V14/napi-V14
• IPC / RPC 开发指导
  https://developer.huawei.com/consumer/en/doc/harmonyos-guides/ipc-rpc-development-guideline
• JSVM API 参考
  https://developer.huawei.com/consumer/cn/doc/harmonyos-references-V5/_j_s_v_m-V5