VSCode笔记之插件开发

1. 前言

本文将描述 VSCode 插件开发的相关内容，以供读者和笔者后续查阅参考。

1.1 背景

首先，我们应当知道，VSCode 是基于 electron 开发的，VSCode 的主界面（功能页面）类似于在 Chrome 打开了 web 页面一般。因此 VSCode 插件开发类似于 Chrome 插件的开发。Chrome 插件、VSCode 插件的 API 及开发规范是由不同的公司和团队设计，因此在 API 上有所区别，但本质是相近的。

1.2 快速入门

关于快速入门这块的内容，推荐如下内容：

• 官方文档-快速入门
• VSCode 插件开发全攻略
• VSCode 插件开发文档

由于快速入门的资料非常多，所以笔者不再赘述。

1.3 核心概念

1.3.1 清单文件

官方文档-清单文件

package.json

插件的一些基础信息均在该文件中配置，比如：右键菜单&快捷键、激活事件等。

1.3.2 业务代码

VSCode 插件默认使用 typescript 开发（官方脚手架所生成的项目是基于 webpack 构建的），支持 nodejs 及 VSCode 所提供的各种 API，亦支持使用 npm 之类的工具安装三方依赖包。

2. 插件开发

本小节将介绍 VSCode 插件开发过程中的意事项以及关于常用功能的内容。

2.1 激活事件(activationEvents)

官方文档-激活事件

在 VSCode 中，插件都是懒加载的，需要向 VSCode 提供插件激活的时机。

2.1.1 指令的位置

package.json

2.1.2 配置规则

目前支持如下配置：

• onLanguage
• onCommand
• onDebug
• onDebugInitialConfigurations
• onDebugResolve
• workspaceContains
• onFileSystem
• onView
• onUri
• onWebviewPanel
• onCustomEditor
• *
• onStartupFinished

特别注意：

• 值的格式是 string[]，比如："activationEvents": ["onStartupFinished"]。

string[]

2.2 右键菜单&快捷键

官方文档-Contribution Points

2.2.1 指令的位置

package.json

2.2.2 示例

官方文档-Menus
官方文档-Keybindings

// package.json

{
  "contributes": {
    "commands": [
      {
        "command": "explorer",
        "title": "Shawn Explorer"
      }
    ],
    "menus": {
      "editor/title/context": [
        {
          "command": "explorer",
          "group": "z_commands@1",
          "when": ""
        }
      ],
      "explorer/context": [
        {
          "command": "explorer",
          "group": "z_commands@1",
          "when": ""
        }
      ]
    },
    "keybindings": [
      {
        "command": "explorer",
        "key": "ctrl+shift+f11",
        "mac": "cmd+shift+f11"
      }
    ]
  }
}

特别说明：

• 在配置“右键菜单&快捷键”时，需要先在contributes.commands声明指令，然后在 typescript 代码中，使用vscode.commands.registerCommand(command, fn)实现指令所对应的业务逻辑。
• 由于 VSCode 的插件是懒加载的(具体请查阅“2.1”小节的内容)，如果指令所对应的vscode.commands.registerCommand(command, fn)未被执行，那么即使在package.json配置了“右键菜单&快捷键”，也无法按照预期来响应所期待的行为。

2.3 打包&发布

官方文档-发布插件

首选安装vsce，安装命令如下：

• npm install -g vsce

2.3.1 创建Token

请参照官方文档创建“publisher”和个人访问令牌(Personal Access Tokens)。

特别注意：
创建个人访问令牌(Personal Access Tokens)的时候，组织(Organization)请选择“All accessible organizations”，范围(Scopes)请选择“Full access”。

2.3.2 添加publisher

1. 在package.json文件里增加publisher字段，
2. 使用vsce login publisher_name登录，登录时使用个人访问令牌(Personal Access Tokens)来做账户验证

2.3.3 确保readme.md符合内容要求

2.3.3.1 常见错误

• Make sure to edit the README.md file before you package or publish your extension.

  解决办法：请在README.md文件中添加 http 地址(如果只是打包可以添加http地址，如果是发布README.md中的资源必须全部是HTTPS的，如果是HTTP会发布失败）。

2.3.4 指定插件的图标

在package.json文件里增加"icon": "assets/images/tools.png"(assets放在项目的根目录中)，请注意图标的大小至少为 128x128 像素（对于 Retina 屏幕为 256x256）。

2.3.5 打包

打包命令：

• vsce package

打包之后所生成的.vsix文件，默认在项目的根目录。

2.3.6 发布

发布之后，README.md文件默认会显示在插件主页；CHANGELOG.md会显示在变更选项卡。发布成功后等待几分钟才能在应用市场搜到所发布的插件。

发布有两种方式：

• 使用 vsce 工具发布
• 仅使用 vsce 打包，使用web管理平台手动发布

2.3.6.1 全量发布

发布命令：

• vsce publish

修改了代码之后，重新发布也可以执行这个命令。

2.3.6.2 增量发布

发布命令：

• vsce publish patch

增量发布是根据版本号来做的，版本号：major.minor.patch。执行vsce publish patch后会自动修改package.json里面的版本号。也可以根据需要写成vsce publish minor、vsce publish major。

2.3.6.3 取消发布

vsce unpublish publisher_name.extension_name