激活事件

激活事件 是一组 JSON 声明，您可以在 package.json 扩展清单 的 activationEvents 字段中进行声明。当激活事件发生时，您的扩展程序将被激活。以下是所有可用的激活事件的列表

• 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

当用户通过 UI（例如通过“选择并启动调试”命令）请求动态调试配置时，在调用 DebugConfigurationProvider 的 provideDebugConfigurations 方法以提供动态调试配置之前，会发出此激活事件。

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

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

当打开指定的 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。