vscode plugin development

plugin 开发使用 yo 开发

下面是 package.json 中比较重要的两个字段

1. activationEvents 字段：

• 事件注册：activationEvents 就像是 事件监听器，它定义了插件 何时启动，即 何时满足某个条件时，启动插件。
• 它是一个 激活条件的注册，当符合某个条件时（例如打开特定类型的文件、执行特定的命令等），插件才会 被激活 和 加载。

总结：它控制 插件的加载时机，就像在事件驱动编程中注册事件一样。只有当事件发生时，插件才会被启动。

例子：

"activationEvents": [
  "onLanguage:python",  // 只有当打开 Python 文件时，插件才会激活
  "onCommand:extension.sayHello"  // 只有当执行某个命令时，插件才会激活
]

---

2. contributes 字段：

• 提供功能：contributes 定义了 插件提供的功能，它声明了插件会向 VSCode 编辑器 贡献哪些服务，例如命令、快捷键、视图、语言支持等。
• 你可以将它看作是插件的功能注册，它 告诉 VSCode 该插件能够做什么，并且当插件被激活时，VSCode 会根据这些贡献来加载插件的功能。

总结：它定义了插件被激活后会做什么工作、提供什么功能，就像是 方法注册，插件启动后执行这些方法。

例子：

"contributes": {
  "commands": [
    {
      "command": "extension.sayHello",
      "title": "Say Hello"
    }
  ],
  "keybindings": [
    {
      "command": "extension.sayHello",
      "key": "ctrl+shift+h",
      "when": "editorTextFocus"
    }
  ]
}

---

关系概述：

• activationEvents：是 事件注册，它告诉 VSCode 在什么情况下启动插件。
• contributes：是 功能注册，它定义了插件启动后会 提供哪些功能，这些功能会在插件激活后执行。

举个例子说明：

假设你开发了一个插件，它提供了一个命令 extension.sayHello，并且这个命令可以通过快捷键 Ctrl+Shift+H 来触发：

1. activationEvents 定义了插件 什么时候被激活：

   • 只有当打开 .js 文件时，插件才会被激活。

   "activationEvents": [
     "onLanguage:javascript"  // 只有在打开 JavaScript 文件时插件才激活
   ]

2. contributes 定义了插件激活后 提供的功能：

   • 注册了一个命令 extension.sayHello，并将它绑定到快捷键 Ctrl+Shift+H。

   "contributes": {
     "commands": [
       {
         "command": "extension.sayHello",
         "title": "Say Hello"
       }
     ],
     "keybindings": [
       {
         "command": "extension.sayHello",
         "key": "ctrl+shift+h"
       }
     ]
   }

   在这个例子中，contributes 定义了插件提供的功能（命令和快捷键），而 activationEvents 确定了插件 什么时候加载和启动（只有在打开 .js 文件时）。

---

总结：

• activationEvents：相当于 事件注册，它定义了插件 何时激活（什么时候启动插件）。
• contributes：相当于 功能注册，它定义了插件 激活后提供什么功能（比如命令、视图、快捷键等）。

通过这种方式，VSCode 可以按需加载插件，确保只有在需要时才启动插件，并且插件启动后能够提供预期的功能。

插件的基本开发流程：

1. 注册激活事件 (activationEvents)：

   • 你通过 activationEvents 字段定义插件 何时激活。这些激活事件可以是 VSCode 内部的多种事件（例如打开某种类型的文件、执行某个命令、编辑器启动完成等）。
   • 插件只有在满足这些条件时才会被加载和激活。

2. 通过 contributes 注册插件功能（命令、快捷键等）：

   • 在 contributes 字段中，你 注册插件提供的功能，例如定义插件的 命令（如 extension.sayHello）、快捷键、视图、代码片段等。
   • 这些功能会在插件被激活后，由 VSCode 加载并允许用户交互。

3. 在插件中使用 VSCode 插件 API 实现功能：

   • 插件的 实际功能 是在激活后的代码中实现的，你可以使用 VSCode 提供的插件 API（例如 vscode.commands、vscode.window、vscode.workspace 等）来编写你的业务逻辑。
   • 这些 API 提供了操作编辑器、工作区、文件等的能力，比如创建命令、编辑文本、打开文件、显示信息框等。

流程示意：

1. 定义激活事件：

你通过 activationEvents 设置插件的激活时机。比如你可能希望插件在打开 .js 文件时才激活：

"activationEvents": [
  "onLanguage:javascript"  // 只有打开 .js 文件时，插件才会激活
]

2. 注册插件功能（通过 contributes）：

通过 contributes，你注册插件提供的功能，例如定义命令、快捷键等：

"contributes": {
  "commands": [
    {
      "command": "extension.sayHello",
      "title": "Say Hello"
    }
  ],
  "keybindings": [
    {
      "command": "extension.sayHello",
      "key": "ctrl+shift+h",  // 快捷键为 Ctrl+Shift+H
      "when": "editorTextFocus"  // 在编辑器有焦点时触发
    }
  ]
}

3. 编写插件功能：

在插件的代码中（通常是 extension.js 或 extension.ts），你实现插件的具体功能，比如执行命令时的逻辑。

const vscode = require("vscode");

function activate(context) {
  // 注册命令 'extension.sayHello'
  let disposable = vscode.commands.registerCommand(
    "extension.sayHello",
    function () {
      // 通过 VSCode API 显示信息框
      vscode.window.showInformationMessage("Hello, VSCode!");
    }
  );

  context.subscriptions.push(disposable);
}

function deactivate() {}

module.exports = {
  activate,
  deactivate,
};

在上面的代码中：

• vscode.commands.registerCommand('extension.sayHello', ...) 是通过插件 API 注册命令。
• vscode.window.showInformationMessage('Hello, VSCode!') 是插件执行时用来与用户交互的 API，它会弹出一个信息框显示 “Hello, VSCode!”。

4. 插件激活：

当用户打开 .js 文件时，VSCode 会根据 activationEvents 中定义的激活条件加载插件（即激活插件）。一旦插件被激活，VSCode 会自动注册 contributes 中定义的命令和功能。

总结：

1. 注册激活事件（activationEvents）：控制插件 何时被激活。
2. 通过 contributes 注册功能（命令、快捷键等）：定义插件 激活后 提供的功能。
3. 在插件中使用 VSCode 插件 API 实现功能：使用 VSCode 提供的 API 编写插件的具体逻辑，执行命令、交互、操作文件等。

这个流程确保了插件的 按需激活 和 高效运行，并且使插件能够根据用户的需求提供特定的功能。