HarmonyOS

CTRL+K
GuidesNDK DevelopmentCode DevelopmentUsing Node-API for ArkTS/JS and C/C++ Language InteractionNode-API GuidesWorking with Primitives Using Node-API

Working with Primitives Using Node-API

Last updated: 2026-09-04 06:52
Content overview
Expand

Introduction

Node-API provides APIs for converting data between C/C++ and ArkTS data types and obtaining the ArkTS objects in specified format.

Basic Concepts

Before using Node-API to operate ArkTS objects, you need to understand the following basic concepts:

  • Conversion between ArkTS and C/C primitives: You can use Node-API to convert ArkTS values to C/C++ data types, for example, convert an ArkTS value into a C/C++ integer and convert an ArkTS string into a C/C++ string array. You can also convert C/C++ data into an ArkTS value and return the ArkTS value to ArkTS.

Available APIs

The following table lists the APIs for converting data between ArkTS and C/C++ types.

Expand
API Description
napi_coerce_to_bool Forcibly converts an ArkTS value to an ArkTS Boolean value.
napi_coerce_to_number Forcibly converts an ArkTS value to an ArkTS number.
napi_coerce_to_object Forcibly converts an ArkTS value to an ArkTS object.
napi_coerce_to_string Forcibly converts an ArkTS value to an ArkTS string.
napi_get_boolean Obtains the ArkTS Boolean value based on the given C Boolean value.
napi_get_value_bool Obtains the C/C++ equivalent of the given ArkTS Boolean value.
napi_get_global Obtains an ArkTS global object so that it can be accessed and manipulated in C/C++.
napi_get_null Obtains the ArkTS null.
napi_get_undefined Obtains the ArkTS undefined.

Example

If you are just starting out with Node-API, see Node-API Development Process. The following demonstrates only the C++ and ArkTS code involved in related APIs.

napi_coerce_to_bool

Call napi_coerce_to_bool to forcibly convert an ArkTS value to an ArkTS Boolean value.

CPP code:

Collapse
Word wrap
Dark theme
Copy code
  1. // napi_coerce_to_bool
  2. static napi_value CoerceToBool(napi_env env, napi_callback_info info)
  3. {
  4.     // Get and parse the passed parameters.
  5.     size_t argc = 1;
  6.     napi_value args[1] = {nullptr};
  7.     napi_get_cb_info(env, info, &argc, args, nullptr, nullptr);
  8.     // Convert the passed value to a boolean value.
  9.     napi_value result = nullptr;
  10.     napi_coerce_to_bool(env, args[0], &result);
  11.     // Return the ArkTS boolean value after casting.
  12.     return result;
  13. }
napi_init.cpp

API declaration:

Collapse
Word wrap
Dark theme
Copy code
  1. export const coerceToBool: <T>(data: T) => boolean; // napi_coerce_to_bool
Index.d.ts

ArkTS code:

Collapse
Word wrap
Dark theme
Copy code
  1. // napi_coerce_to_bool
  2. let value = testNapi.coerceToBool<number>(0);
  3. let str = testNapi.coerceToBool<string>('111111111');
  4. let obj = new Object();
  5. let res = testNapi.coerceToBool<Object>(obj);
  6. let result = testNapi.coerceToBool<null>(null);
  7. // false
  8. hilog.info(0x0000, 'testTag', 'Test Node-API napi_coerce_to_bool:%{public}s', value);
  9. // true
  10. hilog.info(0x0000, 'testTag', 'Test Node-API napi_coerce_to_bool:%{public}s', str);
  11. // true
  12. hilog.info(0x0000, 'testTag', 'Test Node-API napi_coerce_to_bool:%{public}s', res);
  13. // false
  14. hilog.info(0x0000, 'testTag', 'Test Node-API napi_coerce_to_bool:%{public}s', result);
Index.ets

napi_coerce_to_number

Call napi_coerce_to_number to forcibly convert an ArkTS value to an ArkTS number.

CPP code:

Collapse
Word wrap
Dark theme
Copy code
  1. // napi_coerce_to_number
  2. static napi_value CoerceToNumber(napi_env env, napi_callback_info info)
  3. {
  4.     // Get and parse the passed parameters.
  5.     size_t argc = 1;
  6.     napi_value args[1] = {nullptr};
  7.     napi_get_cb_info(env, info, &argc, args, nullptr, nullptr);
  8.     // Convert the passed value to a number value.
  9.     napi_value result = nullptr;
  10.     napi_coerce_to_number(env, args[0], &result);
  11.     return result;
  12. }
napi_init.cpp

API declaration:

Collapse
Word wrap
Dark theme
Copy code
  1. export const coerceToNumber: <T>(data: T) => number; // napi_coerce_to_number
Index.d.ts

ArkTS code:

Collapse
Word wrap
Dark theme
Copy code
  1. // napi_coerce_to_number
  2. let value = testNapi.coerceToNumber<string>('2556');
  3. let str = testNapi.coerceToNumber<string>('sssss');
  4. let bool = testNapi.coerceToNumber<boolean>(true);
  5. hilog.info(0x0000, 'testTag', 'Test Node-API napi_coerce_to_number:%{public}d', value);
  6. // The returned value is NaN.
  7. hilog.info(0x0000, 'testTag', 'Test Node-API napi_coerce_to_number:%{public}d', str);
  8. // The returned value is 1.
  9. hilog.info(0x0000, 'testTag', 'Test Node-API napi_coerce_to_number:%{public}d', bool);
Index.ets

napi_coerce_to_object

Call napi_coerce_to_object to forcibly convert an ArkTS value to an ArkTS object.

CPP code:

Collapse
Word wrap
Dark theme
Copy code
  1. // napi_coerce_to_object
  2. static napi_value CoerceToObject(napi_env env, napi_callback_info info)
  3. {
  4.     // Get and parse the passed parameters.
  5.     size_t argc = 1;
  6.     napi_value args[1] = {nullptr};
  7.     napi_value obj = nullptr;
  8.     napi_get_cb_info(env, info, &argc, args, nullptr, nullptr);
  9.     // Convert the passed value to an Object value.
  10.     napi_coerce_to_object(env, args[0], &obj);
  11.     return obj;
  12. }
napi_init.cpp

API declaration:

Collapse
Word wrap
Dark theme
Copy code
  1. export const coerceToObject: <T>(data: T) => Object; // napi_coerce_to_object
Index.d.ts

ArkTS code:

Collapse
Word wrap
Dark theme
Copy code
  1. // napi_coerce_to_object
  2. let value = testNapi.coerceToObject<string>('222222');
  3. let result = testNapi.coerceToObject<number>(111);
  4. hilog.info(0x0000, 'testTag', 'Node-API coerceToObject:%{public}s.', typeof result);
  5. if (typeof value === 'object') {
  6.   hilog.info(0x0000, 'testTag', 'Node-API The value is an object.');
  7. } else {
  8.   hilog.info(0x0000, 'testTag', 'Node-API The value is not an object.');
  9. }
Index.ets

napi_coerce_to_string

Call napi_coerce_to_string to forcibly convert an ArkTS value to an ArkTS string.

CPP code:

Collapse
Word wrap
Dark theme
Copy code
  1. // napi_coerce_to_string
  2. static napi_value CoerceToString(napi_env env, napi_callback_info info)
  3. {
  4.     // Get and parse the passed parameters.
  5.     size_t argc = 1;
  6.     napi_value args[1] = {nullptr};
  7.     napi_get_cb_info(env, info, &argc, args, nullptr, nullptr);
  8.     // Convert the passed value to a string.
  9.     napi_value str = nullptr;
  10.     napi_coerce_to_string(env, args[0], &str);
  11.     return str;
  12. }
napi_init.cpp

API declaration:

Collapse
Word wrap
Dark theme
Copy code
  1. export const coerceToString: <T>(data: T) => string; // napi_coerce_to_string
Index.d.ts

ArkTS code:

Collapse
Word wrap
Dark theme
Copy code
  1. // napi_coerce_to_string
  2. let value = testNapi.coerceToString<number>(212);
  3. let obj = new Object();
  4. let res = testNapi.coerceToString<Object>(obj);
  5. let bool = testNapi.coerceToString<boolean>(false);
  6. hilog.info(0x0000, 'testTag', 'Test Node-API napi_coerce_to_string:%{public}s', value);
  7. hilog.info(0x0000, 'testTag', 'Test Node-API napi_coerce_to_string:%{public}s', typeof res);
  8. hilog.info(0x0000, 'testTag', 'Test Node-API napi_coerce_to_string:%{public}s', bool);
Index.ets

napi_get_boolean

Call napi_get_boolean to obtain the ArkTS Boolean value based on the given C Boolean value.

CPP code:

Collapse
Word wrap
Dark theme
Copy code
  1. // napi_get_boolean
  2. static napi_value GetBoolean(napi_env env, napi_callback_info info)
  3. {
  4.     // Pass and parse two parameters.
  5.     size_t argc = 2;
  6.     napi_value argv[2];
  7.     napi_valuetype data = napi_undefined;
  8.     napi_valuetype value = napi_undefined;
  9.     napi_status status = napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
  10.     if (status != napi_ok) {
  11.         OH_LOG_ERROR(LOG_APP, "napi_get_cb_info failed");
  12.         return nullptr;
  13.     }
  14.     // Determine the type values of the two parameters.
  15.     napi_typeof(env, argv[0], &data);
  16.     napi_typeof(env, argv[1], &value);
  17. 

  18.     napi_value returnValue = nullptr;
  19.     // Determine whether the two type values are equal, and obtain the boolean value of the result.
  20.     status = napi_get_boolean(env, data == value, &returnValue);
  21.     if (status != napi_ok) {
  22.         OH_LOG_ERROR(LOG_APP, "napi_get_boolean failed");
  23.         return nullptr;
  24.     }
  25.     // Return the result.
  26.     return returnValue;
  27. }
napi_init.cpp

API declaration:

Collapse
Word wrap
Dark theme
Copy code
  1. export const getBoolean: <T>(data: T, value: String) => boolean; // napi_get_boolean
Index.d.ts

ArkTS code:

Collapse
Word wrap
Dark theme
Copy code
  1. // napi_get_boolean
  2. let value = testNapi.getBoolean<number>(1, '1');
  3. let data = testNapi.getBoolean<string>('sss', '1');
  4. hilog.info(0x0000, 'testTag', 'Test Node-API napi_get_boolean:%{public}s', value);
  5. hilog.info(0x0000, 'testTag', 'Test Node-API napi_get_boolean:%{public}s', data);
Index.ets

napi_get_value_bool

Call napi_get_value_bool to obtain the C Boolean equivalent of an ArkTS Boolean value.

CPP code:

Collapse
Word wrap
Dark theme
Copy code
  1. // napi_get_value_bool
  2. static napi_value GetValueBool(napi_env env, napi_callback_info info)
  3. {
  4.     size_t argc = 1;
  5.     napi_value args[1] = {nullptr};
  6. 

  7.     napi_get_cb_info(env, info, &argc, args, nullptr, nullptr);
  8.     bool boolC = false;
  9.     napi_status status = napi_get_value_bool(env, args[0], &boolC);
  10.     if (status == napi_boolean_expected) {
  11.         // If napi_get_value_bool succeeds, napi_ok is returned. If a non-boolean value is passed, napi_boolean_expected is returned.
  12.         return nullptr;
  13.     }
  14.     napi_value boolNapi = nullptr;
  15.     status = napi_get_boolean(env, boolC, &boolNapi);
  16.     if (status != napi_ok) {
  17.         OH_LOG_ERROR(LOG_APP, "napi_get_boolean failed");
  18.         return nullptr;
  19.     }
  20.     return boolNapi;
  21. }
napi_init.cpp

API declaration:

Collapse
Word wrap
Dark theme
Copy code
  1. export const getValueBool: (value: boolean | string) => boolean | undefined; // napi_get_value_bool
Index.d.ts

ArkTS code:

Collapse
Word wrap
Dark theme
Copy code
  1. // napi_get_value_bool
  2. // Pass a boolean value and a non-boolean value to test the API. Passing a boolean value returns the original boolean value, and passing other types returns undefined.
  3. hilog.info(0x0000, 'Node-API', 'get_value_bool_not_bool %{public}s',
  4.   testNapi.getValueBool('Hello123'));
  5. hilog.info(0x0000, 'Node-API', 'get_value_bool_true %{public}s', testNapi.getValueBool(true));
  6. hilog.info(0x0000, 'Node-API', 'get_value_bool_false %{public}s', testNapi.getValueBool(false));
Index.ets

napi_get_global

Call napi_get_global to obtain an ArkTS global object. You can use this API to obtain the napi_value that represents an ArkTS global object, so that the global object of the ArkTS runtime can be called by C/C++.

CPP code:

Collapse
Word wrap
Dark theme
Copy code
  1. // napi_get_global
  2. static napi_value GetGlobal(napi_env env, napi_callback_info info)
  3. {
  4.     napi_value global = nullptr;
  5.     // Obtain the global object.
  6.     napi_get_global(env, &global);
  7.     return global;
  8. }
napi_init.cpp

API declaration:

Collapse
Word wrap
Dark theme
Copy code
  1. export const getGlobal: () => Object; // napi_get_global
Index.d.ts

ArkTS code:

Collapse
Word wrap
Dark theme
Copy code
  1. // napi_get_global
  2. let globalObj = testNapi.getGlobal();
  3. // Determine whether the obtained global object has its own properties.
  4. hilog.info(0x0000, 'testTag', 'Test Node-API napi_get_global:%{public}s',
  5.   globalObj.hasOwnProperty!("undefined"));
Index.ets

napi_get_null

Call napi_get_null to obtain null in ArkTS.

CPP code:

Collapse
Word wrap
Dark theme
Copy code
  1. // napi_get_null
  2. static napi_value GetNull(napi_env env, napi_callback_info info)
  3. {
  4.     napi_value nullValue = nullptr;
  5.     napi_get_null(env, &nullValue);
  6.     return nullValue;
  7. }
napi_init.cpp

API declaration:

Collapse
Word wrap
Dark theme
Copy code
  1. export const getNull: () => null; // napi_get_null
Index.d.ts

ArkTS code:

Collapse
Word wrap
Dark theme
Copy code
  1. // napi_get_null
  2. let value = testNapi.getNull();
  3. hilog.info(0x0000, 'testTag', 'Test Node-API napi_get_null:%{public}s', value);
Index.ets

napi_get_undefined

Call napi_get_undefined to obtain undefined in ArkTS.

CPP code:

Collapse
Word wrap
Dark theme
Copy code
  1. // napi_get_undefined
  2. static napi_value GetUndefined(napi_env env, napi_callback_info info)
  3. {
  4.     // Get and parse the passed parameters.
  5.     size_t argc = 1;
  6.     napi_value args[1] = {nullptr};
  7.     napi_get_cb_info(env, info, &argc, args, nullptr, nullptr);
  8. 

  9.     napi_value value = nullptr;
  10.     napi_get_undefined(env, &value);
  11.     // Determine whether the type of the passed parameter is consistent with the type of the undefined value.
  12.     bool isEqual = false;
  13.     napi_strict_equals(env, args[0], value, &isEqual);
  14.     // The parameter is equal to the undefined value.
  15.     napi_value result = nullptr;
  16.     // Return the result after type determination. Returns true if equal, and false if not.
  17.     napi_get_boolean(env, isEqual, &result);
  18.     return result;
  19. }
napi_init.cpp

API declaration:

Collapse
Word wrap
Dark theme
Copy code
  1. export const getUndefined: (value: undefined) => boolean; // napi_get_undefined
Index.d.ts

ArkTS code:

Collapse
Word wrap
Dark theme
Copy code
  1. // napi_get_undefined
  2. let data: undefined = undefined;
  3. let value = testNapi.getUndefined(data);
  4. hilog.info(0x0000, 'testTag', 'Test Node-API napi_get_undefined:%{public}s', value);
Index.ets

To print logs in the native CPP, add the following information to the CMakeLists.txt file and add the header file by using #include "hilog/log.h".

Collapse
Word wrap
Dark theme
Copy code
  1. // CMakeLists.txt
  2. add_definitions( "-DLOG_DOMAIN=0xd0d0" )
  3. add_definitions( "-DLOG_TAG=\"testTag\"" )
  4. target_link_libraries(entry PUBLIC libace_napi.z.so libhilog_ndk.z.so)
Working with Other Node-API Utilities
Implementing Asynchronous Operations Using Node-API
English