Noah's Blog
0%

简单VSCode插件开发实践

发表于 更新于

本篇博客通过vscode插件“Hexo3StepHelper”一键发布

偶尔杀鸡用用牛刀也许不算坏

背景

在以Hexo为框架的个人博客上对文章进行修改后，需要通过三条hexo指令将修改更新到网络上：

1
2
3
$ hexo clean
$ hexo g
$ hexo d

博客每一次有一点的更改，甚至只改一个字，也需要输入这三条指令进行上传，未免有些繁琐。于是，我将这三条指令写进了一个批处理文件中，每次修改后执行一次bat文件便能完成上传。

由于在VSCode里写博客，每次打开bat文件仍然需要输入指令，尽管并不麻烦，但我仍然觉得不够意思。有没有一种方式，能一键进行上传呢？自然而然，我想到了VSCode的插件。

从软件的分类来说，Visual Studio属于集成开发环境（IDE），即集成了文本编辑器、编译器、调试器、用户图形界面等一系列元素的软件；而Visual Studio Code(VSCode) 属于文本编辑器，只具备文本编辑功能。但是，VSCode的插件功能给予了它极大的自由。通过安装插件，能对VSCode的功能进行扩展，使其具备IDE的各种功能。同时，VSCode对插件的开发也有很好的支持和活跃的社区。

环境搭建

在正式开发自己的插件之前，需要先搭建开发环境。

开发VSCode插件需要官方提供的两个包：

  1. Yeoman：通用型项目的脚手架工具，可以通过一套模板，生成对应的项目结构。
  2. generator-code：VS Code扩展生成器，与yo配合使用才能构建项目。

两个包通过npm命令安装：

1
2
$ npm install -g yo
$ npm install -g generator-code

安装完这两个包，环境也就搭建完成了。

开发之前

打开想要开始开发的路径，输入命令：

1
$ yo code

便会进入一串信息的输入，用于构建相应的框架。

  1. What type of extension do you want to create? (Use arrow keys) （即将构建的插件的类型）：

这里根据自己的需求选择就好，作为新手，我们可以选择js语言的extension。

  1. What’s the name of your extension? （插件的名称）：

如题，输入插件的名称。

  1. What’s the identifier of your extension? (myfirstextension) （插件的标识符）：

每个插件在上架VSCode扩展商店前，需要提供一个唯一的标识符，用于识别。

  1. Enable JavaScript type checking in ‘jsconfig.json’? （JS的类型检测）

  1. Initialize a git repository? （是否创建Git仓库）

  1. Which package manager to use? （使用哪个包管理器）

等待命令执行完毕，点击调试按钮，会弹出另一个vscode窗口[扩展开发宿主]，这个即是我们调试的插件的环境。

快捷键Ctrl+Shift+P调出命令窗口，向其中输入”Hello World”

输入结束后回车，窗口右下角出现信息提示，便说明插件成功运行了。

开始开发吧！

VSCode插件的主要文件结构如下图，作为新手，我们最需要关注的是其中的packge.json和extension.js。

package.js

这个文件描述了vscode插件的基本信息，具体内容见下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
{
  "name": "myfirstextension",                       //包名
  "displayName": "MyFirstExtension",                //插件名
  "description": "This is my first extension.",     //插件的描述
  "version": "0.0.1",                               //插件的版本号
  "engines": {                                      //插件支持的最低vscode版本
    "vscode": "^1.71.0"
  },
  "categories": [                                   //插件在商店中的分类
    "Other"
  ],
  "activationEvents": [                             //插件被激活时的事件
    "onCommand:myfirstextension.helloWorld"
  ],
  "main": "./extension.js",
  "contributes": {                                  //贡献点
    "commands": [{                                  //这里定义新命令，将在后面的extension.js中实现
      "command": "myfirstextension.helloWorld",
      "title": "Hello World"
    }]
  },
  "scripts": {                                      //脚本
    "lint": "eslint .",
    "pretest": "npm run lint",
    "test": "node ./test/runTest.js"
  },
  "devDependencies": {                              //依赖的一些版本信息
    "@types/vscode": "^1.71.0",
    "@types/glob": "^7.2.0",
    "@types/mocha": "^9.1.1",
    "@types/node": "16.x",
    "eslint": "^8.20.0",
    "glob": "^8.0.3",
    "mocha": "^10.0.0",
    "typescript": "^4.7.4",
    "@vscode/test-electron": "^2.1.5"
  }
}

extension.js

这个JavaScript文件是插件执行的入口，具体内容见下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
// The module 'vscode' contains the VS Code extensibility API
// Import the module and reference it with the alias vscode in your code below
// 导入vscode模块，这个模块包括了一些与vscode交互的扩展接口
const vscode = require('vscode');

// this method is called when your extension is activated
// your extension is activated the very first time the command is executed
// 当插件被激活时，会调用activate函数
function activate(context) {

	// 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来输出
	console.log('Congratulations, your extension "myfirstextension" 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
    // 这里注册了一个命令，给在package.json中定义的命令提供了实现，当命令每次执行时，这里的方法都会被执行
	let disposable = vscode.commands.registerCommand('myfirstextension.helloWorld', function () {
		// The code you place here will be executed every time your command is executed

		// Display a message box to the user
        // showInformationMessage方法可以通过信息窗口输出信息
		vscode.window.showInformationMessage('Hello World from MyFirstExtension!');
	});

    //这句是插件模板语句
	context.subscriptions.push(disposable);
}

// this method is called when your extension is deactivated
//当插件被销毁（可以理解为关闭）时会调用deactivate方法
function deactivate() {}

//每个插件都必须包含activate和deactivate模块
module.exports = {
	activate,
	deactivate
}

打包与发布

插件在完成编写后，可以通过几种方式分享给别人。

如果插件只是开发来自己使用或者在小范围内使用的话，只需要将打包后的插件发送给使用者，使用者在本地安装就可以了。如果想要将自己的插件在互联网中分享，那么将插件上架到vscode的插件市场，那么所有人都可以下载安装你的插件。

打包发布插件需要vsce工具，通过命令安装：

1
$ npm install -g vsce

安装完成后，在插件的根目录里执行命令便可以对插件进行打包。

1
$ vsce package

打包后文件夹中会出现一个插件名.vsix的文件，这个便是打包后的插件了。在vscode中双击该文件，便可以进行安装使用了。

注意：打包插件前需要修改README.md文件，否则无法进行打包。

将插件发布至扩展市场，需要注册一个开发者账号，具体步骤可以参考官方文档

  1. 在Visual Studio Team Services注册一个账号
  2. 创建Personal Access Token

获取对应的token后，在插件根目录里执行命令：

1
$ vsce login 你的用户名

然后输入获得的token，便完成了账号的绑定。

再执行：

1
$ vsce publish

这样插件便发布到了扩展市场，稍后便可以在网页或vscode的插件市场里搜索到自己的插件了。

如果需要升级已发布的插件，只需要修改版本号再执行vsce publish即可。

目的达成

经历了一番折腾后，我的第一个插件Hexo3StepHelper成功实现了一键更新博客（这篇博客便是通过Hexo3StepHelper一键发布），插件也成功发布到了vscode的扩展市场里，可以被任何人搜索到，后续也会不断更新新功能。也欢迎用vscode和Hexo搭配写博客的朋友试试Hexo3StepHelper，期待着大家的宝贵意见。