VS Code 插件開發之從 0 到 1

VS Code 插件能作什麼

• 改變 VS Code 的顏色和圖標主題——主題
• 在 UI 中添加自定義組件和視圖——擴展工做臺
• 建立 Webview，使用 HTML/CSS/JS 顯示自定義網頁——Webview 指南
• 支持新的編程語言——語言插件概覽
• 支持特定運行時的調試——調試插件指南

初始化項目

安裝腳手架，生成 VS Code 插件項目

# 安裝
yarn global add yo generator-code

# 生成一個能夠立馬開發的項目
yo code

進入你生成的項目中，按下 F5，你會看到一個插件發開主機窗口，其中就運行着插件。

在命令面板(Ctrl+Shift+P) 中輸入Hello World命令，並回車，若是你看到了 Hello World 提示彈

窗，恭喜你，你的第一個簡單的插件就建立成功了 ！

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": "幫助"
            }
        ]
    }
}

動態建立樹視圖

某些狀況下，樹視圖可能須要動態展現，則可使用 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