pscn

Example - Hello World

(こちらのページを自分流に翻訳したものです。2018-12-09)

Your first extension

ここでは初めての方を対象に、Visual Studio Code extension (“Hello World”) を作る過程をお見せします。また、VS Code の拡張性の基本的なコンセプトについてもご説明します。

これから作る extension は、”Hello World” というテキトーな文字列を表示するコマンドを VS Code に追加するものです。後半では、VS Code editor から選択中のテキストに関する情報を取得してみます。

Prerequisites

まずは Node.js をインストールして、$PATH を通しておきます。Node.js には extension generator をインストールするための npm (Node.js Package Manager) が含まれています。

Generate a new extension

とりあえず何か機能を追加したいのなら、コマンドを追加してみましょう。コマンドに callback 関数を関連付ければ、Command Palette や key binding から実行する事ができます。

extension を作るための Yeoman generator があるので、これを使います。Yeoman と Yeoman VS Code Extension generator をインストールし、真新しい extension への一歩を踏み出しましょう。

npm install -g yo generator-code
yo code

Hello World extension を作るには、TypeScript extension または JavaScript extension を選びます。この example では、TypeScript extension を使っています。

The command generator

Running your extension

Running VS Code with an extension

The structure of an extension

実行すると、extension フォルダは以下のようになります。

.
├── .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

では、これらのファイルが何のためにあるのか、見ていきましょう。

The extension manifest: package.json

EXAMPLE TYPESCRIPT EXTENSION MANIFEST

{
    "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 extension の場合、コンパイルする必要がないので、scripts フィールドは不要です。

上の package.json は、この extension について以下のことを言っています。

注: VS Code は、起動時に extension のコードをロードしません。extension がどんな条件でロードされるかは、activationEvents プロパティで設定されます。

Generated code

生成されたコードは、extension.ts の中です (JaveScript extension の場合は 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);
}

注: package.json の contributes セクションは、Command Palette にエントリを追加します。extension.ts/.js に書かれたコードが、"extension.sayHello" の実装になります。

注: TypeScript extension の場合、out/extension.js が生成されます。VS Code はそれをロードして実行します。

Miscellaneous files

Extension activation

ここまで、extension に含まれるファイルについて見てきました。ここからは、extension をアクティベートする方法について見ていきましょう。

Debugging your extension

コマンドの中にブレークポイントをセットして、Extension Development VS Code instance で "Hello world" を実行してみましょう。

Debugging the extension

注: TypeScript extensions の場合、VS Code は out/extension.js をロードして実行しますが、デバッグはオリジナルの TypeScript code 上で行うことが可能です。これは VS Code が out/extension.js.map を生成し、デバッグ時に参照しているためです。

Tip: コード内で、Debug Console に log を出すことができます。

Extension の開発環境について詳しく知りたければ、こちら をご覧ください。

A simple change

extension.ts (または extension.js) を変更してみましょう。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);
    });

Tip: Extension のソースコードを変更したら、Extension Development Host インスタンスを再起動します。再起動するには、Extension Development Host インスタンスで Ctrl+R (macOS: Cmd+R) を押すか、プライマリの VS Code インスタンスの上の方にある Restart ボタンを押します。

ファイルを作成し (File > New File)、テキストを入力して選択してください。Hello World コマンドを実行すると、選択中のテキストの文字数が出力されるはずです。

Running the modified extension

Installing your extension locally

ここまでで作った extension は、Extension Development instance という特殊なインスタンスでのみ実行可能です。これを VS Code のすべてのインスタンスで実行可能にするには、ローカルの extensions フォルダの中に新しくフォルダを作って、そこへコピーします。

Publishing your extension

Extension を公開する方法については、こちらをご覧ください。

Next steps

これで、ごく簡単な extension は作れるようになりました。もう少し凝った extension の例として、Word Count Example では、特定の言語のみを対象とする方法や、エディタの内容が変更された時にイベントに反応する方法について、説明しています。

Extension API に関する一般的な説明については、以下のページをご覧ください。