har-package.md 7.7 KB
Newer Older
E
ester.zhou 已提交
1 2 3 4
# HAR
A Harmony Archive (HAR) is a static shared package that can contain code, C++ libraries, resources, and configuration files. It enables modules and projects to share code related to ArkUI components, resources, and more. Unlike a Harmony Ability Package (HAP), a HAR cannot be independently installed on a device. Instead, it can be referenced only as the dependency of an application module.

## Creating a HAR Module
E
ester.zhou 已提交
5 6 7 8 9 10 11
You can [create a HAR module in DevEco Studio](https://developer.harmonyos.com/cn/docs/documentation/doc-guides-V3/creating_har_api9-0000001518082393-V3#section143510369612).

To better protect your source code, enable obfuscation for the HAR module so that DevEco Studio compiles, obfuscates, and compresses code during HAR building.
> **NOTE**
>
> Obfuscation is only available for ArkTS projects in the stage model.

E
ester.zhou 已提交
12
Whether obfuscation is enabled by default varies by version.
E
ester.zhou 已提交
13

E
ester.zhou 已提交
14
- In API version 9, obfuscation is disabled by default, and can be enabled by setting **artifactType** to **obfuscation** in the **build-profile.json5** file of the HAR module. The configuration is as follows:
E
ester.zhou 已提交
15

E
ester.zhou 已提交
16 17 18 19 20 21
  ```json
  {
    "apiType": "stageMode",
    "buildOption": {
        "artifactType": "obfuscation"
    }
E
ester.zhou 已提交
22
  }
E
ester.zhou 已提交
23 24 25 26
  ```
  The value options of **artifactType** are as follows, with the default value being **original**:
  - **original**: Code is not obfuscated.
  - **obfuscation**: Code is obfuscated using Uglify.
E
ester.zhou 已提交
27

E
ester.zhou 已提交
28
- In API version 10, obfuscation is enabled by default, and can be set through the **enable** field under **ruleOptions** in the **build-profile.json5** file of the HAR module. The configuration is as follows:
E
ester.zhou 已提交
29

E
ester.zhou 已提交
30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47
  ```json
  {
    "apiType": "stageMode",
    "buildOption": {
    },
    "buildOptionSet": [
      {
        "name": "release",
        "arkOptions": {
          "obfuscation": {
            "ruleOptions": {
              "enable": true,
              "files": [
                "./obfuscation-rules.txt"
              ]
            },
            "consumerFiles": [
              "./consumer-rules.txt"
E
ester.zhou 已提交
48
            ]
E
ester.zhou 已提交
49
          }
E
ester.zhou 已提交
50
        }
E
ester.zhou 已提交
51 52 53 54 55
      },
    ],
    "targets": [
      {
        "name": "default"
E
ester.zhou 已提交
56
      }
E
ester.zhou 已提交
57 58 59
    ]
  }
  ```
E
ester.zhou 已提交
60 61 62
### Adaptation Guide

The **artifactType** field is forward compatible, and the original function is not affected. Yet, it is deprecated since API version 10, and you are advised to use the substitute as soon as possible.
E
ester.zhou 已提交
63 64 65 66 67 68 69 70 71

## Precautions for HAR Development
- The HAR does not support the declaration of **abilities** and **extensionAbilities** in its configuration file.
- The HAR does not support the declaration of pages in its configuration file.
- The HAR does not support **worker** configuration under **buildOption** in the **build-profile.json5** file.
- The HAR of the FA model and that of the stage model cannot be referenced by each other.
- The HAR of the stage model cannot reference content in the **AppScope** folder. This is because the content in the **AppScope** folder is not packaged into the HAR during compilation and building.

## Exporting ArkUI Components, APIs, and Resources of the HAR
E
ester.zhou 已提交
72
The **index.ets** file acts as the entry of the HAR export declaration file and is where the HAR exports APIs. This file is automatically generated by DevEco Studio by default. You can specify another file as the entry declaration file in the **main** field in the **oh-package.json5** file of the module. The code snippet is as follows:
E
ester.zhou 已提交
73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129
```json
{
  "main": "index.ets"
}
```
### Exporting ArkUI Components
Use **export** to export the ArkUI components. The code snippet is as follows:
```js
// library/src/main/ets/components/MainPage/MainPage.ets
@Component
export struct MainPage {
  @State message: string = 'Hello World'
  build() {
    Row() {
      Column() {
        Text(this.message)
          .fontSize(50)
          .fontWeight(FontWeight.Bold)
      }
      .width('100%')
    }
    .height('100%')
  }
}
```
In the **index.ets** file, declare the APIs that the HAR exposes to external systems. The code snippet is as follows:
```js
// library/index.ets
export { MainPage } from './src/main/ets/components/MainPage/MainPage'
```
### Exporting TS Classes and Methods
Use **export** to export TS classes and methods. Multiple TS classes and methods can be exported at the same time. The code snippet is as follows:
```js
// library/src/main/ts/test.ets
export class Log {
    static info(msg) {
        console.info(msg);
    }
}

export function func() {
  return "har func";
}

export function func2() {
  return "har func2";
}
```
In the **index.ets** file, declare the APIs that the HAR exposes to external systems. The code snippet is as follows:
```js
// library/index.ets
export { Log } from './src/main/ts/test'
export { func } from './src/main/ts/test'
export { func2 } from './src/main/ts/test'
```
### Resources
Resources are packed into the HAR when it is being compiled and packaged. During compilation and building of a HAP, DevEco Studio collects resource files from the HAP module and its dependent modules. If the resource files of different modules have the same name, DevEco Studio overwrites the resource files based on the following priorities (in descending order):
E
ester.zhou 已提交
130
- AppScope (only for the stage model of API version 9)
E
ester.zhou 已提交
131 132 133 134
- Modules in the HAP file
- If resource conflicts occur between dependent HAR modules, they are overwritten based on the dependency sequence. (The module that is higher in the dependency sequence list has higher priority.)

## Referencing ArkUI Components, APIs, and Resources in the HAR
E
ester.zhou 已提交
135
To start with, [configure dependency](https://developer.harmonyos.com/cn/docs/documentation/doc-guides-V3/creating_har_api9-0000001518082393-V3#section611662614153) on the HAR.
E
ester.zhou 已提交
136 137 138

### Reference ArkUI Components in the HAR

E
ester.zhou 已提交
139
After configuring the dependency on the HAR, you can reference ArkUI components exported from the HAR by using **import**. The code snippet is as follows:
E
ester.zhou 已提交
140 141
```js
// entry/src/main/ets/pages/index.ets
142
import { MainPage } from "library"
E
ester.zhou 已提交
143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166

@Entry
@Component
struct Index {
  @State message: string = 'Hello World'
  build() {
    Row() {
      // Reference the ArkUI component in the HAR.
      MainPage()
      Column() {
        Text(this.message)
          .fontSize(50)
          .fontWeight(FontWeight.Bold)
      }
      .width('100%')
    }
    .height('100%')
  }
}
```
### Referencing TS Classes and Methods in the HAR
To reference the TS classes and methods exported from the HAR, use **import** as follows:
```js
// entry/src/main/ets/pages/index.ets
167 168
import { Log } from "library"
import { func } from "library"
E
ester.zhou 已提交
169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211

@Entry
@Component
struct Index {
  build() {
    Row() {
      Column() {
        Button('Button')
          .onClick(()=>{
            // Reference TS classes and methods in the HAR.
            Log.info("har msg");
            func();
        })
      }
      .width('100%')
    }
    .height('100%')
  }
}
```
### Referencing Resources in the HAR
Use **$r** to reference resources in the HAR. For example, add the **name: hello_har** string (defined in the **string.json** file) and **icon_har.png** image to the **src/main/resources** directory of the HAR module, and then reference the string and image in the entry module. The code snippet is as follows:
```js
// entry/src/main/ets/pages/index.ets
@Entry
@Component
struct Index {
  build() {
    Row() {
      Column() {
        // Reference the string in the HAR.
        Text($r("app.string.hello_har"))
          .fontSize(50)
          .fontWeight(FontWeight.Bold)
        // Reference the image in the HAR.
        Image($r("app.media.icon_har"))
      }
      .width('100%')
    }
    .height('100%')
  }
}
```
E
ester.zhou 已提交
212 213 214 215

## Releasing a HAR

Follow the [instructions](https://developer.harmonyos.com/cn/docs/documentation/doc-guides-V3/creating_har_api9-0000001518082393-V3#section1213451811512) to release a HAR.