VS Code插件开发学习笔记1

1 背景

用VS Code打开Vivado综合和实现后格式为.rpt的report文件，发现VS Code的插件库没有对应的语法高亮插件，然而VS Code并不支持直接自定义关键词高亮（也许有但是我没找到）。.rpt的显示效果如下：

可见，没有高亮的显示效果 能看，但不完全能看。
所以，趁这个机会学习一下VS Code的语法插件开发。

基本上就是按照官网的教程实践了一边，涉及到的资料：

• VS Code 官方API:

2 环境

2.1 需要安装的软件

1. Node.js
2. Git
3. VS Code

2.2 环境设置

• 打开命令提示符，执行npm install -g yo generator-code安装Yeoman以及 VS Code Extension Generator
  Yeoman：用于搭建新应用、添加相关依赖配置、以及完成相关测试的插件。
  VS Code Extension Generator：如其名，开发插件的工具。
  

3 hello world

1. 在命令提示符输入yo code后，按照下面的设置输入相关配置：
   
   在工程新建向导的帮助下，很轻松的新建了一个名为HelloWorld，类型为TypeScript的VS Code插件。工程保存的路径为当前路径下名字为工程名的一个文件夹中。

2. 在命令提示符当前工作路径下输入命令：code ./helloworld，用VSCode打开工程文件夹。这一步需要已经将code.exe路径添加为环境变量，没有的话直接用VSCode图形界面打开文件夹即可。
   

3. 按F5 或者 运行-启动调试 开始调试插件，会弹出插件的调试窗口。

4. 按ctrl_shift+p或者 设置-命令面板，输入hello world并运行搜索出的命令

右下角弹出消息，显示“Hello World form HelloWorld”，完成 hello world功能的调试。

4 工程结构说明

4.1 工程的文件结构

.
├── .vscode
│ ├── launch.json // 启动和调试扩展的配置文件
│ └── tasks.json // 定义TypeScript的build任务的配置文件
├── .gitignore // 忽略build构建输出和node_modules
├── README.md // 描述插件的功能
├── src
│ └── extension.ts // 插件的源代码
├── package.json // 插件的组件清单（manifest）
├── tsconfig.json // TypeScript配置文件

对于理解插件最关键的两个文件：package.json 和 extension.ts

1. package.json：每个插件都必须包含这个文件作为插件的组件清单（manifest），内容由Node.js字段（scripts 、devDependencies等）和VS Code特定字段（publisher、activationEvents 和 contributes等）混合组成，Extension Manifest Reference官方手册

   	{
   	"name": "helloworld",
   	"displayName": "HelloWorld",
   	"description": "hello, vs code extension",
   	"version": "0.0.1",
   	"engines": {
   		"vscode": "^1.59.0"
   	},
   	"categories": [
   		"Other"
   	],
   	"activationEvents": [
   		"onCommand:helloworld.helloWorld"
   	],
   	"main": "./out/extension.js",
   	"contributes": {
   		"commands": [
   			{
   				"command": "helloworld.helloWorld",
   				"title": "Hello World"
   			}
   		]
   	},
   	"scripts": {
   		"vscode:prepublish": "npm run compile",
   		"compile": "tsc -p ./",
   		"watch": "tsc -watch -p ./",
   		"pretest": "npm run compile && npm run lint",
   		"lint": "eslint src --ext ts",
   		"test": "node ./out/test/runTest.js"
   	},
   	"devDependencies": {
   		"@types/vscode": "^1.59.0",
   		"@types/glob": "^7.1.3",
   		"@types/mocha": "^8.2.2",
   		"@types/node": "14.x",
   		"eslint": "^7.27.0",
   		"@typescript-eslint/eslint-plugin": "^4.26.0",
   		"@typescript-eslint/parser": "^4.26.0",
   		"glob": "^7.1.7",
   		"mocha": "^8.4.0",
   		"typescript": "^4.3.2",
   		"vscode-test": "^1.5.2"
   	}
   }
   

主要的字段：

• name 和 publisher：<publisher>.<name>是插件唯一的ID。
• main：程序入口。
• activationEvents ：是激活的一些事件，每次打开特定语言的文本、或者调用命令或者调试时会激活对应的事件。代码中的"onCommand:helloworld.helloWorld"含义就是当调用Hello World命令时会激活这个事件。
• contributes：我的理解是代码中有的一些组件，比如commands就是包含一个标题为Hello World，helloworld工程下ID为helloworld的命令。其他的组件还有断点（breakpoints）、颜色（colors）和调试器（debuggers）等。
• engines.vscode：这指定了扩展所依赖的VS Code API的最小版本。

2. extension.ts：这个文件包含两个函数，activate 和 deactivate。

   // The module 'vscode' contains the VS Code extensibility API
   // Import the module and reference it with the alias vscode in your code below
   import * as vscode from 'vscode';
   
   // this method is called when your extension is activated
   // your extension is activated the very first time the command is executed
   export function activate(context: vscode.ExtensionContext) {
   	
   	// Use the console to output diagnostic information (console.log) and errors (console.error)
   	// This line of code will only be executed once when your extension is activated
   	console.log('Congratulations, your extension "helloworld" is now active!');
   
   	// The command has been defined in the package.json file
   	// Now provide the implementation of the command with registerCommand
   	// The commandId parameter must match the command field in package.json
   	let disposable = vscode.commands.registerCommand('helloworld.helloWorld', () => {
   		// The code you place here will be executed every time your command is executed
   		// Display a message box to the user
   		vscode.window.showInformationMessage('Hello World from HelloWorld!');
   	});
   
   	context.subscriptions.push(disposable);
   }
   
   // this method is called when your extension is deactivated
   export function deactivate() {}
   
   

   • activate 函数：当注册的激活事件发生时执行。在这里当命令helloworld.helloWorld被调用时，就会执行这个函数，然后在函数中对这个命令进行响应（显示一个字符串“Hello World from HelloWorld!”）。
   • deactivate函数：扩展失效之前的清理代码。对于许多扩展，可能不需要显式清除。

4.2 工程的运行机制

helloworld工程的运行完成了下面的3个工作:

• 注册onCommand激活事件:onCommand:extension。因此，当用户运行Hello World命令时，扩展将被激活。
• 使用contribute .commands组件使命令Hello World在命令面板中可用，并将其绑定到命令ID为helloworld.helloworld。
• 使用 VS Code 的 API：Command.registerCommand 绑定一个函数到注册的命令ID：helloworld.helloworld。

所以为了写一个插件工程，需要理解下面三个概念：

• Activation Events：插件激活的事件。
• Contribution Points：插件包含的组件（个人理解，可能翻译的不准确）。
• VS Code API：可以在扩展代码中调用的JavaScript api。

学习了这些基础，下一步就可以试着写一个简单的语法高亮的插件了。