啟用事件

啟用事件是一組 JSON 宣告，您可以在 package.json 擴充功能資訊清單的 activationEvents 欄位中進行宣告。當啟用事件發生時，您的擴充功能就會被啟用。以下是所有可用的啟用事件列表

我們也提供 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"
]

以下是四個更細緻的 onDebug 啟用事件

onDebugAdapterProtocolTracker

每當即將啟動具有特定類型的偵錯工作階段，且可能需要偵錯協定追蹤器時，就會發出 onDebugAdapterProtocolTracker。

onDebugDynamicConfigurations

當呼叫 DebugConfigurationProvider 的 provideDebugConfigurations 方法以在使用者要求時 (例如透過 UI，透過「選取並開始偵錯」命令) 提供動態偵錯組態之前，就會發出此啟用事件。

此啟用事件的存在被用作擴充功能貢獻動態偵錯組態的訊號。

onDebugInitialConfigurations

當呼叫 DebugConfigurationProvider 的 provideDebugConfigurations 方法以提供初始偵錯組態時 (例如每當需要建立 launch.json 時)，就會發出此啟用事件。

onDebugResolve

在呼叫指定類型的 DebugConfigurationProvider 的 resolveDebugConfiguration 方法之前，就會觸發 onDebugResolve:type。

經驗法則：如果偵錯擴充功能的啟用是輕量級的，請使用 onDebug。如果是重量級的，請使用 onDebugInitialConfigurations 和/或 onDebugResolve，具體取決於 DebugConfigurationProvider 是否實作了對應的方法 provideDebugConfigurations 和/或 resolveDebugConfiguration。有關這些方法的更多詳細資訊，請參閱使用 DebugConfigurationProvider。

workspaceContains

每當開啟資料夾，且資料夾包含至少一個符合 glob 模式的檔案時，就會發出 workspaceContains:path，而感興趣的擴充功能將會被啟用。

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

onFileSystem

每當從特定scheme讀取檔案或資料夾時，就會發出 onFileSystem:scheme，而感興趣的擴充功能將會被啟用。這通常是 file-scheme，但透過自訂檔案系統提供者，會出現更多 scheme，例如 ftp 或 ssh。

"activationEvents": [
    "onFileSystem:sftp"
]

onView

每當指定 ID 的檢視在 VS Code 側邊欄中展開時，就會發出此啟用事件，而感興趣的擴充功能將會被啟用。內建檢視不會發出啟用事件。

每當具有 nodeDependencies ID 的檢視可見時，以下啟用事件將會觸發

"activationEvents": [
    "onView:nodeDependencies"
]

注意：從 VS Code 1.74.0 開始，您的擴充功能所貢獻的檢視不需要對應的 onView 啟用事件宣告即可啟用您的擴充功能。

onUri

每當開啟該擴充功能的系統範圍 Uri 時，就會發出此啟用事件，而感興趣的擴充功能將會被啟用。Uri scheme 固定為 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 的 webview 時，就會發出此啟用事件，而感興趣的擴充功能將會被啟用。

例如，以下 onWebviewPanel 的宣告

"activationEvents": [
    "onWebviewPanel:catCoding"
]

將導致擴充功能在 VS Code 需要還原 viewType 為 catCoding 的 webview 時被啟用。viewType 在呼叫 window.createWebviewPanel 時設定，您需要有另一個啟用事件 (例如 onCommand) 來初始啟用您的擴充功能並建立 webview。

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

當使用給定的 scheme 存取編輯工作階段時，就會發出 onEditSession:scheme。

"activationEvents": [
    "onEditSession:file"
]

onSearch

當在具有給定 scheme 的資料夾中開始搜尋時，就會發出 onSearch:scheme。

"activationEvents": [
    "onSearch:file"
]

onOpenExternalUri

每當開啟外部 URI (例如 http 或 https 連結) 時，就會發出啟用事件。

"activationEvents": [
    "onOpenExternalUri"
]

onNotebook

當開啟指定的 Notebook 文件類型時，就會發出 onNotebook:type。

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

onRenderer

當使用 Notebook 輸出轉譯器時，就會發出 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 只會調用一次。此外，擴充功能應該從其主要模組匯出 deactivate() 函數，以在 VS Code 關閉時執行清理工作。如果清理過程是非同步的，則擴充功能必須從 deactivate() 傳回 Promise。如果清理同步執行，則擴充功能可以從 deactivate() 傳回 undefined。

04/03/2025