DOM交互：ArkTS与Web DOM的互操作（142）

在 HarmonyOS 的 ArkUI 开发中ArkTS 与 Web DOM 的互操作是实现 Hybrid混合应用的核心。开发者可以通过 Web 组件及其控制器WebviewController实现双向通信、事件监听以及 DOM 操作。以下是实现 ArkTS 与 Web DOM 互操作的完整架构解析与实战代码一、 核心架构双向通信机制ArkTS 与 Web DOM 之间的数据流动主要依赖WebviewController提供的两个核心方法ArkTS 调用 Web DOM正向通信通过runJavaScript()方法ArkTS 可以直接执行网页中的 JS 代码调用 DOM 节点上的方法或修改 DOM 属性并支持异步获取返回值。Web DOM 调用 ArkTS反向通信通过registerJavaScriptProxy()方法将 ArkTS 对象注册到网页的window全局对象上。网页的 JS 代码可以通过window.objName.method()直接调用原生能力。二、 ArkTS 调用 Web DOM 操作当需要在原生侧主动修改 DOM 或获取 DOM 节点数据时使用runJavaScript注入执行脚本。import { webview } from kit.ArkWeb; Entry Component struct WebDomInteraction { controller: webview.WebviewController new webview.WebviewController(); build() { Column() { Button(修改DOM文本) .onClick(() { // 在页面加载完成后通过 JS 修改 DOM 节点的 innerHTML this.controller.runJavaScript( document.getElementById(title).innerHTML 来自ArkTS的问候 ); }) Button(获取DOM输入框的值) .onClick(() { // 获取 DOM 元素的值并返回给 ArkTS this.controller.runJavaScript(document.getElementById(inputBox).value) .then((result) { console.info(DOM输入框的值: ${result}); }) .catch((error) { console.error(执行JS失败: ${error}); }); }) Web({ src: $rawfile(index.html), controller: this.controller }) .javaScriptAccess(true) // 必须开启 JS 交互权限 .onPageEnd(() { console.info(页面加载完成DOM已就绪); }) } } }三、 Web DOM 调用 ArkTS 原生能力通过代理对象机制让网页 DOM 能够触发原生侧的业务逻辑如弹窗、文件读取等。// 1. 定义暴露给 DOM 的 ArkTS 对象 class NativeBridge { showToast(message: string): void { // 调用鸿蒙原生弹窗 promptAction.showToast({ message: DOM传来消息: ${message} }); } } Entry Component struct WebProxyDemo { controller: webview.WebviewController new webview.WebviewController(); bridge: NativeBridge new NativeBridge(); build() { Column() { Web({ src: $rawfile(index.html), controller: this.controller }) .javaScriptAccess(true) .onPageEnd(() { // 2. 将 ArkTS 对象注册到 Web 的 window 对象上 // 白名单机制仅允许 DOM 调用 showToast 方法 this.controller.registerJavaScriptProxy( this.bridge, nativeBridge, [showToast] ); }) } } }对应的 Web DOM 侧代码 (index.html)button onclicknativeBridge.showToast(Hello ArkTS!) 调用原生弹窗 /button四、 监听 Web DOM 事件与手势ArkTS 可以监听 Web 组件内部 DOM 产生的事件或者拦截用户的触摸手势。Web({ src: $rawfile(index.html), controller: this.controller }) .javaScriptAccess(true) // 监听 DOM 的触摸事件 .onTouchIntercept((event) { console.info(DOM触摸事件类型: ${event.type}); return false; // false表示不拦截继续传递给DOM }) // 监听 DOM 的长按事件 .onLongPress((event) { console.info(DOM长按触发坐标: (${event.x}, ${event.y})); })执行时机限制千万不要在网页加载完成前调用runJavaScript。所有的 DOM 操作和registerJavaScriptProxy必须放在onPageEnd回调中执行否则会因为 DOM 未渲染或 JS 上下文未初始化而导致静默失败。安全白名单在使用registerJavaScriptProxy时务必在第三个参数中严格限定允许 DOM 调用的方法白名单防止恶意网页通过原型链注入调用到敏感的系统 API。大数据传输优化避免在 ArkTS 与 DOM 之间通过字符串拼接传递大型 JSON 对象或文件。推荐通过runJavaScript仅传递文件路径或 ID由原生侧在本地读取数据以大幅降低跨端通信的性能开销。五、 高性能通信WebMessagePort 与异步消息队列基础的runJavaScript和registerJavaScriptProxy适合低频的指令下发与简单回调但在处理高频数据流如实时音视频状态、游戏帧同步时会产生巨大的序列化开销与主线程阻塞。WebMessagePort 双向通道鸿蒙 Web 组件提供了WebMessagePort机制允许 ArkTS 与 Web DOM 之间建立独立的、双向的异步消息通道。通过createWebMessagePorts()创建端口对一端保留在 ArkTS 侧另一端通过postMessage传递给 Web 侧。零拷贝与结构化克隆WebMessagePort 支持结构化克隆算法能够直接传递 ArrayBuffer、TypedArray 等二进制数据无需经过 JSON 序列化/反序列化。对于大体积的图像像素数据或传感器数据流可实现近乎零拷贝的跨端传输。六、 复杂对象序列化与类型安全契约在跨端调用中直接传递复杂的 ArkTS 类实例往往会导致方法丢失或属性未定义。DTO数据传输对象模式严禁直接将带有业务逻辑的 ArkTS 类暴露给 Web 端。应定义纯粹的、仅包含数据的 DTO 接口在 ArkTS 侧将业务对象转换为标准 JSON 结构后再进行传递。TypeScript 类型契约共享在工程架构上建议将 ArkTS 与 Web DOM 交互的接口定义抽取到独立的shared-types目录中。两端共同引用该类型契约配合编译期检查彻底杜绝因字段拼写错误或类型不匹配导致的运行时静默失败。七、 安全沙盒隔离与权限收敛Web 侧的 JS 运行环境存在被注入恶意脚本的风险必须对原生能力的暴露进行严格的权限管控。动态代理与鉴权拦截在registerJavaScriptProxy注入的原生对象内部不应直接执行业务逻辑。应封装一层统一的invoke(method, params)网关在网关层进行 Token 校验、方法白名单匹配及参数合法性审查防止 Web 端越权调用敏感系统 API。DOM 访问沙盒化当 ArkTS 通过runJavaScript注入脚本时应严格限制 DOM 查询的范围。避免使用全局的document.querySelector而是将 DOM 操作限定在特定的 Shadow DOM 或指定的容器节点内防止意外覆盖全局样式或篡改核心 UI 结构。八、 跨端状态同步与生命周期对齐Hybrid 应用中原生侧与 Web 侧往往各自维护独立的状态极易导致 UI 表现不一致。单向数据流与事件总线确立“原生为数据源Web 为展示层”的单向数据流原则。当原生侧状态变更时通过 WebMessagePort 主动推送最新状态Web 侧的用户交互仅作为事件上报由原生侧统一处理并更新状态。生命周期联动ArkTS 必须监听 Web 组件的onPageBegin、onPageEnd以及前后台切换事件。在页面销毁或应用退至后台时主动通知 Web 侧暂停定时器、断开 WebSocket 连接并释放内存防止 Web 侧的后台任务持续消耗设备电量。