• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# 使用Node-API接口关联数据，使其生命周期与当前环境的生命周期相关联
2<!--Kit: NDK-->
3<!--Subsystem: arkcompiler-->
4<!--Owner: @xliu-huanwei; @shilei123; @huanghello-->
5<!--Designer: @shilei123-->
6<!--Tester: @kirl75; @zsw_zhushiwei-->
7<!--Adviser: @fang-jinxu-->
8
9## 简介
10
11在Node-API模块中，可以使用Node-API接口将特定数据与当前环境相关联，并在需要时检索该数据。
12
13## 基本概念
14
15在Node-API中，关联数据指的是将自定义的C++数据结构与当前环境的生命周期绑定，这意味着只要当前运行环境存在，关联数据就会保持有效。
16
17## 场景和功能介绍
18
19以下接口可在Node-API模块中更方便地管理对象实例所需的状态信息、引用计数或其他自定义数据，他们的使用场景如下：
20| 接口 | 描述 |
21| -------- | -------- |
22| napi_set_instance_data | 绑定与当前运行的环境相关联的数据项。 |
23| napi_get_instance_data | 检索与当前运行的环境相关联的数据项。 |
24
25## 使用示例
26
27Node-API接口开发流程参考[使用Node-API实现跨语言交互开发流程](use-napi-process.md)，本文仅对接口对应C++及ArkTS相关代码进行展示。
28
29### napi_set_instance_data
30
31将需要绑定的数据与当前运行的环境相关联。
32
33cpp部分代码
34
35```cpp
36#include <cstdlib>
37#include "napi/native_api.h"
38
39// 定义一个结构来存储实例数据
40struct InstanceData {
41    int32_t value;
42};
43
44// 对象被释放时的回调函数，用于清理实例数据
45void FinalizeCallback(napi_env env, void *finalize_data, void *finalize_hint)
46{
47    if (finalize_data) {
48        InstanceData *data = reinterpret_cast<InstanceData *>(finalize_data);
49        // 释放内存，清除指针指向地址
50        delete (data);
51    }
52}
53
54static napi_value SetInstanceData(napi_env env, napi_callback_info info)
55{
56    size_t argc = 1;
57    napi_value argv[1];
58    napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
59    int32_t instanceDataValue;
60    napi_get_value_int32(env, argv[0], &instanceDataValue);
61    InstanceData *instanceData = new InstanceData;
62    instanceData->value = instanceDataValue;
63    // 调用napi_set_instance_data将实例数据关联到Node-API环境，并指定FinalizeCallback函数
64    napi_status status = napi_set_instance_data(env, instanceData, FinalizeCallback, nullptr);
65    bool success = true;
66    napi_value result = nullptr;
67    if (status == napi_ok) {
68        napi_get_boolean(env, success, &result);
69    }
70    return result;
71}
72```
73<!-- @[napi_set_instance_data](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/NodeAPI/NodeAPIUse/NodeAPIEnvironmentalLifeCycle/entry/src/main/cpp/napi_init.cpp) -->
74
75接口声明
76
77```ts
78// index.d.ts
79export const setInstanceData: (data: number) => boolean;
80```
81<!-- @[napi_set_instance_data_api](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/NodeAPI/NodeAPIUse/NodeAPIEnvironmentalLifeCycle/entry/src/main/cpp/types/libentry/Index.d.ts) -->
82
83ArkTS侧示例代码
84
85```ts
86import { hilog } from '@kit.PerformanceAnalysisKit';
87import testNapi from 'libentry.so';
88let data = 5;
89let value = testNapi.setInstanceData(data);
90hilog.info(0x0000, 'testTag', 'Test Node-API napi_set_instance_data:%{public}s', value);
91```
92<!-- @[ark_napi_set_instance_data](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/NodeAPI/NodeAPIUse/NodeAPIEnvironmentalLifeCycle/entry/src/main/ets/pages/Index.ets) -->
93
94### napi_get_instance_data
95
96检索与当前运行的环境相关联的数据项。
97
98cpp部分代码
99
100```cpp
101#include "napi/native_api.h"
102
103static napi_value GetInstanceData(napi_env env, napi_callback_info info) {
104    InstanceData *resData = nullptr;
105    // napi_get_instance_data获取之前想关联的数据项
106    napi_status status = napi_get_instance_data(env, (void **)&resData);
107    if (status != napi_ok) {
108        return nullptr;
109    }
110    napi_value result;
111    napi_create_int32(env, resData->value, &result);
112    return result;
113}
114```
115<!-- @[napi_get_instance_data](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/NodeAPI/NodeAPIUse/NodeAPIEnvironmentalLifeCycle/entry/src/main/cpp/napi_init.cpp) -->
116
117接口声明
118
119```ts
120// index.d.ts
121export const getInstanceData: () => number | undefined;
122```
123<!-- @[napi_get_instance_data_api](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/NodeAPI/NodeAPIUse/NodeAPIEnvironmentalLifeCycle/entry/src/main/cpp/types/libentry/Index.d.ts) -->
124
125ArkTS侧示例代码
126
127```ts
128import { hilog } from '@kit.PerformanceAnalysisKit';
129import testNapi from 'libentry.so';
130let data = 5;
131testNapi.setInstanceData(data);
132let value = testNapi.getInstanceData();
133hilog.info(0x0000, 'testTag', 'Test Node-API napi_set_instance_data:%{public}d', value);
134```
135<!-- @[ark_napi_get_instance_data](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/NodeAPI/NodeAPIUse/NodeAPIEnvironmentalLifeCycle/entry/src/main/ets/pages/Index.ets) -->
136
137以上代码如果要在native cpp中打印日志，需在CMakeLists.txt文件中添加以下配置信息（并添加头文件：#include "hilog/log.h"）：
138
139```text
140// CMakeLists.txt
141add_definitions( "-DLOG_DOMAIN=0xd0d0" )
142add_definitions( "-DLOG_TAG=\"testTag\"" )
143target_link_libraries(entry PUBLIC libace_napi.z.so libhilog_ndk.z.so)
144```
145