提交 64e70ebe 编写于 作者: G Gloria

Update docs against 16542+16723+17198

Signed-off-by: wusongqing<wusongqing@huawei.com>
上级 148438ff
# Using OpenHarmony JS and TS Third-Party Components
## Overview
OpenHarmony JS and TS third-party components are delivered in the form of OpenHarmony npm packages. Developed based on the traditional npm components, OpenHarmony npm shared packages come with specially designed project structures and configuration files. Such a package enables multiple modules or projects to share code related to OpenHarmony UI and resources. You can go to the [official npm website](https://docs.npmjs.com/about-npm) to learn about the basic functions and mechanisms of npm.
## Searching for OpenHarmony JS and TS Third-Party Components
1. Find the [OpenHarmony-TPC/tpc_resource](https://gitee.com/openharmony-tpc/tpc_resource) project on the Gitee website. You can find a component based on the directory index.
2. Visit the [OpenHarmony website](https://www.openharmony.cn/mainPlay/tpc) and search for required third-party components by type, category, or keyword.
## Installing and Using OpenHarmony JS and TS Third-Party Components
During application development, you can import JS and TS third-party components in the form of source code or OpenHarmony npm packages. Perform the following steps to import and use an OpenHarmony npm package. For details about how to import and use the source code, see **README.md** of the corresponding third-party components.
1. Configure the OpenHarmony npm environment. For details, see [Installing the OpenHarmony npm Package](https://gitee.com/openharmony-tpc/docs/blob/master/OpenHarmony_npm_usage-en.md).
2. Under **Terminal** project, go to the **entry** directory and run the target component's command to install the component. For details about the command, see "Download and Installation" of the third-party component on the OpenHarmony website.
The following uses the installation of the [vCard component](https://growing.openharmony.cn/mainPlay/libraryMaps/vcard_595) as an example. Find the installation command in "Download and Installation" and then run the command.
![npm-usage1.png](npm-usage1.png)
![npm-usage2.png](npm-usage2.png)
3. Check for the **node_modules** file, which is automatically generated in the project folder. In this example, the downloaded third-party library is **@ohos\VCard** in the **node_modules** directory.
![npm-usage3.png](npm-usage3.png)
4. Check for the dependency configuration, which is automatically added to the **package.json** file:
```
"dependencies": {
"@ohos/vcard": "^2.0.5"
}
```
5. Import the component to the file that plans to use the component.
![npm-usage4.png](npm-usage4.png)
6. Use the APIs as you want.
![npm-usage5.png](npm-usage5.png)
# Using Third-Party JavaScript and TypeScript Components
## Overview
OpenHarmony uses a third-party JavaScript or TypeScript component in the form of a Harmony Archive (HAR), which is a static shared package that can contain JavaScript or TypeScript code, C++ libraries, resources, and configuration files. The HAR enables modules and projects to share code related to ArkUI components, resources, and more. Unlike a Harmony Ability Package (HAP), a HAR cannot be independently installed on a device. Instead, it can be referenced only as the dependency of an application module.
## Searching for a Third-Party JavaScript or TypeScript Component
1. Access the [OpenHarmony-TPC/tpc_resource](https://gitee.com/openharmony-tpc/tpc_resource) repository, and find the desired component based on the directory index.
2. Visit the [OpenHarmony website](https://growing.openharmony.cn/mainPlay/tpc) and search for required third-party components by type, category, or keyword.
## Installing and Using a Third-Party JavaScript or TypeScript Component
You can reference a third-party HAR from the ohpm repository or the local repository module.
**Referencing an HAR Installed in the ohpm Repository**
To reference an HAR in the ohpm repository, set the repository information of the third-party HAR. The default repository address on DevEco Studio is "https://repo.harmonyos.com/ohpm/". To use a custom repository address, ensure that the ohpm installation address on DevEco Studio is configured in **Environment Variables > System Variables > PATH**, and then run the following command in the **Terminal** window of DevEco Studio:
```
ohpm config set registry=your_registry1,your_registry2
```
Note: You can configure multiple repository addresses, separated by commas (,).
Then use either of the following methods to set the third-party HAR as a dependency:
- Method 1: In the **Terminal** window, run the following command to install the third-party HAR. DevEco Studio will automatically add the HAR as a dependency to the **oh-package.json5** file of the project.
```
ohpm install @ohos/lottie
```
- Method 2: Set the third-party HAR as a dependency in the **oh-package.json5** file of the project. The following is a configuration example:
```
"dependencies": { "@ohos/lottie": "^2.0.0"}
```
After the dependency is set, run the **ohpm install** command to install the HAR, which will be stored in the **oh_modules** directory of the project.
```
ohpm install
```
**Referencing Files and Resources of the Local Repository Module**
- Method 1: In the **Terminal** window, run the following command to install the third-party HAR. DevEco Studio will automatically add the HAR as a dependency to the **oh-package5.json** file of the project.
```
ohpm install ../library
```
- Method 2: Set the third-party HAR as a dependency in the **oh-package.json5** file of the project. The following is a configuration example:
```
"dependencies": {
"@ohos/library": "file:../library"
}
```
After the dependency is set, run the **ohpm install** command to install the HAR, which will be stored in the **oh_modules** directory of the project.
```
ohpm install
```
> **NOTE**
>
> Pay attention to the following points when referencing an HAR:
>- Only the dependencies declared in **dependencies** of the **oh-package.json5** file in the module and project are used as OpenHarmony dependencies and processed during compilation and building.
>- The **compileSdkVersion** of the referenced module cannot be earlier than that of the OpenHarmony ohpm third-party package on which the referenced module depends. You can view the version in the **src** > **main** > **module.json5** file of the referenced ohpm package in the **oh_modules** directory.
### Referencing an HAR HML Page
In a JavaScript project paradigm, component functions are configured in HML files. To reference an HML page in an HAR, first import the page through the **<element>** tag in the HML file of the project. The sample code is as follows:
```
<element name="comp" src="@ohos/library/src/main/js/components/index/index.hml"></element>
```
In the preceding example, **@ohos/library** indicates the name of the HAR, and the path of the HML page is the relative path in the HAR.
You can then reference the HML page based on the set element name. The sample code is as follows:
```typescript
<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>
```
### Referencing an HAR ArkTS Page
ArkTS is an extension of TypeScript. Therefore, the export and import syntax of ArkTS is the same as that of TypeScript. In the OpenHarmony ohpm module, use **export** to export an ArkTS page. The sample code is as follows:
```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%')
}
}
```
Import the exported ArkTS page in other modules. The following is an example:
```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%')
}
}
```
The procedure for referencing JavaScript/TypeScript methods in the HAR is the same as that for referencing ArkTS pages. In the OpenHarmony ohpm module, export the methods through **export**. The sample code is as follows:
```typescript
// library/index.js
export function func() {
return "[ohpm] func1";
}
```
On other JavaScript/TypeScript pages, use **import** to import the exported methods. The sample code is as follows:
```typescript
// entry/src/main/js/MainAbility/pages/index/index.js
import {func} from "@ohos/library"
export default {
data: {
title: ""
},
onInit() {
this.title = func();
}
}
```
Resources in an OpenHarmony ohpm module can be referenced in another OpenHarmony ohpm module and modules that depend on the OpenHarmony ohpm module. For example, you can add string resources (defined in **string.json**, **name: hello_ohpm** in this example) and image resources (**icon_ohpm.png** in this example) to **scr/main/resources** of the OpenHarmony ohpm module, and then reference the string and image resources in the entry module, as shown below:
Currently, referencing resources in **i18n** files is not supported for the JavaScript-based web-like development paradigm.
```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")) // String resource.
.fontSize(40)
.fontWeight(FontWeight.Bold)
}
.width('50%')
Image($r("app.media.icon_ohpm")) // Image resource.
}
.height('100%')
}
}
```
During compilation and building of a HAP, DevEco Studio collects resource files from the HAP module and its dependent modules. If the resource files of different modules in the same qualifiers directory have the same name, DevEco Studio overwrites the resource files based on the following priorities (in descending order):
- AppScope (supported only by the stage model of API version 9)
- Modules in the HAP file
- Dependent OpenHarmony ohpm modules
# OpenHarmony Third-Party Components
OpenHarmony third-party components are verified software that work with the OpenHarmony system to facilitate your development of OpenHarmony devices or applications. Depending on the programming language they use, these components are classified as JS and TS third-party components or C and C++ third-party components. JS and TS third-party components the JavaScript or TypeScript programming languages and are usually imported as source code or OpenHarmony npm packages. They are used in application development. C and C++ third-party components use the C and C++ programming languages and are usually imported as source code or OpenHarmony hpm packages. They are used as native APIs during application development or directly compiled in the OpenHarmony OS image during device development.
OpenHarmony third-party components are verified software that work with the OpenHarmony system to facilitate your development of OpenHarmony devices or applications. Depending on the programming language they use, these components are classified as third-party JavaScript and TypeScript components or third-party C and C++ components. The third-party JavaScript and TypeScript components use the JavaScript or TypeScript programming language and are usually imported as source code or OpenHarmony HAR files. They are used in application development. The third-party C and C++ components use the C and C++ programming language and are usually imported as source code or OpenHarmony hpm packages. They are used as native APIs during application development or directly compiled in the OpenHarmony OS image during device development.
Currently, OpenHarmony provides UI, animation, image, multimedia, file, network, security, tool, and other third-party components.
Markdown is supported
0% .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑!
想要评论请 注册