From ee602c0fafa5f572399597668734806aea3a5038 Mon Sep 17 00:00:00 2001
From: huoxiaodan <huoxiaodan@kaihongdigi.com>
Date: Thu, 30 Jun 2022 17:58:26 +0800
Subject: [PATCH] add napi_vs_plugin readme

Signed-off-by: huoxiaodan <huoxiaodan@kaihongdigi.com>
---
 napi_vs_plugin/README_zh.md           | 120 ++++++++++++++++++++++++++
 napi_vs_plugin/docs/DEVELOP_ZH.md     |  82 ++++++++++++++++++
 napi_vs_plugin/docs/INSTRUCTION_ZH.md |  66 ++++++++++++++
 3 files changed, 268 insertions(+)
 create mode 100644 napi_vs_plugin/README_zh.md
 create mode 100644 napi_vs_plugin/docs/DEVELOP_ZH.md
 create mode 100644 napi_vs_plugin/docs/INSTRUCTION_ZH.md

diff --git a/napi_vs_plugin/README_zh.md b/napi_vs_plugin/README_zh.md
new file mode 100644
index 00000000..4a905a52
--- /dev/null
+++ b/napi_vs_plugin/README_zh.md
@@ -0,0 +1,120 @@
+# NAPI框架生成工具VSCode插件说明
+
+## 简介
+
+NAPI框架代码生成工具，它可以根据用户指定路径下的ts(typescript)接口文件一键生成NAPI框架代码、业务代码框架、GN文件等。目前工具支持可执行文件、VS Code插件、IntelliJ插件三种入口，本文主要介绍VS Code插件使用指导。
+
+## 目录 
+
+	├── napi_generator                # NAPI框架代码生成工具
+	│   ├── ...                       # 其他文件
+	│   ├── napi_vs_plugin            # VS Code插件代码
+	│   │   ├── docs                  # VS Code插件说明
+	│   │   ├── src    				  # VS Code插件源码
+	│   │   └── README_zh             # VS Code插件说明
+
+## 约束 
+
+系统：建议Ubuntu 20.04或者Windows 10
+
+依赖版本：VS Code 1.62.0
+
+## 使用方法 
+
+### 使用对象
+
+系统开发者
+
+### 使用场景
+
+1) 系统框架层新增子系统，需对应用层提供接口。
+2) 系统框架层子系统能力增强后，需对应用层提供新接口。
+
+### 工具使用
+
+插件下载路径如下，选择napi_generator_outputs.zip下载。
+
+[下载链接](http://ftpkaihongdigi.i234.me:5000/fsdownload/GGsW3B68u/generator_outputs)
+
+具体的工具使用步骤，可以左键单击以下链接了解：
+
+[工具使用说明](https://gitee.com/openharmony/napi_generator/tree/master/napi_vs_plugin/docs/INSTRUCTION_ZH.md)
+
+### 工具输出
+
+根据使用者指定的typescript文件，工具会输出NAPI框架代码、业务代码框架、GN脚本等文件。
+
+为了方便使用者快速上手工具，可供测试的typescript文件存放在以下路径：
+
+```
+napi_vs_plugin
+```
+
+在window环境下的，根据输入文件@ohos.napitest.d.ts和basic.d.ts生成的输出文件，如下所示：
+
+![](../figures/pic-d-ts-transition.png)
+
+其中生成的"napitest.h"文件，定义了框架代码的接口，如下所示：
+
+
+```c++
+#include "napitest.h"
+
+
+namespace napitest {
+
+bool TestClass1::if_direct(std::string &v1, std::string &out) {
+    // TODO
+    return true;
+}
+
+bool TestClass1::if_callback(std::string &v1, std::string &out) {
+    // TODO
+    return true;
+}
+
+......
+}
+```
+      
+### 集成方法
+
+为了实现工具生成的接口被其他子系统或者应用调用，需将生成的代码编译集成到OpenHarmony系统中，编译生成动态库。
+
+把工具的生成代码集成到OpenHarmony的具体操作步骤，可以左键单击以下链接了解：
+
+[生成代码集成到OpenHarmony的方法](https://gitee.com/openharmony/napi_generator/blob/master/docs/ENSEMBLE_METHOD_ZH.md)
+
+## 开发说明
+
+### 对象
+
+工具的开发者
+
+### 开发场景
+
+若当前工具的功能已经不能满足开发者的全部需求，则开发者可以基于已有的源码对工具进行二次开发，来增强工具的能力，编译打包生成自定义的可执行文件和插件。
+       
+### 开发步骤
+
+开发者可以根据如下的步骤来完成对工具VS Code插件的开发：
+
+ [工具开发说明](https://gitee.com/openharmony/napi_generator/tree/master/napi_vs_plugin/docs/DEVELOP_ZH.md)
+    
+## 版本说明 
+
+当前版本已支持的特性和待开发的特性，如下所示：
+
+ [已支持特性](https://gitee.com/openharmony/napi_generator/blob/master/release-notes/napi_generator-1.0.md)
+
+ [待支持特性](https://gitee.com/openharmony/napi_generator/blob/master/docs/ROADMAP_ZH.md)
+
+## FAQ
+
+对于常见问题解决方法指导如下：
+
+  [FAQ](https://gitee.com/openharmony/napi_generator/blob/master/FAQ.md)
+
+## 相关仓
+
+暂无
diff --git a/napi_vs_plugin/docs/DEVELOP_ZH.md b/napi_vs_plugin/docs/DEVELOP_ZH.md
new file mode 100644
index 00000000..38ebcf06
--- /dev/null
+++ b/napi_vs_plugin/docs/DEVELOP_ZH.md
@@ -0,0 +1,82 @@
+# NAPI框架生成工具VSCode插件开发说明
+
+若当前工具功能不满足开发者需求，开发者需增强工具能力，则可基于已有源码进行工具二次开发，编译打包生成自定义的VS Code插件。
+
+## VS Code插件打包说明
+
+### Linux
+
+1.在napi_generator目录下，将napi_generator-linux下可执行文件复制到napi_generator/napi_vs_plugin/src/目录下，执行命令如下：
+
+	cp napi_generator-linux napi_vs_plugin/src/
+
+2.在napi_generator/napi_vs_plugin/src目录下执行命令：
+
+	npm i
+
+3.在napi_generator/napi_vs_plugin/src目录下执行命令：
+
+	npm i typescript
+
+4.在napi_generator/napi_vs_plugin/src目录下执行命令：
+
+	npm i vsce
+
+5.在napi_generator/napi_vs_plugin/src目录下执行命令：
+
+	npx vsce package
+
+  每个选项都选择y，然后回车，最终会在当前目录下打包生成一个插件gnapi-0.0.1.vsix。结果如下：
+
+	harmony@Ubuntu-64:~/napi/napi_generator_5/napi_vs_plugin/src$ npx vsce package
+	WARNING  A 'repository' field is missing from the 'package.json' manifest file.
+	Do you want to continue? [y/N] y
+	WARNING  Using '*' activation is usually a bad idea as it impacts performance.
+	More info: https://code.visualstudio.com/api/references/activation-events#Start-up
+	Do you want to continue? [y/N] y
+	WARNING  LICENSE.md, LICENSE.txt or LICENSE not found
+	Do you want to continue? [y/N] y
+	This extension consists of 3370 files, out of which 1627 are JavaScript files. For performance reasons, you should bundle your extension: https://aka.ms/vscode-bundle-extension . You should also exclude unnecessary files by adding them to your .vscodeignore: https://aka.ms/vscode-vscodeignore
+	DONE  Packaged: /home/harmony/napi/napi_generator_5/napi_vs_plugin/src/gnapi-0.0.1.vsix (3370 files, 44.42MB)
+
+### Windows
+
+1.将napi_generator目录下的napi_generator-win.exe可执行文件复制到napi_generator/napi_vs_plugin/src/目录下。
+
+2.在napi_generator/napi_vs_plugin/src目录下执行命令：
+
+	npm i
+
+3.在napi_generator/napi_vs_plugin/src目录下执行命令：
+
+	npm i typescript
+
+4.在napi_generator/napi_vs_plugin/src目录下执行命令：
+
+	npm i vsce
+
+5.在napi_generator/napi_vs_plugin/src目录下执行命令：
+
+	npx vsce package
+
+  每个选项都选择y，然后回车，最终会在当前目录下打包生成一个插件gnapi-0.0.1.vsix。结果如下：
+
+	E:\napi_generator\napi_generator-master\napi_vs_plugin\src>npx vsce package
+	WARNING  A 'repository' field is missing from the 'package.json' manifest file.
+	Do you want to continue? [y/N] y
+	WARNING  Using '*' activation is usually a bad idea as it impacts performance.
+	More info: https://code.visualstudio.com/api/references/activation-events#Start-up
+	Do you want to continue? [y/N] y
+	WARNING  LICENSE.md, LICENSE.txt or LICENSE not found
+	Do you want to continue? [y/N] y
+	This extension consists of 3467 files, out of which 1692 are JavaScript files. For performance reasons, you should bundle your extension: https://aka.ms/vscode-bundle-extension . You should also exclude unnecessary files by adding them to your .vscodeignore: https://aka.ms/vscode-vscodeignore
+	DONE  Packaged: E:\napi_generator\napi_generator-master\napi_vs_plugin\src\gnapi-0.0.1.vsix (3467 files, 42.3MB)
+
+## 工具测试
+
+  进行工具二次开发后，本地可进行单元测试、story特性测试确保工具的可用性。左键单击以下链接了解详情：
+
+  [单元测试](https://gitee.com/openharmony/napi_generator/blob/master/test/unittest/README_ZH.md)
+
+  [story测试](https://gitee.com/openharmony/napi_generator/blob/master/test/storytest/README_ZH.md)
+
diff --git a/napi_vs_plugin/docs/INSTRUCTION_ZH.md b/napi_vs_plugin/docs/INSTRUCTION_ZH.md
new file mode 100644
index 00000000..81173622
--- /dev/null
+++ b/napi_vs_plugin/docs/INSTRUCTION_ZH.md
@@ -0,0 +1,66 @@
+# NAPI框架生成工具VSCode插件使用说明
+## 简介
+
+VS Code插件下载路径如下，选择napi_generator_outputs.zip中gnapi-0.0.1.vsix下载。
+
+[下载链接](http://ftpkaihongdigi.i234.me:5000/fsdownload/GGsW3B68u/generator_outputs)               
+
+## VS Code插件使用方法
+
+### 说明
+
+visual studio code 版本需1.62.0及以上。
+
+### 步骤
+
+1.打开VS Code，在左侧边栏中选择插件安装。
+
+![](../../figures/pic-plug-in-search.png)
+
+2.单击上面三个点的按钮，选择从VSIX安装选项，然后选择刚才生成的gnapi-0.0.1.vsix插件文件，再单击安装。
+
+![](../../figures/pic-plug-in-select.png)
+
+3.安装完成后就会在VS Code的插件管理器中能看到gnapi这个插件了。
+
+![](../../figures/pic-plug-in-gnapi.png)
+
+4.在VS Code中找到需要转换的.d.ts文件，并且检查需要转换的d.ts文件中是否声明了import的d.ts文件，如果存在需要将import的d.ts文件也放入到待转换的d.ts文件相同的目录下，例如：
+
+![](../../figures/pic-plug-in-select-d-ts.png)
+
+5.鼠标在.d.ts上单击右键，选择“ Generate Napi Frame”选项，工具打开 Generate Napi Frame窗口。选择方式有.d.ts文件、文件夹两种方式，此处以.d.ts文件为例；选择接口文件文本框中默认填写.d.ts文件路径，此处不修改；生成框架路径文本框填写生成文件所放文件夹绝对路径；编译脚本路径文本框选填，此处不填写，然后点击ok。
+
+![](../../figures/pic-plug-in-gen-c++.png)
+
+![](../../figures/pic-generator-napi-frame.png)
+
+6.转换成功工具右下角就会提示“Generated successfully”的信息，并且在.d.ts文件当前目录下生成对应文件，例如：
+
+![](../../figures/pic-plug-in-gen-sucess.png)
+
+7.此外，工具还支持指定路径下.d.ts文件转换、同一目录下多个.d.ts文件同时转换、多级模块.d.ts文件转换等场景。
+
+1）指定路径下.d.ts文件转换（可转换路径下所有.d.ts文件）。Generate Napi Frame窗口中，选择方式修改为文件夹；选择接口文件文本框中填写待转换.d.ts文件路径，此处为E:\demo；生成框架路径填写生成文件所放路径，此处为项目当前路径；编译脚本路径选填，此处不填写，然后点击ok。Generate Napi Frame窗口填写与生成文件如下图所示：
+
+![](../../figures/pic-plug-in-gen-dir-sucess.png)
+
+2）同一目录下多个.d.ts文件同时转换。项目中存在@ohos.napitest.d.ts和@ohos.power.d.ts两个文件，且声明了import的d.ts文件。Generate Napi Frame窗口中，选择方式修改为.d.ts文件；选择接口文件文本框中填写待转换.d.ts文件，此处为“E:\napi_tool_new\@ohos.napitest.d.ts,E:\napi_tool_new\@ohos.power.d.ts”；生成框架路径填写生成文件所放路径，此处为项目当前路径；编译脚本路径选填，此处不填写，然后点击ok。Generate Napi Frame窗口填写与生成文件如下图所示：
+
+![](../../figures/pic-plug-in-gen-files-sucess.png)
+
+3)多级模块.d.ts文件转换。项目中存在@ohos.napi_.test.A.d.ts文件，Generate Napi Frame窗口中，选择方为.d.ts文件；选择接口文件文本框中填写待转换.d.ts文件，此处为“E:\napi_tool_new\@ohos.napi_.test.A.d.ts”；生成框架路径填写生成文件所放路径，此处为项目当前路径；编译脚本路径选填，此处不填写，然后点击ok。Generate Napi Frame窗口填写与生成文件如下图所示：
+
+![](../../figures/pic-plug-in-gen-module-sucess.png)
+
+## 注意
+
+对于ts文件中的number类型，默认转为C++ uint32_t类型，修改框架生成目录中的napitest.h类型赋值，可实现number类型到C++指定数据类型的转换。
+
+![](../../figures/instruction_number_type.png)
+
+## 集成测试
+NAPI框架代码生成后，系统框架开发者进行二次开发后，即可集成到OpenHarmony编译系统，生成对应的库文件，供应用开发者调用接口。工具集成测试的具体操作步骤可以左键单击以下链接了解：
+
+  [工具集成测试](https://gitee.com/openharmony/napi_generator/blob/master/docs/INTEGRATION_TESTING_ZH.md)
+
-- 
Gitee