ArkUI-x跨平台Bridge最佳实践

bridge核心架构思想

平台桥接机制是ArkUI-X框架提供的⼀种ArkTs语⾔和平台原⽣语⾔（Java、OC）之间通信的机制，⽅便⼆者互相调⽤。需要说明的是，平台桥接机制必须在打开ArkUI界⾯时才能进⾏，不能在⾮ArkUI界⾯触发。平台桥接机制有两种应⽤场景：

1.ArkUI界⾯需要和原⽣应⽤底座进⾏业务层⾯通信，⽐如应用中，需要借助宿主通道获取设备状态信息、下发控制命令等；

2.跨平台代码中⽤到了不⽀持跨平台的API，此时⼜想跨平台可以利⽤此机制将不⽀持跨平台的API中转到原⽣实现。包括部分开源API以及全部的闭源API，当前对应API尚不⽀持跨平台，可以基于原⽣平台语⾔封装业务接⼝，通过平台桥接机制供跨平台界⾯调⽤。


bridge支持的能力现状

能力一：支持多种桥接模式

指定桥接模式的时机是在创建平台桥接示例时，创建时的条件：需指定名称，该名称ArkTS侧与平台侧保持一致，为了满足应用不同业务场景的bridge诉求，bridge支持设置不同的桥接模式来进行两端通信（默认为JSON编解码模式）：
模式一：JSON编解码模式
用户场景： JSON模式可以满足用户大多数场景使用，支持基础数据类型、数组类型和结构化数据传递

模式二：二进制编解码模式
用户场景： 二进制模式相比JSON模式其他能力不变，新增加Buffer数据格式，支持传输如图片等数据量大的场景

模式三：线程并发模式
用户场景： 应用Bridge场景如果希望不阻塞主UI线程场景下使用线程并发模式

优势： 用户调度bridge都在Platform线程，然后由Platform线程切换到JS线程，数据编解码都会阻塞主UI线程，为了不阻塞主UI线程，将耗时处理放到后台异步线程中处理， 让Bridge调用者可连续发送数据

创建方式： 线程并发模式目前只能在原生平台侧创建平台桥接实例时指定

能力二：支持原生平台和ArkTS侧数据互相传递

发送数据， 接口参考: sendMessage（ArkTS）（支持直接传递callback）， sendMessage（Android）， sendMessage（iOS）

接收数据， 接口参考: setMessageListener（ArkTS）（接收原生平台sendMessage发送的数据）， setMessageListener（Android）， messageListener（iOS） （onMessage->接收ArkTS侧sendMessage发送的消息、onMessageResponse->原生平台sendmessage后接收ArkTS侧的响应）

数据类型支持， 参考：数据类型支持
能力三：支持原生平台和ArkTS侧方法互相调用

定义被调用方法， Android侧定义被调用方法时需将访问修饰符定义为public

方法注册， ArkTS侧需要通过方法registerMethod定义被原生平台侧调用的方法，原生平台侧供ArkTS侧调用的方法无需注册

方法移除和监听， ArkTS侧可以通过方法unregisterMethod来移除已注册的ArkTS端的方法，原生平台侧通过实现IMethodResult接口，基于其中的onMethodCancel方法来监听ArkTS侧的事件注销通知

方法调用， 参考: callMethod（ArkTS），callMethodWithCallback（ArkTS）， callMethod（Android）， callMethod（iOS）（均支持带参数调用和无参数调用）
bridge如何做到"一码三平台"

前面讲到的bridge主要是解决开发者在进行ArkTS代码开发时，需要使用的鸿蒙API不支持跨平台的问题，在Android和iOS平台上，可以借助bridge调用原生能力来完成任务。同时，对于任何跨平台框架的开发者而言，最终的目的肯定是写一套代码，能够同时运行到三个平台上，即“一码三平台”的思想，所以，如何让开发者使用Bridge适配时，修改最少量的原有架构和逻辑代码是Bridge最佳实践中需要讨论的一个重点。
接下来我们以调用相机管理的能力（该能力提供的api当前不支持跨平台），来介绍跨平台的Bridge实现“一码三平台”的推荐写法

如上图所示，HarmonyOS应用的分层架构主要包括三个层次：产品定制层、基础特性层和公共能力层，具体参考分层架构设计，基础特性层包含的主要是应用中的页面UI逻辑以及其中包含的核心功能逻辑。
这里我们的核心思想便是，上层业务统一调用CameraImpl的一套接口，无需区分平台，CameraImpl中实现平台差异化，即鸿蒙平台getInterface返回的是CameraLocal类，安卓和iOS平台返回的是CameraArkUIX类，下层CameraInterface包含camera能力暴露出去的所有接口，CameraLocal和CameraArkUIX差异化实现了CameraInterface中的所有接口，即CameraArkUIX借助bridge调用原生能力，CameraLocal直接调用鸿蒙API完成鸿蒙应用的能力实现。

上层业务，feature1的页面中有一个按钮，用来查询当前相机是否被禁用，其中“media”需要在feature1模块的oh-package.json5文件中进行依赖配置：

1. // feature1/src/main/ets/pages/Index.ets
2. import { CameraImpl, CameraInterface } from "media";
4. @Entry
5. @Component
6. struct Index {
7.   build() {
8.     Row() {
9.       Column() {
10.         Button('相机状态查询')
11.           .width(300)
12.           .margin({top: 30})
13.           .onClick(() => {
14.             CameraImpl.getInterface().isCameraMuted();
15.           })
16.            }
17.      }
18.   }
19. }

复制代码

改造时，该UI业务逻辑部分保持不变，依赖的相机管理能力统一位于commons层，commons层文件夹下有一个module包含媒体能力，暂且称为media，其中可能包含video、audio和camera等能力。
首先先介绍改造后media中涉及camera能力的目录结构：

1. ├── commons
2. │   ├── media                                                                                // commons层级功能模块 media
3. │   │   ├── src\main\ets
4. │   │   │   ├── camera
5. │   │   │   │   ├── interface                                                        // interface 文件目录
6. |   |   |   |   |   └── CameraInterface.ets                            // Camera 模块功能接口定义
7. |   |   |   |   └── impl                                                                // class 文件目录
8. |   |   |   |       ├── Camera.ets                                            // Camera
9. |   |   |   |       ├── CameraArkUIX.ets                                // ArkUIX实现
10. |   |   |   |       └── CameraLocal.ets                                    // HarmonyOS实现
11. |   |   |   └── 功能...
12. │   │   ├── Index.ets
13. │   │   └── oh-package.json5
14. │   └── 其他模块...

复制代码

1. // commons/media/src/main/ets/camera/interface/CameraInterface.ets
2. export interface CameraInterface {
3.   isCameraMuted(): void;
4. }

复制代码

这里的‘@ohos.bridge’、'utils'分别来自于下文中host_bridge、utils模块，需要在media模块的oh-package.json5文件中进行依赖配置。

1. // commons/media/src/main/ets/camera/impl/CameraArkUIX.ets
2. import { CameraInterface } from '../interface/CameraInterface';
3. import bridge from '@arkui-x.bridge';
4. import { bridgeApi } from '@ohos.bridge';
6. export class CameraArkUIX implements CameraInterface {
7.   private static instance: CameraArkUIX;
9.   public static getInstance(): CameraArkUIX {
10.     if (!CameraArkUIX.instance) {
11.       CameraArkUIX.instance = new CameraArkUIX();
12.     }
13.     return CameraArkUIX.instance;
14.   }
16.   public isCameraMuted(): boolean {
17.     console.log("getInteractive enter arkuix");
18.     return bridgeApi.getBridge().isCameraMuted();
19.   }
20. }

复制代码

1. // commons/media/src/main/ets/camera/impl/CameraLocal.ets
2. import camera from '@ohos.multimedia.camera';
3. import { CameraInterface } from '../interface/CameraInterface';
5. export class CameraLocal implements CameraInterface {
6.   private static instance: CameraLocal;
8.   public static getInstance(): CameraLocal {
9.     if (!CameraLocal.instance) {
10.       CameraLocal.instance = new CameraLocal();
11.     }
12.     return CameraLocal.instance;
13.   }
15.   public isCameraMuted(): boolean {
16.     let cameraManager = camera.getCameraManager(getContext());
17.     let isMuted: boolean = cameraManager.isCameraMuted();
18.     return isMuted;
19.   }
20. }

复制代码

1. // commons/media/src/main/ets/camera/impl/Camera.ets
2. import { CameraArkUIX } from './CameraArkUIX';
3. import { CameraLocal } from './CameraLocal';
4. import { CameraInterface } from './interface/CameraInterface';
5. import { PlatformInfo, PlatformTypeEnum } from 'utils';
7. export class CameraImpl {
8.   public static getInterface(): CameraInterface {
9.     let platform: PlatformTypeEnum = PlatformInfo.getPlatform();
10.     if (platform == PlatformTypeEnum.ANDROID || platform == PlatformTypeEnum.IOS) {
11.       return CameraArkUIX.getInstance();
12.     } else {
13.       return CameraLocal.getInstance();
14.     }
15.   }
16. }

复制代码

此外，需要新建host_bridge模块，用来管理bridge的相关实现方法，具体目录结构及实现如下：

1. ├── commons
2. │   ├── host_bridge                                                                   // 定义bridge的一些公共方法模块
3. │   │   ├── src\main\ets
4. │   │   │   ├── interface                                                                // 可以定义Callback、Response等文件接口
5. |   |   |   └── BridgeApi.ets                                                        // 对外暴露的bridge实现类，在应用生命周期初始化创建
6. │   │   ├── Index.ets                                                                // 对外导出组件实例文件
7. │   │   └── oh-package.json5                                                // host_bridge 依赖项配置文件
8. │   └── 其他模块...

复制代码

1. // commons/host_bridge/src/main/ets/BridgeApi.ets
2. import bridge from '@arkui-x.bridge';
3. import { PlatformInfo, PlatformTypeEnum } from 'utils';
5. export class bridgeApi {
6.   private static bridgeImpl: bridge.BridgeObject;
8.   constructor() {
9.     let platform: PlatformTypeEnum = PlatformInfo.getPlatform();
10.     if (platform == PlatformTypeEnum.ANDROID || platform == PlatformTypeEnum.IOS) {
11.       bridgeApi.bridgeImpl = bridge.createBridge('arkuixbridge');
12.     }
13.   }
15.   static getBridge(): bridge.BridgeObject | null {
16.     return bridgeApi.bridgeImpl? bridgeApi.bridgeImpl:null;
17.   }
18. }

复制代码

这里需要注意的是，bridgeApi的构造函数中创建了名为arkuixbridge的bridge实例对象，用来和安卓或者iOS原生侧进行通信，那么在什么时机去构建bridgeApi的实例对象呢，这里推荐在跨平台入口Ability的onCreate生命周期中初始化，例如：

1. // feature1/src/main/ets/entryability/EntryAbility.ets
2. import { bridgeApi } from '@ohos.bridge';
4. export default class EntryAbility extends UIAbility {
5.   onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
6.     let bridgeImpl: bridgeApi = new bridgeApi();
7.     hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onCreate');
8.   }
9.   ...
10. }

复制代码

common层中的很多能力都依赖平台差异化，所以utils中新建一个PlatformInfo.ets用来提供接口类及平台枚举，具体的目录结构及实现如下：

1. ├── commons
2. │   ├── utils                                                                                // commons层级功能模块 utils 通用方法
3. │   │   ├── src\main\ets
4. │   │   │   ├── common                                                                // 常量、数据结构等定义文件目录
5. |   |   |   └── utils                                                                // class 文件目录
6. |   |   |        └── PlatformInfo.ets                                  // 区分当前设备平台
7. │   │   ├── Index.ets                                                                // utils 对外暴露接口导出文件
8. │   │   └── oh-package.json5                                                // utils 依赖项配置文件
9. │   └── 其他模块...

复制代码

1. // commons/utils/src/main/ets/utils/PlatformInfo.ets
2. import deviceInfo from '@ohos.deviceInfo';
4. export enum PlatformTypeEnum {
5.   HARMONYOS = 'HarmonyOS Platform',
6.   ANDROID = 'Android Platform',
7.   IOS = 'iOS Platform',
8.   UNKNOWN = 'Unknown Platform',
9. }
11. export class PlatformInfo {
12.   static getPlatform(): PlatformTypeEnum {
13.     let osFullNameInfo: string = deviceInfo.osFullName;
14.     let platformName: string = osFullNameInfo.split(' ')[0];
15.     if (platformName.includes("OpenHarmony")) {
16.       return PlatformTypeEnum.HARMONYOS;
17.     } else if (platformName.includes("Android")) {
18.       return PlatformTypeEnum.ANDROID;
19.     } else if (platformName.includes('iOS')) {
20.       return PlatformTypeEnum.IOS;
21.     } else {
22.       return PlatformTypeEnum.UNKNOWN;
23.     }
24.   }
25. }

复制代码

FAQ

Q1：
  上面讲到的都是开源API不支持跨平台时的处理策略，对于均不支持跨平台的HMS API，直接基于上述写法运行起来会直接crash，以活体检测API interactiveLiveness为例，运行态会报如下截图错误，该如何解决？

A1：
1.原因分析： 如果应用工程中import了HMS API并涉及到具体调用，当应用运行起来后还未执行到具体业务逻辑时，方舟虚拟机就会首先遍历寻找实现这些HMS API的hsp，对于鸿蒙应用而言，这些hsp包预置到鸿蒙手机系统，因而可以成功获取，但是安卓和iOS原生平台未集成这些闭源hsp，所以会因找不到hsp直接crash。（注：若import了HMS API，但是只存在对象声明，不调用API的情况不会初始化寻找对应hsp）。

2.解决方案： 仍可以基于上面“一码三平台”的架构，只不过需要在commons层使用HMS API的地方引入动态import的处理策略，以活体检测API为例，具体实现参考如下：

1. // commons/recognize/src/main/ets/Interactive/Interactive.ets
2. import { PlatformInfo, PlatformTypeEnum } from 'utils';
3. import { InteractiveInterface } from './interface/interactiveInterface';
4. import { InteractiveArkUIX } from './impl/interactiveArkUIX';
6. export class Interactive {
7.   public static getInterface(): InteractiveInterface {
8.     let platform: PlatformTypeEnum = PlatformInfo.getPlatform();
9.     if (platform == PlatformTypeEnum.ANDROID || platform == PlatformTypeEnum.IOS) {
10.       return InteractiveArkUIX.getInstance();
11.     } else {
12.           return InteractiveLocal.getInstance();
13.   }
14. }

复制代码

这里不再赘述InteractiveArkUIX的实现，和上文CameraArkUIX思想一致，直接看InteractiveLocal的实现，最重要的便是在使用startLivenessDetection该API之前，需要重新动态import一次具体的系统接口文件，但正如上述所说，函数入口处的isSilentMode、actionsNum和routerOptions只是使用API中的数据类型声明定义变量，这些仍可以直接使用文件入口处import的interactiveLiveness能力而不会带来问题：

1. // commons/recognize/src/main/ets/Interactive//impl/InteractiveLocal.ets
2. import { InteractiveInterface } from '../interface/interactiveInterface';
3. import { BusinessError } from '@kit.BasicServicesKit';
4. import { hilog } from '@kit.PerformanceAnalysisKit';
5. import interactiveLiveness from '@hms.ai.interactiveLiveness'
7. export class InteractiveLocal implements InteractiveInterface {
8.   public startInteractive(): void {
9.     let isSilentMode = "INTERACTIVE_MODE" as interactiveLiveness.DetectionMode;
10.     let actionsNum = 3 as interactiveLiveness.ActionsNumber;
11.     let routerOptions: interactiveLiveness.InteractiveLivenessConfig = {
12.       actionsNum: actionsNum,
13.       isSilentMode: isSilentMode
14.     };
15.     import('@hms.ai.interactiveLiveness').then((ns) => {
16.       try {
17.         ns.default.startLivenessDetection(routerOptions).then((DetectState: boolean) => {
18.           hilog.info(0x0001, "LivenessCollectionIndex", `Succeeded in jumping.`);
19.         }).catch((err: BusinessError) => {
20.           hilog.error(0x0001, "LivenessCollectionIndex", `Failed to jump. Code：${err.code}，message：${err.message}`);
21.         })
22.       } catch (err) {
23.         err = err as BusinessError;
24.         console.error(`startLivenessDetection failed. Code: ${err.code}, message: ${err.message}`);
25.       }
26.       return;
27.     })
28.   }
29. }

复制代码

3.更优化的解决方案： 上述写法虽然可以解决crash的问题，但是不可避免地会在一个ets文件中的不同函数中反复多次进行动态import API，影响开发效率和代码整齐程度，所以可以考虑在Interactive类的平台差异化处，直接进行动态import ets文件的处理，处理完成后，文件内使用HMS API的地方无需再增加动态import API的侵入修改。

1. // commons/recognize/src/main/ets/Interactive/Interactive.ets
2. import { PlatformInfo, PlatformTypeEnum } from 'utils';
3. import { InteractiveInterface } from './interface/interactiveInterface';
4. import { InteractiveArkUIX } from './impl/interactiveArkUIX';
6. export class Interactive {
7.   public static async getInterface(): Promise<InteractiveInterface|null> {
8.     let temp: InteractiveInterface | null = null;
9.     let platform: PlatformTypeEnum = PlatformInfo.getPlatform();
10.     if (platform == PlatformTypeEnum.ANDROID || platform == PlatformTypeEnum.IOS) {
11.       temp = InteractiveArkUIX.getInstance();
12.     } else {
13.       await import('./impl/interactiveLocal').then((ns) => {
14.         temp = new ns.InteractiveLocal();
15.       })
16.     }
17.     return temp;
18.   }
19. }

复制代码

来源：程序园用户自行投稿发布，如果侵权，请联系站长删除
免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！