diff --git a/zh-cn/application-dev/quick-start/Readme-CN.md b/zh-cn/application-dev/quick-start/Readme-CN.md old mode 100755 new mode 100644 index 7a14810f21ec94b0986c5c62ca0bcb5a91593dde..c2245971dbd1985daa84174228a1c741e8ced161 --- a/zh-cn/application-dev/quick-start/Readme-CN.md +++ b/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) diff --git a/zh-cn/application-dev/quick-start/application-package-structure-stage.md b/zh-cn/application-dev/quick-start/application-package-structure-stage.md index 25eb4e2e3d0f21c5f9e4c71b8b378656dd24423b..0b0fffc66f1b913dc38f0a338dd3be0862ab0684 100644 --- a/zh-cn/application-dev/quick-start/application-package-structure-stage.md +++ b/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组件关系示意图 diff --git a/zh-cn/application-dev/quick-start/figures/in-app-hsp-har.png b/zh-cn/application-dev/quick-start/figures/in-app-hsp-har.png new file mode 100644 index 0000000000000000000000000000000000000000..3cce70ac75424dabe0af4436f46319f943c9cade Binary files /dev/null and b/zh-cn/application-dev/quick-start/figures/in-app-hsp-har.png differ diff --git a/zh-cn/application-dev/quick-start/har-package.md b/zh-cn/application-dev/quick-start/har-package.md new file mode 100644 index 0000000000000000000000000000000000000000..88e4c47a32bf2d7fe0162c177ae638ef12ee053a --- /dev/null +++ b/zh-cn/application-dev/quick-start/har-package.md @@ -0,0 +1,169 @@ +# 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%') + } +} +``` diff --git a/zh-cn/application-dev/quick-start/har-structure.md b/zh-cn/application-dev/quick-start/har-structure.md deleted file mode 100644 index 6bd6ad0d4ff3c2c0e9efa60955d19d36d3dd8c2f..0000000000000000000000000000000000000000 --- a/zh-cn/application-dev/quick-start/har-structure.md +++ /dev/null @@ -1,10 +0,0 @@ -# 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模型)等。 diff --git a/zh-cn/application-dev/quick-start/in-app-hsp.md b/zh-cn/application-dev/quick-start/in-app-hsp.md new file mode 100644 index 0000000000000000000000000000000000000000..177700e909363128a4df4da45de0e1d7c56f36f8 --- /dev/null +++ b/zh-cn/application-dev/quick-start/in-app-hsp.md @@ -0,0 +1,153 @@ +# 应用内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 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 a7b664dc4149d0b5db4f41f9db298477a7a25951..c4292680d282936b2ae57267705f45395d6ca1b9 100644 --- a/zh-cn/application-dev/quick-start/module-configuration-file.md +++ b/zh-cn/application-dev/quick-start/module-configuration-file.md @@ -72,7 +72,7 @@ module.json5配置文件包含以下标签。 | 属性名称 | 含义 | 数据类型 | 是否可缺省 | | -------- | -------- | -------- | -------- | | name | 标识当前Module的名称,标签值采用字符串表示(最大长度31个字节),该名称在整个应用要唯一,不支持中文。 | 字符串 | 该标签不可缺省。 | -| type | 标识当前Module的类型。类型有两种,分别:
- entry:应用的主模块。
- feature:应用的动态特性模块。 | 字符串 | 该标签不可缺省。 | +| type | 标识当前Module的类型。类型有4种,分别:
- entry:应用的主模块。
- feature:应用的动态特性模块。
- har:静态共享包模块。
- shared:动态共享包模块。 | 字符串 | 该标签不可缺省。 | | srcEntry | 标识当前Module所对应的代码路径,标签值为字符串(最长为127字节)。 | 字符串 | 该标签可缺省,缺省值为空。 | | description | 标识当前Module的描述信息,标签值是字符串类型(最长255字节)或对描述内容的字符串资源索引。 | 字符串 | 该标签可缺省,缺省值为空。 | | process | 标识当前Module的进程名,标签值为字符串类型(最长为31个字节)。如果在HAP标签下配置了process,该应用的所有UIAbility、DataShareExtensionAbility、ServiceExtensionAbility都运行在该进程中。
**说明:**
- 仅支持系统应用配置,三方应用配置不生效。 | 字符串 | 可缺省,缺省为app.json5文件下app标签下的bundleName。 | diff --git a/zh-cn/application-dev/quick-start/shared-guide.md b/zh-cn/application-dev/quick-start/shared-guide.md new file mode 100644 index 0000000000000000000000000000000000000000..d4de6b7cd2fc4a0414d0dbbcc9307c0212d90809 --- /dev/null +++ b/zh-cn/application-dev/quick-start/shared-guide.md @@ -0,0 +1,19 @@ +# 共享包概述 + +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 diff --git a/zh-cn/application-dev/reference/errorcodes/errorcode-bundle.md b/zh-cn/application-dev/reference/errorcodes/errorcode-bundle.md index 6582878d486508c65b0b6bb726188becc4112219..55d6631c1782f3b42b4b017905c861717d2ad697 100644 --- a/zh-cn/application-dev/reference/errorcodes/errorcode-bundle.md +++ b/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. **处理步骤**
确认新安装的应用版本号是否不低于已安装的同应用版本号。 +## 17700018 安装失败,依赖的模块不存在 + +**错误信息**
+Failed to install because the dependent module does not exist. + +**错误描述**
+安装hap或者hsp时,依赖的模块不存在。 + +**可能原因**
+依赖的模块没有安装。 + +**处理步骤**
+先安装依赖的模块。 + ## 17700020 预置应用无法卸载 **错误信息**