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

nodegit的安装和使用各位同学就自行百度了,我们主要讲解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.tspackage.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,有基础的同学可以先睹为快。

推荐阅读更多精彩内容