一篇文簡單介紹如何開發VS Code插件

圖

本文內容

1. 開發 VSCode 插件
2. VSCode 常用內建 API 介紹
3. 打包 VSCode 插件

開發 VSCode 插件

1. 安裝依賴項

確認已經安裝 Node.js 與 Visual Studio Code 後，打開 Terminal 輸入以下指令安裝插件開發工具

npm install -g yo generator-code

這段指令會在全局安裝兩個工具：yo、generator-code

yo：可以快速搭建各種項目的基礎模板，這邊用來創建VSCode插件專案

genertor-code：用於生成VSCode插件的資本結構

可以說 genertor-code 提供設計圖，而 yo 則根據 genertor-code 提供的設計圖生成具體的 VSCode 插件。

2.創建插件

yo code // 輸入後會需要再填入一些插件資訊用以生成插件

建立完成後，會生成以下目錄

extension/
│
├── .vscode/                 // VSCode 配置文件，啟動與DEBUG的相關設定
├── src/                     // 主要資料夾，放置所有插件功能的邏輯檔案
│   └── extension.ts         
├── package.json             // 紀錄插件的名字、版本號、依賴項...等
├── tsconfig.json            // TypeScript 配置文件，最終會把程式轉為JavaScript
└── README.md                // 插件的說明文檔

主要來看到 extension.ts，這是生成後的主要範例程式

// 導入 vscode 內部工具庫，使我們可以執行一些內建操作
import * as vscode from 'vscode';

// activate() 這個函數會在插件啟動時被執行。參數 context 用於管理插件資源跟狀態
export function activate(context: vscode.ExtensionContext) {

// 輸出一行訊息到控制台，可以當成 Hello world，告訴你插件已正常啟動
console.log('Congratulations, your extension "vscode-extension" is now active!');

// 當 User 執行到 helloWorld 這個命令時會觸發函數內容
const disposable = vscode.commands.registerCommand('vscode-extension.helloWorld', () => {
  // 透過 vscode 內部工具庫的 message 框顯示訊息
  vscode.window.showInformationMessage('Hello World from vscode-extension!');
 });

 context.subscriptions.push(disposable);
}

export function deactivate() {}

3. 啟動

透過側邊欄的 “Run and Debug” 後點擊播放按鈕(或點擊 F5也可以快速啟動)，就會在新的 VSCode 窗口運行當前插件

接著在新的窗口點擊 ctrl+shift+P (Mac cmd+shift+P)，會看到一個 Hello World，這是剛剛我們新增的插件所提供的選項

點擊 Enter後，可以發現另開視窗有彈出一個訊息框(1)，而原先的視窗則有提示"Congratulations, your extension “vscode-extension” is now active!"(2)

這分別是對應到 extension.ts 中的兩行程式

(1) 會輸出到原先視窗的 DEBUG CONSOLE 中

(2) 當使用者選擇了插件提供的選項後，會運行彈出對話框的部分

若修改程式後，要更新程式內容到另開視窗的 VSCode 上，只需點擊原視窗上方重整按鈕就會自動載入

到這邊就算是完成了 Hello World 的部分，接著會介紹開發 VScode 插件可能會使用到的一些內建 API。

VSCode 常用內建 API 介紹

開發 VSCode 插件時，有許多內建的 API 可以用來拓展插件功能，以下會介紹一些常用的內建 API。

輸出 (當需顯示訊息讓使用者看到時)

• 訊息框

可根據分類決定使用何種訊息框，傳入參數為欲顯示的內容。

 const disposable = vscode.commands.registerCommand('vscode-extension.helloWorld', () => {
  vscode.window.showInformationMessage('information message');
  vscode.window.showWarningMessage('warning message');
  vscode.window.showErrorMessage('error message');
 });

• Output 窗口

通過 createOutputChannel 建立一個輸出面板，再於這個面板上輸出 Hello World，最後聚焦到這個面板上。

 const disposable = vscode.commands.registerCommand('vscode-extension.helloWorld', () => {
  const outputChannel = vscode.window.createOutputChannel('輸出頻道');
  outputChannel.appendLine('Hello World!');
  outputChannel.show();
 });

• 狀態列

想在VSCode 下方狀態列顯示插件訊息，可以使用 StatusBarItem

 const disposable = vscode.commands.registerCommand('vscode-extension.helloWorld', () => {
  const statusBarItem = vscode.window.createStatusBarItem(vscode.StatusBarAlignment.Left);
  statusBarItem.text = '狀態列表輸出';
  statusBarItem.show();
 });

// createStatusBarItem 提供了兩個傳入參數
vscode.window.createStatusBarItem(
  alignment: vscode.StatusBarAlignment, 
  priority?: number
): vscode.StatusBarItem


// alignment 是決定對齊方式
// 可傳入 vscode.StatusBarAlignment.Left 或 vscode.StatusBarAlignment.Right

// priority 是可選參數，用於決定優先級，數字越小則越靠前 (default:100)

輸入 (當需讓使用者輸入資料時)

• InputBox (顯示一個輸入框，允許用戶輸入)

const disposable = vscode.commands.registerCommand('vscode-extension.helloWorld', () => {
  vscode.window.showInputBox({ prompt: '請輸入' }).then(value => {
   vscode.window.showInformationMessage(`輸入值為： ${value}!`);
  });
});

// showInputBox 傳入參數可訂製輸入框細節 (僅舉例幾個較常用參數)
vscode.window.showInputBox({
   prompt: '訊息提示',
   placeHolder: 'placeholder',
   value: '預設值',
   password: false
}).then(value => {
   if (value) {
    vscode.window.showInformationMessage(`Hello, ${value
     }!`);
   }
});

// prompt: 輸入提示
// placeHolder: 無值時會顯示此字串
// value: 預設值
// password: true 時隱藏輸入的資料
// ignoreFocusOut 

• quickPick (創建選項提供用戶選擇)

 const disposable = vscode.commands.registerCommand('vscode-extension.helloWorld', async () => {

  const options = [{ label: 'Option 1' }, { label: 'Option 2' }];
  const selectedItems = await vscode.window.showQuickPick(options);

  vscode.window.showInformationMessage(`選擇: ${selectedItems?.label}`);

 });

若是要多選，則可以增加設定 canPickMany: true

 const disposable = vscode.commands.registerCommand('vscode-extension.helloWorld', async () => {

  const options = [{ label: 'Option 1' }, { label: 'Option 2' }, { label: 'Option 3' }];
  const selectedItems = await vscode.window.showQuickPick(options, { canPickMany: true });

  selectedItems?.forEach(item => {
   vscode.window.showInformationMessage(`選擇: ${item.label}`);
  });

 });

打包 VSCode 插件

1. 安裝依賴項

npm install -g vsce

vsce : VSCode 的官方工具，用於插件的打包和發布。

2. 生成 VSIX 文件

vsce package

生成完成後，會在根目錄產生 vscode-extension-0.0.1.vsix 檔案，可以使用 vsce publish 將插件發佈到 Marketplace。

或者若不想發布但想將檔案分享給朋友，可以請朋友將檔案放到對應路徑，於對應路徑打開 VSCode 後於 Terminal 輸入以下指令：

code --install-extension vscode-extension-0.0.1.vsix

可以在不透過 Marketplace 的方法下安裝 VSCode 插件。

執行 vsce package指令後，可能會遇到的問題

• ReferenceError: ReadableStream is not defined

C:\...\nvm\v16.15.1\node_modules\@vscode\vsce\node_modules\undici\lib\web\fetch\response.js:527
  ReadableStream
  ^

ReferenceError: ReadableStream is not defined

這是因為 ReadableStream 是 Node.js v18+ 中的全域變量。把 node 環境切到 18+ 再執行一次就可以了。

• ERROR It seems the README.md still contains template text. Make sure to edit the README.md file before you package or publish your extension.

偵測到 README.md 包含預設的模板資訊。把 README.md 的內容刪掉或是替換成自己的插件資訊就可以了。