啟用事件

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

我們還提供了 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

onDebugResolve:type 在呼叫指定型別的 DebugConfigurationProvider 的 resolveDebugConfiguration 方法之前觸發。

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

workspaceContains

當開啟一個資料夾，並且該資料夾至少包含一個匹配 glob 模式的檔案時，會發出 workspaceContains:path 啟用事件，並且感興趣的擴充套件將被啟用。

"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 需要恢復具有 catCoding 檢視型別的 webview 時觸發擴充套件的啟用。viewType 在呼叫 window.createWebviewPanel 時設定，您需要另一個啟用事件（例如，onCommand）來最初啟用您的擴充套件並建立 webview。

onCustomEditor

當 VS Code 需要建立具有匹配 viewType 的自定義編輯器時，會發出此啟用事件，並且感興趣的擴充套件將被啟用。

例如，以下 onCustomEditor 的宣告

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

將在 VS Code 需要恢復具有 catCustoms.pawDraw 檢視型別的自定義編輯器時觸發擴充套件的啟用。viewType 在 customEditors 貢獻點中設定，並與 registerCustomEditorProvider 繫結到提供程式。

注意：從 VS Code 1.74.0 開始，您的擴充套件所貢獻的自定義編輯器不需要相應的 onCustomEditor 啟用事件宣告即可啟用您的擴充套件。

onAuthenticationRequest

當擴充套件請求身份驗證會話（透過 authentication.getSession() API）並具有匹配的 providerId 時，會發出此啟用事件，並且感興趣的擴充套件將被啟用。

例如，以下 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

當正在開啟外部 URI（例如 http 或 https 連結）時，會發出一個啟用事件。

"activationEvents": [
    "onOpenExternalUri"
]

onNotebook

當開啟指定的筆記本檔案型別時，會發出 onNotebook:type。

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

onRenderer

當使用筆記本輸出渲染器時，會發出 onRenderer:id。

"activationEvents": [
    "onRenderer:ms-toolsai.jupyter-renderers"
]

onTerminal

當開啟具有給定 shell 型別的特定終端時，會發出 onTerminal:shellType。

"activationEvents": [
  "onTerminal:bash"
]

onTerminalProfile

當啟動特定的終端配置檔案時，會發出 onTerminalProfile:id。

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

onTerminalShellIntegration

當具有給定 shell 型別的終端激活了 shell 整合時，會發出 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 將僅呼叫一次。此外，擴充套件應從其主模組匯出 deactivate() 函式，以在 VS Code 關閉時執行清理任務。如果清理過程是非同步的，擴充套件必須從 deactivate() 返回一個 Promise。如果清理是同步進行的，擴充套件可以從 deactivate() 返回 undefined。

12/10/2025