【鸿蒙开发案例篇】NAPI 实现 ArkTS 与 C++ 间的复杂对象传递

大家好，我是V哥。今天我们将深入探讨在鸿蒙 6.0（API 21）开发中，如何通过 NAPI 实现 ArkTS 与 C++ 间的复杂对象传递 ，包括结构体 和回调函数的跨语言交互。以下是完整实现方案，附详细代码和原理分析。

联系V哥获取 鸿蒙学习资料

---

一、技术架构与核心挑战

技术栈 ：
ArkTS 业务层 → NAPI 桥接层 → C++ 原生逻辑
核心挑战：

1. 结构体传递：ArkTS 对象 ↔ C++ 结构体双向转换
2. 回调函数：C++ 异步操作完成后触发 ArkTS 函数
3. 线程安全：确保跨线程调用不破坏 JS 运行时环境

---

二、案例实现：结构体与回调函数传递

场景描述

ArkTS 向 C++ 传递包含坐标信息的结构体 Point，C++ 计算两点距离后通过回调函数返回结果。

步骤 1：ArkTS 侧定义接口（index.d.ts）

// 定义结构体
export interface Point {
  x: number;
  y: number;
}

// 声明NAPI函数
export const calculateDistance: (
  p1: Point, 
  p2: Point, 
  callback: (result: number) => void
) => void;

步骤 2：C++ 侧实现结构体解析（distance.cpp）

#include <cmath>
#include <napi/native_api.h>

// 定义C++结构体
struct NativePoint {
  double x;
  double y;
};

// 解析ArkTS对象为C++结构体
NativePoint ParsePoint(napi_env env, napi_value obj) {
  NativePoint point;
  napi_value x_value, y_value;
  
  // 获取字段值
  napi_get_named_property(env, obj, "x", &x_value);
  napi_get_named_property(env, obj, "y", &y_value);
  
  // 类型转换
  napi_get_value_double(env, x_value, &point.x);
  napi_get_value_double(env, y_value, &point.y);
  return point;
}

// 计算距离并触发回调
napi_value CalculateDistance(napi_env env, napi_callback_info info) {
  size_t argc = 3;
  napi_value args;
  napi_get_cb_info(env, info, &argc, args, nullptr, nullptr);

  // 解析结构体参数
  NativePoint p1 = ParsePoint(env, args);
  NativePoint p2 = ParsePoint(env, args);
  
  // 计算距离
  double dx = p1.x - p2.x;
  double dy = p1.y - p2.y;
  double distance = sqrt(dx*dx + dy*dy);

  // 获取ArkTS回调函数
  napi_value callback = args;
  
  // 创建回调参数
  napi_value result;
  napi_create_double(env, distance, &result);
  
  // 执行回调（主线程安全）
  napi_value global;
  napi_get_global(env, &global);
  napi_call_function(env, global, callback, 1, &result, nullptr);
  
  return nullptr;
}

步骤 3：注册模块与错误处理

// 模块初始化
EXTERN_C_START
static napi_value Init(napi_env env, napi_value exports) {
  napi_property_descriptor desc = {
    "calculateDistance", nullptr, CalculateDistance, nullptr, nullptr, nullptr, napi_default, nullptr
  };
  napi_define_properties(env, exports, 1, &desc);
  return exports;
}
EXTERN_C_END

// 错误处理（关键！）
if (napi_get_named_property(env, obj, "x", &x_value) != napi_ok) {
  napi_throw_error(env, "INVALID_ARG", "Missing 'x' field in Point object");
  return {0, 0}; // 返回默认值
}

步骤 4：ArkTS 调用层（Index.ets）

import { calculateDistance, Point } from 'libdistance';

@Entry
@Component
struct GeometryDemo {
  @State result: number = 0;

  build() {
    Column() {
      Button("计算两点距离")
        .onClick(() => {
          const p1: Point = { x: 3, y: 4 };
          const p2: Point = { x: 0, y: 0 };
          
          // 传递结构体+回调函数
          calculateDistance(p1, p2, (res: number) => {
            this.result = res; // 回调结果更新UI
          });
        })
      Text(`距离: ${this.result.toFixed(2)}`)
    }
  }
}

---

三、关键技术解析

1. 结构体传递原理

操作	NAPI 接口	作用
获取对象属性	napi_get_named_property()	从ArkTS对象提取字段
类型转换	napi_get_value_double()	JS Number → C++ double
构建返回值	napi_create_object()	将C++结构体封装为ArkTS对象

2. 回调函数安全机制

• 线程限制 ：所有回调必须在主线程（JS线程）执行，否则报错 ecma_vm cannot run in multi-thread

• 生命周期管理 ：

  // 长期持有回调函数需使用引用
  napi_ref callback_ref;
  napi_create_reference(env, callback, 1, &callback_ref);
  
  // 执行时解引用
  napi_value callback_func;
  napi_get_reference_value(env, callback_ref, &callback_func);

• 异步场景 ：通过 napi_create_async_work 将耗时操作移至子线程，完成后在主线程触发回调

---

四、调试与避坑指南

1. 崩溃场景

   • 跨线程调用回调 ：在非主线程执行 napi_call_function 会导致崩溃
   • 解决方案 ：使用 uv_queue_work 或 napi_create_async_work 实现线程切换

2. 内存泄漏预防

   // 释放回调引用
   napi_delete_reference(env, callback_ref);

3. 日志追踪

   #include <hilog/log.h>
   OH_LOG_Print(LOG_APP, LOG_ERROR, 0, "NAPI", "回调执行失败");

---

五、扩展应用：ArkTS 接收 C++ 结构体 若需 C++ 返回结构体给 ArkTS：

// C++ 构建返回对象
napi_value CreatePoint(napi_env env, double x, double y) {
  napi_value obj, x_val, y_val;
  napi_create_object(env, &obj);
  napi_create_double(env, x, &x_val);
  napi_create_double(env, y, &y_val);
  napi_set_named_property(env, obj, "x", x_val);
  napi_set_named_property(env, obj, "y", y_val);
  return obj;
}

---

总结 实现复杂对象传递需掌握：

1. 结构体映射 ：通过 napi_get_named_property 实现字段级转换
2. 回调安全 ：严格限制回调执行在主线程，用 napi_ref 管理生命周期
3. 错误边界 ：对所有 NAPI 调用添加状态检查（napi_status）