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

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

• onAuthenticationRequest
• onChatParticipant
• onCommand
• onCustomEditor
• onDebug
  • onDebugAdapterProtocolTracker
  • onDebugDynamicConfigurations
  • onDebugInitialConfigurations
  • onDebugResolve
• onEditSession
• onFileSystem
• onIssueReporterOpened
• onLanguage
• onLanguageModelTool
• onNotebook
• onOpenExternalUri
• onRenderer
• onSearch
• onStartupFinished
• onTaskType
• onTerminal
  • onTerminalProfile
  • onTerminalShellIntegration
• 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 は、フォルダーが開かれ、そのフォルダーにグロブパターンに一致するファイルが少なくとも 1 つ含まれている場合に発行され、関心のある拡張機能がアクティベートされます。

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

onFileSystem

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

"activationEvents": [
    "onFileSystem:sftp"
]

onView

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

以下の起動イベントは、ID が nodeDependencies のビューが表示されるたびに発生します。

"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 が catCoding という viewType の webview を復元する必要があるときに拡張機能がアクティベートされます。viewType は window.createWebviewPanel の呼び出しで設定され、最初に拡張機能をアクティベートして webview を作成するには、別のアクティベーション イベント (たとえば、onCommand) が必要になります。

onCustomEditor

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

例えば、以下の onCustomEditor の宣言では、

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

VS Code が catCustoms.pawDraw という viewType のカスタムエディターを復元する必要があるときに拡張機能がアクティベートされます。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"
]

onTerminal

onTerminal:shellType は、指定されたシェルタイプの特定のターミナルが開かれたときに発行されます。

"activationEvents": [
  "onTerminal:bash"
]

onTerminalProfile

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

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

onTerminalShellIntegration

onTerminalShellIntegration:shellType は、指定されたシェルタイプを持つターミナルでシェル統合がアクティベートされたときに発行されます。

"activationEvents": [
    "onTerminalShellIntegration:bash"
]

onWalkthrough

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

"activationEvents": [
    "onWalkthrough:nodejsWelcome"
]

onIssueReporterOpened

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

"activationEvents": [
    "onIssueReporterOpened"
]

onChatParticipant

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

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

onLanguageModelTool

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

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

起動

* アクティベーション イベントは、VS Code が起動するたびに発行され、関心のある拡張機能がアクティベートされます。

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

"activationEvents": [
    "*"
]

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

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