激活事件

激活事件 是一组 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

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

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

onDebugInitialConfigurations

当需要创建 launch.json 时（例如，每次需要创建 launch.json 时），此激活事件会在调用 DebugConfigurationProvider 的 provideDebugConfigurations 方法之前发出。

onDebugResolve

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

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

当打开外部链接（例如，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。

10/29/2024