From 56cde274ca94cb8eecf59cdd16407fcc33c91344 Mon Sep 17 00:00:00 2001 From: Annie_wang Date: Tue, 17 Jan 2023 21:14:29 +0800 Subject: [PATCH] update docs Signed-off-by: Annie_wang --- en/application-dev/napi/napi-guidelines.md | 62 +++++++++++----------- 1 file changed, 32 insertions(+), 30 deletions(-) diff --git a/en/application-dev/napi/napi-guidelines.md b/en/application-dev/napi/napi-guidelines.md index 188b4f1336..5113c413d5 100644 --- a/en/application-dev/napi/napi-guidelines.md +++ b/en/application-dev/napi/napi-guidelines.md @@ -1,12 +1,14 @@ # Using Native APIs in Application Projects -OpenHarmony applications use JavaScript (JS) when calling native APIs. The native APIs (NAPIs) provided by the [ace_napi](https://gitee.com/openharmony/arkui_napi/tree/master) repository are used to implement interaction with JS. Currently, the **ace_napi** repository supports some third-party **Node.js** interfaces. The names of the NAPIs are the same as those in the third-party **Node.js**. For details about the interfaces supported, see `libnapi.ndk.json` in this repository. +OpenHarmony applications use JavaScript (JS) when calling native APIs. The native APIs (NAPIs) provided by the [ace_napi](https://gitee.com/openharmony/arkui_napi/tree/master) repository are used to implement interaction with JS. The names of the NAPIs are the same as those in the third-party **Node.js**. For details about the interfaces supported, see **libnapi.ndk.json** in the ace_napi repository. ## How to Develop -The IDE has a default project that uses NAPIs. You can choose `File` > `New` > `Create Project` to create a `Native C++` project. The **cpp** directory is generated in the **main** directory. You can use the NAPIs provided by the **ace_napi** repository for development. +The DevEco Studio has a default project that uses NAPIs. -You can `import` the native .so that contains the JS processing logic. For example, `import hello from 'libhello.so'` to use the **libhello.so** capability. Then, the JS object created using the NAPI can be passed to the `hello` object of the application to call the native capability. +You can choose **File** > **New** > **Create Project** to create a **Native C++** project. The **cpp** directory is generated in the **main** directory. You can use the NAPIs provided by the **ace_napi** repository for development. + +You can import the native .so that contains the JS processing logic. For example, **import hello from 'libhello.so'** to use the **libhello.so** capability. Then, the JS object created using the NAPI can be passed to the **hello** object of the application to call the native capability. ## Development Guidelines @@ -17,7 +19,7 @@ You can `import` the native .so that contains the JS processing logic. For examp ### .so Naming Rules -Each module has a .so file. For example, if the module name is `hello`, name the .so file `libhello.so`. The `nm_modname` field in `napi_module` must be `hello`, which is the same as the module name. The sample code for importing the .so file is `import hello from 'libhello.so'`. +Each module has a .so file. For example, if the module name is **hello**, name the .so file **libhello.so**. The **nm_modname** field in **napi_module** must be **hello**, which is the same as the module name. The sample code for importing the .so file is **import hello from 'libhello.so'**. ### JS Objects and Threads @@ -28,7 +30,7 @@ The Ark engine prevents NAPIs from being called to operate JS objects in non-JS ### Importing Header Files -Before using NAPI objects and methods, include **napi/native_api.h**. Otherwise, when only the third-party library header file is included, an error will be reporting, indicating that the interface cannot be found. +Before using NAPI objects and methods, include **napi/native_api.h**. Otherwise, if only the third-party library header file is included, an error will be reporting, indicating that the interface cannot be found. ### napi_create_async_work @@ -50,11 +52,11 @@ napi_status napi_create_async_work(napi_env env, -## Example 1: Encapsulating Synchronous and Asynchronous APIs for the Storage Module +## Encapsulating Synchronous and Asynchronous APIs for the Storage Module ### Overview -This example shows how to encapsulate the synchronous and asynchronous APIs of the storage module. The storage module implements the functions of storing, obtaining, deleting, and clearing data. +This example shows how to encapsulate the synchronous and asynchronous APIs of the **Storage** module. The **Storage** module implements the functions of storing, obtaining, deleting, and clearing data. ### API Declaration @@ -79,11 +81,11 @@ export default storage; ### Implementation -You can obtain the complete code from `sample/native_module_storage/` in the [OpenHarmony/arkui_napi](https://gitee.com/openharmony/arkui_napi/tree/master) repository. +You can obtain the complete code from sample/native_module_storage/ in the [OpenHarmony/arkui_napi](https://gitee.com/openharmony/arkui_napi/tree/master) repository. -#### Registering the Module +**1. Register the module.** -Register four synchronous APIs (`getSync`, `setSync`, `removeSync`, and`clearSync`) and four asynchronous APIs (`get`, `set`, `remove`, and `clear`). +Register four synchronous APIs (**getSync**, **setSync**, **removeSync**, and **clearSync**) and four asynchronous APIs (**get**, **set**, **remove**, and **clear**). ```c++ /*********************************************** @@ -122,9 +124,9 @@ extern "C" __attribute__((constructor)) void StorageRegister() } ``` -#### Implementing getSync +**2. Implement getSync.** -The **getSync** function registered for the storage module is **JSStorageGetSync**. Obtain data from `gKeyValueStorage`, create a string object, and return it. +The **getSync** function registered for the **Storage** module is **JSStorageGetSync**. Obtain data from **gKeyValueStorage**, create a string object, and return the object created. ```c static napi_value JSStorageGetSync(napi_env env, napi_callback_info info) @@ -168,9 +170,9 @@ static napi_value JSStorageGetSync(napi_env env, napi_callback_info info) } ``` -#### Implementing get +**3. Implement get().** -The `get` function registered for the storage module is `JSStorageGet`. +The **get** function registered for the **Storage** module is **JSStorageGet**. ```c static napi_value JSStorageGet(napi_env env, napi_callback_info info) @@ -268,7 +270,7 @@ static napi_value JSStorageGet(napi_env env, napi_callback_info info) } ``` -### JS Sample Code +**JS Sample Code** ```js import storage from 'libstorage.so'; @@ -292,11 +294,11 @@ export default { -## Example 2: Binding Native and JS Objects for the NetServer Module +## Binding Native and JS Objects for the NetServer Module ### Overview -This example shows how to implement the `on/off/once` method and bind C++ and JS objects using the **wrap** API. The NetServer module implements the network service. +This example shows how to implement the **on**, **off**, and **once** methods and bind C++ and JS objects using **wrap()**. The **NetServer** module implements the network service. ### API Declaration @@ -312,9 +314,9 @@ export class NetServer { ### Implementation -You can obtain the complete code from `sample/native_module_netserver/` in the [OpenHarmony/arkui_napi](https://gitee.com/openharmony/arkui_napi/tree/master) repository. +You can obtain the complete code from **sample/native_module_netserver/** in the [OpenHarmony/arkui_napi](https://gitee.com/openharmony/arkui_napi/tree/master) repository. -#### Registering the Module +**1. Register the module.** ```c static napi_value NetServer::Export(napi_env env, napi_value exports) @@ -338,7 +340,7 @@ static napi_value NetServer::Export(napi_env env, napi_value exports) } ``` -#### Binding C++ and JS Objects in a Constructor +**2. Bind C++ and JS objects in a constructor.** ```c napi_value NetServer::JS_Constructor(napi_env env, napi_callback_info cbinfo) @@ -365,7 +367,7 @@ napi_value NetServer::JS_Constructor(napi_env env, napi_callback_info cbinfo) } ``` -#### Obtaining the C++ Object from the JS Object +**3. Obtain a C++ object from a JS object.** ```c napi_value NetServer::JS_Start(napi_env env, napi_callback_info cbinfo) @@ -398,7 +400,7 @@ napi_value NetServer::JS_Start(napi_env env, napi_callback_info cbinfo) } ``` -After `netServer->Start` is executed, call back the `start` event registered by `on`. +After **netServer->Start** is executed, call back the **start** event registered by **on()**. ```c int NetServer::Start(int port) @@ -435,7 +437,7 @@ int NetServer::Start(int port) } ``` -#### Registering Events (on) +**4. Call on() to register an event observer.** ```c napi_value NetServer::JS_On(napi_env env, napi_callback_info cbinfo) @@ -475,7 +477,7 @@ napi_value NetServer::JS_On(napi_env env, napi_callback_info cbinfo) } ``` -### JS Sample Code +**JS Sample Code** ```javascript import { NetServer } from 'libnetserver.so'; @@ -491,7 +493,7 @@ export default { -## Example 3: Calling Back a JS API in a Non-JS Thread +## Calling Back a JS API in a Non-JS Thread ### Overview @@ -499,11 +501,11 @@ This example describes how to invoke a JS callback in a non-JS thread. For examp ### Implementation -You can obtain the complete code from `sample/native_module_callback/` in the [OpenHarmony/arkui_napi](https://gitee.com/openharmony/arkui_napi/tree/master) repository. +You can obtain the complete code from **sample/native_module_callback/** in the [OpenHarmony/arkui_napi](https://gitee.com/openharmony/arkui_napi/tree/master) repository. -#### Registering the Module +**1. Register the module.** -Register the `test` API to pass in a parameter. +Register the **test** API to pass in a parameter. ```c++ /*********************************************** @@ -536,7 +538,7 @@ extern "C" __attribute__((constructor)) void CallbackTestRegister() } ``` -#### Obtaining the Loop in env and Throwing the Task to the JS Thread +**2. Obtain the loop in env and throw the task to a JS thread.** ```c++ #include @@ -627,7 +629,7 @@ static napi_value JSTest(napi_env env, napi_callback_info info) } ``` -### JS Sample Code +**JS Sample Code** ```js import callback from 'libcallback.so'; -- GitLab