編輯

擴充套件剖析

在上一主題中，您已經能夠執行一個基本的擴充套件。那麼它是如何在底層工作的呢？

Hello World 擴充套件做了三件事：

註冊了 onCommand 啟用事件：onCommand:helloworld.helloWorld，因此當用戶執行 Hello World 命令時，擴充套件就會被啟用。
注意：從 VS Code 1.74.0 開始，在 package.json 的 commands 部分宣告的命令在被呼叫時會自動啟用擴充套件，無需在 activationEvents 中明確指定 onCommand 條目。
使用 contributes.commands 貢獻點，使 Hello World 命令在命令面板中可用，並將其繫結到命令 ID helloworld.helloWorld。
使用 commands.registerCommand VS Code API 將一個函式繫結到已註冊的命令 ID helloworld.helloWorld。

理解這三個概念對於在 VS Code 中編寫擴充套件至關重要：

啟用事件：您的擴充套件被啟用的事件。
貢獻點：您在 package.json 擴充套件清單中進行的靜態宣告，用於擴充套件 VS Code。
VS Code API：您可以在擴充套件程式碼中呼叫的 JavaScript API 集。

通常，您的擴充套件會結合使用貢獻點和 VS Code API 來擴充套件 VS Code 的功能。擴充套件功能概述主題可以幫助您為您的擴充套件找到正確的貢獻點和 VS Code API。

讓我們仔細看看 Hello World 示例的原始碼，看看這些概念如何應用於它。

擴充套件檔案結構

.
├── .vscode
│   ├── launch.json     // Config for launching and debugging the extension
│   └── tasks.json      // Config for build task that compiles TypeScript
├── .gitignore          // Ignore build output and node_modules
├── README.md           // Readable description of your extension's functionality
├── src
│   └── extension.ts    // Extension source code
├── package.json        // Extension manifest
├── tsconfig.json       // TypeScript configuration

您可以閱讀更多關於配置檔案

launch.json 用於配置 VS Code 除錯
tasks.json 用於定義 VS Code 任務
tsconfig.json 請查閱 TypeScript 手冊

但是，讓我們重點關注 package.json 和 extension.ts，它們對於理解 Hello World 擴充套件至關重要。

擴充套件清單

每個 VS Code 擴充套件都必須有一個 package.json 作為其擴充套件清單。package.json 包含 Node.js 欄位（如 scripts 和 devDependencies）以及 VS Code 特定欄位（如 publisher、activationEvents 和 contributes）。您可以在擴充套件清單參考中找到所有 VS Code 特定欄位的描述。以下是一些最重要的欄位：

name 和 publisher：VS Code 使用 <publisher>.<name> 作為擴充套件的唯一 ID。例如，Hello World 示例的 ID 是 vscode-samples.helloworld-sample。VS Code 使用此 ID 來唯一標識您的擴充套件。
main：擴充套件的入口點。
activationEvents 和 contributes：啟用事件和貢獻點。
engines.vscode：這指定了擴充套件所依賴的 VS Code API 的最低版本。

{
  "name": "helloworld-sample",
  "displayName": "helloworld-sample",
  "description": "HelloWorld example for VS Code",
  "version": "0.0.1",
  "publisher": "vscode-samples",
  "repository": "https://github.com/microsoft/vscode-extension-samples/helloworld-sample",
  "engines": {
    "vscode": "^1.51.0"
  },
  "categories": ["Other"],
  "activationEvents": [],
  "main": "./out/extension.js",
  "contributes": {
    "commands": [
      {
        "command": "helloworld.helloWorld",
        "title": "Hello World"
      }
    ]
  },
  "scripts": {
    "vscode:prepublish": "npm run compile",
    "compile": "tsc -p ./",
    "watch": "tsc -watch -p ./"
  },
  "devDependencies": {
    "@types/node": "^8.10.25",
    "@types/vscode": "^1.51.0",
    "tslint": "^5.16.0",
    "typescript": "^3.4.5"
  }
}

注意：如果您的擴充套件目標是 1.74 之前的 VS Code 版本，您必須在 activationEvents 中明確列出 onCommand:helloworld.helloWorld。

擴充套件入口檔案

擴充套件入口檔案匯出兩個函式，activate 和 deactivate。當您註冊的啟用事件發生時，activate 將被執行。deactivate 允許您在擴充套件被停用之前進行清理。對於許多擴充套件來說，可能不需要明確的清理，並且可以刪除 deactivate 方法。但是，如果擴充套件需要在 VS Code 關閉或擴充套件被停用或解除安裝時執行操作，則此方法是執行此操作的方法。

VS Code 擴充套件 API 在 @types/vscode 型別定義中宣告。vscode 型別定義的版本由 package.json 中 engines.vscode 欄位的值控制。vscode 型別為您的程式碼提供了 IntelliSense、跳轉到定義以及其他 TypeScript 語言功能。

// The module 'vscode' contains the VS Code extensibility API
// Import the module and reference it with the alias vscode in your code below
import * as vscode from 'vscode';

// this method is called when your extension is activated
// your extension is activated the very first time the command is executed
export function activate(context: vscode.ExtensionContext) {
  // Use the console to output diagnostic information (console.log) and errors (console.error)
  // This line of code will only be executed once when your extension is activated
  console.log('Congratulations, your extension "helloworld-sample" is now active!');

  // The command has been defined in the package.json file
  // Now provide the implementation of the command with registerCommand
  // The commandId parameter must match the command field in package.json
  let disposable = vscode.commands.registerCommand('helloworld.helloWorld', () => {
    // The code you place here will be executed every time your command is executed

    // Display a message box to the user
    vscode.window.showInformationMessage('Hello World!');
  });

  context.subscriptions.push(disposable);
}

// this method is called when your extension is deactivated
export function deactivate() {}

09/11/2025