
HarmonyOS Developer DevEco Studio使用指南-开发共享包
开发HarmonyOS共享包(API 8-9)
HarmonyOS共享包又称为HAR包(HarmonyOS Ability Resources),是在传统的npm三方包的基础上,定义了HarmonyOS npm共享包特定的工程结构和配置文件,支持HarmonyOS页面组件、相关API、资源的调用。通过HarmonyOS npm共享包,您可以实现多个模块或者多个工程共享HarmonyOS组件、资源等相关代码。
HarmonyOS npm共享包的实现依赖于npm,因此您需要了解和掌握npm的基础功能和机制,可通过npm官方文档进行了解。
接下来,将简单介绍HarmonyOS npm模块的工程结构,如下图所示:
相关字段的描述如下,其余字段与Entry或Feature模块相关字段相同,可参考HarmonyOS工程介绍。
- libs:用于存放.so文件。
- src > main > cpp > types:用于存放C++ API描述文件,子目录按照so维度进行划分。
- src > main > cpp > types > liblibrary > index.d.ts:描述C++接口的方法名、入参、返回参数等信息。
- src > main > cpp > types > liblibrary > package.json:描述so三方包声明文件入口和so包名信息。
- src > main > cpp > CMakeLists.txt:CMake配置文件,提供CMake构建脚本
- src > main > cpp > npmlib.cpp:HarmonyOS npm包C++代码源文件。
- index.ets:HarmonyOS npm包导出声明的入口。
本文将介绍如何创建HarmonyOS npm模块、如何编译HarmonyOS npm共享包、如何引用HarmonyOS npm包资源,以及如何将HarmonyOS npm共享包发布到npm仓。
创建HarmonyOS npm模块
- 通过如下两种方法,在HarmonyOS工程中添加HarmonyOS npm块。
- 方法1:鼠标移到工程目录顶部,单击鼠标右键,选择New>Module。
- 方法2:在菜单栏选择File > New > Module。
- 在Choose Your Ability Template界面中,选择Ohos Library,并单击Next。
- 在Configure the New Module界面中,设置新添加的模块信息,设置完成后,单击Finish完成创建。
- Module name:新增模块的名称。
- Language:选择开发HarmonyOS npm包的语言。
- Device type:选择HarmonyOS npm包支持的设备类型。
- Enable Native:是否创建一个用于调用C++代码的HarmonyOS npm共享模块。
创建完成后,会在工程目录中生成HarmonyOS npm共享模块及相关文件。
在开发HarmonyOS npm模块时,请注意以下事项:
- HarmonyOS npm模块的package.json中,必须包含ohos闭包。
- HarmonyOS npm模块暂不支持配置Ability。
编译HarmonyOS npm模块
开发完HarmonyOS npm模块后,选中模块名,然后通过DevEco Studio菜单栏的Build > Make Module ${libraryName}进行编译构建,生成HarmonyOS npm包。HarmonyOS npm包可用于工程其它模块的引用,或将HarmonyOS npm包上传至npm仓库,供其他开发者下载使用。
编译构建的HarmonyOS npm包可在模块下的build目录下获取,包格式为*.tgz。
在编译构建HarmonyOS npm模块时,请注意以下事项:
- 在编译构建HarmonyOS npm包的过程中,DevEco Studio不会将模块中的C++代码打包进.tgz文件中,而是将C++代码编译成动态依赖库.so文件,并放置在libs目录下。原因是C++的编译构建任务只会在工程的模块下被执行。
- 在编译构建HarmonyOS npm包的过程中,会生成资源文件ResourceTable.txt,以便编辑器可以对HarmonyOS npm包中的资源文件进行联想。因此,如果不使用DevEco Studio对HarmonyOS npm进行构建,则DevEco Studio的编辑器会无法联想HarmonyOS npm包中的资源。
发布HarmonyOS npm包
将打包的HarmonyOS npm包发布至npm仓,可供其他开发者安装和引用。npm包的发布,既可以发布到npm官方中心仓,也可以将其发布到DevEco Marketplace提供的HarmonyOS npm专用仓,接下来将重点介绍如何发布到HarmonyOS npm专用仓。关于发布到npm官方中心仓请参考npm官方文档。
- 在HarmonyOS npm模块中(与src文件夹同一级目录下),添加如下文件:
- 新建README.md文件:在README.md文件中必须包含包的介绍和引用方式,还可以根据包的内容添加更详细介绍。
- 新建CHANGELOG.md文件:填写HarmonyOS npm包的版本更新记录。
- 添加LICENSE文件:LICENSE许可文件。
- 重新编译HarmonyOS npm模块,生成*.tgz文件。
- 登录DevEco Marketplace,单击主页右上角的个人中心 > 安全 > AccessToken,在AccessToken页签下,单击“生成新令牌”。
说明
发布HarmonyOS npm包需注册华为开发者帐号,并完成实名认证,具体请参考帐号注册和实名认证。
生成的令牌将会在发布HarmonyOS npm包时使用,请单击令牌末尾的复制按钮复制并保存令牌信息。
- 打开命令行工具执行如下命令设置新的scope:ohos。
- 执行如下命令,设置令牌信息,<authToken>请修改为步骤3中获取的Access Token。
- 执行如下命令发布HarmonyOS npm包,<HarmonyOS npm包名称>请根据实际进行修改。
引用HarmonyOS npm包文件和资源
配置HarmonyOS npm包依赖
引用HarmonyOS npm三方包,包括从HarmonyOS npm仓库进行安装和从本地HarmonyOS npm模块中进行安装两种方式。
- 引用npm仓中的HarmonyOS npm包,首先需要设置HarmonyOS npm三方包的仓库信息,请在DevEco Studio的Terminal窗口执行如下命令进行设置:
然后通过如下两种方式设置HarmonyOS npm三方包依赖信息:
○ 方式一:在Terminal窗口中,执行如下命令安装HarmonyOS npm三方包,DevEco Studio会自动在工程的package.json中自动添加三方包依赖。
○ 方式二:在工程的package.json中设置HarmonyOS npm三方包依赖,配置示例如下:
依赖设置完成后,需要执行npm install命令安装依赖包,依赖包会存储在工程的node_modules目录下。
- 引用本地HarmonyOS npm模块的文件和资源,有如下两种方式:
○ 方式一:在Terminal窗口中,执行如下命令进行安装,并会在package.json中自动添加依赖。
○ 方式二:在工程的package.json中设置HarmonyOS npm三方包依赖,配置示例如下:
- 依赖设置完成后,需要执行npm install命令安装依赖包,依赖包会存储在工程的node_modules目录下。
在引用HarmonyOS npm包时,请注意以下事项:
- 当前只支持在模块和工程下的package.json文件中声明dependencies依赖,才会被当做HarmonyOS依赖使用,并在编译构建过程中进行相应的处理。
- 引用的模块的compileSdkVersion不能低于其依赖的HarmonyOS npm三方包(可在node_modules目录下,找到引用的npm包的src > main > module.json5 中查看)。
引用HarmonyOS npm包hml页面
在JS工程范式中,组件功能由hml承载,开发者可以在JS工程的hml页面通过<element>标签来引入HarmonyOS npm包中的共享hml页面,示例如下:
其中,@ohos/library为HarmonyOS npm包的包名,hml页面的路径为HarmonyOS npm包中的相对路径。
随后便可以通过设置的name来使用该element元素,以引用HarmonyOS npm包中的hml页面,示例如下:
引用HarmonyOS npm包ArkTS页面
ArkTS是TypeScript的扩展,因此导出和引入的语法与TypeScript一致。在HarmonyOS npm模块中,可以通过export导出ArkTS页面,示例如下:
然后在其它模块中通过import引入导出的ArkTS页面,示例如下所示:
引用HarmonyOS npm包内ts/js方法
ts/js方法的导出和引用,与ArkTS页面的引用相同,即在HarmonyOS npm模块中,可以通过export导出ts/js方法,示例如下所示:
然后在其它的ts/js页面中,通过import引入导出的ts/js方法,示例如下所示:
引用HarmonyOS npm包内资源
支持在HarmonyOS npm模块和依赖HarmonyOS npm的模块中引用HarmonyOS npm模块内的资源。例如在HarmonyOS npm模块的scr/main/resources里添加字符串资源(在string.json中定义,name:hello_npm)和图片资源(icon_npm.png)。然后在Entry模块中引用该字符串资源和图片资源的示例如下:
说明
当前暂不支持类Web范式引用i18n文件中的国际化资源。
在编译构建HAP中,DevEco Studio会从HAP模块及依赖的模块中收集资源文件,如果不同模块的相同限定词目录下的资源文件出现重名冲突时,DevEco Studio会按照以下优先级进行覆盖(优先级由高到低):
- AppScope(仅API9的Stage模型支持)
- HAP自身模块
- 依赖的HarmonyOS npm模块
开发HarmonyOS共享包(API 4-7)
HarmonyOS共享包又称为HAR包(HarmonyOS Ability Resources),可以提供应用/服务构建所需的一切内容,包括源代码、资源文件、HarmonyOS配置文件以及第三方库。HAR不同于HAP,HAR不能独立安装运行在设备上,只能作为应用/服务模块的依赖项被引用。
HAR包只能被Phone、Tablet、Car、TV和Wearable工程所引用。
说明
不支持跨语言的HAR包依赖,例如不支持在JS工程中依赖Java开发的HAR包。
创建库模块
在DevEco Studio中,可以通过如下方式创建新的库模块。
- 通过如下两种方法,在工程中添加新的HarmonyOS Library模块。
- 方法1:鼠标移到工程目录顶部,单击鼠标右键,选择New>Module。
- 方法2:在菜单栏选择File > New > Module。
- 在New Module界面中,选择HarmonyOS Library,并单击Next。
- 在Configure the New Module界面中,设置新添加的模块信息,设置完成后,单击Finish完成创建。
- Library name:新增Module所属的类名称。
- Package name:软件包名称。
- Compatible SDK:兼容的SDK版本。
- Device type:选择设备类型。
- 等待工程自动同步完成后,会在工程目录中生成对应的库模块。
将库模块编译为HAR
利用Gradle可以将HarmonyOS Library库模块构建为HAR包,以便在工程中引用HAR或者将HAR包提供给其它开发者进行调用。构建HAR包的方法如下:
在Gradle构建任务中,双击PackageDebugHar或PackageReleaseHar任务,构建Debug类型或Release类型的HAR。
图1 编译debug类型HAR包
图2 编译Release类型HAR包
待构建任务完成后,可以在工程目录中的moduleName > build > outputs > har目录中,获取生成的HAR包。
发布Har包到Maven仓
借助Gradle提供的Maven-publish插件,可以将Har包发布到本地或远程Maven仓。
- 在工程根目录下,单击鼠标右键New > File,创建一个后缀为“.gradle”的文件,如upload.gradle。
- 在创建的upload.gradle文件中,添加如下示例代码。如下示例代码为发布HAR包到Maven仓的最小集,请根据实际发布信息进行修改。
- 在Har模块的build.gradle中,添加HAR发布脚本。添加完成后,单击Sync Now进行同步。
- 同步完成后,会在Gradle任务中增加publishing的任务列表。
- 双击执行publishMavenPublicationToMavenRepository任务,将HAR包发布到指定的Maven地址。
- 本示例是以发布到本地Maven地址为例,发布结果如下图所示:
为应用/服务模块添加依赖
在应用/服务模块(entry或feature模块)中调用HAR,常用的添加依赖的方式包括如下三种。
- 调用同一个工程中的HAR:HAR包和应用/服务模块在同一个工程,打开应用/服务模块的build.gradle文件,在dependencies闭包中,添加如下代码。添加完成后,请单击Sync Now同步工程。
- 调用Maven仓中的HAR:无论Har包是本地Maven仓还是远程Maven仓,均可以采用如下方式添加依赖。
a. 在工程的build.gradle的allprojects闭包中,添加HAR所在的Maven仓地址。
b. 在应用/服务模块的build.gradle的dependencies闭包中,添加如下代码。
c. 添加完成后,单击Sync Now同步工程。
- 调用本地HAR:将Har包放到模块下的libs目录,然后检查build.gradle中是否添加了*.har的依赖。
