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

アクティベーションイベントは、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

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

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のビューが展開されるたびに発行され、対象となる拡張機能がアクティブ化されます。組み込みビューはアクティベーションイベントを発行しません。

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を返しても構いません。