24 Star 83 Fork 342

OpenHarmony / arkui_napi

加入 Gitee
与超过 1200万 开发者一起发现、参与优秀开源项目,私有仓库也完全免费 :)
免费加入
克隆/下载
README.md 12.46 KB
一键复制 编辑 原始数据 按行查看 历史
huangzhenghua 提交于 2023-06-02 11:40 . update README.md

NAPI

Introduction

The foundation/arkui/napi repository contains a development framework for extending the JS Native Module and provides APIs developed based on Node.js N-API for external use.

Figure 1 Architecture

  • NativeEngine

    NativeEngine is the JS engine abstraction layer. It unifies API behavior of the JS engines at the NAPI layer.

  • ModuleManager

    ModuleManager is used to load modules and cache module information.

  • ScopeManager

    ScopeManager manages the NativeValue lifecycle.

  • ReferenceManager

    ReferenceManager manages the NativeReference lifecycle.

Directory Structure

The source code directory structure of this repository is as follows:

foundation/arkui/napi
   ├── interfaces
   │   └── kits
   │       └── napi           # NAPI header files
   ├── module_manager         # Module manager
   ├── native_engine          # NativeEngine abstraction layer
   │   └── impl
   │       └── ark            # Ark-based NativeEngine implementation
   ├── scope_manager          # Scope manager
   └── test                   # Test code

When to Use

NAPI is suitable for processing I/O- and CPU-intensive tasks and system tasks. It encapsulates the capabilities and provides them to apps as JS APIs. NAPI can be used to implement mutual access between JS and C/C++ code. You can use NAPI to develop modules such as network communications, serial port access, multimedia decoding, and sensor data collection.

Available APIs

For details about the API implementation, see the foundation/arkui/napi repository.

Table 1 Available NAPIs

Category

Description

Module registration

Registers module information with a manager.

Exception & Error handling

Throws exceptions.

Object lifecycle

Manages NAPI object lifecycle within limited scopes.

JS object

Creates standard object types.

C-to-NAPI

Converts data types from C to NAPI.

NAPI-to-C

Converts data types from NAPI to C.

Global instance

Obtains global instances.

JS value

Provides APIs executing ===, typeof, instanceof, and other operations alike.

JS object property

Provides functions for performing operations on object properties.

JS function

Invokes functions and creates instances.

Object encapsulation

Binds the external context of JS objects.

Simple asynchronization

Creates asynchronous tasks.

Promise

Creates a function set for a promise.

Script

Runs JS code.

How to Develop

The following example describes how to use NAPI to develop a JS API for obtaining the application bundle name.

The prototype of the JS API is as follows:

function getAppName(): string;

The implementation code of the JS API is as follows:

// app.cpp
#include <stdio.h>
#include <string.h>
#include "napi/native_api.h"
#include "napi/native_node_api.h"

struct AsyncCallbackInfo {
    napi_env env;
    napi_async_work asyncWork;
    napi_deferred deferred;
};

// C/C++ function corresponding to getAppName()
napi_value JSGetAppName(napi_env env, napi_callback_info info) {
    napi_deferred deferred;
    napi_value promise;
    // Create a promise.
    NAPI_CALL(env, napi_create_promise(env, &deferred, &promise));

    AsyncCallbackInfo* asyncCallbackInfo = new AsyncCallbackInfo {
        .env = env,
        .asyncWork = nullptr,
        .deferred = deferred,
    };

    napi_value resourceName;
    napi_create_string_latin1(env, "GetAppName", NAPI_AUTO_LENGTH, &resourceName);
    // Create a queue of asynchronous tasks.
    napi_create_async_work(
        env, nullptr, resourceName,
        // Callback for an asynchronous task
        [](napi_env env, void* data) {},
        // Callback after the asynchronous task is complete
        [](napi_env env, napi_status status, void* data) {
            AsyncCallbackInfo* asyncCallbackInfo = (AsyncCallbackInfo*)data;
            napi_value appName;
            const char* str = "com.example.helloworld";
            napi_create_string_utf8(env, str, strlen(str), &appName);
            // Trigger the callback.
            napi_resolve_deferred(asyncCallbackInfo->env, asyncCallbackInfo->deferred, appName);
            napi_delete_async_work(env, asyncCallbackInfo->asyncWork);
            delete asyncCallbackInfo;
        },
        (void*)asyncCallbackInfo, &asyncCallbackInfo->asyncWork);
    napi_queue_async_work(env, asyncCallbackInfo->asyncWork);
    return promise;
}

// Export the module.
static napi_value AppExport(napi_env env, napi_value exports)
{
    static napi_property_descriptor desc[] = {
        DECLARE_NAPI_FUNCTION("getAppName", JSGetAppName),
    };
    NAPI_CALL(env, napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc));
    return exports;
}

// App module description
static napi_module appModule = {
    .nm_version = 1,
    .nm_flags = 0,
    .nm_filename = nullptr,
    .nm_register_func = AppExport,
    .nm_modname = "app",
    .nm_priv = ((void*)0),
    .reserved = {0}
};

// Register the module.
extern "C" __attribute__((constructor)) void AppRegister()
{
    napi_module_register(&appModule);
}

The build script is as follows:

// BUILD.gn
import("//build/ohos.gni")
ohos_shared_library("app") {
  # Specify the source file to build.
  sources = [
    "app.cpp",
  ]
  # Specify build dependencies.
  deps = [ "//foundation/arkui/napi:ace_napi" ]
  # Specify the directory where the library is generated.
  relative_install_dir = "module"
  subsystem_name = "arkui"
  part_name = "napi"
}

Test code to run in your app is as follows:

import app from '@ohos.app'
export default {
  testGetAppName() {
    app.getAppName().then(function (data) {
      console.info('app name: ' + data);
    });
  }
}

Repositories Involved

ArkUI framework

arkui_ace_engine

arkui_ace_engine_lite

arkui_napi

1
https://gitee.com/openharmony/arkui_napi.git
git@gitee.com:openharmony/arkui_napi.git
openharmony
arkui_napi
arkui_napi
master

搜索帮助