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

アクティベーションイベント（Activation Events）は、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 のビューが展開されるたびに発行され、それに関心を持つ拡張機能がアクティベートされます。組み込みビューはアクティベーションイベントを発行しません。

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

"activationEvents": [
    "onView:nodeDependencies"
]

注: VS Code 1.74.0 以降、拡張機能が提供するビューについては、拡張機能をアクティベートするための onView アクティベーションイベントの宣言は不要です。

onUri

このアクティベーションイベントは、その拡張機能に対するシステム全体の URI が開かれるたびに発行され、それに関心を持つ拡張機能がアクティベートされます。URI スキームは vscode または vscode-insiders に固定されています。URI のオーソリティ（authority）は拡張機能の識別子である必要があります。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 を持つ ウェブビュー を復元する必要があるたびに発行され、それに関心を持つ拡張機能がアクティベートされます。

例えば、以下の onWebviewPanel の宣言は

"activationEvents": [
    "onWebviewPanel:catCoding"
]

VS Code が catCoding という viewType を持つウェブビューを復元する必要がある時に、その拡張機能をアクティベートします。viewType は window.createWebviewPanel の呼び出し時に設定されます。拡張機能を最初にアクティベートしてウェブビューを作成するには、別の（例えば 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 を返すことができます。