HarmonyOS鸿蒙应用开发——探索原生与H5通信框架DSBridge-HarmonyOS的奥秘

李游Leo

于 2024-08-02 22:03:10 发布

阅读量945

点赞数 26

文章标签： harmonyos

本文链接：https://blog.csdn.net/liyou041/article/details/140880716

版权

HarmonyOS版的DSBridge是一个桥梁库，它允许鸿蒙原生环境与JavaScript之间进行交互，彼此能够调用对方的功能。该库目前兼容Android和iOS上第三方DSBridge库的核心功能，基本保持了原有的使用方式。

主要特性包括：

已适配鸿蒙NEXT版本；
支持在原生同步方法中执行串行异步并发任务，并同步等待异步结果，这是根据鸿蒙系统特点而设计的功能；
同时兼容DSBridge 2.0与3.0版本的JS脚本；
支持以类的形式集中统一管理API，同时也支持原生自定义页面组件的直接注册和使用；
支持同步和异步调用方式；
支持进度回调/回传功能，即一次调用可以多次返回结果；
提供API存在性检测功能；
支持监听和拦截JavaScript关闭页面的操作；
支持命名空间API。

源码仓库：

HarmonyOS版：DSBridge-HarmonyOS
Android版：DSBridge-Android（建议使用维护中的版本：github.com/751496032/D…）
iOS版：DSBridge-IOS

由于原DSBridge库的作者已停止维护，对于Android端，我们推荐使用由社区维护的活跃版本，以确保获得最新的功能和修复。

安装指南

安装库：

使用以下命令安装@hzw/ohos-dsbridge库：

ohpm install @hzw/ohos-dsbridge

或者安装本地HAR包：

如果你有一个本地的HAR包，可以使用以下命令进行安装：

ohpm install ../libs/library.har

基本用法

在ArkTS原生侧，你可以通过以下两种方式之一来实现和管理API接口：

1.新建一个类来集中统一管理API：

你可以创建一个名为JsBridge的类，并使用@JavaScriptInterface()装饰器来标注其方法，以便在JavaScript中调用。这个装饰器是为了保持与Android的一致性而自定义的。

export class JsBridge {  
  private cHandler: CompleteHandler = null;  

  /**  
   * 同步方法  
   * @param p 输入参数  
   * @returns 返回字符串  
   */  
  @JavaScriptInterface(false)  
  testSync(p: string): string {  
    LogUtils.d("testSync: " + JSON.stringify(p));  
    return "hello native";  
  }  

  /**  
   * 异步方法  
   * @param p 输入参数  
   * @param handler 回调处理函数  
   */  
  @JavaScriptInterface()  
  testAsync(p: string, handler: CompleteHandler) {  
    LogUtils.d("testAsync: " + JSON.stringify(p));  
    this.cHandler = handler;  
  }  
}

2.在自定义页面组件中直接注册使用：

如果你不希望使用类来管理API接口，你可以在自定义页面组件中直接注册并使用API接口。

@Component  
@Entry  
struct UseInComponentsPage {  
  aboutToAppear() {  
    // 在一个组件内只能存在一个无命名空间的对象  
    this.controller.addJavascriptObject(this);  
  }  

  /**  
   * 组件中的同步方法  
   * @param args 输入参数  
   * @returns 返回字符串  
   */  
  @JavaScriptInterface(false)  
  testComponentSync(args: string): string {  
    return `组件中的同步方法: ${args}`;  
  }  

  /**  
   * 组件中的异步方法  
   * @param args 输入参数  
   * @param handler 回调处理函数  
   */  
  @JavaScriptInterface()  
  testComponentAsync(args: string, handler: CompleteHandler) {  
    handler.complete(`组件中的异步方法: ${args}`);  
  }  
}

注意：

API的同步方法不支持使用async/await声明。如果需要在同步方法内执行异步任务，可以使用taskWait()函数来完成。
异步方法的形参CompleteHandler可用于结果的异步回调。

Web组件中的JS注入与交互

在原生Web组件初始化时，你可以通过WebViewControllerProxy类来获取WebViewController实例，以实现JS注入，并将其关联到Web组件中。接着，将API管理类（如JsBridge）关联到WebViewControllerProxy中，以便在Web页面中调用原生方法。

private controller: WebViewControllerProxy = WebViewControllerProxy.createController();  
  
aboutToAppear() {  
  // 将JsBridge实例添加到WebView中，以便在JavaScript中访问  
  this.controller.addJavascriptObject(new JsBridge());  
}  
  
// 配置Web组件，并关联controller  
Web({   
  src: this.localPath,   
  controller: this.controller.getWebViewController()   
})  
.javaScriptAccess(true) // 允许JavaScript执行  
.javaScriptProxy(this.controller.getJavaScriptProxy()) // 设置JavaScript代理  
.onAlert((event) => {  
  // 处理JavaScript中的alert事件  
  // AlertDialog.show({ message: event.message });  
  return false;  
});

调用JavaScript函数

通过WebViewControllerProxy，你可以方便地调用JavaScript函数。callJs()方法提供了三个参数：第一个是JavaScript中注册的函数名称，第二个是传递给JavaScript函数的参数数组，第三个是监听JavaScript函数返回结果的回调函数。

Button("调用js函数-同步")  
  .onClick(() => {  
    this.controller.callJs("showAlert", [1, 2, '666'], (v) => {  
      this.msg = v + "";  
    });  
  });  
  
Button("调用js函数-异步")  
  .onClick(() => {  
    this.controller.callJs("showAlertAsync", [1, 2, '666'], (v) => {  
      this.msg = v + "";  
    });  
  });

兼容DSBridge2.0

如果你的前端使用的是DSBridge2.0的JS脚本，你可以通过supportDS2()方法来兼容。

aboutToAppear() {  
  // 如果是使用DSBridge2.0，调用supportDS2方法  
  this.controller.supportDS2(true);  
  
  // 注册JavaScript对象，两种方式任选其一  
  this.controller.addJavascriptObject(this);  
  // 或者  
  // this.controller.addJavascriptObject(new JsBridge2());  
  
  // 开启调试模式  
  webview.WebviewController.setWebDebuggingAccess(true);  
}

这样，你就可以在原生Web组件中方便地实现与JavaScript的交互，并兼容不同的JS脚本版本。

JavaScript侧dsBridge初始化与交互

1.初始化dsBridge

你可以通过npm安装或CDN引入的方式来初始化dsBridge。如果项目没有历史包袱，建议直接使用m-dsbridge包。

npm i m-dsbridge

或者，通过CDN引入：

<script src="https://cdn.jsdelivr.net/npm/m-dsbridge/dsBridge.js"></script>

也支持直接使用原Android或iOS的DSBridge库的JS脚本：

<script src="https://cdn.jsdelivr.net/npm/dsbridge/dist/dsbridge.js"></script>

2.注册JavaScript函数供原生调用

通过dsBridge对象，你可以注册JavaScript函数，以便原生代码能够调用它们。

// 注册同步函数  
dsBridge.register('showAlert', function (a, b, c) {  
  alert("原生调用JS showAlert函数 " + a + " " + b + " " + c);  
  return true;  
});  

// 注册异步函数  
dsBridge.registerAsyn('showAlertAsync', function (a, b, c, callback) {  
  let counter = 0;  
  let id = setInterval(() => {  
    if (counter < 5) {  
      callback(counter, false);  
      alert("原生调用JS showAlertAsync函数 " + a + " " + b + " " + c + " " + counter);  
      counter++;  
    } else {  
      callback(counter, true);  
      alert("原生调用JS showAlertAsync函数 " + a + " " + b + " " + c + " " + counter);  
      clearInterval(id);  
    }  
  }, 1000);  
});

在异步函数中，callback函数的最后一个参数如果返回true，则表示完成整个链接的调用；如果返回false，则可以一直回调给原生，实现JavaScript端的一次调用、多次返回。

3.调用原生API

通过dsBridge对象，你也可以调用原生API。第一个参数是原生方法名称，第二个参数是原生方法接收的参数。对于异步方法，还有第三个参数是回调函数，用于接收异步回调结果。

// 同步调用  
let msg = dsBridge.call('testSync', JSON.stringify({data: 100}));  

// 异步调用  
dsBridge.call('testAsync', JSON.stringify({data: 200}), (msg) => {  
  updateMsg(msg);  
});

这样，你就可以在JavaScript侧方便地初始化dsBridge，注册函数供原生调用，以及调用原生API了。

进度回调与页面关闭监听

进度回调（一次调用，多次返回）

在原生端，也支持JavaScript端的一次调用、多次回调的模式，这在某些应用场景下非常有用，比如将原生的下载进度实时同步到JavaScript中。这可以通过CompleteHandler#setProgressData()方法来实现。

原生端示例（假设使用TypeScript和Android环境）：

@JavaScriptInterface()  
testAsync(p: string, handler: CompleteHandler) {  
  LogUtils.d("testAsync: " + JSON.stringify(p));  
  this.cHandler = handler;  
  let counter = 0;  
  setInterval(() => {  
    if (counter < 5) {  
      counter++;  
      handler.setProgressData("异步返回的数据--" + counter);  
    } else {  
      this.cHandler.complete("异步返回的数据--结束");  
      // 注意：通常complete只调用一次，表示异步操作完成。如果需要发送多个结束信号，请确保逻辑的正确性。  
      // this.cHandler.complete("异步返回的数据--结束2"); // 这行代码可能需要根据实际情况调整或删除。  
    }  
  }, 1000);  
}

JavaScript端调用：

dsBridge.call('testAsync', JSON.stringify({data: 200}), (msg) => {  
  updateMsg(msg);  
});

监听或拦截JavaScript关闭页面

当JavaScript调用close()函数尝试关闭当前页面时，原生代码可以设置监听器来观察并决定是否拦截这一行为。

原生端示例（假设使用TypeScript和某原生框架）：

aboutToAppear() {  
  this.controller.setClosePageListener(() => {  
    return false; // 返回false会拦截关闭页面的事件，返回true则允许页面关闭。  
  });  
}

在回调函数中，如果返回false，则会拦截掉关闭页面的事件；如果返回true，则允许页面正常关闭。这提供了一种机制，让原生代码能够控制页面的关闭行为。

销毁结束任务与命名空间管理

销毁结束任务

当异步任务（如setProgressData）仍在执行中，如果此时关闭页面，可能会导致应用闪退。为了避免这种情况，建议在组件的生命周期函数aboutToDisappear()中结束任务。

原生端示例（假设使用TypeScript和某原生框架）：

aboutToDisappear() {  
  this.jsBridge.destroy(); // 销毁并结束所有正在执行的任务  
}

命名空间管理

命名空间可以帮助你更好地管理API，尤其在API数量较多时。它允许你将API分类管理，不同级之间只需用.分隔即可。命名空间支持同步与异步方式使用。

原生端设置命名空间

原生端使用WebViewControllerProxy#addJavascriptObject方法指定一个命名空间名称：

this.controller.addJavascriptObject(new JsBridgeNamespace(), "namespace");

JavaScript端使用命名空间

在JavaScript中，使用命名空间名称加上对应的原生函数名来调用原生功能。

const callNative6 = () => {  
  let msg = dsBridge.call('namespace.testSync', { msg: '来自js命名空间的数据' });  
  updateMsg(msg);  
};  
  
const callNative7 = () => {  
  dsBridge.call('namespace.testAsync', 'test', (msg) => {  
    updateMsg(msg);  
  });  
};

JavaScript端注册命名空间

你也可以在JavaScript端使用dsBridge对象注册js函数的命名空间。

// 注册同步命名空间  
dsBridge.register('sync', {  
  test: function (a, b) {  
    return "namespace:  " + (a + b);  
  }  
});  
  
// 注册异步命名空间  
dsBridge.registerAsync("async", {  
  test: function (a, b, callback) {  
    callback("namespace:  " + (a + b));  
  }  
});

第一个参数是命名空间的名称，比如sync或async，第二个参数是API业务对象实例，支持字面量对象和Class类实例。

原生端调用JavaScript命名空间中的函数

this.controller.callJs("sync.test", [1, 2], (value: string) => {  
  this.msg = value;  
});  
  
this.controller.callJs("async.test", [3, 2], (value: string) => {  
  this.msg = value;  
});

通过命名空间，你可以更加有序地管理你的API，使得代码更加清晰和易于维护。

在原生同步方法中执行串行异步并发任务

在鸿蒙系统中，原生同步方法通常不支持直接使用async/await来处理异步任务，这主要受到鸿蒙Web脚本注入机制的限制，同时也为了兼容Android/iOS项目。为了满足在同步方法中执行异步任务并立即返回结果给H5的需求，我们设计了一个taskWait()函数。

taskWait()函数允许在同步方法中执行串行异步并发任务，主线程会同步等待异步结果。如果任务在3秒内未完成，函数会自动结束等待并返回结果，但这种情况下可能会存在数据丢失的风险。

以下是一个使用taskWait()函数在同步方法中执行异步任务的示例：

/**  
 * 同步方法中执行异步并发任务  
 * @param args 传入参数  
 * @returns 返回计算结果  
 */  
@JavaScriptInterface(false)  
testTaskWait(args: string): number {  
  let p = new Param(100, 200);  
  let p1 = new Param(100, 300);  
  
  // 执行异步任务并等待结果  
  taskWait(p);  
  p1.tag = "Param";  
  taskWait(p1);  
  
  // 输出日志并返回结果  
  LogUtils.d(`testTaskWait sum: ${p.sum}  ${p1.sum}`);  
  return p.sum + p1.sum;  
}

其中，Param类需要继承BaseSendable，并使用@Sendable装饰器声明。异步任务放在run()方法中执行：

@Sendable  
export class Param extends BaseSendable {  
  private a: number = 0;  
  private b: number = 0;  
  public sum: number = 0;  
  public enableLog: boolean = true;  
  
  constructor(a: number, b: number) {  
    super();  
    this.a = a;  
    this.b = b;  
  }  
  
  // 异步任务执行  
  async run(): Promise<void> {  
    this.sum = await this.add();  
  }  
  
  async add(): Promise<number> {  
    return this.a + this.b;  
  }  
}

需要注意的是，taskWait()函数是一个轻量级的同步等待函数，不建议执行耗时过长的任务。对于特别耗时的任务，建议使用异步桥接函数来避免阻塞主线程和数据丢失的风险。

李游Leo

关注

26
点赞
踩
17

收藏

觉得还不错? 一键收藏
打赏
0
评论
HarmonyOS鸿蒙应用开发——探索原生与H5通信框架DSBridge-HarmonyOS的奥秘

HarmonyOS版的DSBridge是一个桥梁库，它允许鸿蒙原生环境与JavaScript之间进行交互，彼此能够调用对方的功能。该库目前兼容Android和iOS上第三方DSBridge库的核心功能，基本保持了原有的使用方式。本文章来带你探索该库的使用。
复制链接

扫一扫