diff --git a/zh-cn/third-party-components/npm-third-party-guide.md b/zh-cn/third-party-components/npm-third-party-guide.md index 60222a480c852f19216688d99dda1dd9822005cc..22be4e935cf4b4388efdb3f4c443ff4ca7ad7c29 100644 --- a/zh-cn/third-party-components/npm-third-party-guide.md +++ b/zh-cn/third-party-components/npm-third-party-guide.md @@ -1,7 +1,7 @@ # OpenHarmony JS和TS三方组件使用指导 ## OpenHarmony JS和TS三方组件介绍 -OpenHarmony JS和TS三方组件是以OpenHarmony npm包的形式，在传统的npm三方组件的基础上，定义了OpenHarmony npm共享包特定的工程结构和配置文件，支持OpenHarmony页面组件相关API、资源的调用。通过OpenHarmony npm包，可以实现多个模块或者多个工程共享OpenHarmony页面、资源等相关代码。前往[npm官方文档](https://docs.npmjs.com/about-npm)，可以了解和掌握npm的基础功能和机制。 +OpenHarmony JS和TS三方组件使用的是OpenHarmony静态共享包，即HAR(Harmony Archive)，可以包含js/ts代码、c++库、资源和配置文件。通过HAR，可以实现多个模块或者多个工程共享ArkUI组件、资源等相关代码。HAR不同于HAP，不能独立安装运行在设备上，只能作为应用模块的依赖项被引用。 @@ -11,41 +11,164 @@ OpenHarmony JS和TS三方组件是以OpenHarmony npm包的形式，在传统的n -2. 访问[OpenHarmony官网](https://www.openharmony.cn/mainPlay/tpc)，通过类型，分类，以及关键字搜索需要的三方组件。 +2. 访问[OpenHarmony官网](https://growing.openharmony.cn/mainPlay/tpc)，通过类型，分类，以及关键字搜索需要的三方组件。 ![official-website.png](official-website.png) ## 安装并使用OpenHarmony JS和TS语言的三方组件 -在应用开发的过程中，JS和TS语言的三方组件，通常以源码或OpenHarmony npm包的方式被引入使用。按照以下步骤即可将OpenHarmony npm包引入应用并使用，源码的具体引入及使用请参考各三方组件README.md指导介绍。 - -1. 配置OpenHarmony npm环境，详情请参考安装教程 [如何安装OpenHarmony npm包](https://gitee.com/openharmony-tpc/docs/blob/master/OpenHarmony_npm_usage.md)。 - -2. 在Terminal项目终端中，进入entry目录，并执行目标组件命令进行安装。具体的下载命令详见OpenHarmony官网该三方组件的“下载安装“模块。 - - 以安装[vcard三方组件](https://growing.openharmony.cn/mainPlay/libraryMaps/vcard_595)为例，找到“下载安装”模块获取其安装命令，并执行该命令安装： - - ![npm-usage1.png](npm-usage1.png) - - ![npm-usage2.png](npm-usage2.png) - -3. 下载完成后在项目文件下自动生成node_modules文件，下载的三方库即node_modules目录下的@ohos\VCard。 - - ![npm-usage3.png](npm-usage3.png) - -4. 在package.json中会自动添加如下依赖： - - ``` - "dependencies": { - "@ohos/vcard": "^2.0.5" +引用三方HAR，包括从仓库进行安装和从本地库模块中进行安装两种方式。 + +**引用仓库安装的HAR** + +引用ohpm仓中的HAR，首先需要设置三方HAR的仓库信息，DevEco Studio默认仓库地址是"https://repo.harmonyos.com/ohpm/"，如果您想设置自定义仓库，请在DevEco Studio的Terminal窗口执行如下命令进行设置（执行命令前，请确保将DevEco Studio中ohpm安装地址配置在“环境变量-系统变量-PATH”中）： +``` +ohpm config set registry=your_registry1,your_registry2 +``` +说明：ohpm支持多个仓库地址，采用英文逗号分隔。 +然后通过如下两种方式设置三方包依赖信息： + - 方式一：在Terminal窗口中，执行如下命令安装三方包，DevEco Studio会自动在工程的oh-package.json5中自动添加三方包依赖。 +``` +ohpm install @ohos/lottie --save +``` + - 方式二：在工程的oh-package.json5中设置三方包依赖，配置示例如下： +``` +"dependencies": { "@ohos/lottie": "^2.0.0"} +``` +依赖设置完成后，需要执行ohpm install命令安装依赖包，依赖包会存储在工程的oh_modules目录下。 +``` +ohpm install +``` + +**引用本地库模块的文件和资源** + +- 方式一：在Terminal窗口中，执行如下命令进行安装，并会在oh-package5.json中自动添加依赖。 +``` +ohpm install ../library --save +``` +- 方式二：在工程的oh-package.json5中设置三方包依赖，配置示例如下： +``` +"dependencies": { + "@ohos/library": "file:../library" +} +``` +依赖设置完成后，需要执行ohpm install命令安装依赖包，依赖包会存储在工程的oh_modules目录下。 +``` +ohpm install +``` + +> **说明：** +> +> 在引用OpenHarmony HAR时，请注意以下事项 +>- 当前只支持在模块和工程下的oh-package.json5文件中声明dependencies依赖，才会被当做OpenHarmony依赖使用，并在编译构建过程中进行相应的处理。 +>- 引用的模块的compileSdkVersion不能低于其依赖的OpenHarmony ohpm三方包（可在oh_modules目录下，找到引用的ohpm包的src > main > module.json5 中查看）。 + + + +### 引用OpenHarmony HAR hml页面 +在JS工程范式中，组件功能由hml承载，开发者可以在JS工程的hml页面通过标签来引入OpenHarmony HAR中的共享hml页面，示例如下： +``` + +``` +其中，@ohos/library为OpenHarmony HAR的包名，hml页面的路径为OpenHarmony HAR中的相对路径。 +随后便可以通过设置的name来使用该element元素，以引用OpenHarmony HAR中的hml页面，示例如下： +```typescript + + +
+ + + {{ $t('strings.hello') }} {{ title }} + +
+``` +### 引用OpenHarmony HAR ArkTS页面 +ArkTS是TypeScript的扩展，因此导出和引入的语法与TypeScript一致。在OpenHarmony ohpm模块中，可以通过export导出ArkTS页面，示例如下： +```typescript +// 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%') } - ``` - -5. 在需要使用该组件的文件中导入组件。 - - ![npm-usage4.png](npm-usage4.png) - -6. 导入组件后直接使用方法即可。 - - ![npm-usage5.png](npm-usage5.png) \ No newline at end of file +} +``` +然后在其它模块中通过import引入导出的ArkTS页面，示例如下所示： +```typescript +// 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%') + } +} +``` +引用OpenHarmony HAR内ts/js方法ts/js方法的导出和引用，与ArkTS页面的引用相同，即在OpenHarmony ohpm模块中，可以通过export导出ts/js方法，示例如下所示： +```typescript +// library/index.js +export function func() { + return "[ohpm] func1"; +} +``` +然后在其它的ts/js页面中，通过import引入导出的ts/js方法，示例如下所示： +```typescript +// entry/src/main/js/MainAbility/pages/index/index.js +import {func} from "@ohos/library" +export default { + data: { + title: "" + }, + onInit() { + this.title = func(); + } +} +``` +引用OpenHarmony HAR内资源支持在OpenHarmony ohpm模块和依赖OpenHarmony ohpm的模块中引用OpenHarmony ohpm模块内的资源。例如在OpenHarmony ohpm模块的scr/main/resources里添加字符串资源（在string.json中定义，name：hello_ohpm）和图片资源（icon_ohpm.png）。然后在Entry模块中引用该字符串资源和图片资源的示例如下： +当前暂不支持类Web范式引用i18n文件中的国际化资源。 +```typescript +// 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_ohpm")) // 字符串资源 + .fontSize(40) + .fontWeight(FontWeight.Bold) + } + .width('50%') + Image($r("app.media.icon_ohpm")) // 图片资源 + } + .height('100%') + } +} +``` +在编译构建HAP中，DevEco Studio会从HAP模块及依赖的模块中收集资源文件，如果不同模块的相同限定词目录下的资源文件出现重名冲突时，DevEco Studio会按照以下优先级进行覆盖（优先级由高到低）： +- AppScope（仅API 9的Stage模型支持） +- HAP包自身模块 +- 依赖的OpenHarmonyHarmony ohpm模块 \ No newline at end of file diff --git a/zh-cn/third-party-components/npm-usage1.png b/zh-cn/third-party-components/npm-usage1.png deleted file mode 100644 index 9dc9a72717182136e77d620c90e45669c4059043..0000000000000000000000000000000000000000 Binary files a/zh-cn/third-party-components/npm-usage1.png and /dev/null differ diff --git a/zh-cn/third-party-components/npm-usage2.png b/zh-cn/third-party-components/npm-usage2.png deleted file mode 100644 index ce9e34ec18125ff473ad48667808081adc1a95d7..0000000000000000000000000000000000000000 Binary files a/zh-cn/third-party-components/npm-usage2.png and /dev/null differ diff --git a/zh-cn/third-party-components/npm-usage3.png b/zh-cn/third-party-components/npm-usage3.png deleted file mode 100644 index 66b6a14069cec3caaa42c0007f7b12ff09773f6f..0000000000000000000000000000000000000000 Binary files a/zh-cn/third-party-components/npm-usage3.png and /dev/null differ diff --git a/zh-cn/third-party-components/npm-usage4.png b/zh-cn/third-party-components/npm-usage4.png deleted file mode 100644 index 8cd881a7ddf90aed5570411c943794829c2fa24d..0000000000000000000000000000000000000000 Binary files a/zh-cn/third-party-components/npm-usage4.png and /dev/null differ diff --git a/zh-cn/third-party-components/npm-usage5.png b/zh-cn/third-party-components/npm-usage5.png deleted file mode 100644 index ec7f772f86dad4deb5f061f6e7cf6ac41748a225..0000000000000000000000000000000000000000 Binary files a/zh-cn/third-party-components/npm-usage5.png and /dev/null differ diff --git a/zh-cn/third-party-components/third-party-components-introduction.md b/zh-cn/third-party-components/third-party-components-introduction.md index 31f1ab1bfd795ff7b8154455a16d59ca234cd494..aaa89c4fac1bb47e7689a963c46e8c62cc81e18a 100644 --- a/zh-cn/third-party-components/third-party-components-introduction.md +++ b/zh-cn/third-party-components/third-party-components-introduction.md @@ -1,6 +1,6 @@ # OpenHarmony三方组件 -OpenHarmony三方组件，是经过验证可在OpenHarmony系统上可重复使用的软件组件，可帮助开发者快速开发OpenHarmony系统或应用。根据其开发语言分为了2种，一种是使用JavaScript和TypeScript语言的三方组件，通常以源码或OpenHarmony npm包的方式引入，在应用开发中使用。另一种是C和C++语言的三方组件，通常以源码或OpenHarmony hpm包的方式引入，在应用开发中以NAPI的方式使用，或直接编译在OpenHarmony操作系统镜像中。 +OpenHarmony三方组件，是经过验证可在OpenHarmony系统上可重复使用的软件组件，可帮助开发者快速开发OpenHarmony系统或应用。根据其开发语言分为了2种，一种是使用JavaScript和TypeScript语言的三方组件，通常以源码或OpenHarmony HAR的方式引入，在应用开发中使用。另一种是C和C++语言的三方组件，通常以源码或OpenHarmony hpm包的方式引入，在应用开发中以NAPI的方式使用，或直接编译在OpenHarmony操作系统镜像中。