鸿蒙 NDK开发：Node-API创建和获取String值（九）

NDK开发中，字符串交互是跨语言通信的基础。Node-API提供了8个用于string值的创建和获取的接口，支持UTF-8、UTF-16、Latin-1、ASCII等多种编码。

一、字符串编码

二、核心接口

三、使用示例

3.1 napi_get_value_string_utf8

将ArkTS的字符类型数据转换为UTF-8编码的字符。

static napi_value GetValueStringUtf8(napi_env env, napi_callback_info info) { size_t argc = 1; napi_value args[1] = {nullptr}; napi_get_cb_info(env, info, &argc, args, nullptr, nullptr); // 获取字符串长度 size_t length = 0; napi_status status = napi_get_value_string_utf8(env, args[0], nullptr, 0, &length); if (status != napi_ok) { OH_LOG_ERROR(LOG_APP, "napi_get_value_string_utf8 failed"); return nullptr; } // 分配缓冲区并获取字符串内容 char *buf = new char[length + 1]; std::memset(buf, 0, length + 1); status = napi_get_value_string_utf8(env, args[0], buf, length + 1, &length); // 创建ArkTS字符串返回 napi_value result = nullptr; status = napi_create_string_utf8(env, buf, length, &result); delete[] buf; return result; }

接口声明（index.d.ts）：

export const getValueStringUtf8: (param: string | number) => string | undefined;

ArkTS调用：

hilog.info(0x0000, 'testTag', 'Result: %{public}s', testNapi.getValueStringUtf8('aaBC+-$%^你好123'));

3.2 napi_create_string_utf8

通过UTF-8编码的C字符串创建ArkTS string值。

static napi_value CreateStringUtf8(napi_env env, napi_callback_info info) { const char *str = u8"你好, World!, successes to create UTF-8 string! 111"; size_t length = strlen(str); napi_value result = nullptr; napi_status status = napi_create_string_utf8(env, str, length, &result); if (status != napi_ok) { napi_throw_error(env, nullptr, "Failed to create UTF-8 string"); return nullptr; } return result; }

ArkTS调用：

hilog.info(0x0000, 'testTag', 'napi_create_string_utf8:%{public}s', testNapi.createStringUtf8());

3.3 napi_get_value_string_utf16

将ArkTS字符串转换为UTF-16编码的字符。

static napi_value GetValueStringUtf16(napi_env env, napi_callback_info info) { size_t argc = 1; napi_value args[1]; napi_get_cb_info(env, info, &argc, args, nullptr, nullptr); char16_t buffer[MAX_BUFFER_SIZE]; size_t bufferSize = MAX_BUFFER_SIZE; size_t stringLen; napi_get_value_string_utf16(env, args[0], buffer, bufferSize, &stringLen); napi_value result = nullptr; napi_create_string_utf16(env, buffer, stringLen, &result); return result; }

ArkTS调用：

let result = testNapi.getValueStringUtf16('hello,'); hilog.info(0x0000, 'testTag', 'napi_get_value_string_utf16:%{public}s', result);

3.4 napi_create_string_utf16

创建一个UTF-16编码的ArkTS字符串。

static napi_value CreateStringUtf16(napi_env env, napi_callback_info info) { const char16_t *str = u"你好, World!, successes to create UTF-16 string! 111"; size_t length = NAPI_AUTO_LENGTH; napi_value result = nullptr; napi_status status = napi_create_string_utf16(env, str, length, &result); if (status != napi_ok) { napi_throw_error(env, nullptr, "Failed to create UTF-16 string"); return nullptr; } return result; }

3.5 napi_get_value_string_latin1

将ArkTS字符串转换为ISO-8859-1编码。

static napi_value GetValueStringLatin1(napi_env env, napi_callback_info info) { size_t argc = 1; napi_value args[1] = {nullptr}; napi_get_cb_info(env, info, &argc, args, nullptr, nullptr); char buf[MAX_BUFFER_SIZE]; size_t length = 0; napi_value napi_Res = nullptr; napi_status status = napi_get_value_string_latin1(env, args[0], buf, MAX_BUFFER_SIZE, &length); if (status != napi_ok) { return nullptr; } napi_create_string_latin1(env, buf, length, &napi_Res); return napi_Res; }

注意：ISO-8859-1编码不支持中文，传入中文字符会乱码。

3.6 napi_create_external_string_utf16（API 22+）

通过外部UTF-16编码的字符串缓冲区创建ArkTS字符串值，避免内存拷贝。

// 定义析构回调函数，在GC时释放外部资源 static void StringFinalizerUTF16(void* data, void* hint) { delete[] static_cast<char16_t*>(data); } static napi_value CreateExternalStringUtf16(napi_env env, napi_callback_info info) { const char16_t source[] = u"你好, World!, successes to create UTF-16 string! 111"; int char16tLength = sizeof(source) / sizeof(char16_t); char16_t* str = new char16_t[char16tLength]; std::copy(source, source + char16tLength, str); napi_value result = nullptr; napi_status status = napi_create_external_string_utf16( env, str, NAPI_AUTO_LENGTH, StringFinalizerUTF16, // GC时回调释放str nullptr, &result ); if (status != napi_ok) { delete[] str; napi_throw_error(env, nullptr, "Failed to create utf16 string"); return nullptr; } return result; }

工作原理：外部字符串受GC管理，当ArkTS string生命周期结束被GC回收时，会触发StringFinalizerUTF16函数释放Native侧资源。

3.7 napi_create_external_string_ascii（API 22+）

通过外部ASCII编码的字符串缓冲区创建ArkTS字符串值，避免内存拷贝。

static void StringFinalizerASCII(void* data, void* hint) { delete[] static_cast<char*>(data); } static napi_value CreateExternalStringAscii(napi_env env, napi_callback_info info) { const char source[] = "hello, World!, successes to create ASCII string! 111"; int charLength = sizeof(source) / sizeof(char); char* str = new char[charLength]; std::copy(source, source + charLength, str); napi_value result = nullptr; napi_status status = napi_create_external_string_ascii( env, str, NAPI_AUTO_LENGTH, StringFinalizerASCII, nullptr, &result ); if (status != napi_ok) { delete[] str; napi_throw_error(env, nullptr, "Failed to create ascii string"); return nullptr; } return result; }

重要：

• str指向的内存必须在ArkTS string对象的整个生命周期内保持有效

• 调用接口后，str指向的内存内容必须保持不可变

• 任何对该内存的写入操作都可能导致程序崩溃

四、CMakeLists.txt配置

如需在Native C++中打印日志：

add_definitions( "-DLOG_DOMAIN=0xd0d0" ) add_definitions( "-DLOG_TAG=\"testTag\"" ) target_link_libraries(entry PUBLIC libace_napi.z.so libhilog_ndk.z.so)

添加头文件：#include "hilog/log.h"

五、8个string接口

5.2 使用建议

5.3 注意事项