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)