|
|
||
|---|---|---|
| .. | ||
| AppScope | ||
| doc/apiguide | ||
| entry | ||
| hvigor | ||
| build-profile.json5 | ||
| hvigorfile.ts | ||
| hvigorw | ||
| hvigorw.bat | ||
| oh-package.json5 | ||
| README.md | ||
NAPI 开发教程
背景
Node-API 介绍
Node-API（以前称为 N-API）是用于构建原生插件的 API。它独立于底层 JavaScript 运行时，并作为 ’Node‘.js 本身的一部分进行维护。此 API 将在 ’Node‘.js 的各个版本中保持稳定的应用二进制接口 (ABI)。它旨在将插件与底层 JavaScript 引擎的变化隔离开来，并允许为一个主要版本编译的模块无需重新编译即可在以后的 ’Node‘.js 主要版本上运行。ABI 稳定性 指南提供了更深入的解释。
插件是使用标头为 C++ 插件 的部分中概述的相同方法/工具构建/打包的。唯一的区别是原生代码使用的 API 集。
Node-API 公开的 API 通常用于创建和操作 JavaScript 值。概念和操作通常映射到 ECMA-262 语言规范中指定的想法。API 具有以下属性：
-
所有 Node-API 调用都会返回
napi_status类型的状态代码。此状态指示 API 调用是成功还是失败。 -
API 的返回值通过 out 参数传递。
-
所有 JavaScript 值都被抽象为一个名为
napi_value的不透明类型。 -
如果出现错误状态代码，可以使用
napi_get_last_error_info获取附加信息。可以在错误处理部分 错误处理 中找到更多信息。
Node-API 是一种 C API，可确保跨版本和不同编译器级别的 ABI 稳定性。C++ API 可以更容易使用。为了支持使用 C++，该项目维护了一个名为 node-addon-api 的 C++ 封装器模块。这个封装器提供了一个可内联的 C++ API。使用 node-addon-api 构建的二进制文件将取决于 导出的基于 Node-API C 的函数的符号。node-addon-api 是编写调用 Node-API 的代码的更有效方式。
Native API（NativeDevelopKit）
Native API是OpenHarmony SDK上提供的一组native开发接口与工具集合（也称为NativeDevelopKit），方便开发者使用C或者C++语言实现应用的关键功能。Native API只覆盖了OHOS基础的一些底层能力，如libc，图形库，窗口系统，多媒体，压缩库等，并没有完全提供类似于JS API上的完整的OHOS 平台能力。在应用中使用Native API会编译成动态库打包到应用中。
名词概念
| 名词 | 名词解释 |
|---|---|
| Native API | OHOS SDK里面native包提供的，面向三方应用开发的Native 接口以及相应编译脚本，编译工具链。包括C运行时基础库libc，3D图形库opengl，面向JS与C跨语言的接口Node-API等，具体内容详见下表。 |
| NativeDevelopKit | Native Develop Kit的缩写，在OHOS上就是Native API；Native API是官方名字，NativeDevelopKit指代相同意思。 |
| SDK CAPI | OHOS Native API中的C语言接口，以及工具链部分，当前OHOS的Native API里面只包含C语言接口，因此Native API与CAPI意思一样，建议交流的时候使用CAPI，防止Native API与napi缩写混用。 |
| Node-API | 曾用名napi，是OHOS中提供JS与C跨语言调用的接口，是Native API接口中的一部分. 该接口在’Node‘.js提供的Node-API基础上扩展而来，但不完全与’Node‘.js中的Node-API完全兼容。 |
| napi | Node-API的曾用名，当前Node-API头文件中的接口仍然以napi_开头，不建议使用。 |
Native API构成介绍
-
目录结构
Native API在SDK包的位置为$(SDK_ROOT)/native目录，主要有以下几个部分组成
目录 功能说明 build 应用中编译动态库的toolchain cmake脚本；这个目录下ohos.toolchain.cmake文件定义了给OHOS交叉编译选项 build-tools 放置编译构建的工具，如cmake docs Native API接口参考文档，通过doxgen从头文件中提取出来 sysroot 放置编译链接的依赖文件目录，包含头文件，动态库等 -
API接口
接口分类 接口功能 引入版本 标准C库 以muslc为基础提供的标准c库接口，当前提供了1500+的接口 8 标准C++库 c++运行时库libcpp_shared，此库在打包的时候需要打包或者静态链接到应用中 8 日志 打印日志到系统的hilog接口 8 Node-API ArkUI提供的，方便应用开发接入JS应用环境的一组类Node-API（也叫napi），是属于Native API的一部分 8 XComponent ArkUI XComponent组件中的界面与触屏事件接口，方便开发者开发高性能图形应用 8 libuv ArkUI集成的三方的异步IO库 8 libz zlib库，提供基本的压缩，解压接口 8 Drawing 系统提供的2D图形库，可以在界面进行绘制 8 OpenGL 系统提供的openglv3接口 8 Rawfile 应用资源访问接口，可以读取应用中打包的各种资源 8 OpenSLES 用于2D，3D音频加速的接口库 8 Mindspore AI模型接口库 9 包管理 包服务接口，方便查询应用包信息 8 -
相关资料
- Native API参考，介绍各个API参考手册
- Native API中支持的标准库，介绍Native API支持的开源标准库
- Native API开发指南，结合具体的例子，场景介绍各类接口的使用
- 如何在Cmake工程中使用NativeDevelopKit，介绍如何使用使用NativeDevelopKit开发一个CMake工程
- Node-API在应用工程中的使用指导, 如何使用Node-API接口
教程介绍
此教程是 Node-API 和 ArkTS 的联合使用版本，展示了如何引入Native-C++的lib库和头文件，然后通过ArkUI进行展示和直接在 OpenHarmony 设备中运行。它为开发人员提供了在 DevEco Studio 开发中使用 lib库和Native-C++ 的能力，并且通过一系列教程来引导用户了解 Native-C++ 中提供的各种功能。
Native-C++ 教程的目的包括：
- 帮助将 Native-C++ 应用于 OpenHarmony 应用开发中
- 帮助 OpenHarmony 社区、开发人员和三方库尤其是C/C++研究人员交互式地访问各种基于 OpenHarmony 的 C/C++ 示例，以帮助理解特定的视觉算法
- 由于 Native-C++ 能够直接在 OpenHarmony 设备中运行，教程页面具有直观和交互式的特点。例如，利用 ArkUI 和 评估 ArkTS 代码，开发人员可以更改 Native-C++ 函数的参数，并在 OpenHarmony 上进行实时的 C/C++ 编程，以实时查看结果。
为了更好地理解这些教程，建议具备一定的 ArkUI，NAPI 和 C++ 应用程序开发知识。通过学习 Native-C++ 教程，开发人员可以更好地利用 Native-C++ 在 OpenHarmony 开发中的优势，并通过交互式的方式进行实时的算法处理，从而加深对 Native-C++和Node-API 的理解和应用能力。
步骤
在本教程中，您将学习如何在 OpenHarmony 应用开发里引入和使用 Native API 开发。
请注意，以下是一些步骤供您参考：
-
使用napitutorials样例工程：
- IDE版本为：DevEco Studio 4.0 Release（Build Version: 4.0.0.600, built on October 17, 2023）。
-
自行开发nativedevkit应用：
- 按照 [创建NativeDevelopKit工程](创建NativeDevelopKit工程 (openharmony.cn)) 教程中的步骤，配置和构建 native C++ 工程。
完成上述步骤后，您就可以在 OpenHarmony 设备上体验 Native API 的能力，并按照 [Node-API](Node-API | ’Node‘.js v20 文档) 教程进行进一步的学习和实践了。