通过vscode-open-in-github-button学习如何开发一款vscode插件

0. 前言

本文参加了由公众号@若川视野 发起的每周源码共读活动，点击了解详情一起参与。

本篇是源码共读44期 | 神器啊，从未想过 VSCode 还能这样直接打开仓库URL，原理揭秘~，点击了解本期详情

1. 插件介绍

在 vscode 的状态栏上添加一个按钮用于跳转至项目 github 的仓库。

项目地址

2. 环境准备

拷贝项目，安装依赖

git clone <https://github.com/antfu/vscode-open-in-github-button> 
# 用vscode 打开项目 
code vscode-open-in-github-button 
# 安装依赖 
pnpm i

项目目录结构

    .
    ├── .github
    │   └── workflows
    │   └── FUNDING.yml
    ├── .vscode
    │   └── extensions.json
    │   └── launch.json
    │   └── tasks.json
    ├── LICENSE
    ├── README.md
    ├── package.json
    ├── pnpm-lock.yaml
    ├── pnpm-workspace.yaml
    ├── res
    │   └── icon.png
    ├── src     # 项目目录
    │   └── index.ts
    ├── test    # 测试目录
    │   └── index.test.ts
    ├── tsconfig.json
    └── tsup.config.ts

抛开工程化的配置不看，我们要关注的是 src下的代码

3.源码分析

其实项目源码就一个文件 src/index.ts ，代码就一个函数

import { StatusBarAlignment, window } from 'vscode'






export function activate() {
  ...
}





export function deactivate() {


}

3.1 activate 和 deactivate 函数

里面有两个函数，一个是 activate 一个是 deactivate 空函数

具体为什么仅仅只是导出了这两个函数，都没有执行，猜想应该是类似于生命周期函数，导致确定的函数名，在生命周期的不同阶段调用不同的函数。

先查阅一下 vscode 的官方文档看看，访问地址

The extension entry file exports two functions, activate and deactivate. activate is executed when your registered Activation Event happens. deactivate gives you a chance to clean up before your extension becomes deactivated. For many extensions, explicit cleanup may not be required, and the deactivate method can be removed. However, if an extension needs to perform an operation when VS Code is shutting down or the extension is disabled or uninstalled, this is the method to do so.

activate 是在注册的激活事件发生时执行，其实就是vscode打开激活的时候，只会执行一次。

deactivate 是用于在vscode停用之前清理的，但对大多数的扩展来说都不用上，可以移除。

3.2 核心代码

export function activate() {
	// 在状态栏的左边最后面创建一个元素
  const statusBar = window.createStatusBarItem(StatusBarAlignment.Left, 0)
	// 状态栏执行的命令，这里是一个字符串，说明是一个已经存在的命令，其实这样里是执行了 open-in-github 扩展的命令
  statusBar.command = 'openInGitHub.openProject'
	// 这里是设置元素的 icon
  statusBar.text = '$(github)'
	// 设置元素的文字提示
  statusBar.tooltip = 'Open in GitHub'
	// 在状态栏中显示该元素
  statusBar.show()
}

window是从 vscode 这个包中导出的对象，可以看一下官网的api介绍，主要是用于处理编辑器当前窗口的命名空间。即可见且活动的编辑器，以及用于显示消息、选择和要求用户输入的 UI 元素。

这里用到了 window 的 createStatusBarItem 方法，是用于创建状态栏下的元素的。可以看一下api介绍

createStatusBarItem(alignment?: StatusBarAlignment, priority?: number): StatusBarItem

接收两个参数，一个是对齐，一个是优先级，返回状态栏创建的元素。

下面是几个类型定义：

export enum StatusBarAlignment {






		/**
		 * Aligned to the left side.
		 */
		Left = 1,

		/**
		 * Aligned to the right side.
		 */
		Right = 2
	}



export interface StatusBarItem {

		/**
		 * The identifier of this item.
		 *
		 * *Note*: if no identifier was provided by the {@linkcode window.createStatusBarItem}
		 * method, the identifier will match the {@link Extension.id extension identifier}.
		 */
		readonly id: string;

		/**
		 * The alignment of this item.
		 */
		readonly alignment: StatusBarAlignment;

		/**
		 * The priority of this item. Higher value means the item should
		 * be shown more to the left.
		 */
		readonly priority: number | undefined;

		/**
		 * The name of the entry, like 'Python Language Indicator', 'Git Status' etc.
		 * Try to keep the length of the name short, yet descriptive enough that
		 * users can understand what the status bar item is about.
		 */
		name: string | undefined;

		/**
		 * The text to show for the entry. You can embed icons in the text by leveraging the syntax:
		 *
		 * `My text $(icon-name) contains icons like $(icon-name) this one.`
		 *
		 * Where the icon-name is taken from the ThemeIcon [icon set](<https://code.visualstudio.com/api/references/icons-in-labels#icon-listing>), e.g.
		 * `light-bulb`, `thumbsup`, `zap` etc.
		 */
		text: string;

		/**
		 * The tooltip text when you hover over this entry.
		 */
		tooltip: string | MarkdownString | undefined;

		/**
		 * The foreground color for this entry.
		 */
		color: string | ThemeColor | undefined;

		/**
		 * The background color for this entry.
		 *
		 * *Note*: only the following colors are supported:
		 * * `new ThemeColor('statusBarItem.errorBackground')`
		 * * `new ThemeColor('statusBarItem.warningBackground')`
		 *
		 * More background colors may be supported in the future.
		 *
		 * *Note*: when a background color is set, the statusbar may override
		 * the `color` choice to ensure the entry is readable in all themes.
		 */
		backgroundColor: ThemeColor | undefined;

		/**
		 * {@linkcode Command} or identifier of a command to run on click.
		 *
		 * The command must be {@link commands.getCommands known}.
		 *
		 * Note that if this is a {@linkcode Command} object, only the {@linkcode Command.command command} and {@linkcode Command.arguments arguments}
		 * are used by the editor.
		 */
		command: string | Command | undefined;

		/**
		 * Accessibility information used when a screen reader interacts with this StatusBar item
		 */
		accessibilityInformation: AccessibilityInformation | undefined;

		/**
		 * Shows the entry in the status bar.
		 */
		show(): void;

		/**
		 * Hide the entry in the status bar.
		 */
		hide(): void;

		/**
		 * Dispose and free associated resources. Call
		 * {@link StatusBarItem.hide hide}.
		 */
		dispose(): void;
	}

我们看到上面对于command的类型定义，可以是 string，也可以是 Command

在这里用的是string，我们搜索了整个代码仓库，并没有搜到有其他地方有这个命令。我们看一下 package.json 中有一个 extensionPack ，查阅了一下vscode官方文档，作用类似于dependencies，知道其实是依赖了 vscode-open-in-github 的命令，这里先不仔细探究vscode-open-in-github的代码，了解到这是打开项目的github地址就可以了，后面再细看里面的代码实现。

$(github) 是一个 vscode 用来以icon显示的语法，icon列表和使用说明可以查看 官网文档

剩下的就没什么好需要理解的了。

3.3 调试代码

官方给了如何调试扩展的说明，文档地址

打开断点，按 F5 就可以进入调试模式了。

4. 自己实现一个

学习一个知识点最好的方式就是自己动手敲一遍。

现在我们自己从0到1实现一个vscode插件，实现的功能跟 vscode-open-in-github-button 差不多。就是在状态栏中添加一个元素，点击跳转到仓库的地址，只不过这个地址从 package.json中直接获取，不做过多的处理。

4.1 初始化

开始一个react项目，有 create-vite 这样的脚手架，开发插件同样有个脚手架。具体我们可以看一下官方文档

全局安装依赖

npm install -g yo generator-code

执行创建项目

yo code

一些列选择之后，得到下面的目录

├── CHANGELOG.md
├── README.md
├── package.json
├── pnpm-lock.yaml
├── src
│   ├── extension.ts
│   └── test
│       ├── runTest.ts
│       └── suite
│           ├── extension.test.ts
│           └── index.ts
├── tsconfig.json
├── vsc-extension-quickstart.md
└── webpack.config.js

4.2 注册命令

项目模板已经帮我们写好了一个注册命令的示例代码

import * as vscode from 'vscode';






export function activate(context: vscode.ExtensionContext) {
	// vscode.commands.registerCommand 注册一个命令
  let disposable = vscode.commands.registerCommand('open-in-github-button2.helloWorld', () => {
    // 弹出提示信息
		vscode.window.showInformationMessage('Hello World from open-in-github-button2!');
  });


	// 往context的subsriptions中添加命令的注销函数
  context.subscriptions.push(disposable);
}




export function deactivate() {}

我们按 F5 进行调试一下， Commond + Shift + P ，输入 Hello World

我们会看到 vscode 的右下角有个信息提醒

为什么是输入 Hello World ，其实就是在 package.json 中定义的 contributes.commands

{
 "contributes": {
    "commands": [
      {
        "command": "open-in-github-button2.helloWorld",
        "title": "Hello World"
      }
    ]
  }
}

更详细的还是看 官方文档

然后我们将 commands里的命令修改成 openProject

"contributes": {
    "commands": [
      {
        "command": "open-in-github-button2.openProject",
        "title": "Open Project"
      }
    ]
  },

然后回到 src/extension.ts 把里面的注册命令修改一下

export function activate(context: vscode.ExtensionContext) {
  let disposable = vscode.commands.registerCommand('open-in-github-button2.openProject', () => {
    vscode.window.showInformationMessage('open project');
  });


  context.subscriptions.push(disposable);
}

然后输入 Open Project 就可以在右下角弹出 open project 信息了。

4.3 实现逻辑

接下来编写 openProject 函数

export function activate(context: vscode.ExtensionContext) {
  let disposable = vscode.commands.registerCommand(
    'open-in-github-button2.openProject',
    openProject
  );




  context.subscriptions.push(disposable);
}


function openProject() {
  const workspace = `${vscode.workspace.rootPath}/package.json`;
  const packageBuffer = fs.readFileSync(workspace);



  if (packageBuffer) {
    const packageJSON = JSON.parse(packageBuffer.toString());

    const url = packageJSON?.repository?.url.replace('git+', '');
    if (url) {
      vscode.window.showInformationMessage(`open project: ${url}`);
      return;
    }
  }
  vscode.window.showInformationMessage(`repository.url is not found in package.json`);
}

这里主要的是如何获取当前仓库的根目录，从而拿到 packagae.json , 从 package.json 中读取 repository.url。vscode提供了 workspace 对象，用来处理当前工作空间的一些相关信息。通过 vscode.workspace.rootPath 就可以拿到根目录了，再拼上一个 package.json。然后用fs去读取 package.json中的内容，从而解析出 repository.url.其中 replace('git+', '') 是为了解决部分地址用 git+url 的形式。

下一步就是打开链接。

其实也比较简单，vscode提供了对应的api vscode.env.openExternal ，可以查看对应的文档

// vscode.window.showInformationMessage(`open project: ${url}`);
 vscode.env.openExternal(url);

这样就可以打开对应的仓库地址啦。

4.4 添加状态栏

let statusBar = vscode.window.createStatusBarItem(vscode.StatusBarAlignment.Left, 0);






  statusBar.command = 'open-in-github-button2.openProject';
  statusBar.tooltip = 'Open in Github';
  statusBar.text = '$(github-inverted)';
  statusBar.show();

现在这样整个代码逻辑就全部完成了

5. 再看 vscode-open-in-github 源码

5.1 入口文件

/* IMPORT */






import Utils from './utils';

/* ACTIVATE */




const activate = Utils.initCommands;


/* EXPORT */

export {activate};

5.2 注册

const Utils = {
  initCommands(context: vscode.ExtensionContext) {
    const { commands } = vscode.extensions.getExtension(
      "fabiospampinato.vscode-open-in-github"
    ).packageJSON.contributes;




    commands.forEach(({ command, title }) => {
      const commandName = _.last(command.split(".")) as string,
        handler = Commands[commandName],
        disposable = vscode.commands.registerCommand(command, () => handler());

      context.subscriptions.push(disposable);
    });

    return Commands;
  }
}

commands 在 package.json 中定义，通过 vscode.extensions.getExtension 获取自身的package.json 中的 commands ，然后遍历注册。

5.3 commands的实现

再看一下commands的实现，看其中一个 openProject

import URL from './url';






function openProject () {
  return URL.open ();
}

再看一下 URL

const URL = {
  ...
  async open(file = false, permalink = false, page?) {
    const url = await URL.get(file, permalink, page);


    vscode.env.openExternal(vscode.Uri.parse(url));
  },
};

[URL.open](<http://URL.open>) 调用了 URL.get 来获取地址。 URL.get 又调用了 Utils.repo 的几个方法

代码行数有点多，但逻辑都比较简单，就不贴上来了。

主要用了 simple-git 这个包来获取当前仓库的一些信息，地址、分支等等。然后拼接出各种地址。获取到后，用 vscode.env.openExternal 打开。

6.总结

了解到了一个简单的 vscode 插件的开发流程。还有一些工程化的东西也非常值得学习，有兴趣的大家可以自己查看。比如 tsup 打包、 bumpp 自动升版本号等等。对于自己去搭建一个工程化项目还是很有帮助的。