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

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

このアクティベーションイベントは、指定された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 のウェブビューを復元する必要があるたびに発行され、対象となる拡張機能がアクティブ化されます。

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

"activationEvents": [
    "onWebviewPanel:catCoding"
]

VS CodeがviewType: catCoding のウェブビューを復元する必要がある場合に、拡張機能がアクティブ化される原因となります。viewType は window.createWebviewPanel の呼び出しで設定され、最初に拡張機能をアクティブ化してウェブビューを作成するために、別の活性化イベント (例えば、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"
]

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": [
    "onChatParticipant:my-language-model-tool"
]

起動

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

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

"activationEvents": [
    "*"
]

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

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