HSP 与 HAR：HarmonyOSNext 共享包开发终极指南
##Harmony OS Next ##Ark Ts ##教育
本文适用于教育科普行业进行学习，有错误之处请指出我会修改。
🌟 HSP 到底是什么？
Harmony 共享包（HSP） 就是个"百宝箱"🎒！它能打包代码、C++库、资源和配置，帮你轻松实现跨模块共享~ 不过要注意：1️⃣ 不能独立发布：必须跟着宿主 APP 一起打包（共用包名和生命周期）2️⃣ 分成两类：
🚀 为什么用 HSP？三大神器！
✅ 省空间：多个 HAP/HSP 共享代码资源，安装包瘦身成功！⚡ 提速神器：运行时按需加载，丝滑体验 get√🤝 团队协作福音：公司内部 APP 直接共用功能模块
⚠️ 使用雷区提示
HSP使用三大禁忌：1. 禁止单独安装！必须随宿主APP一起安装2. 禁止声明Ability组件（UI/Extension都不行）3. 禁止循环依赖/依赖传递！
复制代码
📌 举个栗子说明雷区：
graph LRA[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 组件导出
// 组件定义@Componentexport 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'})
复制代码
💡 关键总结表
✨最佳实践忠告：1️⃣ 用$r()访问资源，别用相对路径！2️⃣ 页面路由用绝对路径公式 3️⃣ 敏感操作包在try-catch里 4️⃣ 跨团队共享用集成态 HSP
📦 HAR 是什么？
鸿蒙静态共享包（HAR） 就是代码资源的"共享充电宝"🔋！能打包：
✅ ArkUI组件 ✅ TS方法 ✅ C++库✅ 配置文件 ✅ 图片/文本资源
复制代码
👉 三大使用场景：
⚠️ 注意：多包重复引用 HAR 会导致安装包膨胀！
🚫 使用限制（避坑指南）
❗ 这些事HAR绝对不能做：1. 禁止单独安装！必须被HAP/HSP依赖2. 禁止声明ExtensionAbility3. 禁止引用AppScope资源（编译时不会打包）4. 禁止循环依赖/依赖传递（雷区同HSP）
复制代码
💡 特殊技巧：
// 拉起HAR中的UIAbility时：startAbility({ moduleName: "宿主模块名", // 必须用宿主模块名！ //...其他参数})
复制代码
🛠️ 创建 HAR 模块
用 DevEco Studio 新建 HAR 模块：
File > New > Module
选择Static Library
自动生成核心文件：
your-har-module├── src│ └── main│ ├── ets # ArkUI代码│ ├── resources # 资源仓库│ └── module.json5 # 配置文件└── index.ets # 导出核心入口✨
复制代码
📌 关键配置：在oh-package.json5中声明入口文件：
{ "main": "index.ets" // 可自定义文件名}
复制代码
📤 四大导出技能（附代码模板）
1️⃣ ArkUI 组件导出
// 定义可复用组件@Componentexport 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 类型信息的特殊项目
💎 核心总结表
✨ 最佳实践口诀：1️⃣ 多用$r()访问资源 2️⃣ 组件导出走index.ets3️⃣ 敏感代码开混淆 4️⃣ 公共库升版 OHPM
HSP 与 HAR 区别
📌 核心知识图谱
🎯 开发者必读精华
✅ 资源导出黄金法则
// 跨模块资源调用唯一正确姿势！ Image($r('app.media.shared_icon')) // 禁用！ => Image("../../resources/xxx.png")
复制代码
⚡ 性能优化三剑客
HSP 动态加载：大功能模块拆解
HAR 树摇优化：ohpm shrink 剔除无用代码
资源压缩：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私仓
评论