ArkUI-X跨平台应用改造指南

现状与诉求

随着 HarmonyOS Next 5.0 版本正式发布，众多开发者基于 ArkTS 语言为 HarmonyOS Next 系统开发了大量应用，这极大地丰富了 HarmonyOS 的生态。越来越多的应用上线，也给开发者带来了挑战，开发者需要同时开发和维护适用于 HarmonyOS Next、Android、iOS 三个平台的应用程序。这不仅意味着开发工作量大幅增加，开发成本也随之上升，而且很难保持一致的交互体验。

ArkUI-X 跨平台框架是基于 HarmonyOS 打造的跨端跨平台框架，能实现 “一次开发、三平台部署”。基于ArkTS开发的HarmonyOS Next应用，配套ArkUI-X跨平台框架，可以快速改造为跨平台应用，缩短开发周期，同时还能确保应用在 HarmonyOS Next、Android、iOS 多个平台上，为用户提供一致的交互体验。

本文重点介绍如何将HarmonyNext应用工程转换为跨平台工程，实现一码多平台。

改造目标

从零开始或基于现有HarmonyOS Next App进行改造，使其可快速部署于Android、IOS平台。

通过ArkUI-X框架Bridge能力实现ArkTS与原生平台交互。

方案说明

依据分层架构设计理念，分三部分阐述。

产品定制层（products）

由于不同操作系统之间的数据平台差异等客观原因，部分功能基于各平台的独特能力来实现不可避免。基于此，在products层，建议开发者建立两个module，分别命名为harmonyos和arkuix。在不同的hap包中集成对应的独特功能模块，最终编译成独立的hap包，以此实现功能隔离的效果。

当然，倘若在app的实际开发进程中确定所有功能在三端应用时均可实现，也就是不需要考虑平台差异性问题，可以直接采用单hap设计。开发者需要根据实际开发状况进行全面综合的考量。

module	编译产物：hap包	运行设备平台/系统能力支持
harmonyos	harmonyos.hap	HarmonyOS Next
arkuix	arkuix.hap	Android
arkuix	arkuix.hap	iOS

products层为App主module，其编译产物为HAP。作为应用的入口。一般保留有应用启动页和应用首页。由于采用了分包编译，需要开发者于harmonyos.hap（下面简称A包）和 arkuix.hap （下面简称B包）中各自独立开发应用启动页和应用首页（下面简称Pages），带来额外的开发量。基于此，建议开发者进行 products层设计时考虑以下几点：

共性考虑：对于App来说，A包和B包都存在”设置页面、我的页面、登录页面“（见上图），这些共性的代码和文件如果分别存放于A包和B包会导致大量的冗余代码，也不利于后期维护，因此建议对其进行抽象，形成一个独立的模块存放（features层模块main），通过module依赖的方式使用。

差异性考虑：对于App来说，仅A包存在”发现页面“（见上图），如果B包运行至”发现页面“时会产生不可预知的后果。

$$ B包的Pages设计时删除相关的页面元素，用户使用基于B包的app时不感知”发现页面“。

$$ 相关的数据结构、方法函数等应重新设计，可以抽象的部分进行抽象，存于features层模块main；无法抽象的部分各自实现。

基础特性层（features）

Features层属于App的特性界面层，其编译产物为HAR/HSP包。在该层级中，包含了应用的所有UI界面、弹窗、媒体图片等元素，这些都是能够被用户直接感知并进行操作的。此层是借助HarmonyOS的ArkUI组件以及相关能力来进行设计与开发的，并且ArkUI-X框架确保了在Android/iOS与HarmonyOS Next上能够拥有相同的展示效果和交互体验。

1.开发者进行设计时需首先考虑ArkUI-X框架的实际适配状况，使用支持跨平台的UI控件、属性、方法进行跨平台开发，因为在UI组件方面存在的差异，是无法借助Bridge能力来弥补的。

2.API接口的使用：在使用API接口时可能会遇到以下两种情况：1、API不支持跨平台。2、API在Android、IOS平台支持能力有差异（具体信息可参考相应的API文档）。因此不建议开发者在features层直接调用API接口实现功能。应尽可能对其抽象，于commons层创建功能模块实现，使用时调用commons层相应功能模块接口。具体实现详见“第三部分：公共能力层（commons）”。

3.共通组件：在实际开发过程中，可以抽象出部分满足多种场景的共通UI。可以在commons层创建模块“uicomponents”，将共通UI抽象并实现，实现代码复用的效果。

4.应注意，features层应合理设计模块，谨慎处理模块间依赖关系，避免循环依赖等问题。

模块main

Products层harmonyos.hap（下面简称A包）和 arkuix.hap （下面简称B包）这样的双hap设计解决了因设备平台差异导致的应用功能差异的问题。但是由此引入了新问题：如果对Products层代码进行量化，那么共性代码（A包和B包可复用的一套代码）是要远远多于差异性代码（A包和B包需各自进行设计，无法复用）的。开发者在后续的开发和维护过程中，每次都需要同时修改分别部署于A包和B包的共性代码。由此产生大量冗余代码和不必要的工作量。

为解决该问题，我们设计了模块main。模块main使用HAR。通过将共性的部分抽取、实现。后续的开发和维护过程中，仅修改main模块即可，从而提升开发效率，减少冗余代码，优化代码结构。

然而，需要特别注意的是，当products层采用单hap设计时，由于所有功能都集成在一个hap包中，因此无需额外创建模块main，以避免不必要的复杂性。

图片左侧为单hap设计，因为不存在差异性代码，所有代码集成于Products层phone.hap中，向下依赖features层。

图片右侧为双hap设计，其中差异性代码各自在harmonyos.hap和arkuix.hap中分别实现，实现功能隔离。共性代码抽象集成于features层模块main中，A包和B包共同依赖模块main，实现代码复用。

公共能力层（commons）

commons层是App的能力集合体，其编译产物为HAR/HSP包，主要用于阐述App的核心功能与附加服务。它向上能够为features层和products层直接给予能力方面的支持，向下则依靠运行设备平台的系统能力。ArkUI - X框架的Bridge能力，为功能模块直接调用Android/iOS平台的能力提供了有力的支撑。

需要注意的是，commons层应当合理规划模块设置，谨慎对待模块间的依赖关系，避免出现循环依赖等问题。

建议开发者首先考虑使用ArkUI-X框架已有API进行开发。

根据当前ArkUI-X框架的适配现状，可分为三种改造方式，结合架构图commons层 NetWork进行说明。至于工程中具体的文件部署细节详见：工程目录结构设计。

说明: 示例代码主要展示整体流程、架构。相关代码细节如接口定义、函数功能实现等需开发者根据实际进行开发填充。