vscode插件开发-helloWorld

前言

在我们使用vscode开发中，经常使用很多好用的vscode插件，那你有没有试着自己实现一个自己的vscode插件呢？如果有，那你可以跟着这个教程一步一步来，慢慢了解开发vscode插件的一些套路，在你真正需要开发一个vscode插件的时候，做到心中有数，手到擒来。

一、vscode和vscode插件(extension)

明白两者的关系对于插件的开发是很重要的。vscode是微软2015年推出的一款轻量级的代码编辑器，最大的优点是开源的生态。微软官方在保证vscode基本的功能的同时，其他的功能通过插件的形式对vscode进行拓展。这个有什么好处呢？对于vscode来说，保证了编辑器的轻量级；对于用户来说，享受轻量级的同时保证了功能的适用性，因为你可以使用别人写好的vscode插件，也可以定制自己的vscode插件，这就使得vscode和市面上之前主流的编辑器如webstorm相比，更有优势。明白了两者的关系，我们就可以进行插件的开发了。

二、官方文档预览

官方文档地址：https://code.visualstudio.com/api。我们推荐阅读英文文档：

如图，注意并不是API右边的extensions，关于插件开发的所有的内容都是在API目录下面，我们先上一眼左侧的目录，然后下面用到的时候会带着大家一起去翻一翻文档。

三、开发环境搭建

• node

• git

• Yeoman

node和git的安装和使用各位同学就自行百度了,我们主要讲解Yeoman的安装和使用，Yeoman 是一种高效、开源的 Web 应用脚手架搭建系统,本身是用JavaScript开发的，但是可以用于任何语言编写的应用。我们这里通过Yeoman搭建vscode插件的开发工程。

你也可以去查阅Yeoman官方文档，了解更多关于Yeoman的信息。

1.安装Yeoman

npm install -g yo generator-code

2.使用Yeoman命令搭建开发目录

在命令行输入命令：

yo code

出现下面的选项：

出现这样的界面，首先说明你的Yeoman是安装成功了，首先需要明确的是，vscode插件的种类分为下面的几种：

  New Extension (TypeScript)  // 不明确是哪种类型的插件 使用TypeScript开发
  New Extension (JavaScript)  // 不明确是哪种类型的插件 使用JavaScript开发
  New Color Theme  // 生成专为主题插件开发的目录
  New Language Support // 生成专为语言插件开发的目录
  New Code Snippets // 生成专为代码片段插件开发的目录
  New Keymap // 生成专为快捷键插件开发的目录
  New Extension Pack // 生成打包功能的插件
  New Language Pack (Localization) // 生成新的语言打包功能的插件

那这里看你个人的需求，总体是没有什么区别，如果你的插件可能包含多种功能，如有主题、有代码片段，那你就可以选择New Extension (TypeScript)或者New Extension (JavaScript)。那我们这里选择使用New Extension (TypeScript)开发一个新的vscode插件，同时也推荐大家使用TypeScript版本的new Extension，因为vscode本身就是使用TypeScript开发的，和TypeScript是天然契合的。

选择New Extension（TypeScript）后会让你填写新建插件的相关信息：

? What type of extension do you want to create? New Extension (TypeScript) 
? What's the name of your extension? hello-world // 插件名字
? What's the identifier of your extension? hello-world // 插件标识符
? What's the description of your extension? hello-world // 插件描述
? Initialize a git repository? Yes // 是否帮你初始化一个git仓库
? Which package manager to use? (Use arrow keys) // 使用什么包管理器
❯ npm 
  yarn

当你做完上面的步骤，Yeoman会在当前目录下生成一个项目，目录结构是这样的：

这就是vscode的开发工程目录。

四、项目目录分析

现在我们已经成功搭建了一个vscode插件开发的工程，我们首先看看目录的基本结构，大致和我们平时开发的项目目录结构差不多，由于是TypeScript语言开发，所以根目录下面多了一个tsconfig.json文件，这个文件的作用是配置TypeScript，我们后面会分析到。简单梳理一下项目结构：

├── .vscode
│   ├── launch.json     // 插件加载和调试的配置
│   └── tasks.json      // 配置TypeScript编译任务
├── .gitignore          // 忽略构建输出和node_modules文件
├── README.md           // 一个友好的插件文档
├── src
│   └── extension.ts    // 插件入口文件
├── package.json        // 插件配置清单
├── tsconfig.json       // TypeScript配置

我们这里重点关注两个文件：extension.ts和package.json，其他的文件在你使用脚手架的时候vscode默认会给你配置好，但是这两个文件却不会，因为你的插件的开发始终会围绕着这两个文件进行，我们将这两个文件单拎出来分析一下。
1.extension.js

这个文件是整个插件的入口文件，当你的插件启动的时候就会首先走这里的逻辑，首先引入了vscode实例对象，该对象是vscode暴露给开发者调用vscode API使用的，换句话说，是通过这个对象进行调用对应的api进行我们插件的二次开发。然后里面有两个钩子函数：

export function activate(context: vscode.ExtensionContext) {
  
}

activate钩子函数是插件激活的时候启动，你可以在这个钩子函数里面定义插件的启动时候相关的逻辑。

export function deactivate() {
  
}

deactivate钩子函数是插件失活的时候触发的钩子函数，比如插件关闭的时候需要清理不需要的引用，你可以在这个函数中手动清除。

2.package.json

这个文件跟我们平时Vue项目中的package.json文件就不太一样了，

{
    "name": "hello-world",
    "displayName": "hello-world",
   "publisher"："mss-plugin"
    "description": "hello-world",
    "version": "0.0.1",
    "engines": {
        "vscode": "^1.51.0"
    },
    "categories": [
        "Other"
    ],
    "activationEvents": [
        
    ],
    "main": "./out/extension.js",
    "contributes": {
        
    },
    "scripts": {
    
    },
    "devDependencies": {
        
    }
}

我们这里只关注重点的字段，其他的字段就跟我们平时开发的vue项目的常规字段作用相同，就不一一介绍了：

• publisher
• engines
• activationEvents
• contributes

publisher字段表示发布的时候生成的私有名字，这个字段的值就是你在vscode应用市场发布的插件的名字，后面插件发布的时候会用到，这里就暂且先提一下。engines表示你使用的vscode引擎的版本，不同的版本API的使用方式可能会有所异同。activationEvents字段是配置触发刚才提到的extendion.js文件中active钩子函数的事件，后面会多次提到这个字段。contributes字段是对插件的一些配置，比如图标，菜单等。

五、跑起一个hello-world
先说实现的效果：我们在vscode的命令面板中出现vsplugin.helloWorld命令，当我们选择这个命令的时候，右下角弹出'欢迎打开新世界的大门'弹窗。话不多说，我们先去查阅文档：

看到文档左侧的GET STRTED的目录下面有Your First Extendion，查阅这个就会发现官网有相关的讲解，你想输出一个hello world，你需要这样做：

首先在我们的入口文件extendion.ts的插件激活函activate中注册一个命令，并定义好触发命令时vscode调用的回调函数

export function activate(context: vscode.ExtensionContext) {
    vscode.commands.registerCommand('vsplugin.helloWorld', () => {
        vscode.window.showInformationMessage('恭喜你，打开新世界的大门！');
    });
}

context: vscode.ExtensionContext这里的vscode就是vscode官方提供给我们调用它的所有API的实例，然后注意我们调用了vscode上面commands对象中的registerCommand方法，这个方法看名字似乎是注册命令的，我们去官网看一下：

找到REFERENCES下面的VS Code API，这里是官网供开发者查阅vscode所有API的一个集合，我们找到commands对象：

所有关于commands对象的方法都在这里有介绍，我们往下翻找到FENCTION:

可以发现传入两个参数，第一个参数是你传入的命令的名称，第二个参数是你命令指定的回调函数。我上面的例子就是按照官网的提示定义了命令和回调函数，同时定义了一个弹窗：

vscode.window.showInformationMessage

但这里仅仅是注册了一个命令和指定了命令的回调函数，我们的命令还没有出现在控制面板中，要想我们注册的命令出现在控制面板中，

我们就得回到开头说到的package.json配置文件中去配置：

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

同样的，我们去翻阅翻阅文档，找到REFERENCES下面的Contribution Points,所有关于配置相关的信息都在这个目录下面：

可以看到有很多的配置，这些配置包括了对vscode面板菜单、命令、快捷键、调试等等的配置，当你需要配置相关功能的时候你就可以来这里查找，我们选择我们需要的commands:

    "contributes": {
        "commands": [
            {
                "command": "vsplugin.helloWorld",
                "title": "helloWorld",
                "category": "demo1"
            }
    ]
    }

正如我们在介绍package.json文件的时候提到，所有vscode的配置都在contributes字段下面进行配置，所有关于命令相关的配置都在commands数组中配置，这也是符合我们预期的，因为我们可能需要需要配置多个命令。commands数组中的对象中的几个属性：

• command：刚才在extension中注册的命令 必须和这里保持一致
• title：命令名称
• 命令分类

当我们在package.json中配置后，使用command + shift + p打开命令面板就可以看到我们这个命令了：

面板中有了命令，但是我们还没有定义什么时候去触发我们的extension.ts中的active钩子函数，因为只有触发了这个钩子函数，我们才能触发里面命令对应的回调函数:

() => {
        vscode.window.showInformationMessage('恭喜你，打开新世界的大门！');
});

所以接着我们去配置下前面提到的activationEvents,这个字段表示在什么时候去激活extension.ts中的激活函数：

"activationEvents": [
        "onCommand:vsplugin.helloWorld"
    ],

可以看一下文档:

image-20201126152258839.png

可以看到有很多的激活事件(Activation Events)，能在激活事件(activationEvents)中配置的选项都在这里。我们需要的是键入命令的时候才激活钩子函数：

官网也给出了例子。

这样，我们的第一个hello-world就成功。如何看到效果呢？

• 按下F5键
• 在弹出的调试的vscode的窗口command + shift +p

就可以在右下角看到我们的弹窗：

这是vscode插件开发的第一篇，后续会陆续推出关于vscode开发的文章，所有的示例代码都在https://github.com/MssText/vscode-plugin-demo，有基础的同学可以先睹为快。