在 VS Code 中试用

激活事件

激活事件是一组 JSON 声明,你在 package.json 扩展清单activationEvents 字段中进行这些声明。当激活事件发生时,你的扩展就会被激活。以下是所有可用的激活事件列表

我们还提供了 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

此激活事件在调用 DebugConfigurationProviderprovideDebugConfigurations 方法之前触发,用于在用户请求动态调试配置时(例如通过 UI 的“选择并开始调试”命令)提供动态调试配置。

此激活事件的存在被用作扩展贡献动态调试配置的信号。

onDebugInitialConfigurations

此激活事件在调用 DebugConfigurationProviderprovideDebugConfigurations 方法之前触发,用于提供初始调试配置,例如在需要创建 launch.json 文件时。

onDebugResolve

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

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

workspaceContains

当打开一个文件夹且该文件夹至少包含一个匹配 glob 模式的文件时,将触发 workspaceContains:path 事件,并且相关的扩展将被激活。

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

onFileSystem

每当读取特定 scheme 的文件或文件夹时,将触发 onFileSystem:scheme 事件,并且相关的扩展将被激活。这通常是 file scheme,但通过自定义文件系统提供程序,会引入更多 scheme,例如 ftpssh

"activationEvents": [
    "onFileSystem:sftp"
]

onView

当 VS Code 侧边栏中展开指定 id 的视图时,将触发此激活事件,并且相关的扩展将被激活。内置视图不触发激活事件。

当 id 为 nodeDependencies 的视图可见时,将触发以下激活事件

"activationEvents": [
    "onView:nodeDependencies"
]

注意:从 VS Code 1.74.0 开始,你的扩展所贡献的视图不再需要相应的 onView 激活事件声明来激活你的扩展。

onUri

当打开该扩展的系统级 Uri 时,将触发此激活事件,并且相关的扩展将被激活。Uri scheme 固定为 vscodevscode-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 需要恢复匹配 viewTypewebview 时,将触发此激活事件,并且相关的扩展将被激活。

例如,下面的 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 需要检索类型为 githubAuthenticationSession 时激活。

注意:从 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