鸿蒙HarmonyOS应用开发之Node-API开发规范

最新推荐文章于 2024-08-27 19:38:16 发布
最新推荐文章于 2024-08-27 19:38:16 发布
阅读量1.4k 收藏 19
点赞数 15
分类专栏： 鸿蒙 OpenHarmony Harmony OS 文章标签： harmonyos 华为 openharmony 移动开发 鸿蒙开发 API
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.csdn.net/weixin_61845324/article/details/137084467
版权
Harmony OS 同时被 3 个专栏收录
314 篇文章 9 订阅
订阅专栏
鸿蒙
249 篇文章 7 订阅
订阅专栏
OpenHarmony
213 篇文章 3 订阅
订阅专栏

当传入napi_get_cb_info的argv不为nullptr时，argv的长度必须大于等于传入argc声明的大小。

当argv不为nullptr时，napi_get_cb_info会根据argc声明的数量将JS实际传入的参数写入argv。如果argc小于等于实际JS传入参数的数量，该接口仅会将声明的argc数量的参数写入argv；而当argc大于实际参数数量时，该接口会在argv的尾部填充undefined。

错误示例

static napi_value IncorrectDemo1(napi_env env, napi_callbackk_info info) {
    // argc 未正确的初始化，其值为不确定的随机值，导致 argv 的长度可能小于 argc 声明的数量，数据越界。
    size_t argc;
    napi_value argv[10] = {nullptr};
    napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
    return nullptr;
}

static napi_value IncorrectDemo2(napi_env env, napi_callback_info info) {
    // argc 声明的数量大与 argv 实际初始化的长度，导致 napi_get_cb_info 接口在写入 argv 时数据越界。
    size_t argc = 5;
    napi_value argv[3] = {nullptr};
    napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
    return nullptr;
}

正确示例

static napi_value GetArgvDemo1(napi_env env, napi_callback_info info) {
    size_t argc = 0;
    // argv 传入 nullptr 来获取传入参数真实数量
    napi_get_cb_info(env, info, &argc, nullptr, nullptr, nullptr);
    // JS 传入参数为0，不执行后续逻辑
    if (argc == 0) {
        return nullptr;
    }
    // 创建数组用以获取JS传入的参数
    napi_value* argv = new napi_value[argc]; 
    napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
    // 业务代码
    // ... ...
    // argv 为 new 创建的对象，在使用完成后手动释放
    delete argv;
    return nullptr;
}

static napi_value GetArgvDemo2(napi_env env, napi_callback_info info) {
    size_t argc = 2;
    napi_value* argv[2] = {nullptr}; 
    // napi_get_cb_info 会向 argv 中写入 argc 个 JS 传入参数或 undefined
    napi_get_cb_info(env, info, &argc, nullptr, nullptr, nullptr);
    // 业务代码
    // ... ...
    return nullptr;
}

生命周期管理

【规则】 合理使用napi_open_handle_scope和napi_close_handle_scope管理napi_value的生命周期，做到生命周期最小化，避免发生内存泄漏问题。

每个napi_value属于特定的HandleScope，HandleScope通过napi_open_handle_scope和napi_close_handle_scope来建立和关闭，HandleScope关闭后，所属的napi_value就会自动释放。

正确示例：

// 在for循环中频繁调用napi接口创建js对象时，要加handle_scope及时释放不再使用的资源。 
// 下面例子中，每次循环结束局部变量res的生命周期已结束，因此加scope及时释放其持有的js对象，防止内存泄漏
for (int i = 0; i < 100000; i++) { 
    napi_handle_scope scope = nullptr;   
    napi_open_handle_scope(env, &scope); 
    if (scope == nullptr) { 
        return; 
    } 
    napi_value res; 
    napi_create_object(env, &res); 
    napi_close_handle_scope(env, scope); 
}

上下文敏感

【规则】 多引擎实例场景下，禁止通过Node-API跨引擎实例访问JS对象。

引擎实例是一个独立运行环境，JS对象创建访问等操作必须在同一个引擎实例中进行。若在不同引擎实例中操作同一个对象，可能会引发程序崩溃。引擎实例在接口中体现为napi_env。

错误示例：

// 线程1执行，在env1创建string对象，值为"bar"、 
napi_create_string_utf8(env1, "bar", NAPI_AUTO_LENGTH, &string);
// 线程2执行，在env2创建object对象，并将上述的string对象设置到object对象中
napi_status status = napi_create_object(env2, &object); 
if (status != napi_ok) { 
    napi_throw_error(env, ...); 
    return; 
} 

status = napi_set_named_property(env2, object, "foo", string); 
if (status != napi_ok) { 
    napi_throw_error(env, ...); 
    return; 
}

所有的JS对象都隶属于具体的某一napi_env，不可将env1的对象，设置到env2中的对象中。在env2中一旦访问到env1的对象，程序可能会发生崩溃。

异常处理

【建议】 Node-API接口调用发生异常需要及时处理，不能遗漏异常到后续逻辑，否则程序可能发生不可预期行为。

正确示例：

// 1.创建对象
napi_status status = napi_create_object(env, &object); 
if (status != napi_ok) { 
    napi_throw_error(env, ...); 
    return;
} 
// 2.创建属性值 
status = napi_create_string_utf8(env, "bar", NAPI_AUTO_LENGTH, &string); 
if (status != napi_ok) { 
    napi_throw_error(env, ...); 
    return; 
} 
// 3.将步骤2的结果设置为对象object属性foo的值 
status = napi_set_named_property(env, object, "foo", string); 
if (status != napi_ok) { 
    napi_throw_error(env, ...); 
    return; 
}

如上示例中，步骤1或者步骤2出现异常时，步骤3都不会正常进行。只有当方法的返回值是napi_ok时，才能保持继续正常运行；否则后续流程可能会出现不可预期的行为。

异步任务

【规则】 当使用uv_queue_work方法将任务抛到JS线程上面执行的时候，对JS线程的回调方法，一般情况下需要加上napi_handle_scope来管理回调方法创建的napi_value的生命周期。

使用uv_queue_work方法，不会走Node-API框架，此时需要开发者自己合理使用napi_handle_scope来管理napi_value的生命周期。

正确示例：

void callbackTest(CallbackContext* context) 
{ 
    uv_loop_s* loop = nullptr; 
    napi_get_uv_event_loop(context->env, &loop); 
    uv_work_t* work = new uv_work_t; 
    context->retData = 1; 
    work->data = (void*)context; 
    uv_queue_work( 
        loop, work, [](uv_work_t* work) {}, 
        // using callback function back to JS thread 
        [](uv_work_t* work, int status) { 
            CallbackContext* context = (CallbackContext*)work->data; 
            napi_handle_scope scope = nullptr; napi_open_handle_scope(context->env, &scope); 
            if (scope == nullptr) { 
                return; 
            } 
            napi_value callback = nullptr; 
            napi_get_reference_value(context->env, context->callbackRef, &callback); 
            napi_value retArg; 
            napi_create_int32(context->env, context->retData, &retArg); 
            napi_value ret; 
            napi_call_function(context->env, nullptr, callback, 1, &retArg, &ret); 
            napi_delete_reference(context->env, context->callbackRef); 
            napi_close_handle_scope(context->env, scope); 
            if (work != nullptr) { 
                delete work; 
            } 
            delete context; 
        } 
    ); 
}

对象绑定

【规则】 使用napi_wrap接口，如果最后一个参数result传递不为nullptr，需要开发者在合适的时机调用napi_remove_wrap函数主动删除创建的napi_ref。

napi_wrap接口定义如下：

napi_wrap(napi_env env, napi_value js_object, void* native_object, napi_finalize finalize_cb, void* finalize_hint, napi_ref* result)

当最后一个参数result不为空时，框架会创建一个napi_ref对象，指向js_object。此时开发者需要自己管理js_object的生命周期，即需要在合适的时机调用napi_remove_wrap删除napi_ref，这样GC才能正常释放js_object，从而触发绑定C++对象native_object的析构函数finalize_cb。

一般情况下，根据业务情况最后一个参数result可以直接传递为nullptr。

正确示例：

// 用法1：napi_wrap不需要接收创建的napi_ref，最后一个参数传递nullptr，创建的napi_ref是弱引用，由系统管理，不需要用户手动释放 
napi_wrap(env, jsobject, nativeObject, cb, nullptr, nullptr)； 

// 用法2：napi_wrap需要接收创建的napi_ref，最后一个参数不为nullptr，返回的napi_ref是强引用，需要用户手动释放，否则会内存泄漏 
napi_ref result; 
napi_wrap(env, jsobject, nativeObject, cb, nullptr, &result)； 
// 当js_object和result后续不再使用时，及时调用napi_remove_wrap释放result 
napi_value result1; 
napi_remove_wrap(env, jsobject, result1);

高性能数组

【建议】 存储值类型数据时，使用ArrayBuffer代替JSArray来提高应用性能。

使用JSArray作为容器储存数据，支持几乎所有的JS数据类型。

使用napi_set_element方法对JSArray存储值类型数据（如int32）时，同样会涉及到与运行时的交互，造成不必要的开销。

ArrayBuffer进行增改是直接对缓冲区进行更改，具有远优于使用napi_set_element操作JSArray的性能表现。

因此此种场景下，更推荐使用napi_create_arraybuffer接口创建的ArrayBuffer对象。

示例：

// 以下代码使用常规JSArray作为容器，但其仅存储int32类型数据。
// 但因为是JS对象，因此只能使用napi方法对其进行增改，性能较低。
static napi_value ArrayDemo(napi_env env, napi_callback_info info)
{
    constexpr size_t arrSize = 1000;
    napi_value jsArr = nullptr;
    napi_create_array(env, &jsArr);
    for (int i = 0; i < arrSize; i++) {
        napi_value arrValue = nullptr;
        napi_create_int32(env, i, &arrValue);
        // 常规JSArray使用napi方法对array进行读写，性能较差。
        napi_set_element(env, jsArr, i, arrValue);
    }
    return jsArr;
}

// 推荐写法：
// 同样以int32类型数据为例，但以下代码使用ArrayBuffer作为容器。
// 因此可以使用C/C++的方法直接对缓冲区进行增改。
static napi_value ArrayBufferDemo(napi_env env, napi_callback_info info)
{
    constexpr size_t arrSize = 1000;
    napi_value arrBuffer = nullptr;
    void* data = nullptr;

    napi_create_arraybuffer(env, arrSize * sizeof(int32_t), &data, &arrBuffer);
    int32_t* i32Buffer = reinterpret_cast<int32_t*>(data);
    for (int i = 0; i < arrSize; i++) {
        // arrayBuffer直接对缓冲区进行修改，跳过运行时，
        // 与操作原生C/C++对象性能相当
        i32Buffer[i] = i;
    }

    return arrBuffer;
}

napi_create_arraybuffer等同于JS代码中的new ArrayBuffer(size)，其生成的对象不可直接在TS/JS中进行读取，需要将其包装为TyppedArray或DataView后方可进行读写。

基准性能测试结果如下：

说明： 以下数据为千次循环写入累计数据，为更好的体现出差异，已对设备核心频率进行限制。

容器类型Benchmark数据（us）
JSArray1566.174
ArrayBuffer3.609

数据转换

【建议】 尽可能的减少数据转换次数，避免不必要的复制。

  • 减少数据转换次数： 频繁的数据转换可能会导致性能下降，可以通过批量处理数据或者使用更高效的数据结构来优化性能；
  • 避免不必要的数据复制： 在进行数据转换时，可以使用Node-API提供的接口来直接访问原始数据，而不是创建新的副本；
  • 使用缓存： 如果某些数据在多次转换中都会被使用到，可以考虑使用缓存来避免重复的数据转换。缓存可以减少不必要的计算，提高性能。

其它

【规则】 使用napi_get_arraybuffer_info接口，第三个参数data资源开发者不允许释放，data的生命周期受引擎管理。

napi_get_arraybuffer_info接口定义如下：

napi_get_arraybuffer_info(napi_env env, napi_value arraybuffer, void** data, size_t* byte_length)

data获取的是ArrayBuffer的Buffer头指针，开发者只可以在范围内读写该Buffer区域，不可以进行释放操作。该段内存由引擎内部的ArrayBuffer Allocator管理，随JS对象ArrayBuffer的生命周期释放。

错误示例：

void* arrayBufferPtr = nullptr;
napi_value arrayBuffer = nullptr;
size_t createBufferSize = ARRAY_BUFFER_SIZE;
napi_status verification = napi_create_arraybuffer(env, createBufferSize, &arrayBufferPtr, &arrayBuffer);
size_t arrayBufferSize;
napi_status result = napi_get_arraybuffer_info(env, arrayBuffer, &arrayBufferPtr, &arrayBufferSize);
delete arrayBufferPtr; // 这一步是禁止的，创建的arrayBufferPtr生命周期由引擎管理，不允许用户自己delete，否则会double free

【建议】 合理使用napi_object_freeze和napi_object_seal来控制对象以及对象属性的可变性。

napi_object_freeze等同于Object.freeze语义，freeze后对象的所有属性都不可能以任何方式被修改；napi_object_seal等同于Object.seal语义，对象不可增删属性。两者的主要区别是，freeze不能改属性的值，seal还可以改属性的值。

开发者使用以上语义时，需确保约束条件是自己需要的，一旦违背以上语义严格模式下就会抛出Error（默认严格模式）。

为了能让大家更好的学习鸿蒙（HarmonyOS NEXT）开发技术，这边特意整理了《鸿蒙开发学习手册》（共计890页），希望对大家有所帮助：https://qr21.cn/FV7h05

《鸿蒙开发学习手册》：

如何快速入门：https://qr21.cn/FV7h05

  1. 基本概念
  2. 构建第一个ArkTS应用
  3. ……

开发基础知识：https://qr21.cn/FV7h05

  1. 应用基础知识
  2. 配置文件
  3. 应用数据管理
  4. 应用安全管理
  5. 应用隐私保护
  6. 三方应用调用管控机制
  7. 资源分类与访问
  8. 学习ArkTS语言
  9. ……

基于ArkTS 开发：https://qr21.cn/FV7h05

  1. Ability开发
  2. UI开发
  3. 公共事件与通知
  4. 窗口管理
  5. 媒体
  6. 安全
  7. 网络与链接
  8. 电话服务
  9. 数据管理
  10. 后台任务(Background Task)管理
  11. 设备管理
  12. 设备使用信息统计
  13. DFX
  14. 国际化开发
  15. 折叠屏系列
  16. ……

鸿蒙开发面试真题（含参考答案）：https://qr18.cn/F781PH

鸿蒙开发面试大盘集篇（共计319页）：https://qr18.cn/F781PH

1.项目开发必备面试题
2.性能优化方向
3.架构方向
4.鸿蒙开发系统底层方向
5.鸿蒙音视频开发方向
6.鸿蒙车载开发方向
7.鸿蒙南向开发方向

码中之牛
关注
专栏目录
鸿蒙HarmonyOS应用开发之Node-API简介
1
03-27 1431
OpenHarmony Node-API是基于Node.js 8.x LTS的 Node-API 规范扩展开发的机制，为开发者提供了ArkTS/JS与C/C++模块之间的交互能力。它提供了一组稳定的、跨平台的API，可以在不同的操作系统上使用。本文中如无特别说明，后续均使用Node-API指代OpenHarmony Node-API能力。OpenHarmony Node-API与Node.js 8.x LTS的Node-API规范的接口异同点，详见Node-API参考。
OpenHarmony实战开发-分布式设备管理开发指南
m0_70749039的博客
05-14 1278
随着用户不同种类的终端设备数量不断增多，将不同设备作为本端设备能力的扩展，使设备之间协同合作完成各种复杂场景即为设备的分布式业务。
【HarmonyOS NEXT应用开发】案例70：跨语言的复杂参数类型传递
xzs51job的专栏
08-19 902
ArkTS 侧 接收 Native C++ 侧返回的 Array，通过 napi_create_arraybuffer 创建一个 arraybuffer 数组，根据创建的 arraybuffer 通过 napi_create_typedarray 创建一个 typedarray 并将 arraybuffer 存入 output_array，然后给 arraybuffer 赋值，最后返回 output_array。获取ArkTS侧传来的文件路径，处理完后返回pixelmap给ArkTS侧。
鸿蒙HarmonyOS开发实战：网络组件API使用规范总结
最新发布
qazwsx957486的博客
08-27 256
该工具类提供统一简化各种请求方式,入参为json格式内部进行转换为所需对象
鸿蒙HarmonyOS应用开发之使用Node-API接口进行异步任务开发
maniuT的博客
03-27 1316
napi_create_async_work是Node-API接口之一，用于创建一个异步工作对象。可以在需要执行耗时操作的场景中使用，以避免阻塞主线程，确保应用程序的性能和响应性能。例如以下场景：文件操作：读取大型文件或执行复杂的文件操作时，可以使用异步工作对象来避免阻塞主线程。网络请求：当需要进行网络请求并等待响应时，使用异步工作对象可以确保主线程不被阻塞，从而提高应用程序的响应性能。
HarmonyOS非线性容器特性及使用场景
HarmonyOSDev的博客
09-28 247
集合中的key值的查找依赖于hash值以及二分查找算法，通过一个数组存储hash值，然后映射到其他数组中的key值以及value值，key的类型满足ECMA标准中要求的类型。TreeSet依据泛型定义，集合中的value值是有序的，TreeSet的底层是一棵二叉树，可以通过树的二叉查找快速的找到该value值，value的类型满足ECMA标准中要求的类型。TreeMap依据泛型定义，集合中的key值是有序的，TreeMap的底层是一棵二叉树，可以通过树的二叉查找快速的找到键值对。
鸿蒙 HarmonyOS应用开发之API：Context
maniuT的博客
03-26 1774
Context 是应用中对象的上下文，其提供了应用的一些基础信息，例如resourceManager（资源管理）、applicationInfo（当前应用信息）、dir（应用文件路径）、area（文件分区）等，以及应用的一些基本方法，例如createBundleContext()、getApplicationContext()等。UIAbility组件和各种ExtensionAbility派生类组件都有各自不同的Context类。
使用Taro开发鸿蒙原生应用.zip
12-16
在当前的数字化时代，华为推出的鸿蒙操作系统（HarmonyOS）为开发者提供了一个全新的平台，以构建跨设备、无缝协同的应用。Taro 是一个开源的前端框架，它允许开发者使用同一份代码库来构建多端应用，包括微信小程序...
华为鸿蒙Harmony开眼App开发实践：Api9+Stage模式应用
资源摘要信息:"华为鸿蒙Harmony开眼App是基于Api9+Stage模式、ArkTs以及ArkUI技术栈开发的鸿蒙应用。本文将详细介绍该应用的核心功能、开发技术及其在鸿蒙平台上的应用特点。 1. 常用组件的提取 在开发鸿蒙应用时，...
HarmonyOS/OpenHarmony应用开发
m0_68231587的博客
06-13 1348
其中，方舟JS运行时（Ark JS Runtime）是OpenHarmony上JavaScript应用使用的运行时，包含了JS对象的分配器以及垃圾回收器、符合ECMAScript规范的标准库、用于运行Ark前端组件生成的方舟字节码（Aark Bytecode）的解释器、用于存储隐藏类的内联缓存、对外的函数接口（AFFI）等模块。它提供了一系列模块化的组件和API，包括应用管理、模块管理、服务管理、数据管理等功能，开发者可以根据需求选择不同的组件和API，快速构建出高度模块化、可扩展的应用程序。
HarmonyOS 鸿蒙开发DevEco Studio OpenHarmony:通过命令行方式构建应用或服务
sybh的博客
01-21 853
除了使用DevEco Studio一键式构建OpenHarmony应用或原子化服务（简称应用或服务）外，还可以使用命令行工具来调用Hvigor任务进行构建。通过命令行的方式构建应用或服务，可用于构筑CI（Continuous Integration）持续集成流水线，按照计划时间自动化的构建HAP、APP、签名、安装部署等操作，降低开发者负担。
HarmonyOS开发文档（一）_鸿蒙学堂.pdf
09-12
华为鸿蒙操作系统学习资料，文章介绍了HarmonyOS的开发的知识，适合深入了解、学习鸿蒙系统开发者参考使用。
鸿蒙HarmonyOS应用开发之使用Node-API接口进行线程安全开发
maniuT的博客
03-27 999
napi_create_threadsafe_function是Node-API接口之一，用于创建一个线程安全的JavaScript函数。主要用于在多个线程之间共享和调用，而不会出现竞争条件或死锁。例如以下场景：异步计算：如果需要进行耗时的计算或IO操作，可以创建一个线程安全的函数，将计算或IO操作放在另一个线程中执行，避免阻塞主线程，提高程序的响应速度。数据共享：如果多个线程需要访问同一份数据，可以创建一个线程安全的函数，确保数据的读写操作不会发生竞争条件或死锁等问题。
鸿蒙APP开发实战：【Api9】拍照、拍视频；选择图片、视频、文件工具类
2301_76813281的博客
03-26 1940
鸿蒙是完全具备无与伦比的机遇和潜力的；预计到年底将有 5,000 款的应用完成原生鸿蒙开发，这么多的应用需要开发，也就意味着需要有更多的鸿蒙人才。鸿蒙开发工程师也将会迎来爆发式的增长，学习鸿蒙势在必行！
鸿蒙（API 12 Beta2版）NDK开发【JSVM-API使用规范】
鸿蒙的技术博客
08-02 793
**【规则】** 合理使用OH_JSVM_OpenHandleScope和OH_JSVM_CloseHandleScope管理JSVM_Value的生命周期，做到生命周期最小化，避免发生内存泄漏问题。
鸿蒙next开发-OpenHarmony的NDK开发
2301_76813281的博客
01-19 1839
Native API在SDK包的位置为$(SDK_ROOT)/native目录，主要有以下几个部分组成目录功能说明build应用中编译动态库的toolchain cmake脚本；这个目录下ohos.toolchain.cmake文件定义了给OHOS交叉编译选项放置编译构建的工具，如cmakedocsNative API接口参考文档，通过doxgen从头文件中提取出来llvm支持OHOS ABI的llvm交叉编译器sysroot放置编译链接的依赖文件目录，包含头文件，动态库等。
鸿蒙HarmonyOS应用开发之使用Node-API实现跨语言交互开发流程
1
03-27 1489
使用Node-API实现跨语言交互，首先需要按照Node-API的机制实现模块的注册和加载等相关动作。：实现C++方法的调用。代码比较简单，import一个对应的so库后，即可调用C++方法。：.cpp文件，实现模块的注册。需要提供注册lib库的名称，并在注册回调方法中定义接口的映射关系，即Native方法及对应的JS/ArkTS接口名称等。此处以在ArkTS/JS侧实现add()接口、在Native侧实现Add()接口，从而实现跨语言交互为例，呈现使用Node-API进行跨语言交互的流程。
鸿蒙系统 api,鸿蒙OS《Native API参考》
weixin_39693437的博客
05-28 1218
ImageOverviewProvides access to pixel data and pixel map information.Since:3Version:1.0SummaryFilesFile NameDescriptionimage_pixel_map.hDeclaresfunctionsforyoutolockandaccessorunlockpixelda...
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值