“改造” VS Code 編輯器，一起寫個外掛吧！

削微寒發表於2021-04-19

作者：HelloGitHub-小夏（首發於 HelloGitHub 公眾號）

作為一個靠程式碼作為“生計”的開發者，bug 寫的好不好，編輯器真的很重要！那麼 Visual Studio Code 這個大名你肯定不會陌生。作為一個老厲害的編輯器，它的過人之處簡單講講來說有這麼幾點：

  • 首先，它的設計者是一個很有名的工程師：Eric Gamma。20年前，他是《設計模式：可複用物件導向軟體的基礎》的作者之一，這本書在開發社群的地位被視為物件導向軟體開發的指路明燈（瞻望大佬）。

  • 其次，對於寫 JavaScript 的人來說，雖然市面上有很多大大小小不同的編輯器，比如 sublime、atom、webstorm 等等，VS Code 與他們區別在於他比 sublime 開源，比 atom 更快，比 webstorm 更輕。

一、介紹

VS Code 全名 Visual Studio Code 是微軟開源的一款編輯器，GitHub 上標星 115k（11 萬）。它是基於 TypeScript 編寫，總計程式碼數量在 30 萬以上，大型知名開源專案。

專案地址：https://github.com/microsoft/vscode

我們先來簡單看一下它的產品定位吧～可以看到，專案作者對它的定位屬於輕量級的編輯器，所以要求它輕量、響應速度快，適用於多種語言等等。VS Code 的編輯能力來自於一款同樣來自微軟叫做 monaco 的開源 Web 編輯器，同時為了實現跨平臺的需求又引入了 Electron：一個使用 JavaScript，HTML 和 CSS 構建跨平臺的桌面應用程式。

正因為有了清楚的定位和方向，才會有了更加清晰的邊界。或許你很疑惑，他是怎麼支援多種語言的又做到輕量級的？那我們不得不來看一下它的多程式架構。

  • VS Code 有一個主程式入口，負責一些視窗管理、程式間通訊、自動更新等全域性任務；
  • 渲染程式，顧名思義負責一個 Web 頁面的渲染；
  • 外掛宿主程式，每個外掛的程式碼都執行在一個獨立且隔離的 Node 環境的宿主程式中，外掛無法訪問 UI；
  • Debug 程式，用於除錯；
  • 語言服務，是一種重要的特殊擴充，可以為許多程式語言提供編輯體驗，還可以實現 VS Code 支援的自動補充，錯誤檢查（診斷），跳轉到定義以及許多其他的語言功能。

最核心的部分就是它的外掛系統，為編輯器的擴充帶來了更加個性化的開源定製。只要你能找到強大的 VS Code 外掛組合在一起，那你的編輯器一定是一個高階且高效率的工作好幫手。

先來看一下，VS Code 大致有哪些可供我們擴充的能力。

有沒有心癢癢地想自己動手搞一個 VS Code 外掛？下面就帶大家做一個入門級的 VS Code 外掛。

二、環境準備

首先你搞個 Node.js 和 Git。

其次「全域性（-g）」安裝 Yeoman（現代 Web 應用程式腳手架工具）和 VS Code Extension Generator 這兩個官方指定的工具腳手架（生成 VS Code 外掛專案的工具）。

npm install -g yo generator-code

當你看到下面的資訊就說明安裝成功了：

三、初始化專案結構

依賴環境搞好了，接下來就要用到 Yeoman 這個工具來幫我們快速建立專案結構啦！可能有很多人對這個腳手架不熟悉，簡單的說，Yeoman 是一個通用的腳手架系統，它允許建立任何型別的應用程式。你可以用它快速開始新專案。所以不僅僅是 JavaScript 這個語言，Java，Python，C＃等都可以用它來生成專案，只要有對應的生成器就可以。那我們進行下一步，在命令列中輸入 yo code。

讓我們來分析一下這幾個選項的意思，其實和字面意思一樣，從上到下：

  • 新的外掛（Typescript）
  • 新的外掛（JavaScript）
  • 新的主題顏色
  • 新的語言支援
  • 新的程式碼片段
  • 新的鍵值繫結
  • 新的外掛包
  • 新的語言包（本土化）

你可以看到這個工具支援建立多種型別的專案，我們今天先從外掛（Extension）入手，所以第一個和第二個的區別就是，你要是會用 TypeScript 就選第一個，也是官方推薦的一個；要是不想寫各種麻煩的型別定義和型別校驗，就選第二個 JavaScript。
這一次我們選 JavaScript 來做一個簡單的入門， 隨後你會需要填寫一系列初始化的資訊如下：

註釋如下：

  • What type of extension do you want to create?（建立哪一種型別的擴充套件？）
  • What's the name of your extension?（擴充套件的名稱？應該全部為小寫字母，沒有空格）
  • What's the identifier of your extension?（擴充套件的標示？）
  • What's the description of your extension?（擴充套件的描述是什麼？）
  • Initialize a git repository?（是否初始化 git 倉庫？）
  • Which package manager to use? （因為我們裝的是 npm，所以選 npm 就行了，如果你有 yarn，你也可以選 yarn）
  • 使用哪一種包管理器（來下載各種 npm 包）

四、搞一個簡單的 VS Code 外掛

前面的準備的差不多啦！那我們就要開始開「綠皮小火車」啦。

進入剛建立的檔案目錄 cd test-extension，檔案目錄：

或許你覺得檔案目錄嘛，一看就知道了，不就是幾個配置資訊或者專案說明嘛，但是這裡面的配置資訊「非常重要」x3，重要到你可能少一個配置或者配置的不對，功能就出不來。所以我們還是稍微花點筆墨聊聊這裡的資訊。

首先你可以在 package.json 檔案裡面，看到自己在前一個步驟裡面設定的各個值，配置內的各個主要的含義如下，這裡有個小點注意一下，如果你的 VS Code 比較舊，且更新不了最新的，你就把下面的 engines 設定的版本低一點，比如我就改成了 ^1.52.0 確保一定能相容目前的 VS Code 編輯器就可以 :

{
  "name": "test-extension", // 外掛的名字
  "displayName": "test-extension", // 在外掛市場展示的名字
  "description": "vscode extension sample", // 外掛描述
  "version": "0.0.1", // 外掛版本
  "engines": { // 最低支援 vscode 的版本
    "vscode": "^1.52.0"
  },
  "categories": [ // 外掛的類別，用於在外掛市場做區分
    "Other"
  ],
  "activationEvents": [ // 外掛啟用的事件列表，可以有多個觸發機制，所以是陣列形式
    "onCommand:test-extension.helloWorld"
  ],
  "main": "./extension.js", // 外掛主入口
  "contributes": { // 貢獻點，用於擴充外掛功能的配置項，這裡不會細講，先用 command 舉例
    "commands": [
      {
        "command": "test-extension.helloWorld",
        "title": "Hello World"
      }
    ]
  },
  "scripts": {
    "lint": "eslint .",
    "pretest": "npm run lint",
    "test": "node ./test/runTest.js"
  },
  "devDependencies": {
    "@types/vscode": "^1.55.0",
    "@types/glob": "^7.1.3",
    "@types/mocha": "^8.0.4",
    "@types/node": "^12.11.7",
    "eslint": "^7.19.0",
    "glob": "^7.1.6",
    "mocha": "^8.2.1",
    "typescript": "^4.1.3",
    "vscode-test": "^1.5.0"
  }
}

熟悉了配置之後，我們再來看一下外掛的入口檔案 extsnsion.js ，裡面主要有兩個主要的函式，一個是 activate 表示啟用外掛時的處理，一般是註冊命令等一些初始化的操作；另一個是 deactivate ，表示外掛失活的時候做的處理，其實聽名字你也應該有體感，這就是外掛的生命週期裡的兩個鉤子函式嘛。

// 引了 vscode 這個模組，這樣你就可以用它裡面的很多很多功能啦
const vscode = require('vscode');

/**
 * @param {vscode.ExtensionContext} context
 */
function activate(context) {

  console.log('Congratulations, your extension "test-extension" is now active!');

  let disposable = vscode.commands.registerCommand('test-extension.helloWorld', function () {
    vscode.window.showInformationMessage('Hello World from test-extension!');
  });

  context.subscriptions.push(disposable);
}

function deactivate() {}

module.exports = {
  activate,
  deactivate
}

我們來分析一下上面這段程式碼，你可以看到裡面 registerComman 了一個命令，是不是有種似曾相識的感覺？沒錯，就是上面在 package.json 裡面有提到的那個 command，讓我們摘出來一起看看：

...,
 // package.json
 "contributes": { // 貢獻點，用於擴充外掛功能的配置項，這裡不會細講，先用 command 舉例
    "commands": [
      {
        "command": "test-extension.helloWorld",
        "title": "Hello World"
      }
    ]
  },
...

...
// extension.js
function activate(context) {
  console.log('Congratulations, your extension "test-extension" is now active!');

  let disposable = vscode.commands.registerCommand('test-extension.helloWorld', function () {
    vscode.window.showInformationMessage('Hello World from test-extension!');
  });

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

這樣看起來是不是很直觀了？在 package.json 裡面設定的 command 的值，就是 extension.js 裡面 registerCommand 的值。那這幾行命令是什麼意思呢？讓我們一起來執行看看：

他會幫你開啟一個新的 VS Code 編輯器，外掛只會載入到這個編輯器中。現在我們使用呼叫快捷鍵（MacOS） command+p ，輸入 >Hello World （不區分大小寫）：

回車一下，你會發現在右下角一個不起眼的角落裡輸出了這麼一個提示：

我相信聰明的你們結合程式碼一定已經恍然大悟了對不對！不知道你們有沒有這個疑問，上面那個 console.log 去哪裡看？別急，我們回到外掛程式碼的那個編輯器中，仔細看下面這邊，他會在我們輸入上面的命令之後才出現，因為在 package.json 裡面我們配置外掛的啟用時機就是 onCommand:test-extension.helloWorld ：

那我們現在抱著「刻意學習」的思路，改一下上面的程式碼，比如把 test-extension 改成 test ：

...,
// package.json
"activationEvents": [
    "onCommand:test.helloWorld"
],
...,
"contributes": {
  "commands": [
    {
      "command": "test.helloWorld",
      "title": "Hello World"
    }
  ]
},
...

// extension.js
...
function activate(context) {

  console.log('我在這裡！！');

  let disposable = vscode.commands.registerCommand('test.helloWorld', function () {
    vscode.window.showInformationMessage('我改變了 command 的名字!');
  });

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

再按照上面說的觸發方法再來一遍，發現依舊是可以的！所以這裡的名字只是一個名稱空間，你可以改成你想要的任何名字，來適用於比較複雜的外掛體系。既然是個名稱空間，那其實不要這個字首也可以。

五、實現一個屬於自己的外掛

前面介紹了那麼多，大家有沒有發現其實這個體系也不難，有大佬在前面鋪路，其實我們只要按照規則“填空”就好了，那現在我們就來實現一個小小的功能——加一個按鈕和他的點選事件。

修改我們的 package.json 如下，因為當前我希望外掛載入的時候就已經訂閱了按鈕的點選事件，所以這裡我們可以把 activationEvents 改成 *，這樣的話我們的外掛在一開始就可以啟用並註冊事件了：

...,
"activationEvents": [
        "*",
],
"contributes": {
  "commands": [
    {
      "command": "test.helloWorld",
      "title": "Hello World"
    },
    // 註冊一下按鈕點選的事件，再配一個小圖示
    {
      "command": "test.button",
      "title": "按鈕",
      "icon": {
        "light": "./media/light/preview.svg",
        "dark": "./media/dark/preview.svg"
      }
    }
  ],
  // 在這裡加一下下面這個配置
  "menus": {
    "editor/title": [
      {
        "command": "test.button",
        "group": "navigation"
      }
    ]
  }
},
...

然後回到我們的 extension.js 裡面增加一個簡單的訊息提醒：

function activate(context) {
  console.log('我在這裡！！');
  let disposable = vscode.commands.registerCommand('test.helloWorld', function () {
    vscode.window.showInformationMessage('我改變了 command 的名字!');
  });
  // 新增一個按鈕的點選命令操作內容
  let button = vscode.commands.registerCommand('test.button', function () {
    vscode.window.showInformationMessage('按鈕點選');
  });
  // 記得這個新的命令也要放進去訂閱一下
  context.subscriptions.push(disposable, button);
}

看一下效果：

是不是很簡單的就自定義了 VS Code 的樣式？那我們現在就來分析一下我們上面做的事情。首先，我們修改了 package.json 裡的配置，增加了一個 menus ，這個 menus 是什麼呢？答案是選單。選單項定義包含選擇時應呼叫的命令以及該項應顯示的條件（when），所以你也可以給這個選單項顯示加個顯示的邏輯，比如我們規定在開啟 javascript 檔案時才顯示這個按鈕：

{
  "contributes": {
    "menus": {
      "editor/title": [
        {
          "when": "resourceLangId == javascript",
          "command": "test.button",
          "group": "navigation"
        }
      ]
    }
  }
}

而 group 的含義呢，是用來定義選單項的排序和分組的。來自官網的一個圖，表示不同的 group 之間存在的順序關係，當然這個選單不是上面我們寫的那個，而是 editor/context ，所以不同的選單之間的 group 其實是有細微差別的，但是大體都差不多，而 navigation 的顯示優先順序是最高的：

我們也可以加一個這個看看：

"menus": {
  "editor/title": [
    {
      "command": "test.button",
      "group": "navigation",
      "when": "resourceLangId == javascript"
    }
  ],
    "editor/context": [
      {
        "command": "test.button",
        "group": "navigation",
        "when": "resourceLangId == javascript"
      }
    ]
}

效果是一樣的：

如果你好奇還有哪些選單，我這裡簡單整理「翻譯」了一下官網的內容（僅常見選單非全部）：

配置選單項的名稱 選單位置
commandPalette 全域性命令皮膚
explorer/context 資源管理器上下文選單
editor/context 編輯器右鍵上下文選單
editor/title 編輯器標題欄，不配置圖片就顯示文字
editor/title/context 編輯器標題右鍵上下文選單
debug/callstack/context 除錯棧檢視的上下文選單
debug/toolbar 除錯工具欄
scm/title SCM 標題選單
view/title 看標題選單
touchBar macOS 觸控欄
timeline/title 時間軸檢視標題選單欄
extension/context 擴充套件程式檢視上下文選單

六、做個總結

從上面的簡單例子可以看出，VS Code 不僅可以支援我們自定義想要的命令，也允許我們在「限定範圍內」對編輯器進行個性化的擴充。為什麼說是限定範圍呢？因為按官網的話來說，目前外掛體系有下面這些侷限性：

外掛不具備訪問 VS Code UI 的 DOM 的能力。所以不能將自定義的 CSS 應用於 VS Code 或將 HTML 元素新增到 VS Code UI 的擴充套件中去。這樣的限制在於：

  • 確保使用者的操作在可控範圍內，保證操作的一致性
  • 防止因為底層 Web 技術的更迭導致對一些已存在的外掛會有影響
  • 保證開發人員可以繼續在原有外掛基礎上進行一如往常的迭代，而不用再去打破原有的規則重新學習

其實我們今天的內容只是工作區擴充很小一部分內容，要學習這個龐大的體系，還是要不斷的努力學習呀！下一次，我們來走進「宣告類語言特性」，想知道編輯器裡的自動提示和補全是怎麼做到的嘛？

關注 HelloGitHub 公眾號 收到第一時間的更新。

還有更多開源專案的介紹和寶藏專案等待你的發掘。

相關文章