diff --git a/zh-cn/application-dev/quick-start/in-app-hsp.md b/zh-cn/application-dev/quick-start/in-app-hsp.md index 1bec3260f5d5601352c0589ed2198455988ef20b..403b7ff7197c1d29369924549bd31b7a21fcd8c4 100644 --- a/zh-cn/application-dev/quick-start/in-app-hsp.md +++ b/zh-cn/application-dev/quick-start/in-app-hsp.md @@ -1,11 +1,11 @@ # 应用内HSP开发指导 -应用内`HSP`指的是专门为某一应用开发的`HSP`,只能被该应用内部其他`HAP`/`HSP`使用,用于应用内部代码、资源的共享。 -应用内`HSP`跟随其宿主应用的APP包一起发布,与宿主应用同进程,具有相同的包名和生命周期。 +应用内HSP指的是专门为某一应用开发的HSP,只能被该应用内部其他HAP/HSP使用,用于应用内部代码、资源的共享。 +应用内HSP跟随其宿主应用的APP包一起发布,与宿主应用同进程,具有相同的包名和生命周期。 ## 开发应用内HSP -通过DevEco Studio创建一个HSP模块,创建方式可[参考](https://developer.harmonyos.com/cn/docs/documentation/doc-guides-V3/hsp-0000001521396322-V3#section7717162312546),我们以创建一个名为`library`的`HSP`模块为例。基本的工程目录结构大致如下: +通过DevEco Studio创建一个HSP模块,创建方式可[参考](https://developer.harmonyos.com/cn/docs/documentation/doc-guides-V3/hsp-0000001521396322-V3#section7717162312546),我们以创建一个名为`library`的HSP模块为例。基本的工程目录结构如下: ``` library ├── src @@ -17,19 +17,6 @@ library │ └── module.json5 └── oh-package.json5 ``` -模块`module.json5`中的`"type"`标识模块类型,`HSP`的`"type"`是`"shared"`。 -```json -{ - "type": "shared" -} -``` - -`HSP`通过在入口文件中导出接口,对外提供能力。入口文件在模块`oh-package.json5`的`"main"`中配置。例如: -```json -{ - "main": "./src/main/ets/index.ets" -} -``` ### 导出ts类和方法 通过`export`导出ts类和方法,例如: @@ -80,13 +67,53 @@ export struct MyTitleBar { // 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`。 + +### 通过$r访问HSP中资源 +在组件中,经常需要使用字符串、图片等资源。HSP中的组件需要使用资源时,一般将其所用资源放在HSP包内,而非放在HSP的使用方处,以符合高内聚低耦合的原则。 + +在工程中,常通过`$r`/`$rawfile`的形式引用应用资源。可以用`$r`/`$rawfile`访问本模块`resources`目录下的资源,如访问`resources`目录下定义的图片`src/main/resources/base/media/example.png`时,可以用`$r("app.media.example")`。有关`$r`/`$rawfile`的详细使用方式,请参阅文档[资源分类与访问](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/quick-start/resource-categories-and-access.md)中“资源访问-应用资源”小节。 + +不推荐使用相对路径的方式,容易引用错误路径。例如: +当要引用上述同一图片资源时,在HSP模块中使用`Image("../../resources/base/media/example.png")`,实际上该`Image`组件访问的是HSP调用方(如`entry`)下的资源`entry/src/main/resources/base/media/example.png`。 + +```ts +// library/src/main/ets/pages/Index.ets +// 正确用例 +Image($r("app.media.example")) + .width("100%") +// 错误用例 +Image("../../resources/base/media/example.png") + .width("100%") +``` + +### 导出HSP中资源 +跨包访问HSP内资源时,推荐实现一个资源管理类,以封装对外导出的资源,通过该方式: +- HSP开发者可以控制自己需要导出的资源,不需要对外暴露的资源可以不用导出; +- 使用方无须感知HSP内部的资源名称,HSP内部的资源名称变化时也不需要使用方跟着修改。 + +其具体实现如下: + +封装对外提供资源的资源管理类: +```ts +// library/src/main/ets/ResManager.ets +export class ResManager{ + static getPic(): Resource{ + return $r("app.media.pic"); + } + static getDesc(): Resource{ + return $r("app.string.shared_desc"); + } +} +``` + +对外暴露的接口,需要在入口文件`index.ets`中声明: +```ts +// library/src/main/ets/index.ets +export { ResManager } from './ResManager' +``` ### 导出native方法 -在`HSP`中也可以包含`C++`编写的`so`。对于`so`中的`native`方法,`HSP`通过间接的方式导出,以导出`libnative.so`的乘法接口`multi`为例: +在HSP中也可以包含C++编写的`so`。对于`so`中的`native`方法,HSP通过间接的方式导出,以导出`libnative.so`的乘法接口`multi`为例: ```ts // library/src/main/ets/utils/nativeTest.ts import native from "libnative.so" @@ -110,12 +137,13 @@ export { nativeMulti } from './utils/nativeTest' // library/src/main/ets/index.ets export { Log, add, minus } from './utils/test' export { MyTitleBar } from './components/MyTitleBar' +export { ResManager } from './ResManager' export { nativeMulti } from './utils/nativeTest' ``` 在使用方的代码中,可以这样使用: ```ts // entry/src/main/ets/pages/index.ets -import { Log, add, MyTitleBar, nativeMulti } from "library" +import { Log, add, MyTitleBar, ResManager, nativeMulti } from "library" @Entry @Component @@ -133,6 +161,21 @@ struct Index { Log.info("add button click!"); this.message = "result: " + add(1, 2); }) + // ResManager返回的Resource对象,可以传给组件直接使用,也可以从中取出资源来使用 + Image(ResManager.getPic()) + .width("100%") + Button('getStringValue') + .onClick(()=> { + // 先通过当前上下文获取hsp模块的上下文,再获取hsp模块的resourceManager,然后再调用resourceManager的接口获取资源 + getContext().createModuleContext('library').resourceManager.getStringValue(ResManager.getDesc()) + .then(value => { + console.log("getStringValue is " + value); + }) + .catch(error => { + console.log("getStringValue promise error is " + error); + }); + }) + .width("50%") Button('nativeMulti(3, 4)') .onClick(()=>{ Log.info("nativeMulti button click!");