鸿蒙学习实战之路-HarmonyOS包转换全攻略

🥦 鸿蒙学习实战之路-HarmonyOS包转换全攻略

最近好多朋友问我："西兰花，我写了个HarmonyOS组件库，怎么打包成HAR给别人用？""我有个HSP想转成HAR，能行吗？""HAP怎么导出成可复用的HAR？"o(╯□╰)o

别慌别慌！今天这篇，我就把鸿蒙开发中常用的三种包转换（HAR转HSP、HSP转HAR、HAP转HAR）一次性讲明白，全程带代码、带步骤，包你看完就会！

🥦 一、先搞清楚：什么是HAR、HSP、HAP？

在开始转换之前，咱们得先弄明白这三个"包"到底是啥：

包类型	全称	作用	类比
HAR	Harmony Archive	静态共享包，用于代码复用	就像厨房里的"预制菜"，可以直接拿来用
HSP	Harmony Shared Package	动态共享包，运行时加载	类似"外卖"，需要的时候才送过来
HAP	Harmony Ability Package	应用安装包，可直接运行	完整的"一顿饭"，可以直接吃

简单来说：

HAR适合组件库、工具类的复用，编译时集成
HSP适合需要动态更新的功能模块，运行时加载
HAP就是最终用户安装的应用

🥦 二、HAR转HSP：静态包变动态包

有时候咱们写了个HAR组件库，但想让它支持动态更新，这时候就需要把HAR转成HSP了。

1. 操作步骤

步骤1：创建HSP模块

在DevEco Studio中，右键点击项目 > New > Module > HarmonyOS Shared Package (HSP)

步骤2：配置HSP的build-profile.json5

json5 复制代码

{
  "app": {
    "signingConfigs": [],
    "compileSdkVersion": 9,
    "compatibleSdkVersion": 9
  },
  "modules": [
    {
      "name": "my_hsp",
      "srcPath": "./my_hsp",
      "targets": [
        {
          "name": "default",
          "applyToProducts": ["default"]
        }
      ],
      "buildOption": {
        "arkOptions": {
          "runtimeOnly": {
            "jsiLibs": []
          }
        }
      }
    }
  ]
}

步骤3：将HAR的源码复制到HSP模块

把原来HAR里的代码、资源文件复制到HSP的对应目录下

步骤4：构建HSP

点击Build > Build Hap(s)/Hsp(s) > Build Hsp(s)

2. 代码示例

假设我们有个HAR里的按钮组件，转成HSP后这样用：

arkts 复制代码

// 导入HSP里的组件
import { CustomButton } from 'hsp://my_hsp/components/CustomButton';

@Entry
@Component
struct Index {
  build() {
    Column() {
      // 使用HSP里的组件
      CustomButton({
        text: '点击我',
        onClick: () => {
          console.log('HSP组件被点击了！');
        }
      })
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
  }
}

🥦 三、HSP转HAR：动态包变静态包

相反，如果我们有个HSP想转成HAR，方便在其他项目中静态集成，该怎么做呢？

1. 操作步骤

步骤1：创建HAR模块

在DevEco Studio中，右键点击项目 > New > Module > HarmonyOS Archive (HAR)

步骤2：配置HAR的build-profile.json5

json5 复制代码

{
  "app": {
    "signingConfigs": [],
    "compileSdkVersion": 9,
    "compatibleSdkVersion": 9
  },
  "modules": [
    {
      "name": "my_har",
      "srcPath": "./my_har",
      "type": "har",
      "targets": [
        {
          "name": "default",
          "applyToProducts": ["default"]
        }
      ],
      "buildOption": {
        "arkOptions": {
          "runtimeOnly": {
            "jsiLibs": []
          }
        }
      }
    }
  ]
}

步骤3：将HSP的源码复制到HAR模块

注意：需要移除HSP特有的动态加载代码

步骤4：构建HAR

点击Build > Build Hap(s)/Hsp(s) > Build Har(s)

2. 代码示例

转成HAR后，组件的使用方式变成这样：

arkts 复制代码

// 导入HAR里的组件（注意导入路径变化）
import { CustomButton } from '@ohos/my_har/components/CustomButton';

@Entry
@Component
struct Index {
  build() {
    Column() {
      // 使用HAR里的组件
      CustomButton({
        text: '点击我',
        onClick: () => {
          console.log('HAR组件被点击了！');
        }
      })
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
  }
}

🥦 四、HAP转HAR：应用变可复用组件

有时候我们在开发HAP应用时，发现某个功能模块做得特别好，想抽出来做成HAR给其他项目用，这时候就需要HAP转HAR了。

1. 操作步骤

步骤1：创建HAR模块

和前面一样，先创建一个HAR模块

步骤2：分析HAP的功能模块

找出HAP中可复用的组件、工具类等

步骤3：复制代码并处理依赖

复制可复用的源码到HAR模块
处理资源文件（图片、字符串等）
移除应用特有的配置和代码（如MainAbility）

步骤4：配置HAR的public API

在HAR的oh-package.json5中配置需要导出的API：

json5 复制代码

{
  "name": "my_har",
  "version": "1.0.0",
  "description": "我的HAR组件库",
  "main": "index",
  "exports": {
    "./components/*": {
      "default": "./src/main/ets/components/*"
    },
    "./utils/*": {
      "default": "./src/main/ets/utils/*"
    }
  }
}

步骤5：构建HAR

点击Build > Build Hap(s)/Hsp(s) > Build Har(s)

2. 代码示例

假设我们从HAP中抽出了一个轮播图组件：

arkts 复制代码

// 轮播图组件（从HAP中抽出）
@Component
export struct CarouselComponent {
  @Prop images: string[] = [];
  @Prop interval: number = 3000;

  build() {
    Carousel() {
      ForEach(this.images, (image) => {
        Image(image)
          .width('100%')
          .height(200)
          .objectFit(ImageFit.Cover)
      })
    }
    .width('100%')
    .height(200)
    .autoPlay(true)
    .interval(this.interval)
    .loop(true)
  }
}

在其他项目中使用这个HAR组件：

arkts 复制代码

import { CarouselComponent } from '@ohos/my_har/components/CarouselComponent';

@Entry
@Component
struct Index {
  private images: string[] = [
    'https://example.com/image1.jpg',
    'https://example.com/image2.jpg'
  ];

  build() {
    Column() {
      Text('轮播图示例')
        .fontSize(20)
        .margin({ top: 20 })
      
      // 使用从HAP抽出的轮播图组件
      CarouselComponent({
        images: this.images,
        interval: 2000
      })
      .margin({ top: 20 })
    }
    .width('100%')
    .padding(20)
  }
}

🥦 五、三种转换的对比总结

转换类型	使用场景	优点	注意事项
HAR→HSP	需要动态更新的组件库	支持运行时更新	需处理动态加载的兼容性
HSP→HAR	动态模块转静态复用	编译时集成，性能更好	移除动态加载相关代码
HAP→HAR	应用功能模块复用	快速沉淀可复用组件	需清理应用特有代码

🥦 西兰花警告

资源文件处理：转换时要注意资源文件的路径，特别是图片、字符串等，避免资源找不到的问题
API兼容性：HAR和HSP的API导出方式不同，转换后要检查导入路径是否正确
依赖管理：转换时要注意处理第三方依赖，避免重复依赖或版本冲突
签名配置：HSP需要签名配置，而HAR不需要，转换时要注意调整

🥦 西兰花小贴士

如果你经常需要进行包转换，可以考虑写个脚本自动化处理
转换完成后一定要进行测试，确保功能正常
对于复杂的包，建议先小范围转换和测试，再推广使用

🥦 总结

今天咱们学习了HarmonyOS开发中三种常用的包转换：

HAR转HSP：适合需要动态更新的组件库
HSP转HAR：适合将动态模块转成静态复用
HAP转HAR：适合从应用中抽出可复用的功能模块

每种转换都有其适用场景，根据实际需求选择合适的方式即可。

📚 推荐资料：

官方文档：HAR转HSP
官方文档：HSP转HAR
官方文档：HAP转HAR

我是盐焗西兰花，

不教理论，只给你能跑的代码和避坑指南。

下期见！🥦