編輯

啟用事件

啟用事件是你在 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

當用戶請求動態除錯配置時，例如透過“選擇並開始除錯”命令透過 UI 請求，此啟用事件會在呼叫 DebugConfigurationProvider 的 provideDebugConfigurations 方法以提供動態除錯配置之前觸發。

此啟用事件的存在被用作擴充套件貢獻動態除錯配置的訊號。

onDebugInitialConfigurations

當需要建立 launch.json 等初始除錯配置時，此啟用事件會在呼叫 DebugConfigurationProvider 的 provideDebugConfigurations 方法以提供初始除錯配置之前觸發。

onDebugResolve

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

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

workspaceContains

當開啟一個資料夾且該資料夾包含至少一個與 glob 模式匹配的檔案時，workspaceContains:path 會被觸發，相關擴充套件將被啟用。

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

onFileSystem

當從特定方案讀取檔案或資料夾時，onFileSystem:scheme 會被觸發，相關擴充套件將被啟用。這通常是 file 方案，但對於自定義檔案系統提供程式，會引入更多方案，例如 ftp 或 ssh。

"activationEvents": [
    "onFileSystem:sftp"
]

onView

當 VS Code 側邊欄中展開指定 ID 的檢視時，此啟用事件會被觸發，相關擴充套件將被啟用。內建檢視不觸發啟用事件。

以下啟用事件將在 ID 為 nodeDependencies 的檢視可見時觸發：

"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 時設定，你將需要另一個啟用事件（例如 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

當使用給定方案訪問編輯會話時，會觸發 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。

09/11/2025