# napi_generator

**Repository Path**: thirdparty-transplant/napi_generator

## Basic Information

- **Project Name**: napi_generator
- **Description**: 一个用于生成napi代码的Python代码仓库
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-09-19
- **Last Updated**: 2026-02-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: napi, 鸿蒙, OpenHarmony, HarmonyOS

## README

# napi_gen

napi_gen 是一个用于生成鸿蒙NAPI 代码的工具，旨在简化 ArkTs 接口到 C++ NAPI 模块的转换过程。该项目提供了一个命令行工具，能够解析 `.d.ts` 类型定义文件，并生成相应的 C++ 代码和测试代码。

用我们的指令生成后的NAPI代码完成度达到90%以上，开发者只需要完成c/c++接口对接以及少数无法辨认的类型转换即可。

这个项目相对于其他同类型项目更专注NAPI实现，而不仅仅是代码框架。

该项目与[ohog_utils](https://gitee.com/thirdparty-transplant/ohos_utils) 搭配使用。

## 支持特性


|类型   | 功能描述  |是否支持  |
|---|---|---|
| 自定义类型  | 在.d.ts文件定义的类型  | ✓  |
| TS基本类型  | 包括number,void,string,boolean等  |  ✓  |
| 鸿蒙原生类型  | 鸿蒙系统提供的ArkTs类型，比如media.AVFileDescriptor无法识别  | ×  |
| 函数  | .d.ts声明的函数  | ✓  |
| type定义的别名  | 在.d.ts定义的type别名  | ✓  |
| interface定义  |在.d.ts定义的interface类型   |  ✓  |
| async | 声明接口以async规定为异步  |  ×   |
| promise | 声明接口以Promise作为返回类型   |  ✓  |
| callback| 声明接口以callback作为返回类型，但是callback类型需要定义成别名，否则无法处理   |  ✓  |
|class类型|声明为class, 且有构造函数、方法等|  ✓ |

不支持的特性，在生成后的代码中，会以 “TODO”，“NOTE” 等开头的注释进行提示。如下代码所示：

![输入图片说明](docs/figure_1.png)


## 安装

### 稳定版本

使用 `pip`安装：

```sh
pip install napi_gen
```

### 从源码安装

你可以从 [Gitee 仓库]("https://gitee.com/thirdparty-transplant/napi_generator") 克隆源码：

```sh
git clone https://gitee.com/thirdparty-transplant/napi_generator
```

安装依赖并本地安装：

```sh
cd napi_gen
pip install -e .
```

## 使用

### 命令行接口

napi_gen 提供了一个命令行工具，用于生成 NAPI 代码：

```sh
napi-gen index.d.ts -m media
```

#### 参数说明：
- `--module-name` 或 `-m`: 指定生成的模块名称。
- `--output` 或 `-o`: 输出的 C++ 文件路径（可选），默认会创建一个out目录用于存放生成的代码
- `--verbose` 或 `-v`: 启用详细输出。

生成的代码将包括 C++ NAPI 实现和CMakeLists.txt, 可以用提供的build.sh 直接编译成ohos的动态库。

```
out
├── media
│   ├── CMakeLists.txt
│   ├── libopenim.h
│   ├── media_napi.cpp
│   ├── media_napi.h
│   ├── mediacodec_napi.cpp
│   ├── mediacodec_napi.h
│   ├── mediaextractor_napi.cpp
│   ├── mediaextractor_napi.h
│   ├── mediaformat_napi.cpp
│   ├── mediaformat_napi.h
│   └── napi_init.cpp
├── media_test.ets
└── parsed_result.json
```

可以验证生成的代码：
```shell
# 要指定ohos_utils的路径
./build.sh out/media --utils-path /ohos_work/ohos_utils 
```
对于代码中用到的c/c++外部类型，需要打桩处理，否则编译会报错。

## 案例讲解

###  类定义

接口定义如下：

包括构造函数，和三个成员函数， start, stop为Promise类型返回。

```
export class MediaCodec {
  constructor(mine: string);
  bind(extractor: MediaExtractor, callback: (status: number, codecInfo: CodeInfoAttr) => void): void;
  start(): Promise<void>;
  stop(): Promise<void>;
```
生成代码如下：

构造函数：
![输入图片说明](docs/figure_2.png)

start成员函数：

![输入图片说明](docs/figure_3.PNG)

其他同理。

在生成的基础上，按照TODO和Note修改剩余部分即可完成代码。


## 贡献

欢迎贡献代码和改进文档。请参考 [CONTRIBUTING.md](CONTRIBUTING.md) 获取详细的贡献指南。

## 许可证

本项目采用 MIT 许可证。详细信息请参阅 [LICENSE](LICENSE) 文件。

## 文档

更多详细信息和使用示例，请参阅 [官方文档](https://napi_gen.readthedocs.io)。

## 致谢

本项目模板基于 [Cookiecutter](https://github.com/audreyfeldroy/cookiecutter) 和 [audreyfeldroy/cookiecutter-pypackage](https://github.com/audreyfeldroy/cookiecutter-pypackage) 创建。