!16277 【包管理】包共享资料回合3.2 MR

Merge pull request !16277 from hanfeng/OpenHarmony-3.2-Release

zh-cn/application-dev/quick-start/Readme-CN.md

@@ -11,7 +11,6 @@
     - 应用程序包结构
       - [Stage模型应用程序包结构](application-package-structure-stage.md)
       - [FA模型应用程序包结构](application-package-structure-fa.md)
-      - [HAR包结构](har-structure.md)
     - 应用程序包多HAP机制
       - [多HAP机制设计目标](multi-hap-objective.md)
       - [多HAP构建视图](multi-hap-build-view.md)
@@ -20,6 +19,11 @@
       - [多HAP运行机制及数据通信方式](multi-hap-principles.md)
     - [应用程序包安装和卸载流程](application-package-install-uninstall.md)
     - [应用程序包更新流程](application-package-update.md)
+    - 共享包
+      - [共享包概述](shared-guide.md)
+      - [HAR](har-package.md)
+      - HSP
+        - [应用内HSP开发指导](in-app-hsp.md)
     - 应用程序包快速修复
       - [快速修复概述](quickfix-principles.md)
       - [快速修复调试指导](quickfix-debug.md)

zh-cn/application-dev/quick-start/application-package-structure-stage.md

@@ -4,7 +4,7 @@
 基于[Stage模型](application-configuration-file-overview-stage.md)开发的应用，经编译打包后，其应用程序包结构如下图**应用程序包结构（Stage模型）**所示。开发者需要熟悉应用程序包结构相关的基本概念。
 
 
-- 在开发态，一个应用包含一个或者多个Module，可以在[DevEco Studio](https://developer.harmonyos.com/cn/develop/deveco-studio/)工程中[创建一个或者多个Module](https://developer.harmonyos.com/cn/docs/documentation/doc-guides-V3/ohos-adding-deleting-module-0000001218760594-V3)。Module是OpenHarmony应用/服务的基本功能单元，包含了源代码、资源文件、第三方库及应用/服务配置文件，每一个Module都可以独立进行编译和运行。Module分为“Ability”和“Library”两种类型，“Ability”类型的Module对应于编译后的HAP（Harmony Ability Package）；“Library”类型的Module对应于[HAR](har-structure.md)（Harmony Ability Resources）包，即编译后的.tgz文件。
+- 在开发态，一个应用包含一个或者多个Module，可以在[DevEco Studio](https://developer.harmonyos.com/cn/develop/deveco-studio/)工程中[创建一个或者多个Module](https://developer.harmonyos.com/cn/docs/documentation/doc-guides-V3/ohos-adding-deleting-module-0000001218760594-V3)。Module是OpenHarmony应用/服务的基本功能单元，包含了源代码、资源文件、第三方库及应用/服务配置文件，每一个Module都可以独立进行编译和运行。Module分为“Ability”和“Library”两种类型，“Ability”类型的Module对应于编译后的HAP（Harmony Ability Package）；“Library”类型的Module对应于[HAR](har-package.md)（Harmony Archive），或者[HSP](shared-guide.md)（Harmony Shared Package）。
   一个Module可以包含一个或多个[UIAbility](../application-models/uiability-overview.md)组件，如下图所示。
 
     **图1** Module与UIAbility组件关系示意图  

zh-cn/application-dev/quick-start/har-package.md

+# HAR
+HAR（Harmony Archive）是静态共享包，可以包含代码、C++库、资源和配置文件。通过HAR可以实现多个模块或多个工程共享ArkUI组件、资源等相关代码。HAR不同于HAP，不能独立安装运行在设备上，只能作为应用模块的依赖项被引用。
+
+## 创建HAR模块
+HAR对应DevEco Studio工程中的“Library”类型的[Module](https://developer.harmonyos.com/cn/docs/documentation/doc-guides-V3/ohos-adding-deleting-module-0000001218760594-V3)，可以通过DevEco Studio创建一个HAR模块。HAR模块默认不开启混淆能力，开启混淆能力，需要把HAR模块的build-profile.json5文件中的artifactType字段设置为obfuscation，配置如下所示：
+
+```json
+{
+  "apiType": "stageMode",
+  "buildOption": {
+      "artifactType": "obfuscation"
+  }
+}
+```
+artifactType字段有以下两种取值，默认缺省为original。
+- original：不混淆。
+- obfuscation：混淆，目前仅支持uglify混淆。
+
+需要对代码资产进行保护时，建议开启混淆能力，混淆能力开启后，DevEco Studio在构建HAR时，会对代码进行编译、混淆及压缩处理，保护代码资产。
+注意：artifactType字段设置为obfuscation时，apiType字段必须设置为stageMode，因为Stage模型才支持混淆。
+
+## HAR开发注意事项
+- HAR不支持在配置文件中声明abilities、extensionAbilities组件。
+- HAR不支持在配置文件中声明pages页面。
+- HAR不支持在build-profile.json5文件的buildOption中配置worker。
+- FA模型与Stage模型的HAR不支持相互引用。
+- Stage模型的HAR，不能引用AppScope内的内容。在编译构建时APPScope中的内容不会打包到HAR中，导致HAR资源引用失败。
+
+## 导出HAR的ArkUI组件、接口、资源
+index.ets文件是HAR导出声明文件的入口，HAR需要导出的接口，统一在index.ets文件中导出。index.ets文件是DevEco Studio默认自动生成的，用户也可以自定义，在模块的package.json文件中的main字段配置入口声明文件，配置如下所示：
+```json
+{
+  "main": "index.ets"
+}
+```
+### 导出ArkUI组件
+ArkUI组件的导出方式与ts的导出方式一致，通过`export`导出ArkUI组件，示例如下：
+```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%')
+  }
+}
+```
+HAR对外暴露的接口，在index.ets导出文件中声明如下所示：
+```js
+// library/index.ets
+export { MainPage } from './src/main/ets/components/MainPage/MainPage'
+```
+### 导出ts类和方法
+通过`export`导出ts类和方法，支持导出多个ts类和方法，示例如下所示：
+```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";
+}
+```
+HAR对外暴露的接口，在index.ets导出文件中声明如下所示：
+```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'
+```
+### 资源
+HAR模块编译打包时会把资源打包到HAR中。在编译构建HAP时，DevEco Studio会从HAP模块及依赖的模块中收集资源文件，如果不同模块下的资源文件出现重名冲突时，DevEco Studio会按照以下优先级进行覆盖（优先级由高到低）：
+- AppScope（仅API9的Stage模型支持）。
+- HAP包自身模块。
+- 依赖的HAR模块，如果依赖的多个HAR之间有资源冲突，会按照依赖顺序进行覆盖（依赖顺序在前的优先级较高）。
+
+## 引用HAR的ArkUI组件、接口、资源
+引用HAR前，需要先配置对HAR的依赖，配置方式可[参考](https://developer.harmonyos.com/cn/docs/documentation/doc-guides/ohos-development-npm-package-0000001222578434#section89674298391)。
+
+### 引用HAR的ArkUI组件
+
+HAR的依赖配置成功后，可以引用HAR的ArkUI组件。ArkUI组件的导入方式与ts的导入方式一致，通过`import`引入HAR导出的ArkUI组件，示例如下所示：
+```js
+// entry/src/main/ets/pages/index.ets
+import { MainPage } from "@ohos/library"
+
+@Entry
+@Component
+struct Index {
+  @State message: string = 'Hello World'
+  build() {
+    Row() {
+      // 引用HAR的ArkUI组件
+      MainPage()
+      Column() {
+        Text(this.message)
+          .fontSize(50)
+          .fontWeight(FontWeight.Bold)
+      }
+      .width('100%')
+    }
+    .height('100%')
+  }
+}
+```
+### 引用HAR的类和方法
+通过`import`引用HAR导出的ts类和方法，示例如下所示：
+```js
+// entry/src/main/ets/pages/index.ets
+import { Log } from "@ohos/library"
+import { func } from "@ohos/library"
+
+@Entry
+@Component
+struct Index {
+  build() {
+    Row() {
+      Column() {
+        Button('Button')
+          .onClick(()=>{
+            // 引用HAR的类和方法
+            Log.info("har msg");
+            func();
+        })
+      }
+      .width('100%')
+    }
+    .height('100%')
+  }
+}
+```
+### 引用HAR的资源
+通过`$r`引用HAR中的资源，例如在HAR模块的`src/main/resources`里添加字符串资源（在string.json中定义，name：hello_har）和图片资源（icon_har.png），然后在Entry模块中引用该字符串和图片资源的示例如下所示：
+```js
+// entry/src/main/ets/pages/index.ets
+@Entry
+@Component
+struct Index {
+  build() {
+    Row() {
+      Column() {
+        // 引用HAR的字符串资源
+        Text($r("app.string.hello_har"))
+          .fontSize(50)
+          .fontWeight(FontWeight.Bold)
+        // 引用HAR的图片资源
+        Image($r("app.media.icon_har"))
+      }
+      .width('100%')
+    }
+    .height('100%')
+  }
+}
+```

zh-cn/application-dev/quick-start/har-structure.md

-# HAR包结构
-
-
-HAR（OpenHarmony Archive）包用于实现多个模块或多个工程间的代码共享。HAR包不同于HAP，不能独立安装运行在设备上，只能作为应用模块的依赖项被引用。
-
-
-HAR包对应DevEco Studio工程中的“Library”类型的[Module](https://developer.harmonyos.com/cn/docs/documentation/doc-guides-V3/ohos-adding-deleting-module-0000001218760594-V3)。
-
-
-OpenHarmony的[HAR包](https://developer.harmonyos.com/cn/docs/documentation/doc-guides/ohos-development-npm-package-0000001222578434)，是OpenHarmony静态共享包，可以包含代码、C++库、资源和module.json文件（Stage模型）或config.json文件（FA模型）等。

zh-cn/application-dev/quick-start/in-app-hsp.md

+# 应用内HSP开发指导
+
+应用内`HSP`指的是专门为某一应用开发的`HSP`，只能被该应用内部其他`HAP`/`HSP`使用，用于应用内部代码、资源的共享。
+应用内`HSP`跟随其宿主应用的APP包一起发布，与该宿主应用具有相同的包名和生命周期。
+
+## 开发应用内HSP
+
+`HSP`模块可以在`DevEco Studio`中由指定模板创建，我们以创建一个名为`library`的`HSP`模块为例。基本的工程目录结构大致如下：
+```
+library
+├── src
+│   └── main
+│       ├── ets
+│       │   ├── pages
+│       │   └── index.ets
+│       ├── resources
+│       └── module.json5
+└── package.json
+```
+模块`module.json5`中的`"type"`标识模块类型，`HSP`的`"type"`是`"shared"`。
+```json
+{
+    "type": "shared"
+}
+```
+
+`HSP`通过在入口文件中导出接口，对外提供能力。入口文件在模块`package.json`的`"main"`中配置。例如：
+```json
+{
+    "main": "./src/main/ets/index.ets"
+}
+```
+
+### 导出ts类和方法
+通过`export`导出ts类和方法，例如：
+```ts
+// library/src/main/ets/utils/test.ts
+export class Log {
+    static info(msg) {
+        console.info(msg);
+    }
+}
+
+export function add(a: number, b: number) {
+  return a + b;
+}
+
+export function minus(a: number, b: number) {
+  return a - b;
+}
+```
+对外暴露的接口，需要在入口文件`index.ets`中声明：
+```ts
+// library/src/main/ets/index.ets
+export { Log, add, minus } from './utils/test'
+```
+
+### 导出ArkUI组件
+ArkUI组件也可以通过`export`导出，例如：
+```ts
+// library/src/main/ets/components/MyTitleBar.ets
+@Component
+export struct MyTitleBar {
+  build() {
+    Row() {
+      Text($r('app.string.library_title'))
+        .fontColor($r('app.color.white'))
+        .fontSize(25)
+        .margin({left:15})
+    }
+    .width('100%')
+    .height(50)
+    .padding({left:15})
+    .backgroundColor('#0D9FFB')
+  }
+}
+```
+对外暴露的接口，需要在入口文件`index.ets`中声明：
+```ts
+// library/src/main/ets/index.ets
+export { MyTitleBar } from './components/MyTitleBar'
+```
+#### HSP中资源使用说明
+注意，在`HSP`中，通过`$r`/`$rawfile`可以使用本模块`resources`目录下的资源。
+如果使用相对路径的方式，例如：
+在`HSP`模块中使用`Image("common/example.png")`，实际上该`Image`组件访问的是`HSP调用方`（如`entry`）下的资源`entry/src/main/ets/common/example.png`。
+
+### 导出native方法
+在`HSP`中也可以包含`C++`编写的`so`。对于`so`中的`native`方法，`HSP`通过间接的方式导出，以导出`libnative.so`的乘法接口`multi`为例：
+```ts
+// ibrary/src/main/ets/utils/nativeTest.ts
+import native from "libnative.so"
+
+export function nativeMulti(a: number, b: number) {
+    return native.multi(a, b);
+}
+```
+
+对外暴露的接口，需要在入口文件`index.ets`中声明：
+```ts
+// library/src/main/ets/index.ets
+export { nativeMulti } from './utils/nativeTest'
+```
+
+## 使用应用内HSP
+要使用`HSP`中的接口，首先需要在使用方的`package.json`中配置对它的依赖。如果应用内`HSP`和使用方在同一工程下，可以直接本地引用，例如：
+```json
+// entry/src/main/module.json5
+"dependencies": {
+    "library": "file:../library"
+}
+```
+然后就可以像使用`HAR`一样调用`HSP`的对外接口了。
+例如，上面的`library`已经导出了下面这些接口：
+```ts
+// library/src/main/ets/index.ets
+export { Log, add, minus } from './utils/test'
+export { MyTitleBar } from './components/MyTitleBar'
+export { nativeMulti } from './utils/nativeTest'
+```
+在使用方的代码中，可以这样使用：
+```ts
+// entry/src/main/ets/pages/index.ets
+import { Log, add, MyTitleBar, nativeMulti } from "library"
+
+@Entry
+@Component
+struct Index {
+  @State message: string = 'Hello World'
+  build() {
+    Row() {
+      Column() {
+        MyTitleBar()
+        Text(this.message)
+          .fontSize(30)
+          .fontWeight(FontWeight.Bold)
+        Button('add(1, 2)')
+          .onClick(()=>{
+            Log.info("add button click!");
+            this.message = "result: " + add(1, 2);
+          })
+        Button('nativeMulti(3, 4)')
+          .onClick(()=>{
+            Log.info("nativeMulti button click!");
+            this.message = "result: " + nativeMulti(3, 4);
+          })
+      }
+      .width('100%')
+    }
+    .height('100%')
+  }
+}
+```
\ No newline at end of file

zh-cn/application-dev/quick-start/module-configuration-file.md

@@ -72,7 +72,7 @@ module.json5配置文件包含以下标签。
 | 属性名称 | 含义 | 数据类型 | 是否可缺省 |
 | -------- | -------- | -------- | -------- |
 | name | 标识当前Module的名称，标签值采用字符串表示（最大长度31个字节），该名称在整个应用要唯一，不支持中文。 | 字符串 | 该标签不可缺省。 |
-| type | 标识当前Module的类型。类型有两种，分别：<br/>-&nbsp;entry：应用的主模块。<br/>-&nbsp;feature：应用的动态特性模块。 | 字符串 | 该标签不可缺省。 |
+| type | 标识当前Module的类型。类型有4种，分别：<br/>-&nbsp;entry：应用的主模块。<br/>-&nbsp;feature：应用的动态特性模块。<br/>-&nbsp;har：静态共享包模块。<br/>-&nbsp;shared：动态共享包模块。 | 字符串 | 该标签不可缺省。 |
 | srcEntry | 标识当前Module所对应的代码路径，标签值为字符串（最长为127字节）。 | 字符串 | 该标签可缺省，缺省值为空。 |
 | description | 标识当前Module的描述信息，标签值是字符串类型（最长255字节）或对描述内容的字符串资源索引。 | 字符串 | 该标签可缺省，缺省值为空。 |
 | process | 标识当前Module的进程名，标签值为字符串类型（最长为31个字节）。如果在HAP标签下配置了process，该应用的所有UIAbility、DataShareExtensionAbility、ServiceExtensionAbility都运行在该进程中。<br/>**说明：**<br/>- 仅支持系统应用配置，三方应用配置不生效。 | 字符串 | 可缺省，缺省为app.json5文件下app标签下的bundleName。 |

zh-cn/application-dev/quick-start/shared-guide.md

+# 共享包概述
+
+OpenHarmony提供了两种共享包，[HAR（Harmony Achive）](har-package.md)静态共享包，和HSP（Harmony Shared Package）动态共享包。
+
+HAR与HSP都是为了实现代码和资源的共享，都可以包含代码、C++库、资源和配置文件，最大的不同之处在于：HAR中的代码和资源跟随使用方编译，如果有多个使用方，它们的编译产物中会存在多份相同拷贝；而HSP中的代码和资源可以独立编译，运行时在一个进程中代码也只会存在一份。
+
+**图1** `HAR`和`HSP`在`APP`包中的形态示意图
+![in-app-hsp-har](figures/in-app-hsp-har.png)
+
+**HSP旨在解决HAR存在的几个问题：**
+- 多个`HAP`引用相同的`HAR`，导致的`APP`包大小膨胀问题。
+- 多个`HAP`引用相同的`HAR`，`HAR`中的一些状态变量无法共享的问题。
+
+**HSP的一些约束：**
+- `HSP`及其使用方都必须是`Stage`模型。
+- `HSP`及其使用方都必须使用`esmodule`编译模式。
+- `HSP`不支持在配置文件中声明`abilities`、`extensionAbilities`标签。
+
+`HSP`按照使用场景可以分为[应用内HSP](in-app-hsp.md)和应用间HSP，应用间HSP暂不支持。
\ No newline at end of file

zh-cn/application-dev/reference/errorcodes/errorcode-bundle.md

@@ -210,6 +210,20 @@ Failed to install the HAP since the version of the HAP to install is too early.
 **处理步骤**<br/>
 确认新安装的应用版本号是否不低于已安装的同应用版本号。
 
+## 17700018 安装失败，依赖的模块不存在
+
+**错误信息**<br/>
+Failed to install because the dependent module does not exist.
+
+**错误描述**<br/>
+安装hap或者hsp时，依赖的模块不存在。
+
+**可能原因**<br/>
+依赖的模块没有安装。
+
+**处理步骤**<br/>
+先安装依赖的模块。
+
 ## 17700020 预置应用无法卸载
 
 **错误信息**<br/>