扩展 - Hello World

2018-08-11 VS Code 插件阅读量

你的第一个扩展

本文档将指导您创建第一个VS Code扩展(“Hello World”)，并解释VS Code可扩展性的基本概念。

在本演练中，您将向VS Code添加一个新命令，该命令将显示一个简单的“Hello World”消息。在随后的演练中，您将与VS Code编辑器交互，并查询用户当前选择的文本。

先决条件

你需要的节点。在您的$PATH中安装并可用js。Node.js安装包括npm, Node.js包管理器，它将用于安装扩展生成器。

生成一个新的扩展

向VS Code中添加自己的功能的最简单方法是添加一个命令。命令注册一个回调函数，该函数可以从命令调色板调用，也可以通过键绑定调用。

我们编写了一个Yeoman生成器来帮助您开始。安装Yeoman和Yeoman VSCode扩展生成器和脚手架一个新的扩展:

1 2	npm install -g yo generator-code yo code

对于hello world扩展，您可以创建TypeScript扩展或JavaScript扩展。对于本例，我们选择一个TypeScript扩展。

generator

运行您的扩展

启动VS Code，选择文件>打开文件夹并选择生成的文件夹。
按F5或单击调试图标并单击Start。
VS Code的一个新实例将以特殊模式(扩展开发主机)启动，这个新实例现在知道您的扩展了。
按键⇧⌘P和运行该命令命名为Hello World。

恭喜你!您刚刚创建并执行了第一个VS代码命令!

running

扩展的结构

运行后生成的扩展应该具有以下结构:

.
├── .gitignore
├── .vscode                     // VS Code integration
│   ├── launch.json
│   ├── settings.json
│   └── tasks.json
├── .vscodeignore               // files ignored when publishing extension
├── README.md
├── src
│   └── extension.ts            // the source of the extension entry point
├── test                        // test folder
│   ├── extension.test.ts       // extension.test.js, in case of JavaScript extension
│   └── index.ts                // index.js, in case of JavaScript extension
├── node_modules
│   ├── vscode                  // include vscode type definition file for extension development
│   └── typescript              // compiler for typescript (TypeScript only)
├── out                         // compilation output (TypeScript only)
│   ├── extension.js            // the extension entry point
│   ├── extension.js.map
│   └── test
│       ├── extension.test.js
│       ├── extension.test.js.map
│       ├── index.js
│       └── index.js.map
├── package.json                // extension's manifest
├── tsconfig.json               // jsconfig.json, in case of JavaScript extension
└── vsc-extension-quickstart.md // extension development quick start

让我们看看所有这些文件的用途，并解释它们的用途:

扩展清单:`package.json`

每个VS Code扩展必须有一个package.json文件描述它和它的功能。
VS Code在启动时读取此文件，并立即对每个投稿部分作出反应。
请阅读package.json扩展清单参考。
更多关于package.json贡献点的信息。

{
    "name": "myFirstExtension",
    "description": "",
    "version": "0.0.1",
    "publisher": "",
    "engines": {
        "vscode": "^1.5.0"
    },
    "categories": [
        "Other"
    ],
    "activationEvents": [
        "onCommand:extension.sayHello"
    ],
    "main": "./out/extension",
    "contributes": {
        "commands": [{
            "command": "extension.sayHello",
            "title": "Hello World"
        }]
    },
    "scripts": {
        "vscode:prepublish": "tsc -p ./",
        "compile": "tsc -watch -p ./",
        "postinstall": "node ./node_modules/vscode/bin/install",
        "test": "node ./node_modules/vscode/bin/test"
    },
    "devDependencies": {
       "typescript": "^2.0.3",
        "vscode": "^1.5.0",
        "mocha": "^2.3.3",
        "@types/node": "^6.0.40",
        "@types/mocha": "^2.2.32"
   }
}

注意:JavaScript扩展不需要scripts字段，因为不需要编译。

这个具体的package.json描述了一个扩展:

一个条目有助于命令面板(⇧⌘P)的标签“Hello world”将调用命令“extension.sayHello”。
当命令“extension.sayHello”被调用时，请求加载(activationEvents)。
它的主要JavaScript代码在一个名为“./out/extension.js”的文件中。

注意:VS代码在启动时并不急于加载扩展的代码。扩展必须通过activationEvents属性描述它在什么条件下应该被激活(加载)。

生成的代码

生成的扩展代码为extension.ts(或JavaScript扩展为extension.js):

// 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 "my-first-extension" 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('extension.sayHello', () => {
        // 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);
}

每个扩展都应该从它的主文件导出一个名为activate()的函数，当package.json文件中描述的任何activationEvents发生时，VS Code只调用一次。
如果扩展使用OS资源(例如spawns进程)，扩展可以从主文件导出一个名为deactivate()的函数，在这里它可以进行清理工作，VS Code将在关机时调用该函数。
这个特定的扩展导入vscode API，然后注册一个命令，在调用命令“extension.sayHello”时关联要调用的函数。命令的实现在VS代码中显示“Hello world”消息。

注意:package.json的贡献部分向命令调色板添加了一个条目。extension.ts/.js中的代码定义了“extension.sayHello”的实现。
注意:对于TypeScript扩展，生成的文件out/extension.js将在运行时加载并由VS代码执行。

其他文件的

.vscode/launch.json在扩展开发模式中定义了启动VS代码。它还将预启动任务指向运行TypeScript编译器的.vscode/tasks.json中定义的任务。
默认情况下，.vscode/settings.json不包括out文件夹。可以修改要隐藏的文件类型。
.gitignore - 告诉Git版本控制要忽略哪些模式
.vscodeignore -告诉打包工具在发布扩展名时忽略哪些文件。
README.md - 描述VS code用户扩展的README文件。
vsc-extension-quickstart.md -一个快速开始指导你。
test/extension.test.ts - 你可以把你的扩展单元测试放在这里，然后根据VSCode API运行你的测试(参见测试你的扩展)

扩展activation

现在，扩展中包含的文件的角色已经明确，下面是如何激活扩展的:

扩展开发实例发现扩展并读取其package.json文件。
以后当你按⇧⌘P:
注册的命令显示在命令调色板中。
在这个列表中，现在有一个条目“Hello world”在package.json中定义。
选择“Hello world”命令:
调用命令“extension.sayHello”:
- 创建一个激活事件“onCommand:extension.sayHello”。
- 在activationEvents中列出此激活事件的所有扩展都被激活。
  - ./out/extension.js处的文件被加载到JavaScript VM中。
  - VS code寻找一个导出函数激活并调用它。
  - 已经注册了命令“extension.sayHello”，现在已经定义了它的实现。
调用命令“extension.sayHello”实现函数。
命令实现显示“Hello World”消息。

调试您的扩展

设置断点，例如在已注册的命令中，并在扩展开发VS代码实例中运行“Hello world”命令。

hitbp

注意:对于TypeScript扩展，即使VS Code加载并执行out/extension.js，由于生成的源代码映射out/extension.js.map，您实际上能够调试初始的TypeScript代码。map和VS Code对源代码映射的调试器支持。
提示:调试控制台将显示您登录到控制台的所有消息。

了解更多关于扩展开发环境的信息。

一个简单的改变

在extension.ts(或extension.js，在JavaScript扩展中)中，尝试替换extension.sayHello命令实现，以显示编辑器中选择的字符数:

let disposable = vscode.commands.registerCommand('extension.sayHello', () => {
        // The code you place here will be executed every time your command is executed

        let editor = vscode.window.activeTextEditor;
        if (!editor) {
            return; // No open text editor
        }

        let selection = editor.selection;
        let text = editor.document.getText(selection);

        // Display a message box to the user
        vscode.window.showInformationMessage('Selected characters: ' + text.length);
    });

提示:一旦对扩展源代码进行了更改，就需要重新启动VS Code的扩展开发主机实例。您可以在扩展开发主机实例中使用Ctrl+R (macOS: Cmd+R)，或者单击主VS Code实例顶部的Restart按钮。

创建一个文件(文件>新文件)，输入一些文本并选择它。在运行Hello World命令时，现在应该会看到所选字符的计数。

selection

在本地安装您的扩展

到目前为止，您编写的扩展只在VSCode的一个特殊实例中运行，即扩展开发实例。要使您的扩展在VSCode的所有实例中运行，您需要将其复制到本地扩展文件夹下的新文件夹中:

Windows: %USERPROFILE%.vscode\extensions
macOS/Linux: $HOME/.vscode/extensions

发布您的扩展

阅读如何共享扩展。

下一个步骤

在本演练中，我们看到了一个非常简单的扩展。有关更详细的示例，请参阅单词计数示例，该示例展示了如何以特定语言为目标(标记)，并侦听编辑器的文档更改事件。

如果你想了解更多关于扩展api的内容，请尝试以下主题:

扩展API概述-了解VS代码可扩展性的完整模型。
API原则和模式——VS代码可扩展性基于几个指导原则和模式。
贡献点——关于VS代码贡献点的详细信息。
激活事件- VS代码激活事件引用
其他扩展示例—查看我们的示例扩展项目列表。