【鸿蒙开发实战】Native API在HarmonyOS应用工程中的应用

前言

HarmonyOS 的应用必须用 js 来桥接 native。需要使用ace_napi仓中提供的 napi 接口来处理 js 交互。napi 提供的接口名与三方 Node.js 一致，目前支持部分接口，符号表见 ace_napi 仓中的 libnapi.ndk.json 文件。

开发流程

在 DevEco Studio 的模板工程中包含使用 Native API 的默认工程，使用 File->New->Create Project 创建 Native C++模板工程。创建后在 main 目录下会包含 cpp 目录，可以使用 ace_napi 仓下提供的 napi 接口进行开发。

js 侧通过 import 引入 native 侧包含处理 js 逻辑的 so，如：import hello from ‘libhello.so’，意为使用 libhello.so 的能力，native 侧通过 napi 接口创建的 js 对象会给到应用 js 侧的 hello 对象。

开发建议

注册建议

● nm_register_func 对应的函数需要加上 static，防止与其他 so 里的符号冲突。

● 模块注册的入口，即使用__attribute__((constructor))修饰的函数的函数名需要确保不与其他模块重复。

so 命名规则

so 命名必须符合以下规则：

● 每个模块对应一个 so。

● 如模块名为 hello，则 so 的名字为 libhello.so，napi_module 中 nm_modname 字段应为 hello，大小写与模块名保持一致，应用使用时写作：import hello from ‘libhello.so’。

js 对象线程限制

ark 引擎会对 js 对象线程使用进行保护，使用不当会引起应用 crash，因此需要遵循如下原则：

● napi 接口只能在 js 线程使用。

● env 与线程绑定，不能跨线程使用。native 侧 js 对象只能在创建时的线程使用，即与线程所持有的 env 绑定。

头文件引入限制

在使用 napi 的对象和方法时需要引用"napi/native_api.h"。否则在只引入三方库头文件时，会出现接口无法找到的编译报错。

napi_create_async_work 接口说明

napi_create_async_work 里有两个回调：

● execute：用于异步处理业务逻辑。因为不在 js 线程中，所以不允许调用 napi 的接口。业务逻辑的返回值可以返回到 complete 回调中处理。

● complete：可以调用 napi 的接口，将 execute 中的返回值封装成 js 对象返回。此回调在 js 线程中执行。

napi_status napi_create_async_work(napi_env env,
                                   napi_value async_resource,
                                   napi_value async_resource_name,
                                   napi_async_execute_callback execute,
                                   napi_async_complete_callback complete,
                                   void* data,
                                   napi_async_work* result)

storage 模块——同步异步接口封装

模块简介

本示例通过实现 storage 模块展示了同步和异步方法的封装。storage 模块实现了数据的保存、获取、删除、清除功能。

接口声明

import { AsyncCallback } from './basic';
declare namespace storage {
  function get(key: string, callback: AsyncCallback<string>): void;
  function get(key: string, defaultValue: string, callback: AsyncCallback<string>): void;
  function get(key: string, defaultValue?: string): Promise<string>;
  function set(key: string, value: string, callback: AsyncCallback<string>): void;
  function remove(key: string, callback: AsyncCallback<void>): void;
  function clear(callback: AsyncCallback<void>): void;
  function getSync(key: string, defaultValue?: string): string;
  function setSync(key: string, value: string): void;
  function removeSync(key: string): void;
  function clearClear(): void;
}
export default storage;

具体实现

完整代码参见仓下路径：OpenHarmony/arkui_napi仓库 sample/native_module_storage/

1、模块注册

如下，注册了 4 个同步接口（getSync、setSync、removeSync、clearSync）、4 个异步接口（get、set、remove、clear）。

/***********************************************
 * Module export and register
 ***********************************************/
static napi_value StorageExport(napi_env env, napi_value exports)
{
    napi_property_descriptor desc[] = {
        DECLARE_NAPI_FUNCTION("get", JSStorageGet),
        DECLARE_NAPI_FUNCTION("set", JSStorageSet),
        DECLARE_NAPI_FUNCTION("remove", JSStorageDelete),
        DECLARE_NAPI_FUNCTION("clear", JSStorageClear),


        DECLARE_NAPI_FUNCTION("getSync", JSStorageGetSync),
        DECLARE_NAPI_FUNCTION("setSync", JSStorageSetSync),
        DECLARE_NAPI_FUNCTION("deleteSync", JSStorageDeleteSync),
        DECLARE_NAPI_FUNCTION("clearSync", JSStorageClearSync),
    };
    NAPI_CALL(env, napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc));
    return exports;
}


// storage module
static napi_module storage_module = {.nm_version = 1,
                                     .nm_flags = 0,
                                     .nm_filename = nullptr,
                                     .nm_register_func = StorageExport,
                                     .nm_modname = "storage",
                                     .nm_