!16245 元服务分包预加载需求变更

Merge pull request !16245 from 赵淦/master

!16245 元服务分包预加载需求变更
Merge pull request !16245 from 赵淦/master
4db81ab8 · openharmony_ci · Gitee · 920d62a2 · b8f34fc6 · 4db81ab8
7 changed file
--- a/zh-cn/application-dev/quick-start/Readme-CN.md
+++ b/zh-cn/application-dev/quick-start/Readme-CN.md
@@ -25,6 +25,8 @@
      - HSP
        - [应用内HSP开发指导](in-app-hsp.md)
        - [应用间HSP开发指导（仅对系统应用开放）](cross-app-hsp.md)
+    - 原子化服务
+      - [原子化服务开发指导](atomicService.md)
    - 应用程序包快速修复
      - [快速修复概述](quickfix-principles.md)
      - [快速修复调试指导](quickfix-debug.md)

--- a/zh-cn/application-dev/quick-start/app-configuration-file.md
+++ b/zh-cn/application-dev/quick-start/app-configuration-file.md
@@ -33,6 +33,7 @@ app.json5配置文件包含以下标签。
 | 属性名称 | 含义 | 数据类型 | 是否可缺省 |
 | -------- | -------- | -------- | -------- |
 | bundleName | 标识应用的Bundle名称，用于标识应用的唯一性。该标签不可缺省。标签的值命名规则&nbsp;：<br/>-&nbsp;字符串以字母、数字、下划线和符号“.”组成。<br/>-&nbsp;以字母开头。<br/>-&nbsp;最小长度7个字节，最大长度127个字节。<br/>推荐采用反域名形式命名（如com.example.demo，建议第一级为域名后缀com，第二级为厂商/个人名，第三级为应用名，也可以多级）。<br/>其中，随系统源码编译的应用建议命名为“com.ohos.demo”形式，&nbsp;ohos标识OpenHarmony系统应用。 | 字符串 | 该标签不可缺省。 |
+| bundleType| 标识应用的Bundle类型，用于区分应用或者原子化服务。该标签可选值为app和atomicService&nbsp;：<br/>-&nbsp;app：当前Bundle为普通应用。<br/>-&nbsp;atomicService：当前Bundle为原子化服务。| 字符串| 该标签可以缺省，缺省为app。 |
 | debug | 标识应用是否可调试，该标签由IDE编译构建时生成。<br/>-&nbsp;true：可调试。<br/>-&nbsp;false：不可调式。 | 布尔值 | 该标签可以缺省，缺省为false。 |
 | icon | 标识[应用的图标](../application-models/application-component-configuration-stage.md)，标签值为图标资源文件的索引。 | 字符串 | 该标签不可缺省。 |
 | label | 标识[应用的名称](../application-models/application-component-configuration-stage.md)，标签值为字符串资源的索引。 | 字符串 | 该标签不可缺省。 |

--- a/zh-cn/application-dev/quick-start/atomicService.md
+++ b/zh-cn/application-dev/quick-start/atomicService.md
+# 原子化服务
+## 原子化服务分包预加载
+### 使用分包
+为了加快首次启动原子化服务时的速度，可以采用分包策略，原子化服务的代码包可以被划分为几个：一个是类型为entry的模块，包含原子化服务启动时会打开的页面代码和相关资源；其余是“分包”，包含其余的代码和资源。这样，启动原子化服务时，只需下载和安装entry模块，即可立刻启动原子化服务，大大降低原子化服务下载的时间。
+#### 配置方法
+原子化服务分包可以在`DevEco Studio`中创建，我们以创建一个原子化服务为例。基本的工程目录结构大致如下：
+```
+├── AppScope
+|    ├── resources
+|    └── app.json5
+├── entry
+|    └── src/main
+|       ├── ets
+|       ├── resources
+|       └── module.json5
+├── feature
+|    └── src/main
+|       ├── ets
+|       ├── resources
+|       └── module.json5
+├── library
+|    └── src/main
+|       ├── ets
+|       ├── resources
+|       └── module.json5
+├── node_modules
+```
+注意，开发者需要在[app.json5](app-configuration-file.md)中`bundleType`字段指定为`atomicService`，标识当前应用是原子化服务。`app.json5`（路径为：`AppScope/app.json5`）的内容为：
+```json
+{
+  "app": {
+    "bundleName": "com.example.hmservice",
+    "bundleType":"atomicService",
+    "vendor": "example",
+    "versionCode": 1000000,
+    "versionName": "1.0.0",
+    "icon": "$media:app_icon",
+    "label": "$string:app_name",
+    "distributedNotificationEnabled": true,
+    "targetAPIVersion": 9
+  }
+}
+```
+具体分包攻略，详细可参考[多hap开发](multi-hap-objective.md)。
+#### 限制
+1. 原子化服务中每个模块对应的配置文件[module.json5](module-configuration-file.md)中`installationFree`字段必须为`true`。
+2. 打包原子化服务时，需遵循以下大小校验规则：
+- 原子化服务中，所有包的大小总和不能超过10M。
+- 单个包加上其依赖的所有[共享包](in-app-hsp.md)，大小不能超过2M。
+### 使用预加载
+开发者可以通过配置，在原子化服务进入某个模块时，由系统自动预下载可能需要的模块，从而提升进入后续模块的速度。
+原子化服务预加载目前只支持通过配置方式使用，暂不支持通过调用API使用。
+#### 配置方法
+原子化服务预加载行为在点击进入某个模块时，第一帧绘制结束之后触发，可以通过在相应模块的[module.json5](module-configuration-file.md)文件中配置`atomicService`标签下的`preloads`字段来控制，以下为entry模块的`module.json5`（路径为：`entry/src/main/module.json5`）文件内容：
+```json
+{
+  "module": {
+    "name": "entry",
+    "type": "entry",
+    "srcEntrance": "./ets/Application/MyAbilityStage.ts",
+    "description": "$string:entry_desc",
+    "mainElement": "MainAbility",
+    "deviceTypes": [
+      "default",
+      "tablet"
+    ],
+    "deliveryWithInstall": true,
+    "installationFree": true,
+    "pages": "$profile:main_pages",
+    "atomicService": {
+      "preloads": [
+        {
+          "moduleName": "feature"
+        }
+      ]
+    },
+    "abilities": [
+      {
+        "name": "MainAbility",
+        "srcEntrance": "./ets/MainAbility/MainAbility.ts",
+        "description": "$string:MainAbility_desc",
+        "icon": "$media:icon",
+        "label": "$string:MainAbility_label",
+        "startWindowIcon": "$media:icon",
+        "startWindowBackground": "$color:white",
+        "visible": true,
+        "skills": [
+          {
+            "entities": [
+              "entity.system.home"
+            ],
+            "actions": [
+              "action.system.home"
+            ]
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+在完成entry模块的第一帧绘制结束后，会自动执行预加载去下载和安装模块名为feature的模块。
+#### 限制
+preloads列表配置的moduleName对应的[moduleType(模块类型)](../reference/apis/js-apis-bundleManager.md#moduletype)不能为entry。
+## 原子化服务中使用动态共享包
+[Harmony动态共享包](shared-guide.md)（Harmony Shared Package），简称HSP，其可以包含其他模块公用的代码、C++库、资源和配置文件等。
+在原子化服务中使用HSP，可以参考[应用内HSP开发指导](in-app-hsp.md)。
+#### 配置方法
+假设工程目录结构如下：
+```
+├── AppScope
+|    ├── resources
+|    └── app.json5
+├── entry
+|    └── src/main
+|       ├── ets
+|           ├── entryAbility
+|           └── pages
+|               └── Index.ets
+|       ├── resources
+|       └── module.json5
+├── feature
+|    └── src/main
+|       ├── ets
+|       ├── resources
+|       └── module.json5
+├── library
+|    └── src/main
+|       ├── ets
+|           └── pages
+|               └── menu.ets
+|       ├── resources
+|       └── module.json5
+├── node_modules
+```
+若开发者想在entry模块中，添加一个按钮跳转至library模块中的menu页面（路径为：`library/src/main/ets/pages/menu.ets`），那么可以在使用方的代码（entry模块下的Index.ets，路径为：`entry/src/main/ets/MainAbility/Index.ets`）里这样使用：
+```ts
+import router from '@ohos.router';
+@Entry
+@Component
+struct Index {
+    @State message: string = 'Hello World'
+    build() {
+    Row() {
+        Column() {
+        Text(this.message)
+            .fontSize(50)
+            .fontWeight(FontWeight.Bold)
+        // 添加按钮，以响应用户点击
+        Button() {
+            Text('click to menu')
+            .fontSize(30)
+            .fontWeight(FontWeight.Bold)
+        }
+        .type(ButtonType.Capsule)
+        .margin({
+            top: 20
+        })
+        .backgroundColor('#0D9FFB')
+        .width('40%')
+        .height('5%')
+        // 绑定点击事件
+        .onClick(() => {
+            router.pushUrl({
+              url: '@bundle:com.example.hmservice/library/ets/pages/menu'
+            }).then(() => {
+              console.log("push page success");
+            }).catch(err => {
+              console.error(`pushUrl failed, code is ${err.code}, message is ${err.message}`);
+            })
+        }
+        .width('100%')
+    }
+    .height('100%')
+    }
+}
+```
+其中`router.pushUrl`方法的入参中`url`的内容为：
+```ets
+'@bundle:com.example.hmservice/library/ets/pages/menu'
+```
+`url`内容的模板为：
+```ets
+'@bundle:包名（bundleName）/模块名（moduleName）/路径/页面所在的文件名(不加.ets后缀)'
+```
\ No newline at end of file
--- a/zh-cn/application-dev/quick-start/module-configuration-file.md
+++ b/zh-cn/application-dev/quick-start/module-configuration-file.md
@@ -87,6 +87,8 @@ module.json5配置文件包含以下标签。
 | [extensionAbilities](#extensionabilities标签) | 标识当前Module中ExtensionAbility的配置信息，标签值为数组类型，只对当前ExtensionAbility生效。 | 对象 | 该标签可缺省，缺省值为空。 |
 | [requestPermissions](#requestpermissions标签) | 标识当前应用运行时需向系统申请的权限集合。 | 对象 | 该标签可缺省，缺省值为空。 |
 | [testRunner](#testrunner标签) | 标识当前Module用于支持对测试框架的配置。 | 对象 | 该标签可缺省，缺省值为空。 |
+| [atomicService](#atomicservice标签)| 标识当前应用是原子化服务时，有关原子化服务的相关配置。| 对象 | 该标签可缺省，缺省值为空。  |
+| [dependencies](#dependencies标签)| 标识当前模块运行时依赖的共享库列表。| 对象数组 | 该标签可缺省，缺省值为空。  |
 ## deviceTypes标签
@@ -165,7 +167,7 @@ deviceTypes示例：
    "metadata": [{
      "name": "module_metadata",
      "value": "a test demo for module metadata",
-      "resource": "$profile:shortcuts_config",
+      "resource": "$profile:shortcuts_config"
    }],
    "abilities": [{
@@ -715,3 +717,80 @@ testRunner标签示例：
  }
 }
 ```
+## atomicService标签
+此标签用于支持对原子化服务的配置。此标签仅在app.json中bundleType指定为atomicService时使能。
+**表14** **atomicService标签说明**
+| 属性名称 | 含义 | 数据类型 | 是否可缺省 |
+| -------- | -------- | -------- | -------- |
+| preloads | 标识原子化服务中预加载列表 | 对象数组 | 可缺省，缺省值为空。 |
+atomicService标签示例：
+```json
+{
+  "module": {
+    "atomicService": {
+      "preloads":[
+        {
+          "moduleName":"feature"
+        }
+      ]
+    }
+  }
+}
+```
+## preloads标签
+此标签标识原子化服务中预加载列表。
+**表14** **preloads标签说明**
+| 属性名称 | 含义 | 数据类型 | 是否可缺省 |
+| -------- | -------- | -------- | -------- |
+| moduleName | 标识原子化服务中，当前模块被加载时，需预加载的模块名 | 字符串 | 不可缺省。 |
+preloads标签示例：
+```json
+{
+  "module": {
+    "atomicService": {
+      "preloads":[
+        {
+          "moduleName":"feature"
+        }
+      ]
+    }
+  }
+}
+```
+## dependencies标签
+此标签标识模块运行时依赖的共享库列表。
+**表14** **dependencies标签说明**
+| 属性名称 | 含义 | 数据类型 | 是否可缺省 |
+| -------- | -------- | -------- | -------- |
+| moduleName | 标识当前模块依赖的共享库模块名 | 字符串 | 不可缺省。 |
+dependencies标签示例：
+```json
+{
+  "module": {
+    "dependencies": [
+      {
+        "moduleName": "library"
+      }
+    ]
+  }
+}
+```
\ No newline at end of file
--- a/zh-cn/application-dev/reference/apis/js-apis-bundleManager-applicationInfo.md
+++ b/zh-cn/application-dev/reference/apis/js-apis-bundleManager-applicationInfo.md
@@ -31,3 +31,4 @@
 | appDistributionType       | string                                                       | 是   | 否   | 应用程序签名证书的分发类型，分为：app_gallery、enterprise、os_integration和crowdtesting。    |
 | appProvisionType          | string                                                       | 是   | 否   | 应用程序签名证书文件的类型，分为debug和release两种类型。           |
 | systemApp          | boolean                                                       | 是   | 否   | 标识应用是否为系统应用。           |
+| bundleType                |[BundleType](js-apis-bundleManager.md#bundletype)             | 是   | 否   | 标识包的类型，取值为APP(普通应用)或者ATOMIC_SERVICE(原子化服务)。                                |
\ No newline at end of file
--- a/zh-cn/application-dev/reference/apis/js-apis-bundleManager-hapModuleInfo.md
+++ b/zh-cn/application-dev/reference/apis/js-apis-bundleManager-hapModuleInfo.md
@@ -25,3 +25,26 @@ HAP信息，系统应用可以通过[bundleManager.getBundleInfo](js-apis-bundle
 | deviceTypes                       | Array\<string>                                               | 是   | 否   | 可以运行模块的设备类型。   |
 | installationFree                  | boolean                                                      | 是   | 否   | 模块是否支持免安装。       |
 | hashValue                         | string                                                       | 是   | 否   | 模块的Hash值。              |
+| moduleType                        | [ModuleType](js-apis-bundleManager.md#moduletype)            | 是   | 否   | 标识当前模块的类型。      |
+| preloads                          | Array\<[PreloadItem](#preloaditem)>                          | 是   | 否   | 原子化服务中模块的预加载列表。|
+| dependencies                      | Array\<[Dependency](#dependency)>                            | 是   | 否   | 模块运行依赖的动态共享库列表。  |
+## PreloadItem
+描述原子化服务中模块的预加载模块信息。
+ **系统能力:** 以下各项对应的系统能力均为SystemCapability.BundleManager.BundleFramework.Core。
+| 名称      | 类型           | 可读 | 可写 | 说明                        |
+| --------- | -------------- | ---- | ---- | --------------------------- |
+|moduleName | string         | 是   | 否   | 模块运行时，由系统自动执行预加载的模块名称。|
+## Dependency
+描述模块所依赖的动态共享库信息。
+ **系统能力:** 以下各项对应的系统能力均为SystemCapability.BundleManager.BundleFramework.Core。
+| 名称      | 类型           | 可读 | 可写 | 说明                        |
+| --------- | -------------- | ---- | ---- | --------------------------- |
+|moduleName | string         | 是   | 否   | 依赖共享库的模块名称。       |
\ No newline at end of file
--- a/zh-cn/application-dev/reference/apis/js-apis-bundleManager.md
+++ b/zh-cn/application-dev/reference/apis/js-apis-bundleManager.md
@@ -186,6 +186,39 @@ Ability组件信息标志，指示需要获取的Ability组件信息的内容。
 | AUTO_ROTATION_PORTRAIT_RESTRICTED  |11|表示受开关控制的自动竖向旋转模式。|
 | LOCKED                             |12|表示锁定模式。|
+### CompatiblePolicy
+标识共享库的版本兼容类型。
+ **系统能力:** 以下各项对应的系统能力均为SystemCapability.BundleManager.BundleFramework.Core
+| 名称                   | 值   | 说明                             |
+| ---------------------- | ---- | -------------------------------- |
+| BACKWARD_COMPATIBILITY | 1    | 该字段表明共享库是向后兼容类型。 |
+### ModuleType
+标识模块类型。
+ **系统能力:** 以下各项对应的系统能力均为SystemCapability.BundleManager.BundleFramework.Core
+| 名称    | 值   | 说明                 |
+| ------- | ---- | -------------------- |
+| ENTRY   | 1    | 应用的主模块。   |
+| FEATURE | 2    | 应用的动态特性模块。 |
+| SHARED  | 3    | 应用的动态共享库模块。  |
+### BundleType
+标识应用的类型。
+ **系统能力:** 以下各项对应的系统能力均为SystemCapability.BundleManager.BundleFramework.Core
+| 名称           | 值   | 说明            |
+| -------------- | ---- | --------------- |
+| APP            | 0    | 该Bundle是普通应用程序。    |
+| ATOMIC_SERVICE | 1    | 该Bundle是原子化服务。 |
 ## 接口
 ### bundleManager.getBundleInfoForSelf
@@ -3036,46 +3069,3 @@ try {
 }
 ```
-## CompatiblePolicy
-标识共享库的版本兼容类型。
- **系统能力:** 以下各项对应的系统能力均为SystemCapability.BundleManager.BundleFramework.Core
-| 名称                   | 值   | 说明                             |
-| ---------------------- | ---- | -------------------------------- |
-| BACKWARD_COMPATIBILITY | 1    | 该字段表明共享库是向后兼容类型。 |
-## ModuleType
-标识模块类型。
- **系统能力:** 以下各项对应的系统能力均为SystemCapability.BundleManager.BundleFramework.Core
-| 名称    | 值   | 说明                 |
-| ------- | ---- | -------------------- |
-| ENTRY   | 1    | 应用的主模块。   |
-| FEATURE | 2    | 应用的动态特性模块。 |
-| SHARED  | 3    | 应用的动态共享库模块。  |
-## BundleType
-标识应用的类型。
- **系统能力:** 以下各项对应的系统能力均为SystemCapability.BundleManager.BundleFramework.Core
-| 名称           | 值   | 说明            |
-| -------------- | ---- | --------------- |
-| APP            | 0    | 该Bundle是普通应用程序。    |
-| ATOMIC_SERVICE | 1    | 该Bundle是元服务。 |
-## AtomicServiceModuleType
-标识在元服务分包时的分包类型。
- **系统能力:** 以下各项对应的系统能力均为SystemCapability.BundleManager.BundleFramework.Core
-| 名称   | 值   | 说明                        |
-| ------ | ---- | --------------------------- |
-| NORMAL | 0    | 元服务中的页面包。     |
-| MAIN   | 1    | 元服务中的落地页包. |