iOS端交互方式

一、原生 → H5

1. runJavaScript

原生侧主动执行任意 JS 脚本，是最直接的原生调用 H5 方式。

webController.runJavaScript("functionName('params')");
webController.runJavaScript("document.title"); // 也能获取返回值（Promise）

2. javaScriptOnDocumentStart

在 HTML 文档解析之前注入 JS 脚本，适用于注入全局变量、polyfill、监控脚本等。

Web({ src: $url, controller: webController })
  .javaScriptOnDocumentStart('window.NATIVE_ENV = "harmonyos";')

二、H5 → 原生

3. javaScriptProxy（对象注册）

原生注册一个对象暴露给 H5 调用，是 H5 调用原生最主流、最可靠 的方式。

// 原生侧
class JSBridge {
  callNative(funcId: string, data: string): string {
    // 处理 H5 调用
    return "result";
  }
}
let bridge = new JSBridge();

Web({ src: $url, controller: webController })
  .javaScriptProxy({
    object: bridge,
    name: "nativeBridge",        // H5 侧通过 window.nativeBridge 访问
    methodList: ["callNative"],  // 方法白名单
    controller: webController
  })

H5 侧调用：

window.nativeBridge.callNative("func", JSON.stringify({a: 1}));

还有两种等价写法：

• registerJavaScriptProxy(object, name, methodList) — 通过 controller 动态注册/注销
• deleteJavaScriptRegister(name) — 注销代理

4. onLoadIntercept（URL 拦截）

H5 通过 window.location.href 跳转特定协议，原生侧拦截解析。

Web({ src: $url, controller: webController })
  .onLoadIntercept((event: OnLoadInterceptEvent) => {
    let url = event.data.getRequestUrl();
    if (url.startsWith("myapp://")) {
      // 解析协议，处理原生逻辑
      return true; // 拦截，不加载
    }
    return false;
  })

H5 侧：

window.location.href = "myapp://action?data=xxx";
// 或
document.location = "myapp://action?data=xxx";

5. onInterceptRequest（资源请求拦截）

比 onLoadIntercept 更底层，可拦截所有资源请求（Ajax、图片等），可自定义返回内容。

Web({ src: $url, controller: webController })
  .onInterceptRequest((event: OnInterceptRequestEvent) => {
    let request = event.request;
    if (request.getRequestUrl().includes("custom-api://")) {
      // 返回自定义响应，实现伪协议通信
      event.setResponse(new WebResourceResponse(...));
    }
    return event.getResponse();
  })

6. onAlert / onConfirm / onPrompt

H5 调用 alert() / confirm() / prompt() 时原生侧可捕获，常用于轻量级数据传递。

Web({ src: $url, controller: webController })
  .onAlert((event: OnAlertEvent) => {
    let message = event.message; // H5 传入的数据
    // 处理逻辑
    event.result?.handleConfirm(); // 关闭弹窗
    return true; // 已处理，不显示系统默认弹窗
  })

H5 侧：

alert(JSON.stringify({action: "share", data: {...}}));

7. onConsole

H5 的 console.log/warn/error/debug/info 会被原生侧的 onConsole 捕获，适合调试日志收集。

Web({ src: $url, controller: webController })
  .onConsole((event: OnConsoleEvent) => {
    let logMsg = event.message.getMessage();
    let level = event.message.getLogLevel();
    // 原生日志系统记录
    return true;
  })

三、双向 / 混合

8. 消息端口（MessagePort）

通过 postMessage 机制实现双向通信，类似 Chrome 扩展的消息通道。

// 原生侧
let ports: MessagePort[] = [];
// 创建消息通道
webController.createWebMessagePorts(ports);
webController.postMessage("msgKey", [ports[0]], "*");

ports[0].onMessageEvent((result: WebMessage) => {
  // 收到 H5 消息
  let data = result.getData();
});

通信机制

原生侧 H5 侧
① createWebMessagePorts()
② postMessage 将 port 发送给 H5 ──────→ ③ window.onmessage 收到 port
④ port.onMessageEvent 监听 ←── ⑤ port.postMessage("data") 发送
⑥ port.postMessage("reply") ────────→ ⑦ port.onmessage 收到回复

原生侧（ArkTS）：

@Component
struct WebPostMessageDemo {
  controller: WebviewController = new webview.WebviewController();
  ports: MessagePort[] = [];

  aboutToAppear() {
    // ① 创建消息端口
    this.ports = this.controller.createWebMessagePorts();
    
    // ④ 监听 H5 发来的消息
    this.ports[0].onMessageEvent((result: WebMessage) => {
      let data = result.getData();       // 接收到的数据
      console.log('收到 H5 消息:', data);

      // ⑥ 回复消息给 H5
      this.ports[0].postMessageEvent(
        JSON.stringify({ type: 'reply', msg: '原生已收到' })
      );
    });
  }

  build() {
    Web({ src: "https://example.com", controller: this.controller })
      .onPageEnd(() => {
        // ② 页面加载完成后，将 port 发送给 H5——这个port 自带一个单独的槽位
        // 或者通过在页面上onmessage发送到H5端（这边是原生这边通过这种方式发送）
        this.controller.postMessage('init_port', [this.ports[0]], '*');
      })
  }
}

H5 侧（JavaScript）：

// ③ 接收原生发来的端口
window.addEventListener('message', (event) => {
  if (event.data === 'init_port' && event.ports.length > 0) {
    let nativePort = event.ports[0];  // 获得通信端口

    // ⑦ 监听原生回复
    nativePort.onmessage = (e) => {
      console.log('收到原生回复:', e.data);
    };

    // ⑤ 发送消息给原生
    nativePort.postMessage(JSON.stringify({
      action: 'getUserInfo',
      params: { userId: 123 }
    }));
  }
});

与 javaScriptProxy 的对比

关键 API 说明

9. 生命周期事件

通过 Web 组件的事件回调感知 H5 页面状态：

总结对比

最佳实践

主力使用 javaScriptProxy + runJavaScript，复杂双向场景配合 MessagePort，辅助使用 URL 拦截处理特殊协议路由。

Web 前端视角：与原生（App）交互方式

一、Android（WebView）

二、iOS（WKWebView）

三、ArkWeb（鸿蒙）

四、跨平台通用总结

从 H5 角度看，无论哪个平台，本质就是这几招：

核心就一句话：H5 不管平台细节，封装一个统一 JSBridge 层，底层适配不同平台的调用方式即可。