输入关键字搜索
开发者能力认证
鸿蒙高校创新赛
HarmonyOS 7
animation
HarmonyOS行业解决方案
layoutWeight
HarmonyOS模板&组件
bindPopup
bindsheet
CTRL+K
文档管理中心

HarmonyOS

3.1/4.0
输入关键字搜索
开发者能力认证
鸿蒙高校创新赛
HarmonyOS 7
animation
HarmonyOS行业解决方案
layoutWeight
HarmonyOS模板&组件
bindPopup
bindsheet
CTRL+K
指南

您当前浏览的3.1/4.0版本文档归档不再维护，推荐您使用最新的HarmonyOS NEXT版本文档。详细请参考文档维护策略变更。

指南工具DevEco Studio使用指南应用/服务开发开发及引用共享包开发及引用静态共享包（API 8）

开发及引用静态共享包（API 8）

更新时间: 2024-06-29 07:33
本文导读
展开章节

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

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

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

  • 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 > hello.cpp：HarmonyOS npm包C++代码源文件。
  • index.ets：HarmonyOS npm包导出声明的入口。

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

创建HarmonyOS npm模块

  1. 鼠标移到工程目录顶部，单击右键，选择New > Module，在HarmonyOS工程中添加HarmonyOS npm块。
  2. 在Choose Your Ability Template界面中，选择Static 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。

    收起
    自动换行
    深色代码主题
    复制
    1. npm config set @ohos:registry=https://repo.harmonyos.com/npm/

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

    收起
    自动换行
    深色代码主题
    复制
    1. npm config set //repo.harmonyos.com/npm/:_authToken <authToken>

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

    收起
    自动换行
    深色代码主题
    复制
    1. npm publish <HarmonyOS npm包名称>

引用HarmonyOS npm包文件和资源

配置HarmonyOS npm包依赖

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

  • 引用npm仓中的HarmonyOS npm包，首先需要设置HarmonyOS npm三方包的仓库信息，请在DevEco Studio的Terminal窗口执行如下命令进行设置：
    收起
    自动换行
    深色代码主题
    复制
    1. npm config set @ohos:registry=https://repo.harmonyos.com/npm/
    然后通过如下两种方式设置HarmonyOS npm三方包依赖信息：
    • 方式一：在Terminal窗口中，执行如下命令安装HarmonyOS npm三方包，DevEco Studio会自动在工程的package.json中自动添加三方包依赖。
      收起
      自动换行
      深色代码主题
      复制
      1. npm install @ohos/vcard --save
    • 方式二：在工程的package.json中设置HarmonyOS npm三方包依赖，配置示例如下：
      收起
      自动换行
      深色代码主题
      复制
      1. "dependencies": {
      2.   "@ohos/vcard": "^2.1.0"
      3. }

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

      收起
      自动换行
      深色代码主题
      复制
      1. npm install
  • 引用本地HarmonyOS npm模块的文件和资源，有如下两种方式：
    • 方式一：在Terminal窗口中，执行如下命令进行安装，并会在package.json中自动添加依赖。
      收起
      自动换行
      深色代码主题
      复制
      1. npm install ../library --save
    • 方式二：在工程的package.json中设置HarmonyOS npm三方包依赖，配置示例如下：
      收起
      自动换行
      深色代码主题
      复制
      1. "dependencies": {
      2.   "library": "file:../library"
      3. }

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

      收起
      自动换行
      深色代码主题
      复制
      1. 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页面，示例如下：

收起
自动换行
深色代码主题
复制
  1. <element name="comp" src="library/src/main/js/components/index/index.hml"></element>

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

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

收起
自动换行
深色代码主题
复制
  1. <element name="comp" src="library/src/main/js/components/index/index.hml"></element>
  3. <div class="container">
  4.     <comp></comp>
  5.     <text class="title">
  6.         {{ $t('strings.hello') }} {{ title }}
  7.     </text>
  8. </div>

引用HarmonyOS npm包ArkTS页面

ArkTS是TypeScript的扩展，因此导出和引入的语法与TypeScript一致。在HarmonyOS npm模块中，可以通过export导出ArkTS页面，示例如下：
收起
自动换行
深色代码主题
复制
  1. // library/src/main/ets/components/MainPage/MainPage.ets
  2. @Entry
  3. @Component
  4. export struct MainPage {
  5.   @State message: string = 'Hello World'
  6.   build() {
  7.     Row() {
  8.       Column() {
  9.         Text(this.message)
  10.           .fontSize(50)
  11.           .fontWeight(FontWeight.Bold)
  12.       }
  13.       .width('100%')
  14.     }
  15.     .height('100%')
  16.   }
  17. }
然后在其它模块中通过import引入导出的ArkTS页面，示例如下所示：
收起
自动换行
深色代码主题
复制
  1. // entry/MainAbility/pages/index.ets
  2. 

  3. import { MainPage } from "library"
  4. @Entry
  5. @Component
  6. struct Index {
  7.   @State message: string = 'Hello World'
  8. 

  9.   build() {
  10.     Column() {
  11.       MainPage()
  12.       Row() {
  13.         Text(this.message)
  14.           .fontSize(50)
  15.           .fontWeight(FontWeight.Bold)
  16.       }
  17.       .width('100%')
  18.     }
  19.     .height('10%')
  20.   }
  21. }

引用HarmonyOS npm包内ts/js方法

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

收起
自动换行
深色代码主题
复制
  1. // library/index.js
  2. export function func() {
  3.   return "[npm] func1";
  4. }

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

收起
自动换行
深色代码主题
复制
  1. // entry/src/main/js/MainAbility/pages/index/index.js
  2. import {func} from "library"
  3. export default {
  4.     data: {
  5.         title: ""
  6.     },
  7.     onInit() {
  8.         this.title = func();
  9.     }
  10. }

引用HarmonyOS npm包内资源

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

说明

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

收起
自动换行
深色代码主题
复制
  1. // entry/src/main/ets/MainAbility/pages/index.ets
  2. @Entry
  3. @Component
  4. struct Index {
  5.   @State message: string = 'Hello World'
  6.   build() {
  7.     Column() {
  8.       Row() {
  9.         Text($r("app.string.hello_npm")) // 字符串资源
  10.           .fontSize(40)
  11.           .fontWeight(FontWeight.Bold)
  12.       }
  13.       .width('50%')
  14.       Image($r("app.media.icon_npm")) // 图片资源
  15.     }
  16.     .height('100%')
  17.   }
  18. }

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

  • AppScope（仅API 9的Stage模型支持）
  • HAP自身模块
  • 依赖的HarmonyOS npm模块

开发及引用静态共享包（API 9）
开发及引用静态共享包（API 4-7）
简体中文
华为开发者联盟 版权所有 ©2026
问题反馈
使用条款
华为开发者联盟用户协议
关于华为开发者联盟与隐私的声明
Cookies
开源软件声明
在 指南 中进行搜索
请输入您想要搜索的关键词