NAPI

Введение
Структура директорий
Когда использовать
Доступные API
Как разрабатывать
Задействованные репозитории

Введение

Репозиторий foundation/arkui/napi содержит разработанный фреймворк для расширения JS Native Module и предоставляет API, разработанные на основе Node.js N-API для внешнего использования.

Рисунок 1 Архитектура

NativeEngine

NativeEngine представляет собой абстрактный слой JS-движка. Он унифицирует поведение API движков JS на уровне NAPI.
ModuleManager

ModuleManager используется для загрузки модулей и кэширования информации о модулях.
ScopeManager

ScopeManager управляет жизненным циклом NativeValue.
ReferenceManager

ReferenceManager управляет жизненным циклом NativeReference.

Структура директорий

Структура директорий исходного кода этого репозитория следующая:

foundation/arkui/napi
   ├── interfaces
   │   └── kits
   │       └── napi           # Заголовочные файлы NAPI
   ├── module_manager         # Менеджер модулей
   ├── native_engine          # Абстрактный слой NativeEngine
   │   └── impl
   │       └── ark            # Реализация NativeEngine на основе Ark
   ├── scope_manager          # Менеджер области видимости
   └── test                   # Тестовый код
```## Когда использовать<a name="section11759141594811"></a>

NAPI подходит для обработки задач с интенсивным вводом-выводом и вычислениями, а также системных задач. Он упаковывает возможности и предоставляет их приложениям в виде JS API. NAPI можно использовать для реализации взаимодействия между JS и C/C++ кодом. С его помощью можно разрабатывать модули, такие как сетевое взаимодействие, доступ к последовательным портам, декодирование мультимедиа и сбор данных сенсоров.

## Доступные API<a name="section1611515555510"></a>

Для получения подробной информации о реализации API обратитесь к репозиторию **foundation/arkui/napi**.**Таблица 1** Доступные API NAPI<a name="table10789351555"></a>
<table>
<thead align="left">
<tr id="row1878635175515">
<th class="cellrowborder" valign="top" width="19.439999999999998%" id="mcps1.2.3.1.1">
<p id="p27816352556"><a name="p27816352556"></a><a name="p27816352556"></a>Категория</p>
</th>
<th class="cellrowborder" valign="top" width="80.56%" id="mcps1.2.3.1.2">
<p id="p078835105514"><a name="p078835105514"></a><a name="p078835105514"></a>Описание</p>
</th>
</tr>
</thead>
<tbody>
<tr id="row17863535520">
<td class="cellrowborder" valign="top" width="19.439999999999998%" headers="mcps1.2.3.1.1">
<p id="p678143512552"><a name="p678143512552"></a><a name="p678143512552"></a>Регистрация модуля</p>
</td>
<td class="cellrowborder" valign="top" width="80.56%" headers="mcps1.2.3.1.2">
<p id="p4781035185515"><a name="p4781035185515"></a><a name="p4781035185515"></a>Зарегистрировать информацию о модуле с менеджером.</p>
</td>
</tr>
<tr id="row67951538205618">
<td class="cellrowborder" valign="top" width="19.439999999999998%" headers="mcps1.2.3.1.1">
<p id="p127961438195616"><a name="p127961438195616"></a><a name="p127961438195616"></a>Обработка исключений и ошибок</p>
</td>
<td class="cellrowborder" valign="top" width="80.56%" headers="mcps1.2.3.1.2">
<p id="p47961338195617"><a name="p47961338195617"></a><a name="p47961338195617"></a>Вызывает исключения.</p>
</td>
</tr>
<tr id="row778417510579">
<td class="cellrowborder" valign="top" width="19.439999999999998%" headers="mcps1.2.3.1.1">
<p id="p1878575185715"><a name="p1878575185715"></a><a name="p1878575185715"></a>Жизненный цикл объекта</p>
</td>
<td class="cellrowborder" valign="top" width="80.56%" headers="mcps1.2.3.1.2">
<p id="p1178565175711"><a name="p1178565175711"></a><a name="p1178565175711"></a>Управляет жизненным циклом объекта NAPI в ограниченных областях.</p>
</td>
</tr>
<tr id="row83179619572">
<td class="cellrowborder" valign="top" width="19.439999999999998%" headers="mcps1.2.3.1.1">
<p id="p1531786125717"><a name="p1531786125717"></a><a name="p1531786125717"></a>Объект JS</p>
</td>
<td class="cellrowborder" valign="top" width="80.56%" headers="mcps1.2.3.1.2">
<p id="p1431796125716"><a name="p1431796125716"></a><a name="p1431796125716"></a>Обеспечивает доступ к объектам JavaScript.</p>
</td>
</tr>
</tbody>
</table><p id="p12317663572"><a name="p12317663572"></a><a name="p12317663572"></a>Создает стандартные типы объектов.</p>
</td>
</tr>
<tr id="row63859616579">
<td class="cellrowborder" valign="top" width="19.439999999999998%" headers="mcps1.2.3.1.1">
<p id="p163859616579"><a name="p163859616579"></a><a name="p163859616579"></a>Другое</p>
</td>
<td class="cellrowborder" valign="top" width="80.56%" headers="mcps1.2.3.1.2">
<p id="p173859616579"><a name="p173859616579"></a><a name="p173859616579"></a>Другие функции.</p>
</td>
</tr>
</tbody>
</table>1 "><p id="p438696165720"><a name="p438696165720"></a><a name="p438696165720"></a>C-to-NAPI</p>
</td>
<td class="cellrowborder" valign="top" width="80.56%" headers="mcps1.2.3.1.2">
<p id="p14386462570"><a name="p14386462570"></a><a name="p14386462570"></a>Конвертирует типы данных из C в NAPI.</p>
</td>
</tr>
<tr id="row1145119612578">
<td class="cellrowborder" valign="top" width="19.439999999999998%" headers="mcps1.2.3.1.1">
<p id="p13451116115716"><a name="p13451116115716"></a><a name="p13451116115716"></a>NAPI-to-C</p>
</td>
<td class="cellrowborder" valign="top" width="80.56%" headers="mcps1.2.3.1.2">
<p id="p12451464574"><a name="p12451464574"></a><a name="p12451464574"></a>Конвертирует типы данных из NAPI в C.</p>
</td>
</tr>
<tr id="row1451436155720">
<td class="cellrowborder" valign="top" width="19.439999999999998%" headers="mcps1.2.3.1.1">
<p id="p155147625713"><a name="p155147625713"></a><a name="p155147625713"></a>Глобальный экземпляр</p>
</td>
<td class="cellrowborder" valign="top" width="80.56%" headers="mcps1.2.3.1.2">
<p id="p551466195713"><a name="p551466195713"></a><a name="p551466195713"></a>Получает глобальные экземпляры.</p>
</td>
</tr>
<tr id="row65815617579">
<td class="cellrowborder" valign="top" width="19.439999999999998%" headers="mcps1.2.3.1.1">
<p id="p458119617577"><a name="p458119617577"></a><a name="p458119617577"></a>Значение JS</p>
</td>
<td class="cellrowborder" valign="top" width="80.56%" headers="mcps1.2.3.1.2">
<p id="p65815617579"><a name="p65815617579"></a><a name="p65815617579"></a>Получает значение объекта JavaScript.</p>
</td>
</tr>2 "><p id="p125818625711"><a name="p1125818625711"></a><a name="p1125818625711"></a>Предоставляет API для выполнения операций <strong id="b18893622126"><a name="b18893622126"></a><a name="b18893622126"></a>===</strong>, <strong id="b5190121451212"><a name="b5190121451212"></a><a name="b5190121451212"></a>typeof</strong>, <strong id="b01299162121"><a name="b01299162121"></a><a name="b01299162121"></a>instanceof</strong> и других подобных операций. </p>
 </td>
 </tr>
 <tr id="row10649166145711"><td class="cellrowborder" valign="top" width="19.439999999999998%" headers="mcps1.2.3.1.1 "><p id="p18649196195716"><a name="p18649196195716"></a><a name="p18649196195716"></a>Свойство объекта JS</p>
 </td>
 <td class="cellrowborder" valign="top" width="80.56%" headers="mcps1.2.3.1.2 "><p id="p164919615574"><a name="p164919615574"></a><a name="p164919615574"></a>Предоставляет функции для выполнения операций с свойствами объектов. </p>
 </td>
 </tr>
 <tr id="row0714260574">
   <td class="cellrowborder" valign="top" width="19.439999999999998%" headers="mcps1.2.3.1.1 ">
    <p id="p37143675714"><a name="p37143675714"></a><a name="p37143675714"></a>JS функция</p>
   </td>
   <td class="cellrowborder" valign="top" width="80.56%" headers="mcps1.2.3.1.2 ">
    <p id="p771466115711"><a name="p771466115711"></a><a name="p771466115711"></a>Вызывает функции и создает экземпляры. </p>
   </td>
  </tr>
  <tr id="row1578176155717">
   <td class="cellrowborder" valign="top" width="19.439999999999998%" headers="mcps1.2.3.1.1 ">
    <p id="p1782126155711"><a name="p1782126155711"></a><a name="p1782126155711"></a>Обертка объекта</p>
   </td>
   <td class="cellrowborder" valign="top" width="80.56%" headers="mcps1.2.3.1.2 ">
    <p id="p87821967572"><a name="p87821967572"></a><a name="p87821967572"></a>Привязывает внешний контекст объектов JavaScript. </p>
   </td>
  </tr>
  <tr id="row8854116105717">
   <td class="cellrowborder" valign="top" width="19.439999999999998%" headers="mcps1.2.3.1.1 ">
    <p id="p1685414619578"><a name="p1685414619578"></a><a name="p1685414619578"></a>Простая асинхронность</p>
   </td>
   <td class="cellrowborder" valign="top" width="80.56%" headers="mcps1.2.3.1.2 ">
    <p id="p18854116105717"><a name="p18854116105717"></a><a name="p18854116105717"></a>Позволяет выполнять простые асинхронные операции. </p>
   </td>
  </tr>
</table>   <p id="p1685411612574"><a name="p1685411612574"></a><a name="p1685411612574"></a>Создает асинхронные задачи.</p>
   </td>
  </tr>
  <tr id="row109154635718">
   <td class="cellrowborder" valign="top" width="19.439999999999998%" headers="mcps1.2.3.1.1">
    <p id="p391556195720"><a name="p391556195720"></a><a name="p391556195720"></a>Promise</p>
   </td>
   <td class="cellrowborder" valign="top" width="80.56%" headers="mcps1.2.3.1.2">
    <p id="p1091566135717"><a name="p1091566135717"></a><a name="p1091566135717"></a>Создает набор функций для промиса.</p>
   </td>
  </tr>
  <tr id="row1671493313016">
   <td class="cellrowborder" valign="top" width="19.439999999999998%" headers="mcps1.2.3.1.1">
    <p id="p1971512331709"><a name="p1971512331709"></a><a name="p1971512331709"></a>Скрипт</p>
   </td>
   <td class="cellrowborder" valign="top" width="80.56%" headers="mcps1.2.3.1.2">
    <p id="p371517332013"><a name="p371517332013"></a><a name="p371517332013"></a>Выполняет код JavaScript.</p>
   </td>
  </tr>
  </tbody>
 </table>## Как разрабатывать<a name="section937267212"></a>В следующем примере описывается, как использовать NAPI для разработки JS API для получения имени пакета приложения.

Прототип JS API выглядит следующим образом:

function getAppName(): string;


Код реализации JS API представлен ниже:

// 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++ функция, соответствующая getAppName() napi_value JSGetAppName(napi_env env, napi_callback_info info) { napi_deferred deferred; napi_value 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);
// Создание очереди асинхронных задач.
napi_create_async_work(
    env, nullptr, resourceName,
    // Коллбэк для асинхронной задачи
    [](napi_env env, void* data) {},
    // Коллбэк после завершения асинхронной задачи
    [](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);
        // Вызов коллбэка.
        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;

}

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;
}
```// Описание модуля приложения
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}
};```// Регистрация модуля.
extern "C" __attribute__((constructor)) void AppRegister()
{
    napi_module_register(&appModule);
}

Скрипт сборки выглядит следующим образом:

// BUILD.gn
import("//build/ohos.gni")
ohos_shared_library("app") {
  # Укажите файлы исходного кода для сборки.
  sources = [
    "app.cpp",
  ]
  # Укажите зависимости сборки.
  deps = [ "//foundation/arkui/napi:ace_napi" ]
  # Укажите директорию, где будет сгенерирована библиотека.
  relative_install_dir = "module"
  subsystem_name = "arkui"
  part_name = "napi"
}

Тестовый код для запуска в вашем приложении выглядит следующим образом:

import app from '@ohos.app'
export default {
  testGetAppName() {
    app.getAppName().then(function (data) {
      console.info('имя приложения: ' + data);
    });
  }
}

Вовлечённые репозитории

ArkUI framework

arkui_ace_engine

arkui_ace_engine_lite

arkui_napi

OSCHINA-MIRROR/openharmony-arkui_napi

NAPI

Введение

Структура директорий

Вовлечённые репозитории

Комментарии ( 0 )

Введение

Обновления

Участники

Недавние действия

OSCHINA-MIRROR/openharmony-arkui_napi .gitee-modal { min-width: 500px !important; } .gitee-modal .close { right: 0.6rem !important; }

NAPI

Введение

Структура директорий

Вовлечённые репозитории

Комментарии ( 0 )

Введение

Обновления

Участники

Недавние действия

OSCHINA-MIRROR/openharmony-arkui_napi