鸿蒙OS开发实例：【Native C++】

介绍

本篇Codelab主要介绍如何使用DevEco Studio创建一个Native C++应用。应用采用Native C++模板，实现使用NAPI调用C标准库的功能。使用C标准库hypot接口计算两个给定数平方和的平方根。在输入框中输入两个数字，点击计算结果按钮显示计算后的数值。

相关概念

• [Native API]：NAPI提供的接口名与三方Node.js一致，目前支持部分接口。
• [Native API中支持的标准库]：目前支持标准C库、C++库、OpenSL ES、zlib。

环境搭建

软件要求

• [DevEco Studio]版本：DevEco Studio 3.1 Release。
• OpenHarmony SDK版本：API version 9。
• 鸿蒙文档参考：[gitee.com/li-shizhen-skin/harmony-os/blob/master/README.md]

硬件要求

• 开发板类型：[润和RK3568开发板]。
• OpenHarmony系统：3.2 Release。
• 鸿蒙NEXT学习文档紫料可mau123789添加v直接领

环境搭建

完成本篇Codelab我们首先要完成开发环境的搭建，本示例以RK3568开发板为例，参照以下步骤进行：

1. [获取OpenHarmony系统版本]：标准系统解决方案（二进制）。以3.2 Release版本为例：
   
2. 搭建烧录环境。
   1. [完成DevEco Device Tool的安装]
   2. [完成RK3568开发板的烧录]
3. 搭建开发环境。
   1. 开始前请参考[工具准备]，完成DevEco Studio的安装和开发环境配置。
   2. 开发环境配置完成后，请参考[使用工程向导]创建工程（模板选择“Empty Ability”）。
   3. 工程创建完成后，选择使用[真机进行调测]。

代码结构解读

本篇Codelab只对核心代码进行讲解，对于完整代码，我们会在gitee中提供。

使用Native C++模板创建项目会自动生成cpp文件夹、types文件夹、CMakeList.txt文件，开发者可以根据实际情况自行添加修改其他文件及文件夹。

├──entry/src/main
│  ├──common
│  │  └──CommonContants.ets               // 常量定义文件
│  ├──cpp                                 // C++代码区
│  │  ├──CMakeLists.txt                   // CMake编译配置文件
│  │  ├──hello.cpp                        // C++源代码
│  │  └──types                            // 接口存放文件夹
│  │     └──libhello
│  │        ├──index.d.ts                 // 接口文件
│  │        └──oh-package.json5           // 接口注册配置文件
│  └──ets                                 // 代码区
│     ├──entryability
│     │  └──EntryAbility.ts               // 程序入口类
│     └──pages
│        └──Index.ets                     // 主界面
└──entry/src/main/resources               // 资源文件目录

架构组成

应用架构

应用架构可以分为三部分：C++、ArkTS、工具链。

• C++：包含各种文件的引用、C++或者C代码、Native项目必需的配置文件等。
• ArkTS：包含界面UI、自身方法、调用引用包的方法等。
• 工具链：包含CMake编译工具在内的系列工具。

使用ArkTS调用C++方法的过程中，需要使用到NAPI、CMake等工具来做中间转换，整个架构及其关联关系参考示意图。

示意图中，hello.cpp文件实现C++方法，并通过NAPI将C++方法与ArkTS方法关联。

C++代码通过CMake编译工具编译成动态链接库so文件，使用index.d.ts文件对外提供接口。ArkTS引入so文件后调用其中的接口。

编译架构

ArkTS与C++方法的调用、编译流程参考示意图。图中C++代码通过CMake编译生成so文件后可以直接被ArkTS侧引入，最终通过hvigor编译成可执行的hap包。

Native项目开发流程

Native侧操作详解

1. 配置模块描述信息，设置Init方法为napi_module的入口方法。 attribute ((constructor))修饰的方法由系统自动调用，使用NAPI接口napi_module_register()传入模块描述信息进行模块注册。Native C++模板创建项目会自动生成此结代码，开发者可根据实际情况修改其中内容。

   // hello.cpp
   static napi_module demoModule = {
       nm_version = 1,
       nm_flags = 0,
       nm_filename = nullptr,
       nm_register_func = Init,         // napi_module入口方法
       nm_modname = "hello",            // napi_module模块名
       nm_priv = ((void *)0),
       reserved = { 0 }
   };
   
   extern "C" __attribute__((constructor)) void RegisterModule(void) {
       napi_module_register(&demoModule);
   }
   

2. Init方法为Native C++模板生成的结构，开发者可根据实际情况修改其中内容。在napi_property_descriptor desc[]中，我们需要将编写的MyHypot方法与对外提供的接口myHypot接口进行关联，其他参数使用示例默认值填写。使用NAPI接口napi_define_properties构建包含方法对应列表的返回值。

   // hello.cpp
   static napi_value Init(napi_env env, napi_value exports)
   {
       if ((nullptr == env) || (nullptr == exports)) {
           OH_LOG_Print(LOG_APP, LOG_ERROR, LOG_PRINT_DOMAIN, "Init", "env or exports is null");
           return exports;
       }
   
       napi_property_descriptor desc[] = {
           { "myHypot", nullptr, MyHypot, nullptr, nullptr, nullptr, napi_default, nullptr }
       };
       if (napi_ok != napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc)) {
           OH_LOG_Print(LOG_APP, LOG_ERROR, LOG_PRINT_DOMAIN, "Init", "napi_define_properties failed");
           return nullptr;
       }
       return exports;
   }
   

3. 本例中使用C标准库的hypot方法进行计算。引入C标准库头文件math.h，使用double类型解析传入的参数后，调用C标准库方法hypot计算两数平方的和后计算平方根。使用NAPI接口napi_create_double将结果转化为napi_value类型的变量并返回。

   // hello.cpp
   #include < hilog/log.h >
   #include "napi/native_api.h"
   #include "math.h"
   
   static napi_value MyHypot(napi_env env, napi_callback_info info)
   {
       if ((nullptr == env) || (nullptr == info)) {
           OH_LOG_Print(LOG_APP, LOG_ERROR, LOG_PRINT_DOMAIN, "MyHypot", "env or exports is null");
           return nullptr;
       }
   
       // 参数数量
       size_t argc = PARAMETER_COUNT;
   
       // 定义参数数组
       napi_value args[PARAMETER_COUNT] = { nullptr };
   
       // 获取传入的参数并放入参数数组中
       if (napi_ok != napi_get_cb_info(env, info, &argc, args, nullptr, nullptr)) {
           OH_LOG_Print(LOG_APP, LOG_ERROR, LOG_PRINT_DOMAIN, "MyHypot", "api_get_cb_info failed");
           return nullptr;
       }
   
       // 将传入的参数转化为double类型
       double valueX = 0.0;
       double valueY = 0.0;
       if (napi_ok != napi_get_value_double(env, args[0], &valueX) ||
           napi_ok != napi_get_value_double(env, args[1], &valueY)) {
           OH_LOG_Print(LOG_APP, LOG_ERROR, LOG_PRINT_DOMAIN, "MyHypot", "napi_get_value_double failed");
           return nullptr;
       }
   
       // 调用C标准库的hypot接口进行计算
       double result = hypot(valueX, valueY);
   
       // 创建返回结果并返回
       napi_value napiResult;
       if (napi_ok != napi_create_double(env, result, &napiResult)) {
           OH_LOG_Print(LOG_APP, LOG_ERROR, LOG_PRINT_DOMAIN, "MyHypot", "napi_create_double failed");
           return nullptr;
       }
       return napiResult;
   }
   

4. 添加接口文件以及接口配置文件。接口文件index.d.ts用于对外提供方法说明。接口配置文件oh-package.json5文件中将index.d.ts与CMake编译的so文件关联起来。模块级目录下oh-package.json5文件添加so文件依赖。

   // index.d.ts
   export const myHypot: (a: number, b: number) = > number;
   

   // oh-package.json5
   {
     "name": "libhello.so",
     "types": "./index.d.ts"
   }
   
   // entry/oh-package.json5
   {
     "devDependencies": {
       "@types/libhello.so": "file:./src/main/cpp/types/libhello"
     }
   }
   

5. 在CMakeLists.txt文件中配置CMake编译参数。配置需要添加的hello.cpp文件，编译后的so文件名为libhello.so。CMakeLists.txt是CMake编译的配置文件，里面的大部分内容无需修改，project、add_library方法中的内容可以根据实际情况修改。

   # CMakeLists.txt
   # 声明使用 CMAKE 的最小版本号
   cmake_minimum_required(VERSION 3.4.1)
   
   # 配置项目信息
   project(NativeTemplateDemo)
   
   # set命令，格式为set(key value)，表示设置key的值为value
   set(NATIVERENDER_ROOT_PATH ${CMAKE_CURRENT_SOURCE_DIR})
   
   # 设置头文件的搜索目录
   include_directories(
       ${NATIVERENDER_ROOT_PATH}
       ${NATIVERENDER_ROOT_PATH}/include
   )
   
   # 添加日志库
   find_library(
       # Sets the name of the path variable.
       hilog-lib
       # Specifies the name of the NDK library that
       # you want CMake to locate.
       hilog_ndk.z
   )
   
   # 添加名为hello的库，库文件名为libhello.so
   add_library(hello SHARED hello.cpp)
   
   # 添加构建需要链接的库
   target_link_libraries(hello PUBLIC ${hilog-lib} libace_napi.z.so libc++.a)
   

   说明：

   • CMAKE_CURRENT_SOURCE_DIR：CMakeList.txt文件所在的目录。
   • add_library：添加本地的cpp文件，多cpp文件使用空格或换行间隔。
   • target_link_libraries：添加需要链接的库，本篇Codelab使用C标准库hypot方法，此处链接libc++.a库文件。

ArkTS调用C++方法

Index.ets文件使用import语句导入CMake编译出的so文件。Button组件添加点击事件，点击按钮触发点击事件时，调用libhello.so对外提供的myHypot方法，执行计算并返回计算结果。依据结果值进行格式化，显示科学计数法或保留指定位小数。

// Index.ets
import libHello from 'libhello.so';

@Entry
@Component
struct Index {
  ...
  build() {
    ...
    Button($r('app.string.submit_button'))
      .onClick(() = > {
        let resultTemp = libHello.myHypot(this.numX, this.numY);
        if (resultTemp > CommonContants.MAX_RESULT) {
          this.result = resultTemp.toExponential(CommonContants.EXPONENTIAL_COUNT);
        } else {
          this.result = resultTemp.toFixed(CommonContants.FIXED_COUNT);
        }
      })
  }
}

界面设计

界面由标题、文本说明、计算结果展示、输入框、按钮组成。Index.ets文件完成界面实现，使用Column及Row容器组件进行布局。

// Index.ets
@Entry
@Component
struct NativeTemplate {
  ...
  build() {
    Column() {
      ...
      Column() {
        ...
        Row() {
          ...
          TextInput({ controller: this.textInputControllerX })
            .type(InputType.Number)
        }
        .height($r('app.float.tips_num_height'))
        .width(CommonContants.FULL_PARENT)
        Row() {
          ...
          TextInput({ controller: this.textInputControllerY })
            .type(InputType.Number)
            .onChange(value = > {
              this.numY = parseFloat(value);
            })
        }
        .height($r('app.float.tips_num_height'))
        .width(CommonContants.FULL_PARENT)
      }
      Row() {
        Button($r('app.string.submit_button'))
          .height(CommonContants.FULL_PARENT)
          .width($r('app.float.button_width'))
      }
      .height($r('app.float.button_height'))
      .width(CommonContants.FULL_PARENT)
    }
    .width(CommonContants.FULL_PARENT)
    .height(CommonContants.FULL_PARENT)
  }
}

审核编辑 黄宇