VS Code 插件开发之从 0 到 1

VS Code 插件能做什么

• 改变 VS Code 的颜色和图标主题——主题
• 在 UI 中添加自定义组件和视图——扩展工作台
• 创建 Webview，使用 HTML/CSS/JS 显示自定义网页——Webview 指南
• 支持新的编程语言——语言插件概览
• 支持特定运行时的调试——调试插件指南

初始化项目

安装脚手架，生成 VS Code 插件项目

# 安装
yarn global add yo generator-code

# 生成一个可以立马开发的项目
yo code

image

进入你生成的项目中，按下 F5，你会看到一个插件发开主机窗口，其中就运行着插件。

在命令面板(Ctrl+Shift+P) 中输入Hello World命令，并回车，如果你看到了 Hello World 提示弹

窗，恭喜你，你的第一个简单的插件就创建成功了 ！

image

How this work

Hello World插件包含了 3 个部分：

• 注册onCommand 激活事件: onCommand:extension.helloWorld，所以用户可以在输入Hello World命令后激活插件。
• 使用contributes.commands 发布内容配置，绑定一个命令 ID extension.helloWorld，然后 Hello World命令就可以在命令面板中使用了。
• 使用commands.registerCommand VS Code API 将一个函数绑定到你注册的命令 IDextension.helloWorld上。

打开 src/extension 文件，我们可以看到处理 hello world 命令的函数

import * as vscode from "vscode";

// 插件激活
export function activate(context: vscode.ExtensionContext) {
  // 注册命令，即在命令面板中显示的命令
  let disposable = vscode.commands.registerCommand("ext.helloWorld", () => {
    // 显示 hello world 弹窗
    vscode.window.showInformationMessage("Hello World from ext!");
  });

  // 订阅
  context.subscriptions.push(disposable);
}

export function deactivate() {}

此外，在 package.json 文件中可以看到命令注册相关的配置

{
  "activationEvents": ["onCommand:ext.helloWorld"],
  "contributes": {
    "commands": [
      {
        "command": "ext.helloWorld",
        "title": "Hello World"
      }
    ]
  }
}

简单的 Hello World 插件已经蕴含了开发 VS Code 插件的关键点：

• 激活事件：决定插件激活的时机
• 发布内容配置：注册插件的能力，如命令，UI，调试
• VS Code API： 使用 VS Code API 实现插件的能力

大体上，插件就是通过组合发布内容配置和 VS Code API 扩展 VS Code 的功能。

命令

命令会触发 VS Code 中注册过的行为，命令是插件与用户交互的重要渠道，VS Code 插件的诸多功能都需要结合命令实现逻辑。

新建命令

使用 vscode.commands.registerCommand 创建新的命令，并绑定处理逻辑

import * as vscode from "vscode";

export function activate(context: vscode.ExtensionContext) {
  const command = "myExtension.sayHello";

  const commandHandler = (name?: string = "world") => {
    console.log(`Hello ${name}!!!`);
  };

  const cmd = vscode.commands.registerCommand(command, commandHandler);

  context.subscriptions.push(cmd);
}

执行命令

执行命令的路径有多种

• 使用 vscode.commands.executeCommand('commandId', args)
• 用户通过命令面板执行
• 通过配置绑定命令触发执行，如右键菜单绑定命令触发执行

仅通过 registerCommand 注册的命令可以通过executeCommand 执行，但不会显示在命令面板中，需要在 package.json中配置对应的命令配置项(contribution)：

{
  "contributes": {
    "commands": [
      {
        "command": "myExtension.sayHello",
        "title": "Say Hello"
      }
    ]
  }
}

命令激活场景

面向用户的命令需要配置命令激活的场景，否则无法被触发。

{
  "activationEvents": ["onCommand:myExtension.sayHello"]
}

让菜单项只显示在命令面板中

注册的命令默认显示在命令面板中。要想控制命令的可见性，我们提供了一个commandPalette菜单配置，在这个配置中，你可以定义一个when控制是否在命令菜单中显示。

下面的片段只在编辑器中选中了什么东西的时候才会在命令面板中显示出 "Hello World"：

{
  "contributes": {
    "menus": {
      "commandPalette": [
        {
          "command": "myExtension.sayHello",
          "when": "editorLangId == markdown"
        }
      ]
    }
  }
}

内置命令

VS Code API 也提供了一些内置命令，我们可以调用这些命令实现一些系统级的能力

• vscode.openFolder 打开文件夹
• vscode.open 打开提供的资源，如 URL，文件等

Built-in Commands

树视图（Tree View）

树视图是 VS Code 中比较常见的功能，我们常用的资源管理器就是一种树视图。插件可以使用树视图支持简单的 UI 操作。

视图容器与树视图

视图容器包含了一列视图(views)，这些视图又包含在内置的视图容器中。

目前只可以配置活动栏（activitybar），下面的示例展示了活动栏中的云开发视图容器是如何配置的:

• 配置视图容器：在package.json中的contributes.viewsContainers 中配置以下字段
  • id: 新视图容器的名称
  • title: 展示给用户的视图容器名称，它会显示在视图容器上方
  • icon: 在活动栏中展示的图标
• 配置树视图：在 package.json中的 contributes.views 中给视图配置一个 Id 外加一个名称

{
  "contributes": {
    "viewsContainers": {
        "activitybar": [
            {
                "id": "tcb",
                "title": "云开发 Toolkit",
                "icon": "assets/logo.svg"
            }
        ]
    },
    "views": {
        "tcb": [
            {
                "id": "tcb.views.function",
                "name": "已部署云函数"
            },
            {
                "id": "tcb.views.help",
                "name": "帮助"
            }
        ]
    }
}

image

动态创建树视图

某些情况下，树视图可能需要动态展示，则可以使用 createTreeView 创建动态的树视图。FtpTreeDataProvider 需要实现 vscode.TreeDataProvider 定义的方法，

vscode.window.createTreeView("ftpExplorer", {
  treeDataProvider: new FtpTreeDataProvider(),
});

树视图操作

我们可以配置视图下述位置的操作：

• view/title: 标题位置显示的操作
• view/item/context: 每个视图项的操作

image

例如

{
  "contributes": {
    "menus": {
      "view/title": [
        {
          "command": "tcb.refresh",
          "group": "navigation"
        }
      ],
      "view/item/context": [
        {
          "command": "tcb.viewFunction",
          "group": "group@order"
        }
      ]
    }
  }
}

发布插件

当完成了一个高质量的插件后，我们可以将它发布到 VS Code 扩展市场，这样其他人就可以找到、下载并使用我们的插件了。或者，我们可以将扩展打包为可安装的 VSIX 格式，直接分享给其他用户使用。

安装 VSCE

VSCE，即 Visual Studio Code Extensions，是一个用于打包、发布和管理 VS Code 插件的命令行工具。

# 安装
npm install -g vsce

# 将插件打包成 .vsix 文件
vsce package

发布检查

在发布插件到市场前，最好检查一下插件的配置是否符合规范

• README：介绍你的插件，帮助他人更好的了解这个插件
• name：插件的名称，必须用全小写，无空格的字母组成
• version：SemVer 版本模式兼容
• publisher：发行方名称
• displayName：插件市场所显示的插件名称
• icon：插件的 Logo
• description：简单地描述一下你的插件是做什么的
• keywords：关键字数组，这样用户可以更方便地找到你的插件
• main：插件入口

发布

在你检查完插件信息，准好好发布后，你可以使用下面的命令直接将插件发布到市场中

vsce publish

更新

vsce 支持通过 SemVer 语义标识符：major，minor，patch 增量更新插件版本号。例如，你想把插件从 1.0.0 更新到 1.1.0，那么加上minor：

vsce publish minor

插件 package.json 的 version 会先更新，然后才发布插件

参考文档

• VS Code API

  VS Code API

• When 语法

  microsoft/vscode-docs