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模块

1. 通过如下两种方法，在HarmonyOS工程中添加HarmonyOS 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：选择开发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官方文档​​。

1. 在HarmonyOS npm模块中（与src文件夹同一级目录下），添加如下文件：

• 新建README.md文件：在README.md文件中必须包含包的介绍和引用方式，还可以根据包的内容添加更详细介绍。
• 新建CHANGELOG.md文件：填写HarmonyOS npm包的版本更新记录。
• 添加LICENSE文件：LICENSE许可文件。

2. 重新​​编译HarmonyOS npm模块​​，生成*.tgz文件。
3. 登录​​DevEco Marketplace​​，单击主页右上角的个人中心 > 安全 > AccessToken，在AccessToken页签下，单击“生成新令牌”。

说明

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

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

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

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

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

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

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

npm publish <HarmonyOS npm包名称>

引用HarmonyOS npm包文件和资源

配置HarmonyOS npm包依赖

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

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

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

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

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

npm install @ohos/vcard --save

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

"dependencies": {
  "@ohos/vcard": "^2.1.0"
}

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

npm install

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

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

npm install ../library --save

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

"dependencies": {
  "@ohos/library": "file:../library"
}

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

npm install

在引用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页面，示例如下：

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

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

随后便可以通过设置的name来使用该element元素，以引用HarmonyOS npm包中的hml页面，示例如下：

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

<div class="container">
    <comp></comp>
    <text class="title">
        {{ $t('strings.hello') }} {{ title }}
    </text>
</div>

引用HarmonyOS npm包ArkTS页面

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

// library/src/main/ets/components/MainPage/MainPage.ets
@Entry
@Component
export struct MainPage {
  @State message: string = 'Hello World'
  build() {
    Row() {
      Column() {
        Text(this.message)
          .fontSize(50)
          .fontWeight(FontWeight.Bold)
      }
      .width('100%')
    }
    .height('100%')
  }
}

然后在其它模块中通过import引入导出的ArkTS页面，示例如下所示：

// entry/MainAbility/pages/index.ets

import { MainPage } from "@ohos/library"
@Entry
@Component
struct Index {
  @State message: string = 'Hello World'

  build() {
    Column() {
      MainPage()
      Row() {
        Text(this.message)
          .fontSize(50)
          .fontWeight(FontWeight.Bold)
      }
      .width('100%')
    }
    .height('10%')
  }
}

引用HarmonyOS npm包内ts/js方法

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

// library/index.js
export function func() {
  return "[npm] func1";
}

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

// entry/src/main/js/MainAbility/pages/index/index.js
import {func} from "@ohos/library"
export default {
    data: {
        title: ""
    },
    onInit() {
        this.title = func();
    }
}

引用HarmonyOS npm包内资源

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

说明

当前暂不支持类Web范式引用i18n文件中的国际化资源。

// entry/src/main/ets/MainAbility/pages/index.ets
@Entry
@Component
struct Index {
  @State message: string = 'Hello World'
  build() {
    Column() {
      Row() {
        Text($r("app.string.hello_npm")) // 字符串资源
          .fontSize(40)
          .fontWeight(FontWeight.Bold)
      }
      .width('50%')
      Image($r("app.media.icon_npm")) // 图片资源
    }
    .height('100%')
  }
}

在编译构建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中，可以通过如下方式创建新的库模块。

1. 通过如下两种方法，在工程中添加新的HarmonyOS Library模块。

• 方法1：鼠标移到工程目录顶部，单击鼠标右键，选择New>Module。
• 方法2：在菜单栏选择File > New > Module。

2. 在New Module界面中，选择HarmonyOS Library，并单击Next。

3. 在Configure the New Module界面中，设置新添加的模块信息，设置完成后，单击Finish完成创建。

• Library name：新增Module所属的类名称。
• Package name：软件包名称。
• Compatible SDK：兼容的SDK版本。
• Device type：选择设备类型。

4. 等待工程自动同步完成后，会在工程目录中生成对应的库模块。

将库模块编译为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仓。

1. 在工程根目录下，单击鼠标右键New > File，创建一个后缀为“.gradle”的文件，如upload.gradle。
2. 在创建的upload.gradle文件中，添加如下示例代码。如下示例代码为发布HAR包到Maven仓的最小集，请根据实际发布信息进行修改。

apply plugin: 'maven-publish'

def DEFAULT_POM_NAME='myLibrary'
def DEFAULT_POM_VERSION='1.0.1'  //har包版本信息
def DEFAULT_POM_ARTIFACT_ID="harTest"  //har包ID
def DEFAULT_POM_GROUP_ID='com.huawei.har'  //项目组ID
def DEFAULT_POM_PACKAGING='har'  //包类型，固定为har
def DEFAULT_POM_DESCRIPTION='myLib for harmonyos'
def MAVEN_USERNAME='admin'   //远程Maven仓的用户名
def MAVEN_PASSWORD='******'  //远程Maven仓的密码
def LOCAL_MAVEN_REPOSITORY_URL='D:/01.localMaven/'  //本地Maven仓地址
def REMOTE_MAVEN_REPOSITORY_URL='https:// '  //远程Maven仓地址

afterEvaluate { project ->
    DEFAULT_POM_ARTIFACT_ID = project.name
    publishing {
        publications {
            maven(MavenPublication) {
                from components.debug  //指定发布的har包类型为debug或release
                group = DEFAULT_POM_GROUP_ID
                artifactId = DEFAULT_POM_ARTIFACT_ID
                version = DEFAULT_POM_VERSION
                pom {
                    name = DEFAULT_POM_NAME
                    description = DEFAULT_POM_DESCRIPTION
                    packaging = DEFAULT_POM_PACKAGING
                }
            }
        }
        repositories {
            maven {
                url = LOCAL_MAVEN_REPOSITORY_URL  //发布到本地Maven仓
                //发布到远程Maven仓的地址以及Maven仓的帐号和密码
                /*url = REMOTE_MAVEN_REPOSITORY_URL
                 credentials {
                    username MAVEN_USERNAME
                    password MAVEN_PASSWORD
                 }
                */
            }
        }
    }
}

3. 在Har模块的build.gradle中，添加HAR发布脚本。添加完成后，单击Sync Now进行同步。

apply from:'../upload.gradle'

4. 同步完成后，会在Gradle任务中增加publishing的任务列表。

5. 双击执行publishMavenPublicationToMavenRepository任务，将HAR包发布到指定的Maven地址。

6. 本示例是以发布到本地Maven地址为例，发布结果如下图所示：

为应用/服务模块添加依赖

在应用/服务模块（entry或feature模块）中调用HAR，常用的添加依赖的方式包括如下三种。

1. 调用同一个工程中的HAR：HAR包和应用/服务模块在同一个工程，打开应用/服务模块的build.gradle文件，在dependencies闭包中，添加如下代码。添加完成后，请单击Sync Now同步工程。

dependencies {
    implementation project(":mylibrary")
}

2. 调用Maven仓中的HAR：无论Har包是本地Maven仓还是远程Maven仓，均可以采用如下方式添加依赖。

   a. 在工程的build.gradle的allprojects闭包中，添加HAR所在的Maven仓地址。

repositories {
        maven {
            url 'file://D:/01.localMaven/'  //添加Maven仓地址，可以是本地Maven地址，也可以是远程Maven地址
        }
}

   b. 在应用/服务模块的build.gradle的dependencies闭包中，添加如下代码。

dependencies {
    implementation 'com.huawei.har:mylibrary:1.0.1'
}

   c. 添加完成后，单击Sync Now同步工程。

3. 调用本地HAR：将Har包放到模块下的libs目录，然后检查build.gradle中是否添加了*.har的依赖。

dependencies {
    ...
    implementation fileTree(dir: 'libs', include: ['*.jar', '*.har'])
}

文章转载自：​​https://developer.harmonyos.com/cn/docs/documentation/doc-guides-V3/creating_har-0000001059626724-V3​​