コントリビューションポイント

貢献ポイントは、package.json の contributes フィールドで行う JSON 宣言の集合です。拡張機能マニフェスト。拡張機能は、Visual Studio Code 内の様々な機能を拡張するために、貢献ポイントを登録します。利用可能なすべての貢献ポイントのリストを以下に示します。

contributes.authentication

認証プロバイダーを登録します。これにより、プロバイダーのアクティベーションイベントが設定され、拡張機能の機能に表示されます。

{
  "contributes": {
    "authentication": [
      {
        "label": "Azure Dev Ops",
        "id": "azuredevops"
      }
    ]
  }
}

contributes.breakpoints

通常、デバッガー拡張機能には、拡張機能がブレークポイントの設定が有効になる言語ファイルの種類をリストする contributes.breakpoints エントリも含まれています。

{
  "contributes": {
    "breakpoints": [
      {
        "language": "javascript"
      },
      {
        "language": "javascriptreact"
      }
    ]
  }
}

contributes.colors

新しいテーマカラーを登録します。これらの色は、エディターのデコレーターやステータスバーで拡張機能によって使用できます。一度定義すると、ユーザーは workspace.colorCustomization 設定で色をカスタマイズでき、ユーザーテーマは色の値を設定できます。

{
  "contributes": {
    "colors": [
      {
        "id": "superstatus.error",
        "description": "Color for error message in the status bar.",
        "defaults": {
          "dark": "errorForeground",
          "light": "errorForeground",
          "highContrast": "#010203",
          "highContrastLight": "#feedc3"
        }
      }
    ]
  }
}

カラーの既定値は、ライト、ダーク、ハイコントラストのテーマに対して定義でき、既存のカラーへの参照、またはカラーの16進値のいずれかになります。

拡張機能は、ThemeColor API を使用して、新しいテーマカラーと既存のテーマカラーを利用できます

const errorColor = new vscode.ThemeColor('superstatus.error');

contributes.commands

コマンドの UI を登録します。UI は、タイトルと (オプションで) アイコン、カテゴリ、有効状態から構成されます。有効化は、when 句で表現されます。既定では、コマンドはコマンドパレット (⇧⌘P (Windows, Linux Ctrl+Shift+P)) に表示されますが、他のメニューにも表示できます。

登録されたコマンドの表示は、含まれるメニューによって異なります。たとえば、コマンドパレットはコマンドに category を接頭辞として付加し、簡単にグループ化できるようにします。ただし、コマンドパレットはアイコンや無効なコマンドを表示しません。一方、エディターのコンテキストメニューは無効な項目を表示しますが、カテゴリラベルは表示しません。

注: コマンドが (キーバインド、コマンドパレット、その他のメニュー、またはプログラムによって) 呼び出されると、VS Code は onCommand:${command} というアクティベーションイベントを発行します。

注: 製品アイコンからアイコンを使用する場合、light と dark を設定するとアイコンが無効になります。正しい構文は "icon": "$(book)" です。

コマンドの例

{
  "contributes": {
    "commands": [
      {
        "command": "extension.sayHello",
        "title": "Hello World",
        "category": "Hello",
        "icon": {
          "light": "path/to/light/icon.svg",
          "dark": "path/to/dark/icon.svg"
        }
      }
    ]
  }
}

VS Code 拡張機能でのコマンドの使用方法の詳細については、コマンド拡張ガイドを参照してください。

commands extension point example

コマンドアイコンの仕様

サイズ: アイコンは 16x16 ピクセルで、1 ピクセルのパディング (画像は 14x14) を持ち、中央に配置する必要があります。
色: アイコンは単一の色を使用する必要があります。
形式: アイコンは SVG 形式にすることが推奨されますが、任意の画像ファイル形式が受け入れられます。

command icons

contributes.configuration

ユーザーに公開される設定を登録します。ユーザーは、これらの設定オプションを [設定] エディターで、または settings.json ファイルを直接編集して設定できます。

このセクションは、単一の設定カテゴリを表す単一のオブジェクト、または複数の設定カテゴリを表すオブジェクトの配列のいずれかになります。複数の設定カテゴリがある場合、[設定] エディターにはその拡張機能の目次にサブメニューが表示され、タイトルキーがサブメニューエントリ名として使用されます。

設定の例

{
  "contributes": {
    "configuration": {
      "title": "Settings Editor Test Extension",
      "type": "object",
      "properties": {
        "settingsEditorTestExtension.booleanExample": {
          "type": "boolean",
          "default": true,
          "description": "Boolean Example"
        },
        "settingsEditorTestExtension.stringExample": {
          "type": "string",
          "default": "Hello World",
          "description": "String Example"
        }
      }
    }
  }
}

configuration extension point example

拡張機能からこれらの値を vscode.workspace.getConfiguration('myExtension') を使用して読み取ることができます。

設定スキーマ

設定エントリは、JSON エディターで設定を編集する際にインテリセンスを提供するためと、設定 UI で表示される方法を定義するために使用されます。

settings UI screenshot with numbers

タイトル

カテゴリの title 1️⃣️ は、そのカテゴリで使用される見出しです。

{
  "configuration": {
    "title": "GitMagic"
  }
}

複数の設定カテゴリを持つ拡張機能の場合、カテゴリのいずれかのタイトルが拡張機能の表示名と同じである場合、設定 UI はそのカテゴリを「既定のカテゴリ」として扱い、そのカテゴリの order フィールドを無視し、その設定をメインの拡張機能の見出しの下に配置します。

title フィールドと displayName フィールドの両方で、「Extension」、「Configuration」、「Settings」のような単語は冗長です。

✔ "title": "GitMagic"
❌ "title": "GitMagic Extension"
❌ "title": "GitMagic Configuration"
❌ "title": "GitMagic Extension Configuration Settings"

プロパティ

configuration オブジェクトの properties 2️⃣ は、キーが設定 ID で、値が設定に関する追加情報を提供する辞書を形成します。拡張機能には複数の設定カテゴリを含めることができますが、拡張機能の各設定には独自のユニーク ID が必要です。設定 ID は、別の設定 ID の完全なプレフィックスにすることはできません。

明示的な order フィールドがないプロパティは、設定 UI で辞書順に表示されます (マニフェストにリストされている順序ではありません)。

設定タイトル

設定 UI では、各設定の表示タイトルを構築するために複数のフィールドが使用されます。キーの大文字は、単語の区切りを示すために使用されます。

単一カテゴリおよび既定カテゴリ設定の表示タイトル

設定が単一の設定カテゴリを持つ場合、またはカテゴリが拡張機能の表示名と同じタイトルを持つ場合、そのカテゴリ内の設定に対して、設定 UI は設定 ID と拡張機能の name フィールドを使用して表示タイトルを決定します。

例として、設定 ID gitMagic.blame.dateFormat と拡張機能名 authorName.gitMagic の場合、設定 ID のプレフィックスが拡張機能名のサフィックスと一致するため、設定 ID の gitMagic 部分は表示タイトルから削除され、「Blame: Date Format」となります。

複数カテゴリ設定の表示タイトル

設定が複数の設定カテゴリを持ち、カテゴリが拡張機能の表示名と同じタイトルを持たない場合、そのカテゴリ内の設定に対して、設定 UI は設定 ID とカテゴリの id フィールドを使用して表示タイトルを決定します。

例として、設定 ID css.completion.completePropertyWithSemicolon とカテゴリ ID css の場合、設定 ID のプレフィックスがカテゴリ ID のサフィックスと一致するため、設定 UI で設定 ID の css 部分が削除され、生成される設定のタイトルは「Completion: Complete Property With Semicolon」になります。

設定プロパティスキーマ

設定キーは、JSON スキーマのスーパーセットを使用して定義されます。

description / markdownDescription

description 3️⃣ は、タイトルと入力フィールドの後に表示されます。ただし、ブール値の場合は、説明がチェックボックスのラベルとして使用されます。 6️⃣

{
  "gitMagic.blame.heatMap.enabled": {
    "description": "Specifies whether to provide a heatmap indicator in the gutter blame annotations"
  }
}

description の代わりに markdownDescription を使用すると、設定の説明は設定 UI で Markdown として解析されます。

{
  "gitMagic.blame.dateFormat": {
    "markdownDescription": "Specifies how to format absolute dates (e.g. using the `${date}` token) in gutter blame annotations. See the [Moment.js docs](https://momentjs.dokyumento.jp/docs/#/displaying/format/) for valid formats"
  }
}

markdownDescription の場合、改行または複数の段落を追加するには、単に \n を使用するのではなく、文字列 \n\n を使用して段落を区切ります。

タイプ

タイプが number 4️⃣、string 5️⃣、boolean 6️⃣ のエントリは、設定 UI で直接編集できます。

{
  "gitMagic.views.pageItemLimit": {
    "type": "number",
    "default": 20,
    "markdownDescription": "Specifies the number of items to show in each page when paginating a view list. Use 0 to specify no limit"
  }
}

文字列設定は、設定エントリで "editPresentation": "multilineText" を設定すると、複数行のテキスト入力としてレンダリングできます。

boolean エントリの場合、markdownDescription (または markdownDescription が指定されていない場合は description) がチェックボックスの横のラベルとして使用されます。

{
  "gitMagic.blame.compact": {
    "type": "boolean",
    "description": "Specifies whether to compact (deduplicate) matching adjacent gutter blame annotations"
  }
}

一部の object および array タイプの設定は、設定 UI でレンダリングされます。number、string、または boolean の単純な配列は、編集可能なリストとしてレンダリングされます。タイプが string、number、integer、および/または boolean のプロパティを持つオブジェクトは、キーと値の編集可能なグリッドとしてレンダリングされます。オブジェクト設定は、UI でレンダリングするために、additionalProperties を false に設定するか、適切な type プロパティを持つオブジェクトに設定する必要もあります。

object または array 型の設定が、ネストされたオブジェクト、配列、または null などの他の型も含むことができる場合、その値は設定 UI にレンダリングされず、JSON を直接編集することによってのみ変更できます。ユーザーには、上記のスクリーンショットに示すように、settings.json で編集へのリンクが表示されます。8️⃣

順序

カテゴリとそれらのカテゴリ内の設定の両方で、整数型の order プロパティを持つことができ、これは他のカテゴリや設定との相対的な並べ替え方法を示す参照を提供します。

2つのカテゴリに order プロパティがある場合、順序番号が小さいカテゴリが最初に表示されます。カテゴリに order プロパティが与えられていない場合、そのプロパティが与えられたカテゴリの後に表示されます。

同じカテゴリ内の2つの設定に order プロパティがある場合、順序番号が小さい設定が最初に表示されます。同じカテゴリ内の別の設定に order プロパティが与えられていない場合、そのカテゴリ内でそのプロパティが与えられた設定の後に表示されます。

2つのカテゴリが同じ order プロパティ値を持つ場合、または同じカテゴリ内の2つの設定が同じ order プロパティ値を持つ場合、それらは設定 UI 内で辞書順に昇順で並べ替えられます。

enum / enumDescriptions / markdownEnumDescriptions / enumItemLabels

enum 7️⃣ プロパティの下に項目の配列を提供すると、設定 UI はそれらの項目のドロップダウンメニューをレンダリングします。

また、enum プロパティと同じ長さの文字列の配列である enumDescriptions プロパティを提供することもできます。enumDescriptions プロパティは、各 enum 項目に対応するドロップダウンメニューの下部に設定 UI で説明を提供します。
また、enumDescriptions の代わりに markdownEnumDescriptions を使用することもでき、その場合、説明は Markdown として解析されます。markdownEnumDescriptions は enumDescriptions よりも優先されます。
設定 UI でドロップダウンオプション名をカスタマイズするには、enumItemLabels を使用できます。

例

{
  "settingsEditorTestExtension.enumSetting": {
    "type": "string",
    "enum": ["first", "second", "third"],
    "markdownEnumDescriptions": [
      "The *first* enum",
      "The *second* enum",
      "The *third* enum"
    ],
    "enumItemLabels": ["1st", "2nd", "3rd"],
    "default": "first",
    "description": "Example setting with an enum"
  }
}

settings UI screenshot of example enum setting above

deprecationMessage / markdownDeprecationMessage

deprecationMessage または markdownDeprecationMessage を設定すると、その設定には指定したメッセージとともに警告の下線が表示されます。また、ユーザーによって設定されない限り、その設定は設定 UI から非表示になります。markdownDeprecationMessage を設定した場合、Markdown は設定ホバーや問題ビューにはレンダリングされません。両方のプロパティを設定した場合、deprecationMessage はホバーと問題ビューに表示され、markdownDeprecationMessage は設定 UI で Markdown としてレンダリングされます。

例

{
  "json.colorDecorators.enable": {
    "type": "boolean",
    "description": "Enables or disables color decorators",
    "markdownDeprecationMessage": "**Deprecated**: Please use `#editor.colorDecorators#` instead.",
    "deprecationMessage": "Deprecated: Please use editor.colorDecorators instead."
  }
}

その他の JSON スキーマプロパティ

設定値に対する他の制約を記述するために、検証 JSON スキーマプロパティのいずれかを使用できます。

プロパティの既定値を定義するための default
数値の値を制限するための minimum と maximum
文字列の長さを制限するための maxLength、minLength
文字列を特定の正規表現に制限するための pattern
パターンが一致しない場合に、カスタマイズされたエラーメッセージを表示するための patternErrorMessage
文字列を date、time、ipv4、email、uri などのよく知られた形式に制限するための format
配列の長さを制限するための maxItems、minItems
[設定] エディターで文字列設定に対して単一行入力ボックスまたは複数行テキストエリアのどちらをレンダリングするかを制御するための editPresentation

サポートされていない JSON スキーマプロパティ

設定セクションでサポートされていないのは次のとおりです。

$ref および definition: 設定スキーマは自己完結型である必要があり、集約された設定 JSON スキーマドキュメントがどのように見えるかについて仮定することはできません。

これらの機能やその他の機能の詳細については、JSON スキーマのリファレンスを参照してください。

スコープ

設定には、次のいずれかのスコープを設定できます。

application - VS Code のすべてのインスタンスに適用され、ユーザー設定でのみ構成できる設定。
machine - ユーザー設定またはリモート設定でのみ設定できる、マシン固有の設定。たとえば、マシン間で共有すべきではないインストールパスなどです。これらの設定の値は同期されません。
machine-overridable - ワークスペースまたはフォルダーの設定によって上書きできる、マシン固有の設定。これらの設定の値は同期されません。
window - ユーザー、ワークスペース、またはリモート設定で構成できる、ウィンドウ (インスタンス) 固有の設定。
resource - ファイルとフォルダーに適用され、フォルダー設定を含むすべての設定レベルで構成できるリソース設定。
language-overridable - 言語レベルで上書きできるリソース設定。

設定スコープは、[設定] エディターを通じていつ設定がユーザーに利用可能になるか、および設定が適用可能かどうかを決定します。scope が宣言されていない場合、既定は window です。

以下は、組み込みの Git 拡張機能からの設定スコープの例です。

{
  "contributes": {
    "configuration": {
      "title": "Git",
      "properties": {
        "git.alwaysSignOff": {
          "type": "boolean",
          "scope": "resource",
          "default": false,
          "description": "%config.alwaysSignOff%"
        },
        "git.ignoredRepositories": {
          "type": "array",
          "default": [],
          "scope": "window",
          "description": "%config.ignoredRepositories%"
        },
        "git.autofetch": {
          "type": ["boolean", "string"],
          "enum": [true, false, "all"],
          "scope": "resource",
          "markdownDescription": "%config.autofetch%",
          "default": false,
          "tags": ["usesOnlineServices"]
        }
      }
    }
  }
}

git.alwaysSignOff には resource スコープがあり、ユーザー、ワークスペース、またはフォルダーごとに設定できる一方で、window スコープを持つ無視されるリポジトリリストは、VS Code ウィンドウまたはワークスペース (マルチルートの場合もあります) に対してよりグローバルに適用されることがわかります。

ignoreSync

ignoreSync を true に設定すると、設定がユーザーの設定と同期されるのを防ぐことができます。これは、ユーザー固有ではない設定に役立ちます。たとえば、remoteTunnelAccess.machineName 設定はユーザー固有ではないため、同期すべきではありません。scope を machine または machine-overridable に設定した場合、ignoreSync の値にかかわらず設定は同期されませんのでご注意ください。

{
  "contributes": {
    "configuration": {
      "properties": {
        "remoteTunnelAccess.machineName": {
          "type": "string",
          "default": "",
          "ignoreSync": true
        }
      }
    }
  }
}

```json
{
  "remoteTunnelAccess.machineName": {
    "type": "string",
    "default": '',
    "ignoreSync": true
  }
}

設定へのリンク

設定 UI でクリック可能なリンクとしてレンダリングされる別の設定へのリンクを、markdown 型のプロパティで特別な構文: `#target.setting.id#` を使用して挿入できます。これは markdownDescription、markdownEnumDescriptions、markdownDeprecationMessage で機能します。例

  "files.autoSaveDelay": {
    "markdownDescription": "Controls the delay in ms after which a dirty editor is saved automatically. Only applies when `#files.autoSave#` is set to `afterDelay`.",
    // ...
  }

設定 UI では、次のようにレンダリングされます。

setting link example

contributes.configurationDefaults

他の登録済み設定の既定値を登録し、その既定値を上書きします。

以下の例は、files.autoSave 設定の既定の動作を、フォーカス変更時にファイルを自動保存するように上書きします。

"configurationDefaults": {
      "files.autoSave": "onFocusChange"
}

また、提供された言語の既定のエディター設定を登録することもできます。たとえば、次のスニペットは markdown 言語の既定のエディター設定を登録します。

{
  "contributes": {
    "configurationDefaults": {
      "[markdown]": {
        "editor.wordWrap": "on",
        "editor.quickSuggestions": {
          "comments": "off",
          "strings": "off",
          "other": "off"
        }
      }
    }
  }
}

contributes.customEditors

customEditors 貢献ポイントは、拡張機能が提供するカスタムエディターを VS Code に伝える方法です。たとえば、VS Code は、カスタムエディターがどの種類のファイルで動作するか、および任意の UI でカスタムエディターを識別する方法を知る必要があります。

カスタムエディター拡張機能のサンプルのための基本的な customEditor の貢献例です。

"contributes": {
  "customEditors": [
    {
      "viewType": "catEdit.catScratch",
      "displayName": "Cat Scratch",
      "selector": [
        {
          "filenamePattern": "*.cscratch"
        }
      ],
      "priority": "default"
    }
  ]
}

customEditors は配列であるため、拡張機能は複数のカスタムエディターを登録できます。

viewType - カスタムエディターの一意の識別子。

これは、VS Code が package.json のカスタムエディター貢献とコード内のカスタムエディター実装を関連付ける方法です。これはすべての拡張機能で一意である必要があり、"preview" のような一般的な viewType の代わりに、拡張機能に一意のものを確実に使用してください (例: "viewType": "myAmazingExtension.svgPreview")。
displayName - VS Code の UI でカスタムエディターを識別する名前。

表示名は、ビュー: 別の方法で再度開くドロップダウンなどの VS Code UI でユーザーに表示されます。
selector - カスタムエディターがアクティブになるファイルを指定します。

selector は、1つ以上のglob パターンの配列です。これらの glob パターンはファイル名と照合され、カスタムエディターがそれらに使用できるかどうかを決定します。filenamePattern のような *.png は、すべての PNG ファイルに対してカスタムエディターを有効にします。

また、ファイル名やディレクトリ名に一致するより具体的なパターンを作成することもできます (例: **/translations/*.json)。
priority - (オプション) カスタムエディターがいつ使用されるかを指定します。

priority は、リソースが開かれているときにカスタムエディターがいつ使用されるかを制御します。可能な値は次のとおりです。
- "default" - カスタムエディターの selector に一致するすべてのファイルに対してカスタムエディターを使用しようとします。特定のファイルに複数のカスタムエディターがある場合、ユーザーは使用するカスタムエディターを選択する必要があります。
- "option" - 既定ではカスタムエディターを使用しませんが、ユーザーがそれに切り替えたり、既定として設定したりできるようにします。

詳細については、カスタムエディター拡張機能ガイドを参照してください。

contributes.debuggers

VS Code にデバッガーを登録します。デバッガー貢献には次のプロパティがあります。

type は、起動構成でこのデバッガーを識別するために使用される一意の ID です。
label は、UI でこのデバッガーのユーザーに表示される名前です。
program は、実際のデバッガーまたはランタイムに対して VS Code デバッグプロトコルを実装するデバッグアダプターへのパスです。
runtime は、デバッグアダプターへのパスが実行可能ファイルではないが、ランタイムが必要な場合。
configurationAttributes は、このデバッガーに固有の起動構成引数のスキーマです。JSON スキーマの構成要素 $ref と definition はサポートされていないことに注意してください。
initialConfigurations は、初期の launch.json を生成するために使用される起動構成をリストします。
configurationSnippets は、launch.json を編集する際に IntelliSense を通じて利用可能な起動構成をリストします。
variables は置換変数を導入し、デバッガー拡張機能によって実装されたコマンドにそれらをバインドします。
languages は、デバッグ拡張機能が「既定のデバッガー」とみなされる言語。

デバッガーの例

{
  "contributes": {
    "debuggers": [
      {
        "type": "node",
        "label": "Node Debug",

        "program": "./out/node/nodeDebug.js",
        "runtime": "node",

        "languages": ["javascript", "typescript", "javascriptreact", "typescriptreact"],

        "configurationAttributes": {
          "launch": {
            "required": ["program"],
            "properties": {
              "program": {
                "type": "string",
                "description": "The program to debug."
              }
            }
          }
        },

        "initialConfigurations": [
          {
            "type": "node",
            "request": "launch",
            "name": "Launch Program",
            "program": "${workspaceFolder}/app.js"
          }
        ],

        "configurationSnippets": [
          {
            "label": "Node.js: Attach Configuration",
            "description": "A new configuration for attaching to a running node program.",
            "body": {
              "type": "node",
              "request": "attach",
              "name": "${2:Attach to Port}",
              "port": 9229
            }
          }
        ],

        "variables": {
          "PickProcess": "extension.node-debug.pickNodeProcess"
        }
      }
    ]
  }
}

debugger を統合する方法の詳細なウォークスルーについては、デバッガー拡張機能を参照してください。

contributes.grammars

言語に TextMate 文法を登録します。この文法が適用される language、文法の TextMate scopeName、およびファイルパスを指定する必要があります。

注: 文法を含むファイルは JSON (ファイル名が .json で終わるもの) または XML plist 形式 (その他のすべてのファイル) にすることができます。

文法の例

{
  "contributes": {
    "grammars": [
      {
        "language": "markdown",
        "scopeName": "text.html.markdown",
        "path": "./syntaxes/markdown.tmLanguage.json",
        "embeddedLanguages": {
          "meta.embedded.block.frontmatter": "yaml"
        }
      }
    ]
  }
}

言語に関連付けられた TextMate 文法を登録してシンタックスハイライトを受け取る方法の詳細については、シンタックスハイライトガイドを参照してください。

grammars extension point example

contributes.icons

ID と既定のアイコンを指定して、新しいアイコンを登録します。そのアイコン ID は、拡張機能 (またはその拡張機能に依存する他の拡張機能) によって、ThemeIcon を使用できる場所 (new ThemeIcon("iconId"))、Markdown 文字列 ($(iconId))、および特定の貢献ポイントのアイコンとして使用できます。

{
  "contributes": {
    "icons": {
      "distro-ubuntu": {
        "description": "Ubuntu icon",
        "default": {
          "fontPath": "./distroicons.woff",
          "fontCharacter": "\\E001"
        }
      },
      "distro-fedora": {
        "description": "Ubuntu icon",
        "default": {
          "fontPath": "./distroicons.woff",
          "fontCharacter": "\\E002"
        }
      }
    }
  }
}

contributes.iconThemes

VS Code にファイルアイコンテーマを登録します。ファイルアイコンはファイル名の横に表示され、ファイルの種類を示します。

ID (設定で使用)、ラベル、およびファイルアイコン定義ファイルへのパスを指定する必要があります。

ファイルアイコンテーマの例

{
  "contributes": {
    "iconThemes": [
      {
        "id": "my-cool-file-icons",
        "label": "Cool File Icons",
        "path": "./fileicons/cool-file-icon-theme.json"
      }
    ]
  }
}

ファイルアイコンテーマの作成方法については、ファイルアイコンテーマガイドを参照してください。

contributes.jsonValidation

特定の種類の json ファイルの検証スキーマを登録します。url の値は、拡張機能に含まれるスキーマファイルへのローカルパス、またはJSON スキーマストアのようなリモートサーバー URL のいずれかになります。

{
  "contributes": {
    "jsonValidation": [
      {
        "fileMatch": ".jshintrc",
        "url": "https://json.schemastore.org/jshintrc"
      }
    ]
  }
}

contributes.keybindings

ユーザーがキーの組み合わせを押したときに呼び出されるコマンドを定義するキーバインディングルールを登録します。キーバインディングの詳細については、キーバインディングのトピックを参照してください。

キーバインディングを登録すると、[既定のキーボードショートカット] にそのルールが表示され、コマンドのすべての UI 表示で追加したキーバインディングが示されるようになります。そしてもちろん、ユーザーがキーの組み合わせを押すと、コマンドが呼び出されます。

注: VS Code は Windows、macOS、Linux で実行され、修飾キーが異なるため、「key」を使用して既定のキーの組み合わせを設定し、特定のプラットフォームで上書きできます。

注: コマンドが (キーバインディングまたはコマンドパレットから) 呼び出されると、VS Code は onCommand:${command} というアクティベーションイベントを発行します。

キーバインディングの例

Windows および Linux では Ctrl+F1、macOS では Cmd+F1 が "extension.sayHello" コマンドをトリガーするように定義する。

{
  "contributes": {
    "keybindings": [
      {
        "command": "extension.sayHello",
        "key": "ctrl+f1",
        "mac": "cmd+f1",
        "when": "editorTextFocus"
      }
    ]
  }
}

keybindings extension point example

contributes.languages

プログラミング言語の定義を登録します。これにより、新しい言語が導入されるか、VS Code が言語に関して持つ知識が強化されます。

contributes.languages の主な効果は次のとおりです。

vscode.TextDocument.languageId や onLanguage アクティベーションイベントなど、VS Code API の他の部分で再利用できる languageId を定義します。
- aliases フィールドを使用して、人間が読める名前を登録できます。リストの最初の項目が人間が読めるラベルとして使用されます。
ファイル名拡張子 (extensions)、ファイル名 (filenames)、ファイル名glob パターン (filenamePatterns)、特定の行で始まるファイル (ハッシュバンなど) (firstLine)、および mimetypes をその languageId に関連付けます。
登録された言語の宣言型言語機能のセットを登録します。設定可能な編集機能の詳細については、言語設定ガイドを参照してください。
テーマがその言語のアイコンを含んでいない場合に、ファイルアイコンテーマとして使用できるアイコンを登録します。

言語の例

{
  "contributes": {
    "languages": [
      {
        "id": "python",
        "extensions": [".py"],
        "aliases": ["Python", "py"],
        "filenames": [],
        "firstLine": "^#!/.*\\bpython[0-9.-]*\\b",
        "configuration": "./language-configuration.json",
        "icon": {
          "light": "./icons/python-light.png",
          "dark": "./icons/python-dark.png"
        }
      }
    ]
  }
}

contributes.menus

エディターまたはエクスプローラーにコマンドのメニュー項目を登録します。メニュー項目定義には、選択時に呼び出されるコマンドと、項目が表示される条件が含まれます。後者は、キーバインディングのwhen 句コンテキストを使用する when 句で定義されます。

command プロパティは、メニュー項目を選択したときに実行するコマンドを示します。submenu プロパティは、この場所にレンダリングするサブメニューを示します。

command メニュー項目を宣言する際、alt プロパティを使用して代替コマンドを定義することもできます。メニューを開くときに Alt を押すと表示され、呼び出されます。Windows および Linux では Shift もこの動作をします。これは Alt がウィンドウメニューバーをトリガーしてしまうような状況で役立ちます。

最後に、group プロパティはメニュー項目の並べ替えとグループ化を定義します。navigation グループは特殊で、常にメニューの先頭/最初に並べ替えられます。

注: when 句はメニューに適用され、enablement 句はコマンドに適用されることに注意してください。enablement はすべてのメニュー、さらにはキーバインディングにも適用されますが、when は単一のメニューにのみ適用されます。

現在、拡張機能開発者は以下に貢献できます。

commandPalette - グローバルコマンドパレット
comments/comment/title - コメントタイトルメニューバー
comments/comment/context - コメントコンテキストメニュー
comments/commentThread/title - コメントスレッドタイトルメニューバー
comments/commentThread/context- コメントスレッドコンテキストメニュー
debug/callstack/context - デバッグコールスタックビューコンテキストメニュー
debug/callstack/context グループ inline - デバッグコールスタックビューインラインアクション
debug/toolBar - デバッグビューツールバー
debug/variables/context - デバッグ変数ビューコンテキストメニュー
editor/context - エディターコンテキストメニュー
editor/lineNumber/context - エディター行番号コンテキストメニュー
editor/title - エディタータイトルメニューバー
editor/title/context - エディタータイトルコンテキストメニュー
editor/title/run - エディタータイトルメニューバーの実行サブメニュー
explorer/context - エクスプローラービューコンテキストメニュー
extension/context - 拡張機能ビューコンテキストメニュー
file/newFile - [ファイル] メニューおよびようこそページの [新しいファイル] 項目
interactive/toolbar - 対話型ウィンドウツールバー
interactive/cell/title - 対話型ウィンドウセルタイトルメニューバー
notebook/toolbar - ノートブックツールバー
notebook/cell/title - ノートブックセルタイトルメニューバー
notebook/cell/execute - ノートブックセル実行メニュー
scm/title - SCM タイトルメニュー
scm/resourceGroup/context - SCM リソースグループメニュー
scm/resourceFolder/context - SCM リソースフォルダーメニュー
scm/resourceState/context - SCM リソースメニュー
scm/change/title - SCM 変更タイトルメニュー
scm/sourceControl- SCM ソース管理メニュー
terminal/context - ターミナルコンテキストメニュー
terminal/title/context - ターミナルタイトルコンテキストメニュー
testing/item/context - テストエクスプローラー項目コンテキストメニュー
testing/item/gutter - テスト項目用のガター装飾メニュー
timeline/title - タイムラインビュータイトルメニューバー
timeline/item/context - タイムラインビュー項目コンテキストメニュー
touchBar - macOS Touch Bar
view/title - ビュータイトルメニュー
view/item/context - ビュー項目コンテキストメニュー
webview/context - 任意のwebview コンテキストメニュー
任意の登録されたサブメニュー

注 1: コマンドが (コンテキスト) メニューから呼び出されると、VS Code は現在選択されているリソースを推測し、そのリソースをコマンド呼び出し時のパラメーターとして渡そうとします。たとえば、エクスプローラー内のメニュー項目には選択されたリソースの URI が渡され、エディター内のメニュー項目にはドキュメントの URI が渡されます。

注 2: editor/lineNumber/context に登録されたメニュー項目のコマンドには、行番号も渡されます。さらに、これらの項目は、when 句で editorLineNumber コンテキストキーを参照できます。たとえば、in または not in 演算子を使用して、拡張機能が管理する配列値のコンテキストキーに対してテストできます。

登録されたコマンドは、タイトルに加えて、呼び出し元のメニュー項目がボタンとして (たとえば、タイトルメニューバーに) 表示されるときに VS Code が表示するアイコンを指定できます。

コマンドメニュー項目です。

{
  "contributes": {
    "menus": {
      "editor/title": [
        {
          "when": "resourceLangId == markdown",
          "command": "markdown.showPreview",
          "alt": "markdown.showPreviewToSide",
          "group": "navigation"
        }
      ]
    }
  }
}

menus extension point example

同様に、特定のビューに追加されたコマンドメニュー項目です。以下の例は、ターミナルなどの任意のビューに貢献します。

{
  "contributes": {
    "menus": {
      "view/title": [
        {
          "command": "terminalApi.sendText",
          "when": "view == terminal",
          "group": "navigation"
        }
      ]
    }
  }
}

Adding a menu entry to view/title with view == terminal will result in an action in the panel when the terminal is open

サブメニュー項目です。

{
  "contributes": {
    "menus": {
      "scm/title": [
        {
          "submenu": "git.commit",
          "group": "2_main@1",
          "when": "scmProvider == git"
        }
      ]
    }
  }
}

menus extension point example (submenu)

package.json でコマンドを登録すると、自動的にコマンドパレット (⇧⌘P (Windows, Linux Ctrl+Shift+P)) に表示されます。コマンドの表示をより詳細に制御できるように、commandPalette メニュー項目があります。これにより、コマンドがコマンドパレットに表示されるべきかどうかを制御する when 条件を定義できます。

以下のスニペットは、「Hello World」コマンドをエディターで何かが選択されている場合にのみコマンドパレットに表示されるようにします。

{
  "commands": [
    {
      "command": "extension.sayHello",
      "title": "Hello World"
    }
  ],
  "menus": {
    "commandPalette": [
      {
        "command": "extension.sayHello",
        "when": "editorHasSelection"
      }
    ]
  }
}

グループの並べ替え

メニュー項目はグループに並べ替えることができます。それらは、以下の既定値/ルールに従って辞書順に並べ替えられます。これらのグループにメニュー項目を追加したり、その間、下、または上に新しいメニュー項目グループを追加したりできます。

エディターコンテキストメニューには、次の既定のグループがあります。

navigation - navigation グループはすべての場合で最初に表示されます。
1_modification - このグループは次に表示され、コードを変更するコマンドが含まれます。
9_cutcopypaste - 基本的な編集コマンドを含む、最後から2番目の既定のグループ。
z_commands - コマンドパレットを開くエントリを含む最後の既定のグループ。

Menu Group Sorting

エクスプローラーコンテキストメニューには、次の既定のグループがあります。

navigation - VS Code 全体のナビゲーションに関連するコマンド。このグループはすべての場合で最初に表示されます。
2_workspace - ワークスペース操作に関連するコマンド。
3_compare - 差分エディターでのファイルの比較に関連するコマンド。
4_search - 検索ビューでの検索に関連するコマンド。
5_cutcopypaste - ファイルの切り取り、コピー、貼り付けに関連するコマンド。
6_copypath - ファイルパスのコピーに関連するコマンド。
7_modification - ファイルの変更に関連するコマンド。

エディタータブコンテキストメニューには、次の既定のグループがあります。

1_close - エディターのクローズに関連するコマンド。
3_preview - エディターのピン留めに関連するコマンド。

エディタータイトルメニューには、次の既定のグループがあります。

navigation - ナビゲーションに関連するコマンド。
1_run - エディターの実行とデバッグに関連するコマンド。
1_diff - 差分エディターの操作に関連するコマンド。
3_open - エディターのオープンに関連するコマンド。
5_close - エディターのクローズに関連するコマンド。

navigation および 1_run はプライマリエディタータイトル領域に表示されます。その他のグループはセカンダリエリア (... メニューの下) に表示されます。

ターミナルタブコンテキストメニューには、次の既定のグループがあります。

1_create - ターミナルの作成に関連するコマンド。
3_run - ターミナルで何かを実行する/実行に関連するコマンド。
5_manage - ターミナルの管理に関連するコマンド。
7_configure - ターミナル設定に関連するコマンド。

ターミナルコンテキストメニューには、次の既定のグループがあります。

1_create - ターミナルの作成に関連するコマンド。
3_edit - テキスト、選択範囲、またはクリップボードの操作に関連するコマンド。
5_clear - ターミナルのクリアに関連するコマンド。
7_kill - ターミナルのクローズ/強制終了に関連するコマンド。
9_config - ターミナル設定に関連するコマンド。

タイムラインビュー項目コンテキストメニューには、次の既定のグループがあります。

inline - 重要または頻繁に使用されるタイムライン項目コマンド。ツールバーとしてレンダリングされます。
1_actions - タイムライン項目との連携に関連するコマンド。
5_copy - タイムライン項目情報のコピーに関連するコマンド。

拡張機能ビューコンテキストメニューには、次の既定のグループがあります。

1_copy - 拡張機能情報のコピーに関連するコマンド。
2_configure - 拡張機能の設定に関連するコマンド。

グループ内の並べ替え

グループ内の順序は、タイトルまたは順序属性によって決まります。メニュー項目のグループ内ローカル順序は、以下に示すようにグループ識別子に @<number> を追加することによって指定されます。

{
  "editor/title": [
    {
      "when": "editorHasSelection",
      "command": "extension.Command",
      "group": "myGroup@1"
    }
  ]
}

contributes.problemMatchers

問題マッチャーパターンを登録します。これらの貢献は、出力パネルランナーとターミナルランナーの両方で機能します。以下は、拡張機能で gcc コンパイラのプロブレムマッチャーを登録する例です。

{
  "contributes": {
    "problemMatchers": [
      {
        "name": "gcc",
        "owner": "cpp",
        "fileLocation": ["relative", "${workspaceFolder}"],
        "pattern": {
          "regexp": "^(.*):(\\d+):(\\d+):\\s+(warning|error):\\s+(.*)$",
          "file": 1,
          "line": 2,
          "column": 3,
          "severity": 4,
          "message": 5
        }
      }
    ]
  }
}

このプロブレムマッチャーは、tasks.json ファイルで名前参照 $gcc を介して使用できるようになりました。例は次のとおりです。

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "build",
      "command": "gcc",
      "args": ["-Wall", "helloWorld.c", "-o", "helloWorld"],
      "problemMatcher": "$gcc"
    }
  ]
}

参照: プロブレムマッチャーの定義

contributes.problemPatterns

問題マッチャーで使用できる名前付き問題パターンを登録します (上記参照)。

contributes.productIconThemes

VS Code に製品アイコンテーマを登録します。製品アイコンとは、VS Code で使用されるすべてのアイコンのうち、ファイルアイコンと拡張機能から登録されたアイコンを除くすべてのアイコンです。

ID (設定で使用)、ラベル、およびアイコン定義ファイルへのパスを指定する必要があります。

製品アイコンテーマの例

{
  "contributes": {
    "productIconThemes": [
      {
        "id": "elegant",
        "label": "Elegant Icon Theme",
        "path": "./producticons/elegant-product-icon-theme.json"
      }
    ]
  }
}

製品アイコンテーマの作成方法については、製品アイコンテーマガイドを参照してください。

contributes.resourceLabelFormatters

ワークベンチのすべての場所で URI を表示する方法を指定するリソースラベルフォーマッターを登録します。たとえば、拡張機能がスキーム remotehub を持つ URI のフォーマッターを登録する方法を次に示します。

{
  "contributes": {
    "resourceLabelFormatters": [
      {
        "scheme": "remotehub",
        "formatting": {
          "label": "${path}",
          "separator": "/",
          "workspaceSuffix": "GitHub"
        }
      }
    ]
  }
}

これは、スキーム remotehub を持つすべての URI が、URI の path セグメントのみを表示してレンダリングされ、区切り文字が / になることを意味します。remotehub URI を持つワークスペースは、そのラベルに GitHub のサフィックスを持ちます。

contributes.semanticTokenModifiers

テーマルールを介してハイライトできる新しいセマンティックトークン修飾子を登録します。

{
  "contributes": {
    "semanticTokenModifiers": [
      {
        "id": "native",
        "description": "Annotates a symbol that is implemented natively"
      }
    ]
  }
}

セマンティックハイライトの詳細については、セマンティックハイライトガイドを参照してください。

contributes.semanticTokenScopes

セマンティックトークンの型と修飾子、およびスコープ間のマッピングを、フォールバックとして、または言語固有のテーマをサポートするために登録します。

{
  "contributes": {
    "semanticTokenScopes": [
      {
        "language": "typescript",
        "scopes": {
          "property.readonly": ["variable.other.constant.property.ts"]
        }
      }
    ]
  }
}

セマンティックハイライトの詳細については、セマンティックハイライトガイドを参照してください。

contributes.semanticTokenTypes

テーマルールを介してハイライトできる新しいセマンティックトークン型を登録します。

{
  "contributes": {
    "semanticTokenTypes": [
      {
        "id": "templateType",
        "superType": "type",
        "description": "A template type."
      }
    ]
  }
}

セマンティックハイライトの詳細については、セマンティックハイライトガイドを参照してください。

contributes.snippets

特定の言語のスニペットを登録します。language 属性は言語識別子であり、path はスニペットファイルへの相対パスであり、VS Code スニペット形式でスニペットを定義します。

以下の例は、Go 言語のスニペットを追加する方法を示しています。

{
  "contributes": {
    "snippets": [
      {
        "language": "go",
        "path": "./snippets/go.json"
      }
    ]
  }
}

contributes.submenus

メニュー項目を登録できるプレースホルダーとしてサブメニューを登録します。サブメニューには、親メニューに表示される label が必要です。

タイトルに加えて、コマンドは VS Code がエディタータイトルメニューバーに表示するアイコンを定義することもできます。

サブメニューの例

{
  "contributes": {
    "submenus": [
      {
        "id": "git.commit",
        "label": "Commit"
      }
    ]
  }
}

submenus extension point example

contributes.taskDefinitions

システム内の登録されたタスクを一意に識別できるオブジェクトリテラル構造を登録および定義します。タスク定義には最低限 type プロパティがありますが、通常は追加のプロパティを定義します。たとえば、package.json ファイル内のスクリプトを表すタスクのタスク定義は次のようになります。

{
  "taskDefinitions": [
    {
      "type": "npm",
      "required": ["script"],
      "properties": {
        "script": {
          "type": "string",
          "description": "The script to execute"
        },
        "path": {
          "type": "string",
          "description": "The path to the package.json file. If omitted the package.json in the root of the workspace folder is used."
        }
      }
    }
  ]
}

タスク定義は、required および properties プロパティに JSON スキーマ構文を使用して定義されます。type プロパティはタスクタイプを定義します。上記の例の場合：

"type": "npm" は、タスク定義を npm タスクに関連付けます。
"required": [ "script" ] は、script 属性を必須として定義します。path プロパティはオプションです。
"properties" : { ... } は、追加のプロパティとその型を定義します。

拡張機能が実際にタスクを作成する場合、package.json ファイルで登録されたタスク定義に準拠する TaskDefinition を渡す必要があります。npm の例では、package.json ファイル内のテストスクリプトのタスク作成は次のようになります。

let task = new vscode.Task({ type: 'npm', script: 'test' }, ....);

contributes.terminal

VS Code にターミナルプロファイルを登録し、拡張機能がプロファイルの作成を処理できるようにします。定義されると、ターミナルプロファイル作成時にそのプロファイルが表示されます。

{
  "activationEvents": ["onTerminalProfile:my-ext.terminal-profile"],
  "contributes": {
    "terminal": {
      "profiles": [
        {
          "title": "Profile from extension",
          "id": "my-ext.terminal-profile"
        }
      ]
    }
  }
}

定義されると、そのプロファイルはターミナルプロファイルセレクターに表示されます。アクティブ化されると、ターミナルオプションを返すことでプロファイルの作成を処理します。

vscode.window.registerTerminalProfileProvider('my-ext.terminal-profile', {
  provideTerminalProfile(
    token: vscode.CancellationToken
  ): vscode.ProviderResult<vscode.TerminalOptions | vscode.ExtensionTerminalOptions> {
    return { name: 'Profile from extension', shellPath: 'bash' };
  }
});

contributes.themes

VS Code にカラーテーマを登録し、エディター内のシンタックストークン用のワークベンチカラーとスタイルを定義します。

ラベル、テーマがダークテーマかライトテーマか (VS Code の残りの部分がテーマに合わせて変更されるように)、およびファイルへのパス (JSON 形式) を指定する必要があります。

テーマの例

{
  "contributes": {
    "themes": [
      {
        "label": "Monokai",
        "uiTheme": "vs-dark",
        "path": "./themes/monokai-color-theme.json"
      }
    ]
  }
}

color theme extension point example

カラーテーマの作成方法については、カラーテーマガイドを参照してください。

contributes.typescriptServerPlugins

VS Code の JavaScript および TypeScript のサポートを拡張するTypeScript サーバープラグインを登録します。

{
  "contributes": {
    "typescriptServerPlugins": [
      {
        "name": "typescript-styled-plugin"
      }
    ]
  }
}

上記の拡張機能の例は、JavaScript および TypeScript 用の styled-component IntelliSense を追加するtypescript-styled-plugin を提供します。このプラグインは拡張機能からロードされ、拡張機能に通常の NPM dependency としてインストールされている必要があります。

{
  "dependencies": {
    "typescript-styled-plugin": "*"
  }
}

TypeScript サーバープラグインは、ユーザーが VS Code の TypeScript バージョンを使用している場合、すべての JavaScript および TypeScript ファイルでロードされます。ユーザーがワークスペースバージョンの TypeScript を使用している場合は、プラグインが明示的に "enableForWorkspaceTypeScriptVersions": true を設定しない限り、アクティブ化されません。

{
  "contributes": {
    "typescriptServerPlugins": [
      {
        "name": "typescript-styled-plugin",
        "enableForWorkspaceTypeScriptVersions": true
      }
    ]
  }
}

プラグイン設定

拡張機能は、VS Code の組み込み TypeScript 拡張機能によって提供される API を介して、登録された TypeScript プラグインに設定データを送信できます。

// In your VS Code extension

export async function activate(context: vscode.ExtensionContext) {
  // Get the TS extension
  const tsExtension = vscode.extensions.getExtension('vscode.typescript-language-features');
  if (!tsExtension) {
    return;
  }

  await tsExtension.activate();

  // Get the API from the TS extension
  if (!tsExtension.exports || !tsExtension.exports.getAPI) {
    return;
  }

  const api = tsExtension.exports.getAPI(0);
  if (!api) {
    return;
  }

  // Configure the 'my-typescript-plugin-id' plugin
  api.configurePlugin('my-typescript-plugin-id', {
    someValue: process.env['SOME_VALUE']
  });
}

TypeScript サーバープラグインは、onConfigurationChanged メソッドを介して設定データを受け取ります。

// In your TypeScript plugin

import * as ts_module from 'typescript/lib/tsserverlibrary';

export = function init({ typescript }: { typescript: typeof ts_module }) {
  return {
    create(info: ts.server.PluginCreateInfo) {
      // Create new language service
    },
    onConfigurationChanged(config: any) {
      // Receive configuration changes sent from VS Code
    }
  };
};

この API を使用すると、VS Code 拡張機能は VS Code の設定を TypeScript サーバープラグインと同期したり、プラグインの動作を動的に変更したりできます。この API が実際にどのように使用されているかについては、TypeScript TSLint プラグインとlit-html拡張機能を参照してください。

contributes.views

VS Code にビューを登録します。ビューの識別子と名前を指定する必要があります。次のビューコンテナーに貢献できます。

explorer: アクティビティバーのエクスプローラービューコンテナー
scm: アクティビティバーのソース管理 (SCM) ビューコンテナー
debug: アクティビティバーの実行とデバッグのビューコンテナー
test: アクティビティバーのテストビューコンテナー
拡張機能によって提供されるカスタムビューコンテナー。

ユーザーがビューを開くと、VS Code は onView:${viewId} というアクティベーションイベントを発行します (以下の例では onView:nodeDependencies)。また、when コンテキスト値を指定することで、ビューの表示を制御することもできます。指定された icon は、タイトルを表示できない場合 (たとえば、ビューをアクティビティバーにドラッグした場合など) に使用されます。contextualTitle は、ビューが既定のビューコンテナーから移動され、追加のコンテキストが必要な場合に使用されます。

{
  "contributes": {
    "views": {
      "explorer": [
        {
          "id": "nodeDependencies",
          "name": "Node Dependencies",
          "when": "workspaceHasPackageJSON",
          "icon": "media/dep.svg",
          "contextualTitle": "Package Explorer"
        }
      ]
    }
  }
}

views extension point example

ビューのコンテンツは、次の2つの方法で設定できます。

createTreeView API を介してデータプロバイダーを提供するか、または registerTreeDataProvider API を介してデータプロバイダーを直接登録して、TreeView でデータを設定します。TreeView は階層データとリストを表示するのに最適です。tree-view-sampleを参照してください。
registerWebviewViewProvider でプロバイダーを登録して、WebviewView で。Webview ビューでは、ビュー内に任意の HTML をレンダリングできます。詳細については、webview view sample extensionを参照してください。

contributes.viewsContainers

カスタムビューを登録できるビューコンテナーを登録します。ビューコンテナーの識別子、タイトル、およびアイコンを指定する必要があります。現在、アクティビティバー (activitybar) とパネル (panel) に貢献できます。以下の例は、Package Explorer ビューコンテナーがアクティビティバーにどのように貢献され、ビューがそれに貢献されるかを示しています。

{
  "contributes": {
    "viewsContainers": {
      "activitybar": [
        {
          "id": "package-explorer",
          "title": "Package Explorer",
          "icon": "resources/package-explorer.svg"
        }
      ]
    },
    "views": {
      "package-explorer": [
        {
          "id": "package-dependencies",
          "name": "Dependencies"
        },
        {
          "id": "package-outline",
          "name": "Outline"
        }
      ]
    }
  }
}

Custom views container

アイコンの仕様

サイズ: アイコンは 24x24 で中央に配置する必要があります。
色: アイコンは単一の色を使用する必要があります。
形式: アイコンは SVG 形式にすることが推奨されますが、任意の画像ファイル形式が受け入れられます。
状態: すべてのアイコンは次の状態スタイルを継承します。

状態不透明度

既定値 60%

ホバー 100%

アクティブ 100%

contributes.viewsWelcome

カスタムビューにウェルカムコンテンツを登録します。ウェルカムコンテンツは、空のツリービューにのみ適用されます。ツリーに子がなく、TreeView.message もない場合、ビューは空と見なされます。慣例として、行単独で存在するコマンドリンクはボタンとして表示されます。view プロパティを使用して、ウェルカムコンテンツが適用されるビューを指定できます。ウェルカムコンテンツの表示は、when コンテキスト値で制御できます。ウェルカムコンテンツとして表示されるテキストは、contents プロパティで設定されます。

{
  "contributes": {
    "viewsWelcome": [
      {
        "view": "scm",
        "contents": "In order to use git features, you can open a folder containing a git repository or clone from a URL.\n[Open Folder](command:vscode.openFolder)\n[Clone Repository](command:git.clone)\nTo learn more about how to use git and source control in VS Code [read our docs](https://aka.ms/vscode-scm).",
        "when": "config.git.enabled && git.state == initialized && workbenchState == empty"
      }
    ]
  }
}

Welcome content example

複数のウェルカムコンテンツ項目を1つのビューに登録できます。この場合、VS Code コアからのコンテンツが最初に表示され、次に組み込み拡張機能からのコンテンツ、そして他のすべての拡張機能からのコンテンツが続きます。

contributes.walkthroughs

サンプル拡張機能

[はじめに] ページに表示されるウォークスルーを登録します。ウォークスルーは拡張機能のインストール時に自動的に開かれ、ユーザーに拡張機能の機能を紹介する便利な方法を提供します。

ウォークスルーは、タイトル、説明、ID、および一連のステップで構成されます。さらに、コンテキストキーに基づいてウォークスルーを非表示または表示するために when 条件を設定できます。たとえば、Linux プラットフォームでのセットアップを説明するウォークスルーには、Linux マシンでのみ表示されるように when: "isLinux" を指定できます。

ウォークスルーの各ステップには、タイトル、説明、ID、およびメディア要素 (画像または Markdown コンテンツのいずれか) があり、さらにステップがチェックされる原因となるオプションのイベントセットも含まれます (以下の例を参照)。ステップの説明は Markdown コンテンツであり、**太字**、__下線__、および ``コード`` のレンダリングと、リンクをサポートします。ウォークスルーと同様に、ステップには、コンテキストキーに基づいて表示または非表示にするための when 条件を指定できます。

SVG は、そのスケーラビリティと VS Code のテーマカラーのサポートを考慮すると、画像に推奨されます。SVG でテーマカラーを簡単に参照するには、Visual Studio Code Color Mapper Figma プラグインを使用してください。

{
  "contributes": {
    "walkthroughs": [
      {
        "id": "sample",
        "title": "Sample",
        "description": "A sample walkthrough",
        "steps": [
          {
            "id": "runcommand",
            "title": "Run Command",
            "description": "This step will run a command and check off once it has been run.\n[Run Command](command:getting-started-sample.runCommand)",
            "media": { "image": "media/image.png", "altText": "Empty image" },
            "completionEvents": ["onCommand:getting-started-sample.runCommand"]
          },
          {
            "id": "changesetting",
            "title": "Change Setting",
            "description": "This step will change a setting and check off when the setting has changed\n[Change Setting](command:getting-started-sample.changeSetting)",
            "media": { "markdown": "media/markdown.md" },
            "completionEvents": ["onSettingChanged:getting-started-sample.sampleSetting"]
          }
        ]
      }
    ]
  }
}

Walkthrough example

完了イベント

既定では、completionEvents イベントが提供されていない場合、ステップは、そのボタンのいずれかがクリックされたとき、またはステップにボタンがない場合は開かれたときにチェックされます。より詳細な制御が必要な場合は、completionEvents のリストを提供できます。

利用可能な完了イベントは次のとおりです。

onCommand:myCommand.id: コマンドが実行されたときにステップをチェックします。
onSettingChanged:mySetting.id: 指定された設定が変更されたときにステップをチェックします。
onContext:contextKeyExpression: コンテキストキー式が true と評価されたときにステップをチェックします。
extensionInstalled:myExt.id: 指定された拡張機能がインストールされている場合にステップをチェックします。
onView:myView.id: 指定されたビューが表示されたときにステップをチェックします。
onLink:https://...: 指定されたリンクがウォークスルーを介して開かれたときにステップをチェックします。

ステップがチェックされると、ユーザーが明示的にステップのチェックを外すか、進行状況をリセット (はじめに: 進行状況をリセットコマンドを介して) するまで、チェックされたままになります。

07/09/2025

状態	不透明度
既定値	60%
ホバー	100%
アクティブ	100%

コントリビューションポイント

contributes.authentication

contributes.breakpoints

contributes.colors

contributes.commands

コマンドの例

コマンドアイコンの仕様

contributes.configuration

設定の例

設定スキーマ

タイトル

プロパティ

設定タイトル

単一カテゴリおよび既定カテゴリ設定の表示タイトル

複数カテゴリ設定の表示タイトル

設定プロパティスキーマ

description / markdownDescription

タイプ

順序

enum / enumDescriptions / markdownEnumDescriptions / enumItemLabels

deprecationMessage / markdownDeprecationMessage

その他の JSON スキーマプロパティ

サポートされていない JSON スキーマプロパティ

スコープ

ignoreSync

設定へのリンク

contributes.configurationDefaults

contributes.customEditors

contributes.debuggers

デバッガーの例

contributes.grammars

文法の例

contributes.icons

contributes.iconThemes

ファイルアイコンテーマの例

contributes.jsonValidation

contributes.keybindings

キーバインディングの例

contributes.languages

言語の例

contributes.menus

メニューの例

コマンドパレットメニュー項目のコンテキスト固有の表示設定

グループの並べ替え

グループ内の並べ替え

contributes.problemMatchers

contributes.problemPatterns

contributes.productIconThemes

製品アイコンテーマの例

contributes.resourceLabelFormatters

contributes.semanticTokenModifiers

contributes.semanticTokenScopes

contributes.semanticTokenTypes

contributes.snippets

contributes.submenus

サブメニューの例

contributes.taskDefinitions

contributes.terminal

contributes.themes

テーマの例

contributes.typescriptServerPlugins

プラグイン設定

contributes.views

contributes.viewsContainers

アイコンの仕様

contributes.viewsWelcome

contributes.walkthroughs

完了イベント