1# HAR 2HAR(Harmony Archive)是静态共享包,可以包含代码、C++库、资源和配置文件。通过HAR可以实现多个模块或多个工程共享ArkUI组件、资源等相关代码。 3 4## 使用场景 5- 支持应用内共享,也可以发布后供其他应用使用。 6- 作为二方库,发布到[OHPM私仓](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V13/ide-ohpm-repo-V13),供公司内部其他应用使用。 7- 作为三方库,发布到[OHPM中心仓](https://ohpm.openharmony.cn/),供其他应用使用。 8- 多包(HAP/HSP)引用相同的HAR时,会造成多包间代码和资源的重复拷贝,从而导致应用包膨大。 9 10## 约束限制 11 12- HAR不支持在设备上单独安装/运行,只能作为应用模块的依赖项被引用。 13- HAR不支持在配置文件中声明[ExtensionAbility](../application-models/extensionability-overview.md)组件,但支持[UIAbility](../application-models/uiability-overview.md)组件。 14- HAR不支持在配置文件中声明[pages](./module-configuration-file.md#pages标签)页面,但是可以包含pages页面,并通过[命名路由](../ui/arkts-routing.md#命名路由)的方式进行跳转。 15- HAR不支持引用AppScope目录中的资源。在编译构建时,AppScope中的内容不会打包到HAR中,因此会导致HAR资源引用失败。 16- HAR可以依赖其他HAR,但不支持循环依赖,也不支持依赖传递。 17 18## 创建 19通过DevEco Studio创建一个HAR模块,详见[创建库模块](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V13/ide-har-V13#section643521083015)。 20 21 22## 开发 23 24介绍如何导出HAR的ArkUI组件、接口、资源,供其他应用或当前应用的其他模块引用。 25 26Index.ets文件是HAR导出声明文件的入口,HAR需要导出的接口,统一在Index.ets文件中导出。Index.ets文件是DevEco Studio默认自动生成的,用户也可以自定义,在模块的oh-package.json5文件中的main字段配置入口声明文件,配置如下所示: 27```json 28{ 29 "main": "Index.ets" 30} 31``` 32### 导出ArkUI组件 33ArkUI组件的导出方式与ts的导出方式一致,通过`export`导出ArkUI组件,示例如下: 34```ts 35// library/src/main/ets/components/mainpage/MainPage.ets 36@Component 37export struct MainPage { 38 @State message: string = 'HAR MainPage'; 39 40 build() { 41 Column() { 42 Row() { 43 Text(this.message) 44 .fontSize(32) 45 .fontWeight(FontWeight.Bold) 46 } 47 .margin({ top: '32px' }) 48 .height(56) 49 .width('624px') 50 51 Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center, alignContent: FlexAlign.Center }) { 52 Column() { 53 Image($r('app.media.pic_empty')).width('33%') 54 Text($r('app.string.empty')) 55 .fontSize(14) 56 .fontColor($r('app.color.text_color')) 57 } 58 }.width('100%') 59 .height('90%') 60 } 61 .width('100%') 62 .height('100%') 63 .backgroundColor($r('app.color.page_background')) 64 } 65} 66``` 67HAR对外暴露的接口,在Index.ets导出文件中声明如下所示: 68```ts 69// library/Index.ets 70export { MainPage } from './src/main/ets/components/mainpage/MainPage'; 71``` 72### 导出ts类和方法 73通过`export`导出ts类和方法,支持导出多个ts类和方法,示例如下所示: 74```ts 75// library/src/main/ts/test.ets 76export class Log { 77 static info(msg: string) { 78 console.info(msg); 79 } 80} 81 82export function func() { 83 return 'har func'; 84} 85 86export function func2() { 87 return 'har func2'; 88} 89``` 90HAR对外暴露的接口,在Index.ets导出文件中声明如下所示: 91```ts 92// library/Index.ets 93export { Log } from './src/main/ts/test'; 94export { func } from './src/main/ts/test'; 95export { func2 } from './src/main/ts/test'; 96``` 97 98### 导出native方法 99在HAR中也可以包含C++编写的so。对于so中的native方法,HAR通过以下方式导出,以导出liblibrary.so的加法接口add为例: 100```ts 101// library/src/main/ets/utils/nativeTest.ets 102import native from 'liblibrary.so'; 103 104export function nativeAdd(a: number, b: number): number { 105 let result: number = native.add(a, b); 106 return result; 107} 108``` 109HAR对外暴露的接口,在Index.ets导出文件中声明如下所示: 110```ts 111// library/Index.ets 112export { nativeAdd } from './src/main/ets/utils/nativeTest'; 113``` 114 115### 导出资源 116在编译构建HAP时,DevEco Studio会从HAP模块及依赖的模块中收集资源文件,如果不同模块下的资源文件出现重名冲突时,DevEco Studio会按照以下优先级进行覆盖(优先级由高到低): 117- AppScope(仅Stage模型支持)。 118- HAP包自身模块。 119- 依赖的HAR模块,如果依赖的多个HAR之间有资源冲突,会按照工程oh-package.json5中dependencies下的依赖顺序进行覆盖,依赖顺序在前的优先级较高。例如下方示例中dayjs和lottie中包含同名文件时,会优先使用dayjs中的资源。 120> **说明:** 121> 122> 如果在AppScope/HAP模块/HAR模块的国际化目录中配置了资源,在相同的国际化限定词下,合并的优先级也遵循上述规则。同时,国际化限定词中配置的优先级高于在base中的配置。如:在AppScope的base中配置了资源字段,在HAR模块的en_US中配置了同样的资源字段,则在en_US的使用场景中,会更优先使用HAR模块中配置的资源字段。 123``` 124// oh-package.json5 125{ 126 "dependencies": { 127 "dayjs": "^1.10.4", 128 "lottie": "^2.0.0" 129 } 130} 131``` 132 133## 使用 134 135介绍如何配置HAR依赖,并引用HAR的ArkUI组件、接口、资源。 136 137引用HAR前,需要先配置对HAR的依赖,详见[引用HAR文件和资源](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V13/ide-har-import-V13)。 138 139### 引用HAR的ArkUI组件 140 141HAR的依赖配置成功后,可以引用HAR的ArkUI组件。ArkUI组件的导入方式与ts的导入方式一致,通过`import`引入HAR导出的ArkUI组件,示例如下所示: 142```ts 143// entry/src/main/ets/pages/IndexSec.ets 144import { MainPage } from 'library'; 145 146@Entry 147@Component 148struct IndexSec { 149 build() { 150 Row() { 151 // 引用HAR的ArkUI组件 152 MainPage() 153 } 154 .height('100%') 155 } 156} 157``` 158### 引用HAR的ts类和方法 159通过`import`引用HAR导出的ts类和方法,示例如下所示: 160```ts 161// entry/src/main/ets/pages/Index.ets 162import { Log } from 'library'; 163import { func } from 'library'; 164 165@Entry 166@Component 167struct Index { 168 @State message: string = 'Hello World'; 169 170 build() { 171 Column() { 172 Text(this.message) 173 .fontFamily('HarmonyHeiTi') 174 .fontWeight(FontWeight.Bold) 175 .fontSize(32) 176 .fontWeight(700) 177 .fontColor($r('app.color.text_color')) 178 .textAlign(TextAlign.Start) 179 .margin({ top: '32px' }) 180 .width('624px') 181 182 //引用HAR的ts类和方法 183 Button($r('app.string.button')) 184 .id('button') 185 .height(48) 186 .width('624px') 187 .margin({ top: '4%' }) 188 .type(ButtonType.Capsule) 189 .fontFamily('HarmonyHeiTi') 190 .borderRadius($r('sys.float.ohos_id_corner_radius_button')) 191 .backgroundColor($r('app.color.button_background')) 192 .fontColor($r('sys.color.ohos_id_color_foreground_contrary')) 193 .fontSize($r('sys.float.ohos_id_text_size_button1')) 194 .onClick(() => { 195 // 引用HAR的类和方法 196 Log.info('har msg'); 197 this.message = 'func return: ' + func(); 198 }) 199 } 200 .width('100%') 201 .backgroundColor($r('app.color.page_background')) 202 .height('100%') 203 } 204} 205``` 206 207### 引用HAR的native方法 208通过`import`引用HAR导出的native方法,示例如下所示: 209```ts 210// entry/src/main/ets/pages/Index.ets 211import { nativeAdd } from 'library'; 212 213@Entry 214@Component 215struct Index { 216 @State message: string = 'Hello World'; 217 218 build() { 219 Column() { 220 Text(this.message) 221 .fontFamily('HarmonyHeiTi') 222 .fontWeight(FontWeight.Bold) 223 .fontSize(32) 224 .fontWeight(700) 225 .fontColor($r('app.color.text_color')) 226 .textAlign(TextAlign.Start) 227 .margin({ top: '32px' }) 228 .width('624px') 229 230 //引用HAR的native方法 231 Button($r('app.string.native_add')) 232 .id('nativeAdd') 233 .height(48) 234 .width('624px') 235 .margin({ top: '4%', bottom: '6%' }) 236 .type(ButtonType.Capsule) 237 .fontFamily('HarmonyHeiTi') 238 .borderRadius($r('sys.float.ohos_id_corner_radius_button')) 239 .backgroundColor($r('app.color.button_background')) 240 .fontColor($r('sys.color.ohos_id_color_foreground_contrary')) 241 .fontSize($r('sys.float.ohos_id_text_size_button1')) 242 .onClick(() => { 243 this.message = 'result: ' + nativeAdd(1, 2); 244 }) 245 } 246 .width('100%') 247 .backgroundColor($r('app.color.page_background')) 248 .height('100%') 249 } 250} 251``` 252 253### 引用HAR的资源 254通过`$r`引用HAR中的资源,例如在HAR模块的`src/main/resources`里添加字符串资源(在string.json中定义,name:hello_har)和图片资源(icon_har.png),然后在Entry模块中引用该字符串和图片资源的示例如下所示: 255```ts 256// entry/src/main/ets/pages/Index.ets 257@Entry 258@Component 259struct Index { 260 @State message: string = 'Hello World'; 261 262 build() { 263 Column() { 264 // 引用HAR的字符串资源 265 Text($r('app.string.hello_har')) 266 .id('stringHar') 267 .fontFamily('HarmonyHeiTi') 268 .fontColor($r('app.color.text_color')) 269 .fontSize(24) 270 .fontWeight(500) 271 .margin({ top: '40%' }) 272 273 List() { 274 ListItem() { 275 // 引用HAR的图片资源 276 Image($r('app.media.icon_har')) 277 .id('iconHar') 278 .borderRadius('48px') 279 } 280 .margin({ top: '5%' }) 281 .width('312px') 282 } 283 .alignListItem(ListItemAlign.Center) 284 } 285 .width('100%') 286 .backgroundColor($r('app.color.page_background')) 287 .height('100%') 288 } 289} 290``` 291## 编译 292 293HAR可以作为二方库和三方库提供给其他应用使用,如果需要对代码资产进行保护时,建议[开启混淆能力](../arkts-utils/source-obfuscation.md#开启代码混淆)。 294 295混淆能力开启后,DevEco Studio在构建HAR时,会对代码进行编译、混淆及压缩处理,保护代码资产。 296 297HAR模块原先默认开启混淆能力,会对API 10及以上的HAR模块,且编译模块为release时,自动进行简单的代码混淆;**从DevEco Studio 5.0.3.600开始,新建工程默认关闭代码混淆功能**,可以在HAR模块的build-profile.json5文件中的ruleOptions字段下的enable进行开启混淆,详情请见[代码混淆](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V13/ide-build-obfuscation-V13),配置如下所示: 298 299 ```json 300 { 301 "apiType": "stageMode", 302 "buildOption": { 303 }, 304 "buildOptionSet": [ 305 { 306 "name": "release", 307 "arkOptions": { 308 "obfuscation": { 309 "ruleOptions": { 310 "enable": true, 311 "files": [ 312 "./obfuscation-rules.txt" 313 ] 314 }, 315 "consumerFiles": [ 316 "./consumer-rules.txt" 317 ] 318 } 319 } 320 }, 321 ], 322 "targets": [ 323 { 324 "name": "default" 325 } 326 ] 327 } 328 ``` 329 330### 编译生成TS文件 331 332> **场景说明** 333> 334>在HAR中使用Sendable时,开启该配置。 335 336> **使用限制** 337> 338>在依赖TS HAR时,禁止引用TS HAR中的ArkUI组件。 339 340HAR模块中arkts文件编译后,默认产物为js文件,想要将产物修改为ts文件,可以在HAR模块下的module.json5文件中将"metadata"字段下的"name"设置为“UseTsHar”,配置如下所示: 341 342 ```json 343 { 344 "module": { 345 "name": "TsClosedHar", 346 "type": "har", 347 "deviceTypes": [ 348 "default", 349 "tablet", 350 "2in1" 351 ], 352 "metadata": [ 353 { 354 "name": "UseTsHar", 355 "value": "true" 356 } 357 ] 358 } 359 } 360 ``` 361 362## 发布 363 364详见[发布HAR](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V13/ide-har-publish-V13)。 365 366## 相关实例 367 368- [购物示例应用](https://gitee.com/openharmony/applications_app_samples/tree/master/code/Solutions/Shopping/OrangeShopping)