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 设计。开发者需要根据实际开发状况进行全面综合的考量。

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 进行说明。至于工程中具体的文件部署细节详见：工程目录结构设计。

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