啟用事件

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

• onAuthenticationRequest
• onChatParticipant
• onCommand
• onCustomEditor
• onDebug
  • onDebugAdapterProtocolTracker
  • onDebugDynamicConfigurations
  • onDebugInitialConfigurations
  • onDebugResolve
• onEditSession
• onFileSystem
• onIssueReporterOpened
• onLanguage
• onLanguageModelTool
• onNotebook
• onOpenExternalUri
• onRenderer
• onSearch
• onStartupFinished
• onTaskType
• onTerminalProfile
• 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"
]

以下是另外四個更精細的 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

每當從特定方案讀取檔案或資料夾時，就會發出 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 需要還原 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"
]

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。