We use essential cookies for the website to function, as well as analytics cookies for analyzing and creating statistics of the website performance. To agree to the use of analytics cookies, click "Accept All". You can manage your preferences at any time by clicking "Cookie Settings" on the footer. More Information.

Cookie Settings
Only Essential Cookies
Accept All
MaterialsConsole

HarmonyOS

输入关键字搜索
HMS Core
AppGallery Connect
HUAWEI HiAI
CTRL+K

Wrapping a Native Object in a Sendable ArkTS Object

Last updated: 2026-09-08 08:15
Content overview

When to Use

You can call napi_wrap_sendable to bind an ArkTS Sendable object to a native C++ object. Then, call napi_unwrap_sendable to obtain the C++ object bound to the ArkTS object and perform operations on the C++ object.

Example

  1. Declare the APIs, configure compile settings, and register the module.

    Declare the APIs.

    Collapse
    Word wrap
    Dark theme
    Copy code
    1. // index.d.ets
    2. @Sendable
    3. export class MyObject {
    4.   constructor(arg: number);
    5.   plusOne(): number;
    6. 

    7.   public get value();
    8.   public set value(newVal: number);
    9. }

    Configure compile settings.

    Collapse
    Word wrap
    Dark theme
    Copy code
    1. # the minimum version of CMake.
    2. cmake_minimum_required(VERSION 3.5.0)
    3. project(napi_wrap_sendable_demo)
    4. 

    5. set(NATIVERENDER_ROOT_PATH ${CMAKE_CURRENT_SOURCE_DIR})
    6. 

    7. if(DEFINED PACKAGE_FIND_FILE)
    8.     include(${PACKAGE_FIND_FILE})
    9. endif()
    10. 

    11. include_directories(${NATIVERENDER_ROOT_PATH}
    12.                     ${NATIVERENDER_ROOT_PATH}/include)
    13. 

    14. add_definitions("-DLOG_DOMAIN=0x0000")
    15. add_definitions("-DLOG_TAG=\"testTag\"")
    16. 

    17. add_library(entry SHARED napi_init.cpp)
    18. target_link_libraries(entry PUBLIC libace_napi.z.so libhilog_ndk.z.so)

    Register the module.

    Collapse
    Word wrap
    Dark theme
    Copy code
    1. // napi_init.cpp
    2. #include "napi/native_api.h"
    3. #include "hilog/log.h"
    4. 

    5. // A native class. Its instance is wrapped in a Sendable ArkTS object.
    6. class MyObject {
    7. public:
    8.     static napi_value Init(napi_env env, napi_value exports);
    9.     static void Destructor(napi_env env, void *nativeObject, void *finalize_hint);
    10. 

    11. private:
    12.     explicit MyObject(double value_ = 0);
    13.     ~MyObject();
    14. 

    15.     static napi_value New(napi_env env, napi_callback_info info);
    16.     static napi_value GetValue(napi_env env, napi_callback_info info);
    17.     static napi_value SetValue(napi_env env, napi_callback_info info);
    18.     static napi_value PlusOne(napi_env env, napi_callback_info info);
    19. 

    20.     double value_;
    21.     napi_env env_;
    22. };
    23. 

    24. static thread_local napi_ref g_ref = nullptr;
    25. 

    26. MyObject::MyObject(double value) : value_(value), env_(nullptr) {}
    27. 

    28. MyObject::~MyObject() {}
    29. 

    30. void MyObject::Destructor(napi_env env, void *nativeObject, [[maybe_unused]] void *finalize_hint) {
    31.     OH_LOG_INFO(LOG_APP, "MyObject::Destructor called");
    32.     reinterpret_cast<MyObject *>(nativeObject)->~MyObject();
    33. }
    34. 

    35. napi_value MyObject::Init(napi_env env, napi_value exports) {
    36.     napi_value num = nullptr;
    37.     napi_status status = napi_create_double(env, 0, &num);
    38.     if (status != napi_ok) {
    39.         napi_throw_error(env, nullptr, "Node-API napi_create_double fail");
    40.         return nullptr;
    41.     }
    42.     napi_property_descriptor properties[] = {
    43.         {"value", nullptr, nullptr, GetValue, SetValue, nullptr, napi_default, nullptr},
    44.         {"plusOne", nullptr, PlusOne, nullptr, nullptr, nullptr, napi_default, nullptr},
    45.     };
    46. 

    47.     napi_value cons = nullptr;
    48.     // Define a Sendable class MyObject.
    49.     status = napi_define_sendable_class(env, "MyObject", NAPI_AUTO_LENGTH, New, nullptr,
    50.                             sizeof(properties) / sizeof(properties[0]), properties, nullptr, &cons);
    51.     if (status != napi_ok) {
    52.         napi_throw_error(env, nullptr, "Node-API napi_define_sendable_class fail");
    53.         return nullptr;
    54.     }
    55. 

    56.     status = napi_create_reference(env, cons, 1, &g_ref);
    57.     if (status != napi_ok) {
    58.         napi_throw_error(env, nullptr, "Node-API napi_create_reference fail");
    59.         return nullptr;
    60.     }
    61.     // Mount the MyObject class to the exports object.
    62.     status = napi_set_named_property(env, exports, "MyObject", cons);
    63.     if (status != napi_ok) {
    64.         napi_throw_error(env, nullptr, "Node-API napi_set_named_property fail");
    65.         return nullptr;
    66.     }
    67.     return exports;
    68. }
    69. 

    70. EXTERN_C_START
    71. // Initialize the module.
    72. static napi_value Init(napi_env env, napi_value exports) {
    73.     MyObject::Init(env, exports);
    74.     return exports;
    75. }
    76. EXTERN_C_END
    77. 

    78. // Information about the module. Record information such as the Init() function and module name.
    79. static napi_module nativeModule = {
    80.     .nm_version = 1,
    81.     .nm_flags = 0,
    82.     .nm_filename = nullptr,
    83.     .nm_register_func = Init,
    84.     .nm_modname = "entry",
    85.     .nm_priv = nullptr,
    86.     .reserved = {0},
    87. };
    88. 

    89. // When the .so file is loaded, this function is automatically called to register the nativeModule module with the system.
    90. extern "C" __attribute__((constructor)) void RegisterObjectWrapModule() { napi_module_register(&nativeModule); }

  2. Wrap a C++ object in a Sendable ArkTS object in a constructor.

    Collapse
    Word wrap
    Dark theme
    Copy code
    1. napi_value MyObject::New(napi_env env, napi_callback_info info) {
    2.     OH_LOG_INFO(LOG_APP, "MyObject::New called");
    3. 

    4.     napi_value newTarget = nullptr;
    5.     napi_status status = napi_get_new_target(env, info, &newTarget);
    6.     if (status != napi_ok) {
    7.         napi_throw_error(env, nullptr, "Node-API napi_get_new_target fail");
    8.         return nullptr;
    9.     }
    10.     if (newTarget != nullptr) {
    11.         // Invoked as the constructor `new MyObject(...)`.
    12.         size_t argc = 1;
    13.         napi_value args[1] = { nullptr };
    14.         napi_value jsThis = nullptr;
    15.         status = napi_get_cb_info(env, info, &argc, args, &jsThis, nullptr);
    16.         if (status != napi_ok) {
    17.             napi_throw_error(env, nullptr, "Node-API napi_get_cb_info fail");
    18.             return nullptr;
    19.         }
    20. 

    21.         double value = 0.0;
    22.         napi_valuetype valuetype = napi_undefined;
    23.         status = napi_typeof(env, args[0], &valuetype);
    24.         if (status != napi_ok) {
    25.             napi_throw_error(env, nullptr, "Node-API napi_typeof fail");
    26.             return nullptr;
    27.         }
    28.         if (valuetype != napi_undefined) {
    29.             status = napi_get_value_double(env, args[0], &value);
    30.             if (status != napi_ok) {
    31.                 napi_throw_error(env, nullptr, "Node-API napi_get_value_double fail");
    32.                 return nullptr;
    33.             }
    34.         }
    35. 

    36.         MyObject *obj = new MyObject(value);
    37. 

    38.         obj->env_ = env;
    39.         // Use napi_wrap_sendable to wrap obj (the C++ object) in jsThis (the Sendable ArkTS object).
    40.         status = napi_wrap_sendable(env, jsThis, reinterpret_cast<void *>(obj), MyObject::Destructor, nullptr);
    41.         if (status != napi_ok) {
    42.             napi_throw_error(env, nullptr, "Node-API napi_wrap_sendable fail");
    43.             delete obj;
    44.             return nullptr;
    45.         }
    46. 

    47.         return jsThis;
    48.     } else {
    49.         // Invoked as the plain function `MyObject(...)`.
    50.         size_t argc = 1;
    51.         napi_value args[1] = { nullptr };
    52.         status = napi_get_cb_info(env, info, &argc, args, nullptr, nullptr);
    53.         if (status != napi_ok) {
    54.             napi_throw_error(env, nullptr, "Node-API napi_get_cb_info fail");
    55.             return nullptr;
    56.         }
    57. 

    58.         napi_value cons = nullptr;
    59.         status = napi_get_reference_value(env, g_ref, &cons);
    60.         if (status != napi_ok) {
    61.             napi_throw_error(env, nullptr, "Node-API napi_get_reference_value fail");
    62.             return nullptr;
    63.         }
    64.         napi_value instance = nullptr;
    65.         status = napi_new_instance(env, cons, argc, args, &instance);
    66.         if (status != napi_ok) {
    67.             napi_throw_error(env, nullptr, "Node-API napi_new_instance fail");
    68.             return nullptr;
    69.         }
    70. 

    71.         return instance;
    72.     }
    73. }

  3. Retrieve the C++ object from the Sendable ArkTS object and perform subsequent operations on the C++ object.

    Collapse
    Word wrap
    Dark theme
    Copy code
    1. napi_value MyObject::GetValue(napi_env env, napi_callback_info info) {
    2.     OH_LOG_INFO(LOG_APP, "MyObject::GetValue called");
    3. 

    4.     napi_value jsThis = nullptr;
    5.     napi_status status = napi_get_cb_info(env, info, nullptr, nullptr, &jsThis, nullptr);
    6.     if (status != napi_ok) {
    7.         napi_throw_error(env, nullptr, "Node-API napi_get_cb_info fail");
    8.         return nullptr;
    9.     }
    10. 

    11.     MyObject *obj = nullptr;
    12.     // Use napi_unwrap_sendable to retrieve obj (the C++ object) previously wrapped in jsThis (the Sendable ArkTS object), and perform subsequent operations.
    13.     status = napi_unwrap_sendable(env, jsThis, reinterpret_cast<void **>(&obj));
    14.     if (status != napi_ok) {
    15.         napi_throw_error(env, nullptr, "Node-API napi_unwrap_sendable fail");
    16.         return nullptr;
    17.     }
    18.     napi_value num = nullptr;
    19.     status = napi_create_double(env, obj->value_, &num);
    20.     if (status != napi_ok) {
    21.         napi_throw_error(env, nullptr, "Node-API napi_create_double fail");
    22.         return nullptr;
    23.     }
    24. 

    25.     return num;
    26. }
    27. 

    28. napi_value MyObject::SetValue(napi_env env, napi_callback_info info) {
    29.     OH_LOG_INFO(LOG_APP, "MyObject::SetValue called");
    30. 

    31.     size_t argc = 1;
    32.     napi_value value = nullptr;
    33.     napi_value jsThis = nullptr;
    34. 

    35.     napi_status status = napi_get_cb_info(env, info, &argc, &value, &jsThis, nullptr);
    36.     if (status != napi_ok) {
    37.         napi_throw_error(env, nullptr, "Node-API napi_get_cb_info fail");
    38.         return nullptr;
    39.     }
    40. 

    41.     MyObject *obj = nullptr;
    42.     // Use napi_unwrap_sendable to retrieve obj (the C++ object) previously wrapped in jsThis (the Sendable ArkTS object), and perform subsequent operations.
    43.     status = napi_unwrap_sendable(env, jsThis, reinterpret_cast<void **>(&obj));
    44.     if (status != napi_ok) {
    45.         napi_throw_error(env, nullptr, "Node-API napi_unwrap_sendable fail");
    46.         return nullptr;
    47.     }
    48.     status = napi_get_value_double(env, value, &obj->value_);
    49.     if (status != napi_ok) {
    50.         napi_throw_error(env, nullptr, "Node-API napi_get_value_double fail");
    51.         return nullptr;
    52.     }
    53. 

    54.     return nullptr;
    55. }
    56. 

    57. napi_value MyObject::PlusOne(napi_env env, napi_callback_info info) {
    58.     OH_LOG_INFO(LOG_APP, "MyObject::PlusOne called");
    59. 

    60.     napi_value jsThis = nullptr;
    61.     napi_status status = napi_get_cb_info(env, info, nullptr, nullptr, &jsThis, nullptr);
    62.     if (status != napi_ok) {
    63.         napi_throw_error(env, nullptr, "Node-API napi_get_cb_info fail");
    64.         return nullptr;
    65.     }
    66. 

    67.     MyObject *obj = nullptr;
    68.     // Use napi_unwrap_sendable to retrieve obj (the C++ object) previously wrapped in jsThis (the Sendable ArkTS object), and perform subsequent operations.
    69.     status = napi_unwrap_sendable(env, jsThis, reinterpret_cast<void **>(&obj));
    70.     if (status != napi_ok) {
    71.         napi_throw_error(env, nullptr, "Node-API napi_unwrap_sendable fail");
    72.         return nullptr;
    73.     }
    74.     obj->value_ += 1;
    75.     napi_value num = nullptr;
    76.     status = napi_create_double(env, obj->value_, &num);
    77.     if (status != napi_ok) {
    78.         napi_throw_error(env, nullptr, "Node-API napi_create_double fail");
    79.         return nullptr;
    80.     }
    81. 

    82.     return num;
    83. }

  4. ArkTS code:

    Collapse
    Word wrap
    Dark theme
    Copy code
    1. import { hilog } from '@kit.PerformanceAnalysisKit';
    2. import { MyObject } from 'libentry.so';
    3. 

    4. try {
    5.     let object : MyObject = new MyObject(0);
    6.     object.value = 1023.1;
    7.     hilog.info(0x0000, 'testTag', 'MyObject value after set: %{public}s', object.value.toString());
    8.     hilog.info(0x0000, 'testTag', 'MyObject plusOne: %{public}s', object.plusOne().toString());
    9. } catch (error) {
    10.     hilog.error(0x0000, 'testTag', 'Test Node-API error: %{public}s', error.message);
    11. }
English
©2026 HUAWEI Developers. All rights reserved.
Terms of Use
Statement About HUAWEI Developers and Privacy
Cookies
Cookie Settings
Open-Source Software Notice
Search in Guides
Enter a keyword.