如何创建您的第一个VisualStudio代码扩展

介绍

Visual Studio Code 是 Microsoft 的代码编辑器，可用于 Windows、Linux 和 macOS。它提供了扩展，您可以通过 Visual Studio Code Marketplace 安装这些扩展，以在您的编辑器中添加附加功能。当您找不到完全符合您需要的扩展程序时，可以创建自己的扩展程序。

在本文中，你将创建你的第一个 Visual Studio Code 扩展。

先决条件

要完成本教程，您需要：

下载并安装最新版本的 Visual Studio Code。
遵循如何安装 Node.js 并创建本地开发环境在您的计算机上安装 Node.js。

本教程已使用 Node v14.4.0、npm v6.14.5、yo v3.1.1 和 generator-code v1.2.16 进行了验证。

第 1 步 — 安装工具

Visual Studio Code 团队创建了一个用于创建扩展的生成器，该生成器生成所有必要的启动文件以开始创建扩展。

要开始开发 VS 代码扩展，您需要两个不同的 npm 包：

yo - Yeoman 的命令行界面。
generator-code - 用于编写 Visual Studio Code 扩展的 Yeoman 生成器。

您可以使用 Visual Studio Code 的内置终端使用 npx 运行 yo 和 generator-code 的本地副本，然后运行命令 yo code初始化你的新项目：

npx -p yo -p generator-code yo code

此时，Yeoman 将运行代码生成器。

第 2 步 — 创建您的第一个扩展

您现在已准备好创建您的第一个扩展。

然后，您将回答有关您的项目的几个问题。您将需要在“TypeScript”和“JavaScript”之间选择要创建的扩展类型。我们将在本教程中选择 JavaScript。

然后你会被问到更多的问题。对于本教程，选择了以下选项：

? What type of extension do you want to create? New Extension (JavaScript)
? What's the name of your extension? testytest
? What's the identifier of your extension? testytest
? What's the description of your extension? This is a test extension
? Enable JavaScript type checking in 'jsconfig.json'? Yes
? Initialize a git repository? Yes
? Which package manager to use? npm

此过程完成后，您将拥有开始使用所需的所有文件。您最重要的两个文件是：

package.json
extension.js

打开【X5X】【X9X】，一起来看看吧。您将看到名称、描述等。还有两个非常重要的部分。

activationEvents：这是将激活您的扩展的事件列表。扩展是延迟加载的，因此在这些激活事件之一发生之前它们不会被激活。
commands：您提供给用户以通过您的扩展程序运行的命令列表。

我们将很快回到这些。

包.json

{
  // ...
  "activationEvents": [
    "onCommand:testytest.helloWorld"
  ],
  "main": "./extension.js",
  "contributes": {
    "commands": [
      {
        "command": "testytest.helloWorld",
        "title": "Hello World"
      }
    ]
  },
  // ...
}

您还可以查看 extension.js 文件。这是我们要为我们的扩展编写代码的地方。这里有一些样板代码，所以让我们分解一下。

下面突出显示的行是我们的命令在 VS Code 中注册的位置。请注意，此名称 helloWorld 与 package.json 中的命令相同。这是故意的。 package.json 定义了用户可用的命令，但 extension.js 文件注册了该命令的代码。

扩展.js

// ...

/**
 * @param {vscode.ExtensionContext} context
 */
function activate(context) {
  console.log('Congratulations, your extension "testytest" is now active!');

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

  context.subscriptions.push(disposable);
}

// ...

在这个 Hello World 示例中，该命令所做的只是向用户显示“Hello World”消息。

第三步——调试你的扩展

现在我们已经安装了所有必要的文件，我们可以运行我们的扩展程序。

.vscode 文件夹是 VS Code 为您的项目存储各种配置文件的地方。在这种情况下，它包括一个包含调试配置的 launch.json。

.vscode/launch.json

// ...
{
  // ...
  "configurations": [
    {
      "name": "Run Extension",
      "type": "extensionHost",
      "request": "launch",
      "runtimeExecutable": "${execPath}",
      "args": [
        "--extensionDevelopmentPath=${workspaceFolder}"
      ]
    },
    // ...
  ]
}

从这里，我们可以调试。打开屏幕左侧的调试选项卡，然后单击“播放”图标。

这将打开一个新的（调试）VS Code 实例。

打开这个 VS Code 的调试实例后，您可以在 Mac 上使用 COMMAND+SHIFT+P 或在 Windows 上使用 CTRL+SHIFT+P 打开命令面板，然后运行 Hello World。

您将看到右下角弹出“Hello World”消息。

第 4 步 - 编辑您的扩展程序

在编写代码之前，让我们再看一下 package.json 文件中的 activationEvents 部分。同样，本节包含一个事件列表，当它们发生时将激活我们的扩展。默认情况下，它设置为在我们的命令运行时激活。

理论上，这个事件可以是任何东西，更具体地说是 * 任何东西。通过将激活事件设置为 * 这意味着您的扩展将在 VS Code 启动时加载。这绝不是必需的，只是一个注释。

包.json

{
  // ...
  "activationEvents": [
    "*"
  ],
  // ...
}

我们有必要的文件，我们知道如何调试。现在让我们开始构建我们的扩展。假设我们希望这个扩展能够创建一个 HTML 文件，其中已经包含样板代码并添加到我们的项目中。

让我们首先更新命令的名称。在 extension.js 中，将命令名称从 extension.helloworld 更新为 extension.createBoilerplate。

扩展.js

// ...

/**
 * @param {vscode.ExtensionContext} context
 */
function activate(context) {
  console.log('Congratulations, your extension "testytest" is now active!');

  let disposable = vscode.commands.registerCommand('testytest.createBoilerplate', function () {
    vscode.window.showInformationMessage('Hello World from testytest!');
  });

  context.subscriptions.push(disposable);
}

// ...

现在，根据命令的更改相应地更新 package.json 文件。

包.json

{
  // ...
  "activationEvents": [
    "onCommand:testytest.createBoilerplate"
  ],
  "main": "./extension.js",
  "contributes": {
    "commands": [
      {
        "command": "testytest.createBoilerplate",
        "title": "Create Boilerplate"
      }
    ]
  },
  // ...
}

现在，让我们编写我们的功能。我们要做的第一件事是需要几个包。我们将使用 fs（文件系统）和 path 模块。

扩展.js

const fs = require('fs');
const path = require('path');

我们还需要获取当前文件夹的路径。在命令内部，添加以下代码段：

扩展.js

if (!vscode.workspace) {
  return vscode.window.showErrorMessage('Please open a project folder first');
}

const folderPath = vscode.workspace.workspaceFolders[0].uri
  .toString()
  .split(':')[1];

我们还需要将样板 HTML 代码存储到一个变量中，以便我们可以将其写入文件。这是样板 HTML：

扩展.js

const htmlContent = `<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <meta http-equiv="X-UA-Compatible" content="ie=edge" />
  <title>Document</title>
  <link rel="stylesheet" href="app.css" />
</head>
<body>
  <script src="app.js"></script>
</body>
</html>`;

现在我们需要写入文件。我们可以调用文件系统模块的writeFile函数，传入文件夹路径和HTML内容。

请注意，我们使用路径模块将文件夹路径与我们要创建的文件的名称结合起来。然后在回调内部，如果有错误，我们会显示给用户。否则，我们让用户知道我们成功创建了样板文件：

扩展.js

fs.writeFile(path.join(folderPath, 'index.html'), htmlContent, (err) => {
  if (err) {
    return vscode.window.showErrorMessage('Failed to create boilerplate file!');
  }
  vscode.window.showInformationMessage('Created boilerplate files');
});

这是完整功能的样子：

扩展.js

//...
  let disposable = vscode.commands.registerCommand(
    'testytest.createBoilerplate', async function () {
    // The code you place here will be executed every time your command is executed

    if (!vscode.workspace) {
      return vscode.window.showErrorMessage('Please open a project folder first');
    }

    const folderPath = vscode.workspace.workspaceFolders[0].uri
      .toString()
      .split(':')[1];

    const htmlContent = `<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <meta http-equiv="X-UA-Compatible" content="ie=edge" />
  <title>Document</title>
  <link rel="stylesheet" href="app.css" />
</head>
<body>
  <script src="app.js"></script>
</body>
</html>`;

    fs.writeFile(path.join(folderPath, 'index.html'), htmlContent, (err) => {
      if (err) {
        return vscode.window.showErrorMessage(
          'Failed to create boilerplate file!'
        );
      }
      vscode.window.showInformationMessage('Created boilerplate files');
    });

    // ...
  }
// ...

继续调试您新开发的扩展。然后，打开命令面板并运行 Create Boilerplate（记住我们更改了名称）。

运行命令后，您将看到新生成的 index.html 文件和一条消息让用户知道：

结论

要了解有关使用哪些 API 以及如何使用它们的更多信息，请通读 Visual Studio Code Extension API 文档。

本教程的代码可在 GitHub 上找到。