HSP与HAR：HarmonyOSNext共享包开发终极指南

HSP与HAR：HarmonyOSNext共享包开发终极指南

##Harmony OS Next ##Ark Ts ##教育

本文适用于教育科普行业进行学习，有错误之处请指出我会修改。

---

🌟 HSP 到底是什么？

Harmony共享包（HSP） 就是个"百宝箱"🎒！它能打包代码、C++库、资源和配置，帮你轻松实现跨模块共享~ 不过要注意： 1️⃣ ​​不能独立发布​​：必须跟着宿主APP一起打包（共用包名和生命周期） 2️⃣ ​​分成两类​​：

类型	特点	使用范围
应用内HSP 🤖	编译时绑定特定包名	专属单个APP
集成态HSP 🧩	发布时不绑定包名	同组织多APP共享 （工具链会自动换包名&重签名）

---

🚀 为什么用HSP？三大神器！

✅ 省空间：多个HAP/HSP共享代码资源，安装包瘦身成功！ ⚡ ​​提速神器​​：运行时按需加载，丝滑体验get√ 🤝 ​​团队协作福音​​：公司内部APP直接共用功能模块

---

⚠️ 使用雷区提示

HSP使用三大禁忌：
1. 禁止单独安装！必须随宿主APP一起安装
2. 禁止声明Ability组件（UI/Extension都不行）
3. 禁止循环依赖/依赖传递！

📌 举个栗子说明雷区：

graph LR
A[HSP-A] --> B[HSP-B]
B --> C[HSP-C]
C -. ❌不可 .-> A   // 循环依赖禁止！
A -. ❌不可 .-> C   // 依赖传递禁止！

---

🔧 动手创建HSP

用DevEco Studio新建HSP模块（比如叫library），目录长这样：

MyApplication
├── library
│   ├── src
│   │   └── main
│   │       ├── ets
│   │       │   └── pages
│   │       │       └── index.ets    # 页面文件✨
│   │       ├── resources            # 资源仓库📦
│   │       └── module.json5         # 配置文件📄
│   ├── oh-package.json5             
│   ├── index.ets                    # 入口文件🚪
│   └── build-profile.json5          
└── build-profile.json5               # 工程级配置

---

🛠️ 如何导出资源？（四种姿势）

1️⃣ ArkUI组件导出

// 组件定义
@Component
export struct MyTitleBar {
  build() {
    Text($r('app.string.title')) // 正确资源引用姿势✅
      .fontSize(32)
  }
}

// 入口文件声明
export { MyTitleBar } from './src/...';

2️⃣ TS类/方法导出

// 工具类
export class Log {
  static info(msg) { console.log(msg) } 
}

// 入口文件声明
export { Log } from './src/...'; 

3️⃣ Native方法导出

import native from 'liblibrary.so';
export function nativeMulti(a,b) {
  return native.multi(a,b); // 调用C++方法
}

4️⃣ 资源安全导出（强推！）

// 创建资源管理类
export class ResManager {
  static getPic() {
    return $r('app.media.pic'); // ✅绝对路径最安全
  }
}
// 错误示范：Image("../../xxx.png") ❌相对路径会炸！

---

🎯 HSP使用指南

1️⃣ 引用HSP功能

先在oh-package.json5添加依赖：

"dependencies": {
  "library": "file:../library"
}

然后一键调用：

import { Log, ResManager } from 'library';

Log.info("Hi HSP!"); 
Image(ResManager.getPic()) // 直接使用图片

2️⃣ 跨模块跳转页面

跳HSP页面：

router.pushUrl({
  url: '@bundle:com.example.app/library/ets/pages/Menu'
})

📌 URL公式： @bundle:包名/模块名/路径/文件名(无后缀)

返回HAP页面：

router.back({ url: 'pages/Index' }) // 回宿主页

返回HSP页面：

router.back({ 
  url: '@bundle:com.example.app/library/ets/pages/Menu'
})

---

💡 关键总结表

操作类型	语法模板	示例
HSP跳转	@bundle:bundleName/moduleName/path/page	@bundle:com.demo.app/library/ets/Menu
回HAP页	pages/PageName	pages/Index
回HSP页	@bundle:.../page	@bundle:com.demo.app/library/ets/Menu

---

✨最佳实践忠告： 1️⃣ 用$r()访问资源，别用相对路径！ 2️⃣ 页面路由用绝对路径公式 3️⃣ 敏感操作包在try-catch里 4️⃣ 跨团队共享用集成态HSP

---

📦 HAR是什么？

鸿蒙静态共享包（HAR） 就是代码资源的"共享充电宝"🔋！能打包：

✅ ArkUI组件 ✅ TS方法 ✅ C++库
✅ 配置文件 ✅ 图片/文本资源

👉 三大使用场景：

场景	范围	特点
应用内共享 🤖	单个APP内部	模块间直接调用
二方库 🏢	公司内部	发布到OHPM私仓
三方库 🌐	全网开发者	上传OHPM中心仓

⚠️ 注意：多包重复引用HAR会导致安装包膨胀！

---

🚫 使用限制（避坑指南）

❗ 这些事HAR绝对不能做：
1. 禁止单独安装！必须被HAP/HSP依赖
2. 禁止声明ExtensionAbility
3. 禁止引用AppScope资源（编译时不会打包）
4. 禁止循环依赖/依赖传递（雷区同HSP）

💡 特殊技巧：

// 拉起HAR中的UIAbility时：
startAbility({
  moduleName: "宿主模块名", // 必须用宿主模块名！
  //...其他参数
})

---

🛠️ 创建HAR模块

用DevEco Studio新建HAR模块：

1. File > New > Module
2. 选择Static Library
3. 自动生成核心文件：

your-har-module
├── src
│   └── main
│       ├── ets          # ArkUI代码
│       ├── resources    # 资源仓库
│       └── module.json5 # 配置文件
└── index.ets            # 导出核心入口✨

📌 关键配置：在oh-package.json5中声明入口文件：

{
  "main": "index.ets" // 可自定义文件名
}

---

📤 四大导出技能（附代码模板）

1️⃣ ArkUI组件导出

// 定义可复用组件
@Component
export struct MainPage { /*...*/ }

// 在index.ets声明导出
export { MainPage } from './src/...';

2️⃣ TS类/方法导出

// 工具类封装
export class Log {
  static info(msg) { console.log(msg) }
}

// index.ets批量导出
export { Log, func1, func2 } from './src/...';

3️⃣ Native方法导出

import native from 'libyour.so';
export function nativeAdd(a,b) {
  return native.add(a,b); // 调用C++方法
}

4️⃣ 资源导出（易错！）

🆘 资源冲突优先级：
1. AppScope资源 > 2. 当前HAP资源 > 3. HAR资源
（同资源名时，优先级高的覆盖低的）

✅ 正确引用姿势：

Image($r('app.media.icon_har')) // 自动应用优先级规则

---

🔌 HAR使用全攻略

▶️ 配置依赖

在调用方的oh-package.json5添加：

"dependencies": {
  "your-har": "file:../your-har-path" 
}

▶️ 调用组件/方法

import { MainPage, Log, nativeAdd } from 'your-har';

// 使用ArkUI组件
MainPage()

// 调用TS方法
Log.info("调用成功！");

// Native计算
nativeAdd(1,2); 

▶️ 使用资源

直接通过$r调用：

Text($r('app.string.hello_har')) // 文本资源
Image($r('app.media.icon_har')) // 图片资源

---

⚙️ 进阶编译配置

🔒 代码混淆（保护资产）

在build-profile.json5中开启：

"arkOptions": {
  "obfuscation": {
    "ruleOptions": {
      "enable": true, // 关键开关！
      "files": ["./obfuscation-rules.txt"] 
    }
  }
}

⚡ 生成TS产物（实验特性）

在module.json5中添加元数据：

"metadata": [{
  "name": "UseTsHar",
  "value": "true" // 将js输出改为ts
}]

💡 适用场景：需要保留TS类型信息的特殊项目

---

💎 核心总结表

功能	支持情况	备注
独立安装	❌	必须被依赖
声明UIAbility	✅	需用宿主模块名拉起
声明Extension	❌	绝对禁止
资源优先级	宿主HAP > HAR	同名资源覆盖
TS产物输出	可配置	需metadata标记

✨ 最佳实践口诀： 1️⃣ 多用$r()访问资源 2️⃣ 组件导出走index.ets 3️⃣ 敏感代码开混淆 4️⃣ 公共库升版OHPM

HSP与HAR区别

📌 核心知识图谱

能力维度	HSP（动态）	HAR（静态）
共享特性	运行时按需加载 ⚡	编译时打包 📦
适用场景	同组织多应用共享 🤝	全局公共库/私有仓库 🌐
资源隔离	✅ 独立包名资源	❌ 服从优先级覆盖
组件支持	❌ 禁声明Ability	✅ 支持UIAbility
包体影响	🔻 按需加载瘦身	⚠️ 多引用会膨胀

---

🎯 开发者必读精华

✅ 资源导出黄金法则

// 跨模块资源调用唯一正确姿势！  
Image($r('app.media.shared_icon'))  
// 禁用！ => Image("../../resources/xxx.png")  

⚡ 性能优化三剑客

1. HSP动态加载：大功能模块拆解
2. HAR树摇优化：ohpm shrink 剔除无用代码
3. 资源压缩：rawfile目录 放非索引资源

🚫 高危操作红线

- 循环依赖：A→B→C→A ❌  
- HAR引用AppScope资源 ❌  
- HSP独立安装 ❌  
+ 集成态HSP自动重签名 ✅  

---

🔧 实战工具箱

1️⃣ 混淆配置模板

// build-profile.json5  
"obfuscation": {  
  "ruleOptions": {  
    "enable": true,  
    "files": ["./security-rules.txt"] // 自定义混淆规则  
  }  
}  

2️⃣ TS编译秘籍

// module.json5  
"metadata": [{  
  "name": "UseTsHar",  
  "value": "true"  // 输出TS类型文件！  
}]  

---

💎 终极总结： ​​HarmonyOSNext共享包设计哲学 = 动态灵活(HSP) + 静态沉淀(HAR)​​ ✨ 团队协作选HSP跨应用共享 | 开源复用用HAR上传OHPM 🔥 现在上手：DevEco Studio新建Module → 导出核心能力 → 发布OHPM私仓