diff --git a/zh-cn/application-dev/quick-start/Readme-CN.md b/zh-cn/application-dev/quick-start/Readme-CN.md index 34d3bb66aa5367e975ea54ff28d803b54953f79e..ef1c7b868f3a4be8ee86d36c2c3109f0011a314b 100755 --- a/zh-cn/application-dev/quick-start/Readme-CN.md +++ b/zh-cn/application-dev/quick-start/Readme-CN.md @@ -4,7 +4,7 @@ - [开发准备](start-overview.md) - [使用ArkTS语言开发（Stage模型）](start-with-ets-stage.md) - [使用ArkTS语言开发（FA模型）](start-with-ets-fa.md) - - [使用JS语言开发（FA模型）](start-with-js-fa.md) + - [使用JS语言开发（FA模型）](start-with-js-fa.md) - 开发基础知识 - 应用程序包基础知识 - [应用程序包概述](application-package-overview.md) @@ -25,6 +25,8 @@ - HSP - [应用内HSP开发指导](in-app-hsp.md) - [应用间HSP开发指导（仅对系统应用开放）](cross-app-hsp.md) + - 原子化服务 + - [原子化服务开发指导](atomicService.md) - 应用程序包快速修复 - [快速修复概述](quickfix-principles.md) - [快速修复调试指导](quickfix-debug.md) diff --git a/zh-cn/application-dev/quick-start/app-configuration-file.md b/zh-cn/application-dev/quick-start/app-configuration-file.md index a890fd96269336f5bd3e8b52fa3c1f2e9640bf14..12c2d3e8888a81c4b0096cdcb30c25a770449f67 100644 --- 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名称，用于标识应用的唯一性。该标签不可缺省。标签的值命名规则 ：
- 字符串以字母、数字、下划线和符号“.”组成。
- 以字母开头。
- 最小长度7个字节，最大长度127个字节。
推荐采用反域名形式命名（如com.example.demo，建议第一级为域名后缀com，第二级为厂商/个人名，第三级为应用名，也可以多级）。
其中，随系统源码编译的应用建议命名为“com.ohos.demo”形式， ohos标识OpenHarmony系统应用。 | 字符串 | 该标签不可缺省。 | +| bundleType| 标识应用的Bundle类型，用于区分应用或者原子化服务。该标签可选值为app和atomicService ：
- app：当前Bundle为普通应用。
- atomicService：当前Bundle为原子化服务。| 字符串| 该标签可以缺省，缺省为app。 | | debug | 标识应用是否可调试，该标签由IDE编译构建时生成。
- true：可调试。
- false：不可调式。 | 布尔值 | 该标签可以缺省，缺省为false。 | | icon | 标识[应用的图标](../application-models/application-component-configuration-stage.md)，标签值为图标资源文件的索引。 | 字符串 | 该标签不可缺省。 | | label | 标识[应用的名称](../application-models/application-component-configuration-stage.md)，标签值为字符串资源的索引。 | 字符串 | 该标签不可缺省。 | diff --git a/zh-cn/application-dev/quick-start/atomicService.md b/zh-cn/application-dev/quick-start/atomicService.md new file mode 100644 index 0000000000000000000000000000000000000000..d99306b2a37028f0c1e3c27269f17c614cd3df36 --- /dev/null +++ b/zh-cn/application-dev/quick-start/atomicService.md @@ -0,0 +1,218 @@ +# 原子化服务 + +## 原子化服务分包预加载 + +### 使用分包 + +为了加快首次启动原子化服务时的速度，可以采用分包策略，原子化服务的代码包可以被划分为几个：一个是类型为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 diff --git a/zh-cn/application-dev/quick-start/module-configuration-file.md b/zh-cn/application-dev/quick-start/module-configuration-file.md index d1524a70ba9a993d1cc5e8c83a2f347c4106e656..3fe3c55f39d090ab0ea9acda31bddf31bd134eed 100644 --- 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": [{ @@ -226,7 +228,7 @@ OpenHarmony系统对无图标应用严格管控。如果HAP中没有配置启动 }] }], ... - + } } ``` @@ -457,7 +459,7 @@ extensionAbilities示例： "icon": "$media:icon", "label" : "$string:extension_name", "description": "$string:form_description", - "type": "form", + "type": "form", "permissions": ["ohos.abilitydemo.permission.PROVIDER"], "readPermission": "", "writePermission": "", @@ -471,7 +473,7 @@ extensionAbilities示例： "metadata": [ { "name": "ohos.extension.form", - "resource": "$profile:form_config", + "resource": "$profile:form_config", } ] } @@ -529,7 +531,7 @@ metadata中指定shortcut信息，其中： - name：指定shortcuts的名称。使用ohos.ability.shortcuts作为shortcuts信息的标识。 - resource：指定shortcuts信息的资源位置。 - + | 属性 | 含义 | 类型 | 默认值 | | -------- | -------- | -------- | -------- | | shortcutId | 标识快捷方式的ID。字符串的最大长度为63字节。 | 字符串 | 该标签不可缺省。 | @@ -539,7 +541,7 @@ metadata中指定shortcut信息，其中： 1. 在/resource/base/profile/目录下配置shortcuts_config.json配置文件。 - + ```json { "shortcuts": [ @@ -559,7 +561,7 @@ metadata中指定shortcut信息，其中： ``` 2. 在module.json5配置文件的abilities标签中，针对需要添加快捷方式的UIAbility进行配置metadata标签，使shortcut配置文件对该UIAbility生效。 - + ```json { "module": { @@ -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 diff --git a/zh-cn/application-dev/reference/apis/js-apis-bundleManager-applicationInfo.md b/zh-cn/application-dev/reference/apis/js-apis-bundleManager-applicationInfo.md index 9ac0871230226db8437ef0c34a495b1d0cac96a2..13b7c2e15489346fc2b37edbde593dce3260d6e5 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-bundleManager-applicationInfo.md +++ b/zh-cn/application-dev/reference/apis/js-apis-bundleManager-applicationInfo.md @@ -30,4 +30,5 @@ | descriptionResource | [Resource](js-apis-resource-manager.md#resource9) | 是 | 否 | 应用程序的描述资源信息，通过ApplicationInfo 获取的resource 包含了该资源的信息的bundleName、moduleName 和 id，可以调用全球化的接口[@ohos.resourceManager.d.ts](https://gitee.com/openharmony/interface_sdk-js/blob/master/api/@ohos.resourceManager.d.ts)中的getMediaContent来获取详细的资源数据信息。| | appDistributionType | string | 是 | 否 | 应用程序签名证书的分发类型，分为：app_gallery、enterprise、os_integration和crowdtesting。 | | appProvisionType | string | 是 | 否 | 应用程序签名证书文件的类型，分为debug和release两种类型。 | -| systemApp | boolean | 是 | 否 | 标识应用是否为系统应用。 | \ No newline at end of file +| systemApp | boolean | 是 | 否 | 标识应用是否为系统应用。 | +| bundleType |[BundleType](js-apis-bundleManager.md#bundletype) | 是 | 否 | 标识包的类型，取值为APP(普通应用)或者ATOMIC_SERVICE(原子化服务)。 | \ No newline at end of file diff --git a/zh-cn/application-dev/reference/apis/js-apis-bundleManager-hapModuleInfo.md b/zh-cn/application-dev/reference/apis/js-apis-bundleManager-hapModuleInfo.md index 3496e020162075029fec44755921de0c08229412..a875c3f90429166aa42f9c4f4d3b4e86d22e2164 100644 --- 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\ | 是 | 否 | 可以运行模块的设备类型。 | | 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 diff --git a/zh-cn/application-dev/reference/apis/js-apis-bundleManager.md b/zh-cn/application-dev/reference/apis/js-apis-bundleManager.md index 3380547721122aadf017c595c8cf25d052d15af9..4baddf1ecd63eb6787d97495e26be7d4daf715f3 100644 --- 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 @@ -501,7 +534,7 @@ getApplicationInfo(bundleName: string, appFlags: [number](#applicationflag), use | 17700004 | The specified user ID is not found. | | 17700026 | The specified bundle is disabled. | -**示例：** +**示例：** ```ts import bundleManager from '@ohos.bundle.bundleManager'; @@ -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 | 元服务中的落地页包. |