アクティベーション イベント

アクティベーション イベントは、package.json 拡張機能マニフェスト の activationEvents フィールドで行う JSON 宣言のセットです。拡張機能は、アクティベーション イベントが発生するとアクティブ化されます。利用可能なすべての アクティベーション イベント のリストを以下に示します。

• onAuthenticationRequest
• onChatParticipant
• onCommand
• onCustomEditor
• onDebug
  • onDebugAdapterProtocolTracker
  • onDebugDynamicConfigurations
  • onDebugInitialConfigurations
  • onDebugResolve
• onEditSession
• onFileSystem
• onIssueReporterOpened
• onLanguage
• onLanguageModelTool
• onNotebook
• onOpenExternalUri
• onRenderer
• onSearch
• onStartupFinished
• onTaskType
• onTerminalProfile
• onUri
• onView
• onWalkthrough
• onWebviewPanel
• workspaceContains
• *

また、package.json 拡張機能マニフェスト のすべてのフィールドのリファレンスも提供しています。

onLanguage

このアクティベーション イベントは、特定の言語に解決されるファイルが開かれると常に発行され、対象の拡張機能がアクティブ化されます。

"activationEvents": [
    "onLanguage:python"
]

onLanguage イベントは、言語識別子 値を受け取ります。

複数の言語は、activationEvents 配列内の個別の onLanguage エントリで宣言できます。

"activationEvents": [
    "onLanguage:json",
    "onLanguage:markdown",
    "onLanguage:typescript"
]

注: VS Code 1.74.0 以降では、拡張機能によって提供される言語は、拡張機能をアクティブ化するために対応する onLanguage アクティベーション イベント宣言を必要としません。

さらに、拡張機能を言語が使用される前にアクティブ化する必要がある場合は、汎用的な onLanguage アクティベーション イベントを使用してこれを保証できます。

"activationEvents": [
    "onLanguage"
]

注: 拡張機能が必要な場合にのみアクティブ化するのがベスト プラクティスです。拡張機能が言語のサブセットで動作する場合は、すべての言語でアクティブ化するよりも、そのサブセットをリストする方がユーザーにとって適切です。

onCommand

このアクティベーション イベントは、コマンドが呼び出されると常に発行され、対象の拡張機能がアクティブ化されます。

"activationEvents": [
    "onCommand:extension.sayHello"
]

注: VS Code 1.74.0 以降では、拡張機能によって提供されるコマンドは、拡張機能をアクティブ化するために対応する onCommand アクティベーション イベント宣言を必要としません。

onDebug

このアクティベーション イベントは、デバッグ セッションが開始される前に発行され、対象の拡張機能がアクティブ化されます。

"activationEvents": [
    "onDebug"
]

これらは、さらに 4 つのきめ細かい onDebug アクティベーション イベントです。

onDebugAdapterProtocolTracker

onDebugAdapterProtocolTracker は、特定のタイプでのデバッグ セッションが起動されようとしており、デバッグ プロトコル トラッカーが必要になる可能性がある場合に常に発行されます。

onDebugDynamicConfigurations

このアクティベーション イベントは、ユーザーが「デバッグの選択と開始」コマンドなどを使用して UI を介して動的デバッグ構成を要求した場合に、DebugConfigurationProvider の provideDebugConfigurations メソッドが呼び出される直前に発行されます。

このアクティベーション イベントの存在は、拡張機能が動的デバッグ構成を提供しているというシグナルとして使用されます。

onDebugInitialConfigurations

このアクティベーション イベントは、launch.json を作成する必要がある場合など、初期デバッグ構成を提供するために DebugConfigurationProvider の provideDebugConfigurations メソッドが呼び出される直前に発行されます。

onDebugResolve

onDebugResolve:type は、指定されたタイプの DebugConfigurationProvider の resolveDebugConfiguration メソッドが呼び出される直前に発生します。

経験則: デバッグ拡張機能のアクティブ化が軽量な場合は、onDebug を使用します。重い場合は、DebugConfigurationProvider が対応するメソッド provideDebugConfigurations および/または resolveDebugConfiguration を実装しているかどうかに応じて、onDebugInitialConfigurations および/または onDebugResolve を使用します。これらのメソッドの詳細については、DebugConfigurationProvider の使用 を参照してください。

workspaceContains

workspaceContains:path は、フォルダーが開かれ、そのフォルダーに glob パターン に一致するファイルが少なくとも 1 つ含まれている場合に常に発行され、対象の拡張機能がアクティブ化されます。

"activationEvents": [
    "workspaceContains:**/.editorconfig"
]

onFileSystem

onFileSystem:scheme は、特定の スキーム からのファイルまたはフォルダーが読み取られると常に発行され、対象の拡張機能がアクティブ化されます。これは通常 file スキームですが、カスタム ファイル システム プロバイダーを使用すると、ftp や ssh など、より多くのスキームが導入されます。

"activationEvents": [
    "onFileSystem:sftp"
]

onView

このアクティベーション イベントは、指定された ID のビューが VS Code サイドバーで展開されると常に発行され、対象の拡張機能がアクティブ化されます。組み込みビューは、アクティベーション イベントを発行しません。

以下のアクティベーション イベントは、nodeDependencies ID を持つビューが表示されると常に発生します。

"activationEvents": [
    "onView:nodeDependencies"
]

注: VS Code 1.74.0 以降では、拡張機能によって提供されるビューは、拡張機能をアクティブ化するために対応する onView アクティベーション イベント宣言を必要としません。

onUri

このアクティベーション イベントは、その拡張機能のシステム全体の URI が開かれると常に発行され、対象の拡張機能がアクティブ化されます。URI スキームは、vscode または vscode-insiders のいずれかに固定されています。URI の権限は、拡張機能の識別子である必要があります。URI の残りの部分は任意です。

"activationEvents": [
    "onUri"
]

vscode.git 拡張機能が onUri をアクティベーション イベントとして定義している場合、次のいずれかの URI が開かれるとアクティブ化されます。

• vscode://vscode.git/init
• vscode://vscode.git/clone?url=https%3A%2F%2Fgithub.com%2FMicrosoft%2Fvscode-vsce.git
• vscode-insiders://vscode.git/init (VS Code Insiders の場合)

onWebviewPanel

このアクティベーション イベントは、VS Code が一致する viewType を持つ webview を復元する必要がある場合に常に発行され、対象の拡張機能がアクティブ化されます。

たとえば、以下の onWebviewPanel の宣言

"activationEvents": [
    "onWebviewPanel:catCoding"
]

により、VS Code が viewType: catCoding を持つ webview を復元する必要がある場合に拡張機能がアクティブ化されます。viewType は window.createWebviewPanel の呼び出しで設定され、拡張機能を最初にアクティブ化して webview を作成するには、別のアクティベーション イベント (たとえば、onCommand) が必要になります。

onCustomEditor

このアクティベーション イベントは、VS Code が一致する viewType を持つ カスタム エディター を作成する必要がある場合に常に発行され、対象の拡張機能がアクティブ化されます。

たとえば、以下の onCustomEditor の宣言

"activationEvents": [
    "onCustomEditor:catCustoms.pawDraw"
]

により、VS Code が viewType: catCustoms.pawDraw を持つカスタム エディターを復元する必要がある場合に拡張機能がアクティブ化されます。viewType は、customEditors コントリビューション ポイント で設定され、registerCustomEditorProvider を持つプロバイダーにバインドされます。

注: VS Code 1.74.0 以降では、拡張機能によって提供されるカスタム エディターは、拡張機能をアクティブ化するために対応する onCustomEditor アクティベーション イベント宣言を必要としません。

onAuthenticationRequest

このアクティベーション イベントは、拡張機能が一致する providerId を持つ認証セッション (authentication.getSession() API 経由) を要求すると常に発行され、対象の拡張機能がアクティブ化されます。

たとえば、以下の onAuthenticationRequest の宣言

"activationEvents": [
    "onAuthenticationRequest:github"
]

により、VS Code がタイプ github の AuthenticationSession を取得する必要がある場合に拡張機能がアクティブ化されます。

注: VS Code 1.74.0 以降では、拡張機能によって提供される認証プロバイダーは、拡張機能をアクティブ化するために対応する onAuthenticationRequest アクティベーション イベント宣言を必要としません。

onStartupFinished

このアクティベーション イベントは、VS Code の起動後しばらくしてから発行され、対象の拡張機能がアクティブ化されます。これは * アクティベーション イベントに似ていますが、VS Code の起動を遅くすることはありません。現在、このイベントは、* アクティブ化されたすべての拡張機能のアクティブ化が完了した後に発行されます。

"activationEvents": [
    "onStartupFinished"
]

onTaskType

onTaskType:type は、特定のタイプのタスクをリストまたは解決する必要がある場合に常に発行されます。

"activationEvents": [
    "onTaskType":"npm"
]

注: VS Code 1.76.0 以降では、拡張機能によって提供されるタスクは、拡張機能をアクティブ化するために対応する onTaskType アクティベーション イベント宣言を必要としません。

onEditSession

onEditSession:scheme は、指定されたスキームで編集セッションにアクセスすると発行されます。

"activationEvents": [
    "onEditSession:file"
]

onSearch

onSearch:scheme は、指定されたスキームを持つフォルダーで検索が開始されると発行されます。

"activationEvents": [
    "onSearch:file"
]

onOpenExternalUri

http または https リンクなどの外部 URI が開かれると常に発行されるアクティベーション イベント。

"activationEvents": [
    "onOpenExternalUri"
]

onNotebook

onNotebook:type は、指定されたノートブック ドキュメント タイプが開かれると発行されます。

"activationEvents": [
    "onNotebook:jupyter-notebook",
    "onNotebook:interactive"
]

onRenderer

onRenderer:id は、ノートブック出力レンダラーが使用されると発行されます。

"activationEvents": [
    "onRenderer:ms-toolsai.jupyter-renderers"
]

onTerminalProfile

onTerminalProfile:id は、特定のターミナル プロファイルが起動されると発行されます。

"activationEvents": [
    "onTerminalProfile:terminalTest.terminal-profile"
]

onWalkthrough

onWalkthrough:id は、指定されたウォークスルーが開かれると発行されます。

"activationEvents": [
    "onWalkthrough:nodejsWelcome"
]

onIssueReporterOpened

このアクティベーション イベントは、(たとえば、ヘルプ: 問題を報告 を使用して) 問題レポーターが開かれると発行されます。

"activationEvents": [
    "onIssueReporterOpened"
]

onChatParticipant

指定されたチャット参加者が呼び出されると発行されるアクティベーション イベント。

"activationEvents": [
    "onChatParticipant:my-chat-participant"
]

onLanguageModelTool

指定された言語モデル ツールが呼び出されると発行されるアクティベーション イベント。

"activationEvents": [
    "onChatParticipant:my-language-model-tool"
]

起動

* アクティベーション イベントは、VS Code が起動すると常に発行され、対象の拡張機能がアクティブ化されます。

注: 優れたユーザー エクスペリエンスを確保するために、このアクティベーション イベントは、他のアクティベーション イベントの組み合わせがユース ケースで機能しない場合にのみ拡張機能で使用してください。

"activationEvents": [
    "*"
]

注: 拡張機能は複数のアクティベーション イベントをリッスンでき、それは "*" をリッスンするよりも推奨されます。

注: 拡張機能は、メイン モジュールから activate() 関数をエクスポートする必要があります。指定されたアクティベーション イベントのいずれかが発行されると、VS Code によって一度だけ呼び出されます。また、拡張機能は、VS Code シャットダウン時にクリーンアップ タスクを実行するために、メイン モジュールから deactivate() 関数をエクスポートする必要があります。クリーンアップ プロセスが非同期の場合は、拡張機能は deactivate() から Promise を返す必要があります。クリーンアップが同期的に実行される場合、拡張機能は deactivate() から undefined を返す場合があります。