从零开始开发一款属于你的VS Code 插件

布满荆棘的人生 2023-07-18 11:26 32阅读 0赞

视频作者：韩骏, 文字编辑：PiperLiu, 排版：胖琪, 审核：左左

> ❝
> 
> 视频日期：2019年12月9日 
> 
> 会议主题：微软技术暨生态大会 2018
> 
> 会议日期：2018年10月25日 
> 
> 演讲题目：从零开始开发一款属于你的 Visual Studio Code 插件 
> 
> 主讲人：韩骏 - 微软开发工具事业部
> 
> ❞

## 预热部分 ##

#### 主讲人介绍 ####

截止18年开会，主讲人已经开发过 16 款 VS Code 插件，其中很多插件备受好评。比如 Code Runner 已经有 400 多万下载量， GitHub 上收获 1k 星标。

主讲人有着很深的 VS Code 的插件开发经验。

#### VS Code 介绍 ####

Visual Studio Code 是一款微软推出的编辑器，具有以下特点：

*  开源
 *  跨平台（macOS, Linux, Windows）
 *  轻量级
 *  智能提示（intelliSense）
 *  代码调试
 *  内置 Git 支持
 *  多语言支持
 *  丰富的插件

谈到 VSC 的开发，就有两点不得不提：`Electron` 框架与 `Monaco Editor` 。

VSC 是完全基于 `Electron` 进行开发的。

`Electron` 框架具有以下特点：

*  基于 Node.js （作为后端）和 Chromium （作为前端）；
 *  使用 HTML 、 CSS 和 JavaScript 开发跨平台桌面 GUI 应用程序；
 *  使用者有：Atom 、 Skype 、 GitHub Desktop 、 Slack ...

还有一个重要的组件，是 `Monaco Editor` 。其实， `Monaco Editor` 在微软内部有很多应用。

`Monaco Editor` 有以下特点：

*  基于浏览器的代码编辑器：intelliSense ，代码验证，语法高亮，文件比较...
 *  支持主流浏览器：IE 11 ， Edge ， Chrome ， Firefox ， Safari 和 Opera ；
 *  使用者：Azure DevOps ， OneDrive ， Edge Dev Tools ， Gitee Web IDE 。

## VSC 插件 ##

#### 简介 ####

VSC 有超过 8000 个插件（截止演讲的 2018 年），内容包含语言、调试器、代码格式化、代码片段、键盘映射、主题...

VSC 如此受欢迎，离不开其丰富的插件生态。

#### VSC 的插件开发 ####

可以分为四个步骤：

*  设计
 *  实现
 *  推广
 *  维护

#### I 设计部分 ####

设计部分的第一个关键词：**「灵感」**。那么，怎样获取灵感？

第一点：`从自身需求出发`。以 Code Runner 为例：韩老师在微软曾开发过许多语言，自己曾有过一个需求：“是否可以省去在 terminal 中进入某个目录运行代码这个环节，而直接运行自己所需测试的十几行代码片段呢？”韩老师发现并没有相应插件，于是他开发了 Code Runner 。

第二点：`去发现别人的需求`，比如去 GitHub issues 或者 feature request 去发现别人的需求。比如在开发前端时，自动补全 Tag 是一个很有用的功能，但当时 VSC 并未实现，于是韩老师开发了 Auto Close Tag 插件。

第三点：`查考老牌编辑器已有功能`。因为 VSC 属于新兴编辑器，功能尚不完备，可以参考其他编辑器，获取需求灵感，从而开发相应插件。

设计部分的第二个关键词：**「目标用户」**。

以 Code Runner 为例，其目标用户可定位成：

*  初学者：初学者可能仅仅想了解语言的语法，无需了解编译过程，因此使用 Code Runner 可以轻松运行代码，省去其他编译命令；
 *  “懒人”：Code Runner 提供了多个快捷键与触发动作，大大提升调试效率；
 *  多语言用户：多语言开发无需切换开发环境或编辑器。

#### II 实现部分 ####

首先，应该配置好开发环境，有三点关键步骤：

*  Visual Studio Code
 *  Node.js
 *  Yeoman and VS Code Extension generator

其中 `Yeoman` 和 `generator` 可从 npm 配置：

npm install -g yo generator-code

接下来，我们通过一个 Demo 来演示 VS Code 的开发。

**「第一步」**，确认已经安装配置好了 `Yeoman` 与 `VS Code Extension generator`，打开 terminal ，输入 `yo code` 。

![format_png][]

**「第二步」**，在命令行中会供你选择 `Extension` 的种类，这里推荐大家使用基于 `TypeScript` 进行开发，即选择 `New Extension (TypeScript)` 。

**「第三步」**，依照命令行中的提示，输入名字、 ID 、description 、 Publish Name 等等。完成基础配置后，会生成属于你的新插件的项目文件夹，其中会配置好了 VS Code 的 Engine 。

**「第四步」**，使用 VSC 打开你刚刚生成的项目，如下图。

![format_png 1][]

可以注意到，（通过 sky fording ）生成了许多文件，但其实，值得注意的只有两个文件：

*  Extension.ts
 *  package.json

在 package.json 中，关注 contributes ，其定义了一个 Command ：

"contributes": {
        "commands": [
            {
                "command": "extension.helloWorld",
                "title": "Hello World"
            }
        ]
    }

同时注意：

"activationEvents": [
        "onCommand:extension.helloWorld"
    	]

这里表示，该 event 是由 command 激活的。这是出于性能的考虑，在 VSC 中，插件一般都是 lazy load 的，只有激活才启用插件。

而 Extension.ts 可以理解为一个激活的函数。

// 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 "hello-piper" 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('extension.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 Piper!');
    	});
    
    	context.subscriptions.push(disposable);
    }

当 command 出现时，上述实例会 `showInformationMessage('Hello Piper!')`。

**「第五步」**，我们尝试调试这个插件。在左侧的 Run 工具栏中点击 debug 按钮， VSC 会为我们打开一个加载好该插件的新 VSC 。

在新 VSC 中 `Ctrl+Shift+P` 输入我们之前定义好的命令，可见有效。如下图。

![format_png 2][]

> ❝
> 
> 以上就是建立 VSC 插件项目的过程，有经验的开发人员可以阅读微软官方文档 https://code.visualstudio.com/api 进行插件开发。
> 
> ❞

> ❝
> 
> 以上为视频前 25 分钟内容。
> 
> ❞

**「第六步」**，接下来韩老师现场修改 vscode-translator 插件，以此为例讲解关于插件开发的更多操作。以下是详细内容。

vscode-translator 的项目地址：https://github.com/formulahendry/vscode-translator

首先来看 package.json 。

"commands": [{
    		"command": "translator.translate",
    		"title": "Translate"
    	},
    	{
    		"command": "translator.replaceWithTranslation",
    		"title": "Replace with Translation"
    	},
    	{
    		"command": "translator.toggleCaptureWord",
    		"title": "Toggle - Capture Word"
    	}
    ]

在 commands 内注册了关于 Translate 的命令。

"menus": {
    	"editor/context": [{
    			"command": "translator.translate",
    			"group": "navigation@1"
    		},
    		{
    			"command": "translator.replaceWithTranslation",
    			"group": "navigation@2"
    		}
    	]
    }

在 menus 中配置相应命令，可以增加“右键弹出菜单命令”的效果。

"keybindings": [{
    	"command": "translator.translate",
    	"key": "ctrl+alt+z"
    }

很多人喜欢使用键盘快捷键进行操作，鉴于此，韩老师增加了 keybindings 项。

接着我们来看 Extension.ts ，其中也是注册 translate 的相关 Function 。

![format_png 3][]

进入 Extension.ts 注册的函数文件：translator.ts ，我们可以看到：通过 activeTextEditor 对象可以拿到当前 selection 的内容（即需要被翻译的文本）。之后，通过 translate 函数，得到被翻译好的文本。在当前版本中，使用的是有道 API ：

public static async translate(source: string, showErrorMessage: boolean = false): Promise<string> {
    	try {
    		const result = (await axios.get(`https://fanyi.youdao.com/translate?&doctype=json&type=AUTO&i=${encodeURIComponent(source)}`)).data;
    		return result['translateResult'].map((translateResult: any) => translateResult.map((sentence: any) => sentence['tgt']).join('')).join('\n');
    	} catch (error) {
    		if (showErrorMessage) {
    			vscode.window.showErrorMessage(error.toString());
    		}
    		return "";
    	}
    }

至于 hover 功能（鼠标悬浮于文本上），这利用了 VS Code 提供的 HoverProvider 的功能。

import { Hover, HoverProvider, Position, TextDocument } from 'vscode';
    export class TranslatorHoverProvider implements HoverProvider {}

**「第七步」**，关于发布该插件。

VS Code 提供了 VSCE ，可以很方便地发布插件。可以通过 npm 来进行安装。

在发布前，需要进行测试。

韩老师展示了 Azure Pipelines 的全平台测试过程（在 Windows/Mac OS/Linux 平台测试 CI/CD ）。

使用 VSCE publish 来发布。

**「第八步」**，将本地项目与 Azure 配置好后，可以在 Azure 的 Application Insights 上查看用户的下载情况与行为。

> ❝
> 
> 以上为视频前 39 分钟内容， DEMO 部分结束。
> 
> ❞

韩老师分享了三个 Tips ：

Tip 1：快速迭代。帕累托法则（二八定律）是指，80%的用户往往只会用20%的功能。因此，发布第一个版本的插件时，不需要实现全部功能，就可以看出该插件的前景。

Tip 2：可以使用 VS Code Insider ，该版本每天都会更新，可以最快速地查看新功能。

Tip 3：为插件加一些快捷方式。其实插件的转换率（使用人数除以下载数量）的很低，为插件增加快捷方式方便人员使用，可以大幅提高转换率。

#### III 推广部分 ####

推广越早越好。

推广渠道可以有博客论坛等等，比如 Stack Overflow ， v2ex ， 知乎等等。

#### IV 维护部分 ####

首先，维护应该是数据驱动的，可以关注：

*  下载量、月活、日活；
 *  用户的使用行为；
 *  根据不同的使用情况，为相应功能提供优先级；
 *  Fail Fast ， 如果插件效果不好，或许应该尽早放弃。

最后老师讲了讲开源与社区：老师几乎的所有的工具都是开源的。开源是一种双赢的模式，一个好的项目会吸引很多人 pull request 和 issue ，可以让开发者学习很多，也可以帮助插件项目快速迭代成长。

[format_png]: /images/20230528/404a814a64e642b4ba0df2890c6c7050.png
[format_png 1]: /images/20230528/56fe63172db8470e828f57c0af40ba76.png
[format_png 2]: /images/20230528/3cb2e613309a4f9b89a3bceb47a5c062.png
[format_png 3]: /images/20230528/30f02660efed4600ae8493664df89125.png