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文件中进行依赖配置：
// feature1/src/main/ets/pages/Index.ets
import { CameraImpl, CameraInterface } from "media";@Entry
@Component
struct Index {build() {Row() {Column() {Button('相机状态查询').width(300).margin({top: 30}).onClick(() => {CameraImpl.getInterface().isCameraMuted();})}}}
}
改造时，该UI业务逻辑部分保持不变，依赖的相机管理能力统一位于commons层，commons层文件夹下有一个module包含媒体能力，暂且称为media，其中可能包含video、audio和camera等能力。
首先先介绍改造后media中涉及camera能力的目录结构：
├── commons
│ ├── media // commons层级功能模块 media
│ │ ├── src\main\ets
│ │ │ ├── camera
│ │ │ │ ├── interface // interface 文件目录
| | | | | └── CameraInterface.ets // Camera 模块功能接口定义
| | | | └── impl // class 文件目录
| | | | ├── Camera.ets // Camera
| | | | ├── CameraArkUIX.ets // ArkUIX实现
| | | | └── CameraLocal.ets // HarmonyOS实现
| | | └── 功能...
│ │ ├── Index.ets
│ │ └── oh-package.json5
│ └── 其他模块...
// commons/media/src/main/ets/camera/interface/CameraInterface.ets
export interface CameraInterface {isCameraMuted(): void;
}
这里的‘@ohos.bridge’、'utils’分别来自于下文中host_bridge、utils模块，需要在media模块的oh-package.json5文件中进行依赖配置。
// commons/media/src/main/ets/camera/impl/CameraArkUIX.ets
import { CameraInterface } from '../interface/CameraInterface';
import bridge from '@arkui-x.bridge';
import { bridgeApi } from '@ohos.bridge';export class CameraArkUIX implements CameraInterface {private static instance: CameraArkUIX;public static getInstance(): CameraArkUIX {if (!CameraArkUIX.instance) {CameraArkUIX.instance = new CameraArkUIX();}return CameraArkUIX.instance;}public isCameraMuted(): boolean {console.log("getInteractive enter arkuix");return bridgeApi.getBridge().isCameraMuted();}
}
// commons/media/src/main/ets/camera/impl/CameraLocal.ets
import camera from '@ohos.multimedia.camera';
import { CameraInterface } from '../interface/CameraInterface';export class CameraLocal implements CameraInterface {private static instance: CameraLocal;public static getInstance(): CameraLocal {if (!CameraLocal.instance) {CameraLocal.instance = new CameraLocal();}return CameraLocal.instance;}public isCameraMuted(): boolean {let cameraManager = camera.getCameraManager(getContext());let isMuted: boolean = cameraManager.isCameraMuted();return isMuted;}
}
// commons/media/src/main/ets/camera/impl/Camera.ets
import { CameraArkUIX } from './CameraArkUIX';
import { CameraLocal } from './CameraLocal';
import { CameraInterface } from './interface/CameraInterface';
import { PlatformInfo, PlatformTypeEnum } from 'utils';export class CameraImpl {public static getInterface(): CameraInterface {let platform: PlatformTypeEnum = PlatformInfo.getPlatform();if (platform == PlatformTypeEnum.ANDROID || platform == PlatformTypeEnum.IOS) {return CameraArkUIX.getInstance();} else {return CameraLocal.getInstance();}}
}
此外，需要新建host_bridge模块，用来管理bridge的相关实现方法，具体目录结构及实现如下：
├── commons
│ ├── host_bridge // 定义bridge的一些公共方法模块
│ │ ├── src\main\ets
│ │ │ ├── interface // 可以定义Callback、Response等文件接口
| | | └── BridgeApi.ets // 对外暴露的bridge实现类，在应用生命周期初始化创建
│ │ ├── Index.ets // 对外导出组件实例文件
│ │ └── oh-package.json5 // host_bridge 依赖项配置文件
│ └── 其他模块...
// commons/host_bridge/src/main/ets/BridgeApi.ets
import bridge from '@arkui-x.bridge';
import { PlatformInfo, PlatformTypeEnum } from 'utils';export class bridgeApi {private static bridgeImpl: bridge.BridgeObject;constructor() {let platform: PlatformTypeEnum = PlatformInfo.getPlatform();if (platform == PlatformTypeEnum.ANDROID || platform == PlatformTypeEnum.IOS) {bridgeApi.bridgeImpl = bridge.createBridge('arkuixbridge');}}static getBridge(): bridge.BridgeObject | null {return bridgeApi.bridgeImpl? bridgeApi.bridgeImpl:null;}
}
这里需要注意的是，bridgeApi的构造函数中创建了名为arkuixbridge的bridge实例对象，用来和安卓或者iOS原生侧进行通信，那么在什么时机去构建bridgeApi的实例对象呢，这里推荐在跨平台入口Ability的onCreate生命周期中初始化，例如：
// feature1/src/main/ets/entryability/EntryAbility.ets
import { bridgeApi } from '@ohos.bridge';export default class EntryAbility extends UIAbility {onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {let bridgeImpl: bridgeApi = new bridgeApi();hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onCreate');}...
}
common层中的很多能力都依赖平台差异化，所以utils中新建一个PlatformInfo.ets用来提供接口类及平台枚举，具体的目录结构及实现如下：
├── commons
│ ├── utils // commons层级功能模块 utils 通用方法
│ │ ├── src\main\ets
│ │ │ ├── common // 常量、数据结构等定义文件目录
| | | └── utils // class 文件目录
| | | └── PlatformInfo.ets // 区分当前设备平台
│ │ ├── Index.ets // utils 对外暴露接口导出文件
│ │ └── oh-package.json5 // utils 依赖项配置文件
│ └── 其他模块...
// commons/utils/src/main/ets/utils/PlatformInfo.ets
import deviceInfo from '@ohos.deviceInfo';export enum PlatformTypeEnum {HARMONYOS = 'HarmonyOS Platform',ANDROID = 'Android Platform',IOS = 'iOS Platform',UNKNOWN = 'Unknown Platform',
}export class PlatformInfo {static getPlatform(): PlatformTypeEnum {let osFullNameInfo: string = deviceInfo.osFullName;let platformName: string = osFullNameInfo.split(' ')[0];if (platformName.includes("OpenHarmony")) {return PlatformTypeEnum.HARMONYOS;} else if (platformName.includes("Android")) {return PlatformTypeEnum.ANDROID;} else if (platformName.includes('iOS')) {return PlatformTypeEnum.IOS;} else {return PlatformTypeEnum.UNKNOWN;}}
}
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为例，具体实现参考如下：
// commons/recognize/src/main/ets/Interactive/Interactive.ets
import { PlatformInfo, PlatformTypeEnum } from 'utils';
import { InteractiveInterface } from './interface/interactiveInterface';
import { InteractiveArkUIX } from './impl/interactiveArkUIX';export class Interactive {public static getInterface(): InteractiveInterface {let platform: PlatformTypeEnum = PlatformInfo.getPlatform();if (platform == PlatformTypeEnum.ANDROID || platform == PlatformTypeEnum.IOS) {return InteractiveArkUIX.getInstance();} else {return InteractiveLocal.getInstance();}
}
这里不再赘述InteractiveArkUIX的实现，和上文CameraArkUIX思想一致，直接看InteractiveLocal的实现，最重要的便是在使用startLivenessDetection该API之前，需要重新动态import一次具体的系统接口文件，但正如上述所说，函数入口处的isSilentMode、actionsNum和routerOptions只是使用API中的数据类型声明定义变量，这些仍可以直接使用文件入口处import的interactiveLiveness能力而不会带来问题：
// commons/recognize/src/main/ets/Interactive//impl/InteractiveLocal.ets
import { InteractiveInterface } from '../interface/interactiveInterface';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import interactiveLiveness from '@hms.ai.interactiveLiveness'export class InteractiveLocal implements InteractiveInterface {public startInteractive(): void {let isSilentMode = "INTERACTIVE_MODE" as interactiveLiveness.DetectionMode;let actionsNum = 3 as interactiveLiveness.ActionsNumber;let routerOptions: interactiveLiveness.InteractiveLivenessConfig = {actionsNum: actionsNum,isSilentMode: isSilentMode};import('@hms.ai.interactiveLiveness').then((ns) => {try {ns.default.startLivenessDetection(routerOptions).then((DetectState: boolean) => {hilog.info(0x0001, "LivenessCollectionIndex", `Succeeded in jumping.`);}).catch((err: BusinessError) => {hilog.error(0x0001, "LivenessCollectionIndex", `Failed to jump. Code：${err.code}，message：${err.message}`);})} catch (err) {err = err as BusinessError;console.error(`startLivenessDetection failed. Code: ${err.code}, message: ${err.message}`);}return;})}
}
3.更优化的解决方案： 上述写法虽然可以解决crash的问题，但是不可避免地会在一个ets文件中的不同函数中反复多次进行动态import API，影响开发效率和代码整齐程度，所以可以考虑在Interactive类的平台差异化处，直接进行动态import ets文件的处理，处理完成后，文件内使用HMS API的地方无需再增加动态import API的侵入修改。
// commons/recognize/src/main/ets/Interactive/Interactive.ets
import { PlatformInfo, PlatformTypeEnum } from 'utils';
import { InteractiveInterface } from './interface/interactiveInterface';
import { InteractiveArkUIX } from './impl/interactiveArkUIX';export class Interactive {public static async getInterface(): Promise<InteractiveInterface|null> {let temp: InteractiveInterface | null = null;let platform: PlatformTypeEnum = PlatformInfo.getPlatform();if (platform == PlatformTypeEnum.ANDROID || platform == PlatformTypeEnum.IOS) {temp = InteractiveArkUIX.getInstance();} else {await import('./impl/interactiveLocal').then((ns) => {temp = new ns.InteractiveLocal();})}return temp;}
}