HarmonyOS ArkWeb 开发完整指南（上篇）：Hybrid 应用鸿蒙化与 JSBridge

优质文章学习记录

— 7 min read

背景

Hybrid 应用开发是介于 Web 应用和系统应用两者之间的应用开发技术，兼具"系统应用良好交互体验"的优势和"Web 应用跨平台开发"的优势。

其主要原理是由 Native 通过 JSBridge 通道提供统一的 API，然后用 Html/CSS 实现界面，JS 来写业务逻辑，能够调用系统 API，最终的页面在 WebView 中显示。

这篇文章聊聊 ArkWeb 开发的几个核心话题：

  1. Hybrid 应用鸿蒙化方案（架构设计、JSBridge、API 鸿蒙化、组件鸿蒙化）
  2. 同层渲染 Web（原理、实现、生命周期）
  3. 基于 Web 的视频适配
  4. 网页跨域解决方案
  5. Web 组件拦截能力

本文是上篇，主要介绍 Hybrid 应用鸿蒙化方案、双端通信（JSBridge）和 API 鸿蒙化。下篇将介绍组件鸿蒙化（同层渲染）、视频适配、跨域解决方案和 Web 组件拦截能力。

Hybrid 应用鸿蒙化方案

整体架构

Hybrid 应用鸿蒙化方案的整体架构包含三个核心部分：

Ark 进程：

  • 由 ArkTS 引擎提供运行时，具备调用系统 API 的能力
  • 应用启动从 Ark 进程进入，完成 EntryAbility 的初始化并创建 HarmonyOS 应用页面
  • Ark 进程可以动态或者静态创建 Webview 运行时环境，并加载 html/css/js 资源文件

Webview 进程：

  • 默认支持标准 W3C API，对 ArkTS 侧资源的访问有限制
  • Webview 渲染能力主要由 Web 组件提供
  • 用户可以通过 Web 组件的属性配置是否开启同层渲染能力、是否允许执行 JavaScript 脚本等

JSBridge：

  • 上述两种进程的通讯机制，允许数据双向流动
  • Webview 进程通过 JSBridge 通道访问拓展 API

方案设计

Hybrid 应用鸿蒙化方案主要集中在三个方面：

  1. 双端通信 JSBridge 实现：前端与 ArkTS 进行双向通信的桥梁
  2. 拓展接口实现：针对 JS 侧平台相关的 API，提供一套 HarmonyOS 版本的实现
  3. 基于同层渲染的原生组件实现：使用系统提供的同层渲染能力，把部分性能要求比较高的前端组件改成 ArkTS 实现

业务实现中的关键点

Hybrid 应用鸿蒙化方案主要围绕双端通信、API 鸿蒙化、组件鸿蒙化三方面进行开发：

  • 双端通信：JS 侧使用 ArkTS 的通道，是鸿蒙化的基石
  • API 鸿蒙化：针对 JS 侧平台相关的 API，提供一套 HarmonyOS 版本的实现
  • 组件鸿蒙化：针对 Web 组件，以同层渲染的方式提供替代组件，以提升组件的性能与交互体验

双端通信（JSBridge）

JSBridge 扮演 Webview 进程与 ArkUI 主进程沟通的桥梁，是一种双向通信的机制。

HarmonyOS 系统提供 Web 组件以及@ohos.web.webview 等 ArkWeb API 来进行 Web 开发。可以通过 WebMessagePort 以及 javaScriptProxy 代理的方式实现 JSBridge。

WebMessagePort

WebMessagePort 是一种比较基础的消息发送以及接收机制，支持的消息类型为 string 和 ArrayBuffer。

具体业务消息内容的封装和解析需要从零设计，存在上手难、工作量大的特点。

JavaScriptProxy 代理

JavaScriptProxy 代理机制注入 ArkUI 主进程对象（如命名为 native）到 Webview 中，在 Webview 的 window 上生成对应代理对象，业务可以直接调用该代理对象的方法，相关的操作将作用到 ArkUI 主进程的 native 对象。

代码实例如下：

Web({ src:this.param.path, controller:this.webController }).zoomAccess(false).width(Const.WEB_CONSTANT_WIDTH).aspectRatio(1).margin({ left: Const.WEB_CONSTANT_MARGIN_LEFT, right: Const.WEB_CONSTANT_MARGIN_RIGHT, top: Const.WEB_CONSTANT_MARGIN_TOP}).onErrorReceive((event)=>{if(event?.error.getErrorInfo()==='ERR_INTERNET_DISCONNECTED'){this.getUIContext().getPromptAction().showToast({ message:$r('app.string.internet_err'), duration: Const.WEB_CONSTANT_DURATION});}if(event?.error.getErrorInfo()==='ERR_CONNECTION_TIMED_OUT'){this.getUIContext().getPromptAction().showToast({ message:$r('app.string.internet_err'), duration: Const.WEB_CONSTANT_DURATION});}}).onProgressChange((event)=>{if(event?.newProgress === Const.WEB_CONSTANT_PROGRESS_MAX){this.isLoading =false;clearInterval(this.intervalLoading);this.intervalLoading =-1;}}).javaScriptProxy({ object:this.linkObj, name:'linkObj', methodList:['messageFromHtml'], controller:this.webController })

前端可以使用 native.makePhoneCall(…) 的方式进行调用。且方法的参数支持基本类型、字典对象、函数等，对于 JSBridge 的设计提供了便利。

通过对比，javaScriptProxy 注入对象的方式构造 JSBridge 是一个比较好的技术选型。

JSBridge 分层设计

建议 JSBridge 的实现基于注入机制进行设计，并考虑分层设计来提高其通用性和灵活性：

通信层：

  • 对上层屏蔽具体的通信机制，主要负责 Web 侧和 ArkTS 侧数据的传递
  • 但不解析数据的业务含义，不关注传递的数据内容
  • 数据可以序列化为字符串进行传递或者以 object 对象进行传递

通道层（Channel）：

  • 允许注册多种方法层通道
  • 该层的 JS 侧实现负责把方法层的 API 信息对象（包含名称、参数、返回值类型等信息）打包成通信层识别的信息数据，交给通信层传递到 ArkTS 侧
  • ArkTS 侧的实现包含两个主要功能：
    • 把信息数据解包出 API 的信息，并交给 ArkTS 侧的方法层调用具体的 API
    • 执行 jsCall，ArkTS 侧通过 WebviewController.runJavaScript() 方法在执行 JS 侧的回调函数

在 JS 侧，nativeCall() 方法提供打包转换能力：

functionopenDialog(){ linkObj.messageFromHtml(prizesArr[prizesPosition]);}

在 ArkTS 侧，通过 runJavaScript() 执行 JS 侧方法：

Button($r('app.string.btnValue')).fontSize(Const.WEB_CONSTANT_BUTTON_FONT_SIZE).fontColor($r('app.color.start_window_background')).margin({ top: Const.WEB_CONSTANT_BUTTON_MARGIN_TOP}).width(Const.WEB_CONSTANT_BUTTON_WIDTH).height(Const.WEB_CONSTANT_BUTTON_HEIGHT).backgroundColor($r('app.color.blue')).borderRadius(Const.WEB_CONSTANT_BUTTON_BORDER_RADIUS).onClick(()=>{this.webController.runJavaScript('startDraw()');})

方法层（MethodChannel）：

  • 可以针对一类 API 格式封装成一种 MethodChannel
  • 同种 MethodChannel 的 API 具备一致的参数规范、返回值规范，比如小程序 API 规范
  • 这样便于把 API 的调用信息封装成结构化的信息对象，供给通道层进行传递

JSBridge 的设计是否合理关系到应用的性能，开发者也可以考虑是否需要批量缓存请求再统一发送请求来减少请求次数，或者把不变的请求结果进行缓存等等。

API 鸿蒙化

H5 业务设计中除了使用 W3C API 外，还可以使用 ArkTS 侧 API 拓展来访问设备。

系统高阶 API 是对系统 API 的一层封装，实现更符合业务要求的接口。

拓展 API 的规范设计具有较大的灵活性，建议对 API 的参数，返回值类型格式进行限制，使用基本类型或者简单的字典对象，尽量避免使用复杂的类型的参数或返回值。

可以参考比较成熟的小程序框架，其规范格式可以分成三种类型：

  1. func(paramObj)：其中 paramObj 包含基本类型的数据属性以及 success/fail/complete() 回调函数
  2. on/offFunc(callback)：注册和移除监听函数
  3. getXxManager(): obj：获取某类功能的全局单例管理器，如文件管理器。管理器的方法也遵守上述两点规范

设计过程中可以把 API 都汇聚到一个对象作为属性字段存在，方便在切面视角增加统一的参数、返回值加工处理，拦截处理。

上篇总结

上篇介绍了 Hybrid 应用鸿蒙化方案和双端通信：

Hybrid 应用鸿蒙化方案

  • 整体架构（Ark 进程、Webview 进程、JSBridge）
  • 方案设计（双端通信、拓展接口、同层渲染）
  • 业务实现关键点（双端通信、API 鸿蒙化、组件鸿蒙化）

双端通信（JSBridge）

  • WebMessagePort（基础消息机制）
  • JavaScriptProxy 代理（注入对象方式）
  • JSBridge 分层设计（通信层、通道层、方法层）

API 鸿蒙化

  • 系统高阶 API 封装
  • 三种规范格式（func/on-offFunc/getXxManager）

下篇预告：组件鸿蒙化（同层渲染）、基于 Web 的视频适配、网页跨域解决方案、Web 组件拦截能力。

Read more

OpenClaw 最强技能 self-improving-agent 详解：让 AI 从错误中自主学习

OpenClaw 最强技能 self-improving-agent 详解：让 AI 从错误中自主学习

self-improving-agent 是 OpenClaw 生态中最受欢迎的技能，下载量突破 268k。它能让 AI 记住犯过的错误和解决方案，实现持续自我改进。本文将深入讲解其工作原理、安装配置、实战案例和高级用法。 1 引言 在使用 AI 助手的过程中，你是否遇到过这样的困扰： * 今天教 AI 用 sudo 解决权限问题，明天它又忘了 * 同一个 API 文档链接打不开，它下次还给你这个链接 * 重复解释同样的工作流程，效率极低 这些问题源于传统 AI 助手的无状态特性——每次对话都是全新的开始，不会从历史交互中学习。 self-improving-agent 技能正是为了解决这个问题而生的。它通过记录错误、解决方案和用户反馈，让 AI 能够持续学习和改进。 2 self-improving-agent 是什么？ 2.1 官方定义 self-improving-agent
task：全网最牛的AI 白嫖教程，用 trae “套娃”安装Claude code

task：全网最牛的AI 白嫖教程，用 trae “套娃”安装Claude code

task：全网最牛的AI 白嫖教程，用 trae “套娃”安装Claude code 背景 之前一直没有动手处理 AI 编程软件的事情，一直还停留在拉取 github 然后本地安装的“刻板映像”中，而实际情况是在我拥有 AI-IDE 窗口之后，很多工具都可以互相接通，所以我从最开始下载cursor 安装，逐渐转换为cursor 只是我的一个窗口，最终目的是用 安装Claude code。 描述 认知跃迁，从“本地安装工具”的静态思维 → 转向“AI-IDE 为统一入口”的动态集成范式。本质是将 Cursor 视为「AI 编程操作系统」的 Shell，而非终点。核心转变：工具即服务，窗口即接口。 准备怎么干 摸黑开始，
【实测】OpenClaw 爆火背后：国内这几款“执行式AI”平替，谁才是真正的生产力黑马？

【实测】OpenClaw 爆火背后：国内这几款“执行式AI”平替，谁才是真正的生产力黑马？

摘要：最近 GitHub 上 OpenClaw（大龙虾）斩获 21 万 Star，正式宣告 AI 进入“执行代理”元年。但冷静下来看，高昂的 API 账单、复杂的 Docker 配置以及对国内办公软件（钉钉/飞书）的“水土不服”，让很多开发者直呼“玩不起”。本文将深度拆解国内主流 Agent 平台，并引入 RPA 领军者“实在Agent”进行破坏性实测，看看谁才是真正能落地的生产力工具。 1. 行业现状：Agent 落地为何成了“极客的玩具”？ 在过去的一周里，AI 圈的口号已经从“Chat”转向了“Act”。OpenClaw 的爆火证明了用户不再满足于“

@anthropic-ai/claude-code 快速上手指南

本文重点：快速启动项目、配置 API、常用操作，让开发者立即开始实战，命令清单放在最后参考。 一、安装及配置秘钥 说明：Claude Code 依赖 git 和 npm，这里不赘述基础安装。 1.1 安装 Claude Code 升级或首次安装： npminstall-g @anthropic-ai/claude-code ⚠️ 不同版本支持的命令略有差异，最终以 /help 输出为准。 1.2 配置 API 配置文件路径： 系统路径WindowsC:\Users\用户名\.config\claude-code\config.jsonLinux/Mac~/.config/claude-code/config.json 参考：https://platform.