激活事件
激活事件是在 package.json
扩展清单的 activationEvents
字段中进行的一组 JSON 声明。当激活事件发生时,你的扩展程序将被激活。以下是所有可用的激活事件的列表
onAuthenticationRequest
onChatParticipant
onCommand
onCustomEditor
onDebug
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
当用户通过 UI(例如通过“选择并开始调试”命令)请求动态调试配置时,将在调用 DebugConfigurationProvider
的 provideDebugConfigurations
方法以提供动态调试配置之前发出此激活事件。
此激活事件的存在被用作扩展程序贡献动态调试配置的信号。
onDebugInitialConfigurations
当需要创建 launch.json
时,将在调用 DebugConfigurationProvider
的 provideDebugConfigurations
方法以提供初始调试配置之前发出此激活事件。
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 侧边栏中展开时,将发出此激活事件,并且感兴趣的扩展程序将被激活。 内置视图不发出激活事件。
当 id 为 nodeDependencies
的视图可见时,以下激活事件将触发
"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
。