🚀 在 VS Code 中免费获取 ！

扩展解剖

在上一个主题中，您已经能够让一个基本的扩展程序运行起来。它是如何在底层工作的呢？

Hello World 扩展做了 3 件事

  • 注册 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() {}
03/05/2025