Harmony

[Harmony] 纯血鸿蒙跨平台方案 - ArkUI-X

Posted by xiuyuantech on 2025-07-27

ArkUI是一套构建分布式应用的声明式UI开发框架。
它具备简洁自然的UI信息语法、丰富的UI组件、多维的状态管理，
以及实时界面预览等相关能力，帮助您提升应用开发效率，并能在多种设备上实现生动而流畅的用户体验。详情可参考ArkUI框架介绍: https://developer.huawei.com/consumer/cn/arkui 。

ArkUI-X进一步将ArkUI扩展到了多个OS平台：目前支持OpenHarmony、HarmonyOS、Android、 iOS，后续会逐步增加更多平台支持。开发者基于一套主代码，就可以构建支持多平台的精美、高性能应用。
并会在未来逐步支持更多平台，官网是：https://gitee.com/arkui-x 。

ArkUI-X特征

  • 简洁自然的声明式语法。
  • 高效的渲染管线以及平台一致性的渲染机制。
  • 高效的方舟编译器以及运行时。
  • 统一的跨平台API能力集以及扩展机制。
  • 动态化特性。

纯血鸿蒙最低版本支持Api12，DevEco Studio版本至少为5.0.0
中文开发文档，第三方开源库中心，博客园相关教程，鸿蒙json转对象

HAP、HSP、HAR包的区别

  • HAP 全称是Harmony Ability Package，这里且简单翻译为鸿蒙能力包，理解为模块化分包。

    如果类比安卓开发，可以理解为android多模块项目中的module。（这里说一下差异，在项目的源代码上都是类似的结构，一个文件夹是一个module，但在打包编译上，安卓是全部合并，鸿蒙则是每个HAP是独立的，最终打包成一个应用）

    HAP有两种类型，一种是entry，是应用的主模块，作为应用的入口，提供了应用的基础功能
    （注意这里，也就是说，应用的主入口和一些基本功能都应该放到这个模块中来编写代码，这里应该是关系到应用启动以及自由流转功能是否快速且流畅）

    另外一种是feature，特性，或者可以理解为功能模块。

    总的来说HAP是将安装包的不同功能进行模块化分包的操作。

    值得注意的是，HAP并不支持导出接口和ArkUI组件给其他模块使用，也就意味着模块之间是相互隔离的，这里和安卓开发完全不同，安卓的多个模块之间依然可以有层级关系。

  • HSP 全称是Harmony Shared Package，官方称为动态共享包

    HSP要求要和宿主应用具有相同的包名，如果需要给公司内部的其他应用使用，需要了解集成态HSP(建议需要用到再研究)

    使用HSP的优势：

    • 多个HAP/HSP共用的代码和资源放在同一个HSP中，可以提高代码、资源的可重用性和可维护性，同时编译打包时也只保留一份HSP代码和资源，能够有效控制应用包大小。
    • HSP在运行时按需加载，有助于提升应用性能。
    • 同一个组织内部的多个应用之间，可以使用集成态HSP实现代码和资源的共享。

    需要注意的是：HSP可以发布但只能发布到私仓，也可以依赖其他HAR或HSP，但不支持循环依赖，也不支持依赖传递。

  • HAR 全称是Harmony Archive，官方称为静态共享包。

    官方的设定的职责是：通过HAR可以实现多个模块或多个工程共享ArkUI组件、资源等相关代码。

    使用场景主要是：作为二方库，发布到OHPM私仓，供公司内部其他应用使用；或作为三方库，发布到OHPM中心仓，供其他应用使用。

    同样的，需要注意的是：HAR可以依赖其他HAR，不支持循环依赖，也不支持依赖传递（HAR可以依赖HSP，但依赖HSP之后HAR仅支持应用内共享。

规格 HAP HAR HSP
支持在配置文件中声明UIAbility组件与ExtensionAbility组件 √ × ×
支持在配置文件中声明pages页面 √ × √
支持包含资源文件与.so文件 √ √ √
支持依赖其他HAR文件 √ √ √
支持依赖其他HSP文件 √ √ √
支持在设备上独立安装运行 √ × ×

实战

  • 鸿蒙的MVVM模式 MVVM模式介绍 在应用开发中，UI的更新需要随着数据状态的变化进行实时同步，而这种同步往往决定了应用程序的性能和用户体验。为了解决数据与UI同步的复杂性，ArkUI采用了
    Model-View-ViewModel（MVVM）架构模式。MVVM
    将应用分为Model、View和ViewModel三个核心部分，实现数据、视图与逻辑的分离。通过这种模式，UI可以随着状态的变化自动更新，无需手动处理，从而更加高效地管理数据和视图的绑定与更新。

    Model：负责存储和管理应用的数据以及业务逻辑，不直接与用户界面交互。

    View：负责用户界面展示数据并与用户交互，不包含任何业务逻辑。它通过绑定ViewModel层提供的数据来动态更新UI。

    ViewModel：负责管理UI状态和交互逻辑。作为连接Model和View的桥梁，ViewModel监控Model数据的变化，通知View更新UI，同时处理用户交互事件并转换为数据操作。

  • 状态管理
    V1: @State, @Prop, @Prop, @Observed, @Observed, @ObjectLink等；在状态管理V1中，使用$$实现系统组件的双向绑定。

    V2: @Local, @Param, @Event, @ObservedV2, @Monitor, @Computed等；在状态管理V2中，使用!!语法糖统一处理双向绑定。

    AppStorageV2: 应用全局UI状态存储，PersistenceV2: 持久化存储UI状态。

  • 参考案例

避坑

鸿蒙打包hvigorw clean报错No npmrc file is matched in the current user folder解决？

1
2
registry=https://repo.huaweicloud.com/repository/npm/
@ohos:registry=https://repo.harmonyos.com/npm/

Image组件无法响应长按事件？

组件默认拖拽效果，设置为true时，组件可拖拽，绑定的长按手势不生效。API version 9及之前，默认值为false。API version
10及之后，默认值为true。

1
2
Image()
     .draggable(fasle)

@LocalBuilder和@Builder区别？

@Builder：动态绑定到当前组件上下文（通常是子组件），传递到子组件时函数内部this指向子组件实例；可以使用wrapBuilder包裹全局Buidler，通过对象封装避免上下文丢失。
@LocalBuilder：保留原始父组件上下文，传递到子组件时函数内this仍指向父组件实例‌。

安全区域使用expandSafeArea属性无效？

最好同时设置固定宽高和expandSafeArea属性

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
@Entry
@Component
struct SafeAreaExample1 {
@State text: string = ''
    controller: TextInputController = new TextInputController()

    build() {
      Row() {
        Column()
        .height('100%').width('100%')
        .backgroundImage($r('app.media.bg')).backgroundImageSize(ImageSize.Cover)
        .expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.TOP, SafeAreaEdge.BOTTOM])
    }.height('100%')
  }
}

跨平台路由管理？

推荐使用@ohos/router

状态数据监听？

推荐使用@Observe/@ObserveV2/UIUtils.makeObserved

常见问题, 行业实践与常见问题

总结

由于ArkUI-X 是 鸿蒙系统 刚推出的跨平台开发框架，目前仍处于持续迭代中。第三方库支持比较少，跨平台能力兼容比较差，调用失败率达67%，主要因底层能力差异; 当前跨平台渲染性能仍存在10-15%帧率差异（复杂列表场景iOS平均FPS 50 vs 鸿蒙58），分布式能力无法直接跨平台使用。

FEATURED TAGS
Harmony
FRIENDS