VS Code 插件开发之从 0 到 1

时间 2020-07-10

标签 code 插件开发繁體版

原文原文链接

VS Code 插件能作什么

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

初始化项目

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

# 安装
yarn global add yo generator-code

# 生成一个能够立马开发的项目
yo code

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

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

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

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 命令的函数json

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 文件中能够看到命令注册相关的配置api

{
  "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 的功能。bash

命令

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

新建命令

使用 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": "帮助"
            }
        ]
    }
}

动态建立树视图

某些状况下，树视图可能须要动态展现，则可使用 createTreeView 建立动态的树视图。FtpTreeDataProvider 须要实现 vscode.TreeDataProvider 定义的方法，

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

树视图操做

咱们能够配置视图下述位置的操做：

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

例如

{
  "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