编辑

激活事件

激活事件是你在 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

此激活事件在调用 DebugConfigurationProvider 的 provideDebugConfigurations 方法以提供初始调试配置之前触发，例如每当需要创建 launch.json 时。

onDebugResolve

onDebugResolve:type 在调用指定类型的 DebugConfigurationProvider 的 resolveDebugConfiguration 方法之前触发。

经验法则：如果调试扩展的激活是轻量级的，请使用 onDebug。如果它是重量级的，则根据 DebugConfigurationProvider 是否实现了相应的 provideDebugConfigurations 和/或 resolveDebugConfiguration 方法，使用 onDebugInitialConfigurations 和/或 onDebugResolve。有关这些方法的更多详细信息，请参阅使用 DebugConfigurationProvider。

workspaceContains

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

当扩展（通过 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

onTerminal:shellType 在打开具有给定 shell 类型特定终端时触发。

"activationEvents": [
  "onTerminal:bash"
]

onTerminalProfile

onTerminalProfile:id 在启动特定终端配置文件时触发。

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

onTerminalShellIntegration

onTerminalShellIntegration:shellType 在具有给定 shell 类型的终端激活 shell 集成时触发。

"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。

10/09/2025