教你如何開發(fā)VS Code插件？

前言

由于之前的國(guó)際化的項(xiàng)目中總是要統(tǒng)計(jì)老項(xiàng)目中待翻譯的內(nèi)容，然后再交由業(yè)務(wù)進(jìn)行翻譯，如果總是人為統(tǒng)計(jì)不僅相當(dāng)耗費(fèi)精力和時(shí)間，而且還不能保證是否有遺漏，因此想通過編寫一個(gè)i18n-helper插件來(lái)實(shí)現(xiàn)這個(gè)功能。

然而，大家的需求總是出奇的相似（因?yàn)橐呀?jīng)有很多類似的插件存在了），因此沒必要重復(fù)造輪子了，但是如何開發(fā) vscode 插件的過程可以記錄下來(lái)，分享給大家！

跑通官方插件示例

好了，話不多說(shuō)，我們先按著官方文檔跑一下它的插件用例吧！

生成插件目錄

安裝腳手架

npm install -g yo generator-code

初始化插件目錄

終端運(yùn)行yo code，按照提示生成目錄即可。

調(diào)試插件

由于官方文檔缺少一些細(xì)節(jié)，很容易導(dǎo)致小白調(diào)試插件失敗，再常見的有如下情況。

找不到 Hello World 命令

進(jìn)入對(duì)應(yīng)項(xiàng)目目錄后，按照官方文檔的指示可通過如下兩種方式進(jìn)行調(diào)試：

按快捷鍵 F5

點(diǎn)擊編輯器左下方的Run Extension

接著按下Ctrl + Shift + P，并輸入Hello World命令，發(fā)現(xiàn)無(wú)法找到對(duì)應(yīng)的命令：

這個(gè)原因主要是因?yàn)?vscode 版本不一致造成的：

package.json文件中指定的vscode版本號(hào)

當(dāng)前實(shí)際的vscode版本號(hào)：

解決方案自然就是保持版本的一致性

升級(jí)vscode版本

適用于當(dāng)前版本號(hào)低于package.json文件中指定的版本號(hào)

【注意】現(xiàn)在vscode版本的更新模型已經(jīng)調(diào)整為“默認(rèn)”模式，所以現(xiàn)在不會(huì)收到vscode需要更新的信息，也無(wú)法進(jìn)行通過“檢查更新”按鈕來(lái)進(jìn)行更新

修改package.json文件中的vscode對(duì)應(yīng)版本號(hào)

這種方式比較簡(jiǎn)單直接，就是修改為和當(dāng)前正在使用的vscode版本保持一致即可，如下：

Hello World 命令報(bào)錯(cuò)

經(jīng)過上述操作后，重新啟動(dòng)調(diào)試，按下Ctrl + Shift + P，并輸入Hello World命令，就可以找到對(duì)應(yīng)的命令了，但是執(zhí)行該命令時(shí)報(bào)錯(cuò)了：

原因就在于我們沒有編譯文件，此時(shí)注意查看package.json文件中的main字段會(huì)發(fā)現(xiàn)：

很明顯，我們沒有編譯源文件生成目標(biāo)文件，此時(shí)我們只需要通過npm run watch啟用監(jiān)聽模式，讓其進(jìn)行編譯即可：

此時(shí)在執(zhí)行命令，就會(huì)發(fā)現(xiàn)成功了：

【實(shí)戰(zhàn)】編寫 VSCode 插件

插件的三個(gè)概念

激活事件（針對(duì)V1.74.0之前的VSCode版本）

即插件激活的時(shí)機(jī)，目的是支持用戶在輸入Hello World命令后能夠激活插件

例如，使用onCommand進(jìn)行注冊(cè)onCommand:extension.helloWorld

發(fā)布內(nèi)容配置

VS Code通過package.json進(jìn)行擴(kuò)展，通過配置插件清單字段便于開發(fā)插件

例如，使用contributes.commands綁定一個(gè)命令 IDextension.helloWorld，目的是讓Hello World命令就可以在命令面板中匹配到等

VS Code API

插件代碼中需要調(diào)用的一系列JavaScript API使用VS Code的一些功能特性

例如，通過vscode.commands.registerCommand將一個(gè)函數(shù)綁定到對(duì)應(yīng)的命令 IDextension.helloWorld上，激活命令時(shí)執(zhí)行的就是該函數(shù)等

目錄結(jié)構(gòu)比較簡(jiǎn)單就不過多介紹了。

在 VSCode 中預(yù)覽 SVG 文件—?標(biāo)簽預(yù)覽

當(dāng)然相關(guān)的svg插件已經(jīng)有不少了，這里只是用這個(gè)簡(jiǎn)單的需求來(lái)舉個(gè)例子，方便讓大家更容易理解。

SVG 文件在 VSCode 中的原始展示效果

發(fā)布內(nèi)容配置 — package.json 文件

面向用戶的命令

首先，我們要注冊(cè)命令，讓用戶能夠使用我們的插件，這里我們就簡(jiǎn)單支持如下兩種方式：

Ctrl + Shift + P 匹配命令

只需要在package.json中的contributes.commands進(jìn)行如下配置即可，詳情可見contributes.commands

"contributes": {
    "commands": [
          {
            "command": "svg-viewer.previewsvg",
            "title": "Preview SVG"
          }
     ]
}

鼠標(biāo)右鍵菜單選擇命令

這種方式相對(duì)于上面的方式來(lái)講更簡(jiǎn)便，只需要在package.json中的contributes.menus進(jìn)行如下配置即可，詳情可見contributes.menus

"contributes": {
    "menus": {
      "editor/context": [
        {
          "command": "svg-viewer.previewsvg"
        }
      ]
}

上述鼠標(biāo)右鍵菜單選擇命令的配置有一點(diǎn)不好，那就是安裝此插件后，在任何文件中右鍵都會(huì)顯示Preview SVG選項(xiàng)，此時(shí)調(diào)試效果如下：

因?yàn)槲覀兊谋疽馐穷A(yù)覽SVG文件，而不是其他文件，因此對(duì)于不符合的文件就沒有必要展示此選項(xiàng)了，此時(shí)可以通過when 子句上下文來(lái)控制顯示隱藏命令選項(xiàng)，此時(shí)配置更改為：

"contributes": {
    "menus": {
      "editor/context": [
        {
          "command": "svg-viewer.previewsvg",
          "when": "resourceExtname == '.svg'"
        }
      ]
}

調(diào)試效果如下：

使用 VSCode API

注冊(cè)命令

上述我們配置好了命令，現(xiàn)在就需要注冊(cè)命令了，也就是決定當(dāng)命令激活時(shí)需要做些什么事情，即只需要在extension.ts文件的activate方法中做如下修改即可：

// 執(zhí)行命令時(shí)被激活
export function activate(context: vscode.ExtensionContext) {
  // 使用控制臺(tái)輸出診斷信息(console.log)和錯(cuò)誤(console.error)
  // 這行代碼只會(huì)在你的擴(kuò)展被激活時(shí)執(zhí)行一次
  console.log('Congratulations, your extension "svg-viewer" is now active!');


  // 注冊(cè)命令，commandId 參數(shù)必須與 package.json 中的 command 字段匹配
  let disposable = vscode.commands.registerCommand(
    "svg-viewer.previewsvg",
    () => {
      // 具體要做的內(nèi)容
    }
  );


  context.subscriptions.push(disposable);
}

使用 Webview

平時(shí)我們通過瀏覽器使用標(biāo)簽可以查看svg文件的效果，例如：

那么在VSCode中可不可以也以這樣的方式來(lái)實(shí)現(xiàn)呢？

那當(dāng)然是可以的。

我們可以使用如下代碼編輯器中創(chuàng)建一個(gè)Webview，然后其中的html選項(xiàng)內(nèi)容就可以用我們常見的html 結(jié)構(gòu)來(lái)填充，并作為最終結(jié)果來(lái)進(jìn)行渲染，例如：

  // 創(chuàng)建并顯示新的 webview
  const panel = vscode.window.createWebviewPanel(
    "SVGPreview", // 只供內(nèi)部使用，即 webview 的標(biāo)識(shí)
    "SVG Preview", // 面板標(biāo)題
    vscode.ViewColumn.One, // 給新的 webview 面板一個(gè)編輯器視圖
    {} // Webview 選項(xiàng)
  );


  // 設(shè)置HTML內(nèi)容
  panel.webview.html = `
    
      
        
        
        
      
      
        
      
    
`;

獲取目標(biāo)文件的 base64 格式

由于我們打開相應(yīng)svg文件后右鍵進(jìn)行預(yù)覽，那么第一步就得先獲取當(dāng)前這個(gè)文件的路徑，這就又得需要使用的VSCode API了，如下

 const editor = vscode.window.activeTextEditor;
leturl=editor.document.fileName;//獲取到的就是對(duì)應(yīng)文件的絕對(duì)路徑

但是如果你直接把這個(gè)路徑作為標(biāo)簽的src屬性是沒法沒正常渲染的，大致如下：

既然如此，那么我們可以把這個(gè)svg文件讀取到，然后把它轉(zhuǎn)成base64的格式，再交由標(biāo)簽使用即可，此時(shí)我們就需要使用到node內(nèi)置的fs模塊了，即：

  const fs = require("fs");
  const content = fs.readFileSync(url);
return`data:image/svg+xml;base64,${content.toString("base64")}`;

源代碼 & 效果展示

需要查看源碼的可點(diǎn)此獲?。涸创a

經(jīng)過上述的處理我們就可以在VSCode中預(yù)覽svg文件了，效果如下：

在 VSCode 中預(yù)覽 SVG 文件 —

上述方案雖然可以實(shí)現(xiàn)我們需要的功能，但是對(duì)于svg文件來(lái)講還是復(fù)雜了，因?yàn)樵跒g覽其中是可以直接渲染

這個(gè)方案比較簡(jiǎn)單，這里直接貼出extension.ts文件中的代碼了：

import * as vscode from "vscode";


// 執(zhí)行命令時(shí)被激活
export function activate(context: vscode.ExtensionContext) {
  const fs = require("fs");


  // 注冊(cè)命令，commandId 參數(shù)必須與 package.json 中的 command 字段匹配
  let disposable = vscode.commands.registerCommand(
    "svg-viewer.previewsvg",
    () => {
      const url = getActiveTextUrl();
      const content = fs.readFileSync(url, "utf-8");
      opedWebview(content);
    }
  );


  context.subscriptions.push(disposable);
}


// 獲取當(dāng)前文件路徑
export function getActiveTextUrl(): string {
  let url = "";
  const editor = vscode.window.activeTextEditor;


  if (editor) {
    url = editor.document.fileName;
  }


  return url;
}


// 創(chuàng)建并顯示新的 webview
export function opedWebview(content: string) {
  const panel = vscode.window.createWebviewPanel(
    "SVGPreview", // 只供內(nèi)部使用，即 webview 的標(biāo)識(shí)
    "SVG Preview", // 面板標(biāo)題
    vscode.ViewColumn.One, // 給新的 webview 面板一個(gè)編輯器視圖
    {} // Webview 選項(xiàng)
  );


  // 設(shè)置HTML內(nèi)容
  panel.webview.html = getWebviewContent(content);
}


// 渲染模版
export function getWebviewContent(content: string) {
  return `
    
      
        
        
        
        
      
      
        ${content}
      
    
    `;
}


// 停用命令時(shí)執(zhí)行
exportfunctiondeactivate(){}

發(fā)布

發(fā)布到官網(wǎng)應(yīng)用市場(chǎng)

通過這個(gè)地址注冊(cè)開發(fā)者賬號(hào)，然后按提示發(fā)布到官網(wǎng)應(yīng)用市場(chǎng)即可。

使用 vsce 打成 vsix 插件

這種方式可以實(shí)現(xiàn)即使沒有發(fā)布到應(yīng)用市場(chǎng)，也可以直接通過對(duì)應(yīng)文件的方式進(jìn)行插件的安裝和使用。

安裝 vsce 工具

安裝命令npm i vsce -g

打包生成 .vsix 文件

直接使用vsce package命令進(jìn)行打包，完成后就會(huì)生成一個(gè).vsix文件，這個(gè)也就是在后續(xù)安裝插件時(shí)要使用的文件。

【注意】在使用這個(gè)命令打包時(shí)，可能會(huì)出現(xiàn)vsce所需要支持的VSCode最低版本和當(dāng)前使用版本之間存在出入，導(dǎo)致打包失?。?/p>

特別是如果按照前文的方式直接修改package.json文件中的版本號(hào)時(shí)，此時(shí)最好還是將VSCode版本進(jìn)行升級(jí)，而不是手動(dòng)修改版本號(hào)。

安裝 vsix 插件

按照如下方式操作并選擇對(duì)應(yīng)的.vsix文件即可.

通過本篇文章，希望能讓你從一個(gè)VSCode 插件開發(fā)的小白變成大白，能夠?yàn)閳F(tuán)隊(duì)賦能，或者作為自己的一個(gè)技能亮點(diǎn)。

審核編輯：劉清