HarmonyOS 鸿蒙开发DevEco Studio OpenHarmony:开发OpenHarmony npm包

目录

创建OpenHarmony npm模块

编译OpenHarmony npm模块

发布OpenHarmony npm包

引用OpenHarmony npm包文件和资源

配置OpenHarmony npm包依赖

引用OpenHarmony npm包JS组件

引用OpenHarmony npm包eTS组件

引用OpenHarmony npm包内ts/js方法

引用OpenHarmony npm包内资源

OpenHarmony npm包是在传统的npm三方包的基础上，定义了OpenHarmony npm共享包特定的工程结构和配置文件，支持OpenHarmony页面组件、相关API、资源的调用。通过OpenHarmony npm包，您可以实现多个模块或者多个工程共享OpenHarmony页面、资源等相关代码。

OpenHarmony npm共享包的实现依赖于npm，因此您需要了解和掌握npm的基础功能和机制，可通过npm官方文档
进行了解。

接下来，将简单为大家介绍OpenHarmony npm模块的工程结构，如下图所示：

相关字段的描述如下，其余字段与Entry或Feature模块相关字段相同，可参考OpenHarmony工程介绍
。

  • libs：用于存放.so文件。
  • src > main > cpp > types：用于存放C++ API描述文件，子目录按照so维度进行划分。
  • src > main > cpp > types > libhello > index.d.ts：描述C++接口的方法名、入参、返回参数等信息。
  • src > main > cpp > types > libhello > package.json：描述so三方包声明文件入口和so包名信息。
  • src > main > cpp > CMakeLists.txt：CMake配置文件，提供CMake构建脚本
  • src > main > cpp > npmlib.cpp：OpenHarmony npm包C++代码源文件。
  • index.ets：OpenHarmony npm包导出声明的入口。

本文将介绍如何创建OpenHarmony npm模块、如何编译OpenHarmony npm共享包、如何引用HarmonyOS npm包资源，以及如何将OpenHarmony npm共享包发布到npm仓。

创建OpenHarmony npm模块

  1. 通过如下两种方法，在OpenHarmony工程中添加OpenHarmony npm包模块。
    • 方法1：鼠标移到工程目录顶部，单击鼠标右键，选择New>Module。
    • 方法2：在菜单栏选择File > New > Module。
  2. 在Choose Your Ability Template界面中，选择Ohos Library，并单击Next。

  3. 在Configure the New Module界面中，设置新添加的模块信息，设置完成后，单击Finish完成创建。
    • Module name：新增模块的名称。
    • Language：选择开发OpenHarmony npm包的语言。
    • Device type：选择OpenHarmony npm包支持的设备类型。
    • Enable Native：是否创建一个用于调用C++代码的OpenHarmony npm共享模块。

    创建完成后，会在工程目录中生成OpenHarmony npm共享模块及相关文件。

在开发OpenHarmony npm模块时，请注意以下事项：

  • OpenHarmony npm模块的package.json中，必须包含ohos闭包。
  • OpenHarmony npm模块暂不支持配置Ability。
  • FA模型与Stage模型的OpenHarmony npm模块暂不支持互相引用。
  • 在Stage模型中开发OpenHarmony npm共享包时，不推荐引用AppScope内的内容。原因是在编译构建时不会将AppScope中的内容打包到OpenHarmony npm共享包中，将导致资源引用失败。

编译OpenHarmony npm模块

开发完OpenHarmony npm模块后，选中模块名，然后通过DevEco Studio菜单栏的Build > Make Module ${libraryName}进行编译构建，生成OpenHarmony npm包。OpenHarmony npm包可用于工程其它模块的引用，或将OpenHarmony npm包上传至npm仓库，供其他开发者下载使用。

编译构建的OpenHarmony npm包可在模块下的build目录下获取，包格式为*.tgz。

在编译构建OpenHarmony npm包时，请注意以下事项：

  • 在编译构建OpenHarmony npm包的过程中，DevEco Studio不会将模块中的C++代码打包进.tgz文件中，而是将C++代码编译成动态依赖库.so文件，并放置在libs目录下。原因是C++的编译构建任务只会在工程的模块下被执行。
  • 在编译构建OpenHarmony npm包的过程中，会生成资源文件ResourceTable.txt，以便编辑器可以对OpenHarmony npm包中的资源文件进行联想。因此，如果不使用DevEco Studio对OpenHarmony npm进行构建，则DevEco Studio的编辑器会无法联想OpenHarmony npm包中的资源。

发布OpenHarmony npm包

将打包的OpenHarmony npm包发布至npm仓，可供其他开发者安装和引用。npm包的发布，既可以发布到npm官方中心仓，也可以将其发布到DevEco Marketplace提供的OpenHarmony npm专用仓，接下来将重点介绍如何发布到OpenHarmony npm专用仓。关于发布到npm官方中心仓请参考npm官方文档
。

  1. 在OpenHarmony npm模块中（与src文件夹同一级目录下），添加如下文件：
    • 新建README.md文件：在README.md文件中必须包含包的介绍和引用方式，还可以根据包的内容添加更详细介绍。
    • 新建CHANGELOG.md文件：填写OpenHarmony npm包的版本更新记录。
    • 添加LICENSE文件：LICENSE许可文件。
  2. 重新编译OpenHarmony npm模块
    ，生成*.tgz文件。
  3. 登录DevEco Marketplace
    ，单击主页右上角的个人中心 > 安全 > AccessToken，在AccessToken页签下，单击“生成新令牌”。

    说明

    发布OpenHarmony npm包需注册华为开发者帐号，并完成实名认证，具体请参考帐号注册和实名认证
    。

    生成的令牌将会在发布OpenHarmony npm包时使用，请单击令牌末尾的复制按钮复制并保存令牌信息。

  4. 打开命令行工具执行如下命令设置新的scope：ohos。 
    

      

    1. npm config set @ohos:registry=https://repo.harmonyos.com/npm/
      2. 

    

    5. 

  5. 执行如下命令，设置令牌信息，<authToken>请修改为步骤3中获取的Access Token。

    

      

    1. npm config set //repo.harmonyos.com/npm/:_authToken <authToken>
      2. 

    

    6. 

  6. 执行如下命令发布OpenHarmony npm包，<OpenHarmony npm包名称>请根据实际进行修改。

    

      

    1. npm publish <OpenHarmony npm包名称>
      2. 

    

    7. 



引用OpenHarmony npm包文件和资源


配置OpenHarmony npm包依赖


引用OpenHarmony npm三方包，包括从OpenHarmony npm仓库进行安装和从本地OpenHarmony npm模块中进行安装两种方式。


    

  • 引用npm仓中的OpenHarmony npm包，首先需要设置OpenHarmony npm三方包的仓库信息，请在DevEco Studio的Terminal窗口执行如下命令进行设置：

    

      

    1. npm config set @ohos:registry=https://repo.harmonyos.com/npm/
      2. 

    

     然后通过如下两种方式设置OpenHarmony npm三方包依赖信息： 
    

      

    • 方式一：在Terminal窗口中，执行如下命令安装OpenHarmony npm三方包，DevEco Studio会自动在工程的package.json中自动添加三方包依赖。

      

        

      1. npm install @ohos/vcard --save
        2. 

      

      • 

    • 方式二：在工程的package.json中设置OpenHarmony npm三方包依赖，配置示例如下：

      

        

      1. "dependencies": {
        2. 

      2. "@ohos/vcard": "^2.1.0"
        3. 

      3. }
        4. 

      

      依赖设置完成后，需要执行npm install命令安装依赖包，依赖包会存储在工程的node_modules目录下。
      

      

        

      1. npm install
        2. 

      

      • 

    

    • 

  • 引用本地OpenHarmony npm模块的文件和资源，有如下两种方式：

      

    • 方式一：在Terminal窗口中，执行如下命令进行安装，并会在package.json中自动添加依赖。

      

        

      1. npm install ../library --save
        2. 

      

      • 

    • 方式二：在工程的package.json中设置OpenHarmony npm三方包依赖，配置示例如下：

      

        

      1. "dependencies": {
        2. 

      2. "@ohos/library": "file:../library"
        3. 

      3. }
        4. 

      

      依赖设置完成后，需要执行npm install命令安装依赖包，依赖包会存储在工程的node_modules目录下。
      

      

        

      1. npm install
        2. 

      

      • 

    

    • 



在引用OpenHarmony npm包时，请注意以下事项：


    

  • 当前只支持在模块和工程下的package.json文件中声明dependencies依赖，才会被当做OpenHarmony依赖使用，并在编译构建过程中进行相应的处理。
    • 

  • 引用的模块的compileSdkVersion不能低于其依赖的OpenHarmony npm三方包（可在node_modules目录下，找到引用的npm包的src > main > module.json中查看）。
    • 



引用OpenHarmony npm包JS组件


在JS工程范式中，组件功能由hml承载，开发者可以在JS工程的hml页面通过<element>标签来引入OpenHarmony npm包中的共享JS组件，示例如下：




    

  1. <element name="comp" src="@ohos/library/src/main/js/components/index/index.hml"></element>
    2. 



其中，@ohos/library为OpenHarmony npm包的包名，hml页面的路径为OpenHarmony npm包中的相对路径。


随后便可以通过设置的name来使用该element元素，以引用OpenHarmony npm包中的JS组件，示例如下：




    

  1. <element name="comp" src="@ohos/library/src/main/js/components/index/index.hml"></element>
    2. 

  2. 

  3. <div class="container">
    4. 

  4. <comp></comp>
    5. 

  5. <text class="title">
    6. 

  6. {{ $t('strings.hello') }} {{ title }}
    7. 

  7. </text>
    8. 

  8. </div>
    9. 



引用OpenHarmony npm包eTS组件


eTS是TypeScript的扩展，因此导出和引入的语法与TypeScript一致。在OpenHarmony npm模块中，可以通过export导出eTS组件，示例如下：




    

  1. // library/src/main/ets/components/MainPage/MainPage.ets
    2. 

  2. @Entry
    3. 

  3. @Component
    4. 

  4. export struct MainPage {
    5. 

  5. @State message: string = 'Hello World'
    6. 

  6. build() {
    7. 

  7. Row() {
    8. 

  8. Column() {
    9. 

  9. Text(this.message)
    10. 

  10. .fontSize(50)
    11. 

  11. .fontWeight(FontWeight.Bold)
    12. 

  12. }
    13. 

  13. .width('100%')
    14. 

  14. }
    15. 

  15. .height('100%')
    16. 

  16. }
    17. 

  17. }
    18. 



然后在其它模块中通过import引入导出的eTS组件，示例如下所示：




    

  1. // entry/MainAbility/pages/index.ets
    2. 

  2. 

  3. import { MainPage } from "@ohos/library"
    4. 

  4. @Entry
    5. 

  5. @Component
    6. 

  6. struct Index {
    7. 

  7. @State message: string = 'Hello World'
    8. 

  8. 

  9. build() {
    10. 

  10. Column() {
    11. 

  11. MainPage()
    12. 

  12. Row() {
    13. 

  13. Text(this.message)
    14. 

  14. .fontSize(50)
    15. 

  15. .fontWeight(FontWeight.Bold)
    16. 

  16. }
    17. 

  17. .width('100%')
    18. 

  18. }
    19. 

  19. .height('10%')
    20. 

  20. }
    21. 

  21. }
    22. 



引用OpenHarmony npm包内ts/js方法


ts/js方法的导出和引用，与eTS页面的引用相同，即在OpenHarmony npm模块中，可以通过export导出ts/js方法，示例如下所示：




    

  1. // library/index.js
    2. 

  2. export function func() {
    3. 

  3. return "[npm] func1";
    4. 

  4. }
    5. 



然后在其它的ts/js页面中，通过import引入导出的ts/js方法，示例如下所示：




    

  1. // entry/src/main/js/MainAbility/pages/index/index.js
    2. 

  2. import {func} from "@ohos/library"
    3. 

  3. export default {
    4. 

  4. data: {
    5. 

  5. title: ""
    6. 

  6. },
    7. 

  7. onInit() {
    8. 

  8. this.title = func();
    9. 

  9. }
    10. 

  10. }
    11. 



引用OpenHarmony npm包内资源


支持在OpenHarmony npm模块和依赖OpenHarmony npm的模块中引用OpenHarmony npm模块内的资源。例如在OpenHarmony npm模块的scr/main/resources里添加字符串资源（在string.json中定义，name：hello_npm）和图片资源（icon_npm.png），然后在Entry模块中引用该字符串资源和图片资源的示例如下：




    

  1. // entry/src/main/ets/MainAbility/pages/index.ets
    2. 

  2. @Entry
    3. 

  3. @Component
    4. 

  4. struct Index {
    5. 

  5. @State message: string = 'Hello World'
    6. 

  6. build() {
    7. 

  7. Column() {
    8. 

  8. Row() {
    9. 

  9. Text($r("app.string.hello_npm")) // 字符串资源
    10. 

  10. .fontSize(40)
    11. 

  11. .fontWeight(FontWeight.Bold)
    12. 

  12. }
    13. 

  13. .width('50%')
    14. 

  14. Image($r("app.media.icon_npm")) // 图片资源
    15. 

  15. }
    16. 

  16. .height('100%')
    17. 

  17. }
    18. 

  18. }
    19. 



在编译构建HAP中，DevEco Studio会从HAP模块及依赖的模块中收集资源文件，如果不同模块下的资源文件出现重名冲突时，DevEco Studio会按照以下优先级进行覆盖（优先级由高到低）：


    

  • AppScope（仅API9的Stage模型支持）
    • 

  • HAP包自身模块
    • 

  • 依赖的OpenHarmony npm模块
    •