VSCode：简单插件开发

1. 概述

本文演示如何使用最简单的 JavaScript 编写并发布一个 VS Code 扩展。示例扩展 simple-hello-js 在激活时会打开一个小面板，面板中有一个只读文本框显示："Hello, Plugin!"。

2. VS Code 扩展总体框架

2.1 什么是 VS Code 扩展

VS Code 扩展是运行在编辑器里的脚本程序，通过 VS Code 提供的扩展 API 与编辑器交互（显示通知、命令、侧边栏、语言服务、Webview 等）。

2.2 关键概念

package.json：扩展清单，声明元数据、激活事件（activationEvents）、贡献点（contributes）等。
激活（Activation）：扩展在满足 activationEvents 时被加载，常见有 onCommand:、onStartupFinished 等。
入口模块（main）：通常是 extension.js，导出 activate(context) 与可选的 deactivate()。
ExtensionContext：传递给 activate 的上下文，包含 subscriptions 用于统一注销资源。

2.3 架构图与组件说明

下面用流程图描述扩展运行时的主要组件与它们之间的关系，图后逐一解释每个组件的角色：

组件解释：

VS Code 主进程：负责 UI（编辑器、命令面板、侧边栏等），与 Extension Host 通过 IPC 通信。
Extension Host：在单独的进程中运行扩展代码（保护主进程、隔离错误），负责加载扩展的 main 并执行 activate。
package.json：声明扩展的元信息、activationEvents（何时激活）和 contributes（扩展点，例如命令、视图）。
activate(context)：激活时的入口函数，负责注册命令、创建 Webview、订阅事件并把 disposable 推入 context.subscriptions。
WebviewPanel：用于在 VS Code 中显示自定义 HTML UI（例如展示复杂交互）；注意安全（CSP、nonce、postMessage）。

3. 插件工作流程（简要步骤）

一个典型的命令触发工作流：

工作流说明：

用户从命令面板或快捷方式执行某个命令（例如 Simple Hello: Say Hello）。
VS Code 根据 package.json 的 activationEvents 判断扩展是否已激活；若未激活则先载入扩展的 main 模块并调用 activate(context)。
activate(context) 中通常会注册命令并把返回的 disposable 放入 context.subscriptions。此后扩展进入就绪状态。
当用户再次触发命令时，已注册的处理函数（handler）会被执行，处理函数中可以调用 vscode.window.showInformationMessage、创建 WebviewPanel、修改工作区文件等。

4. 示例：simple-hello-js（代码解析与目录说明）

4.1 项目结构

目录结构图下：

d:\vscode-plugin\
└─ simple-hello-js\
   ├─ .gitignore
   ├─ LICENSE
   ├─ package.json
   ├─ src\
   │  └─ extension.js
   └─ dist\
      └─ simple-hello-js-0.0.1.vsix

LICENSE：MIT 许可文件，vsce 打包时需要，以免交互式提示。
package.json：扩展清单，包含扩展元数据、activationEvents、命令注册，以及 repository 字段（避免 vsce 警告）。main 指向 extension.js。
extension.js：扩展唯一入口文件。激活时注册命令 simple-hello.hello，运行后创建 Webview 面板并显示“Hello, Plugin!”。
dist/simple-hello-js-0.0.1.vsix：使用 npx --yes vsce package 打包生成的可安装扩展包；已通过 code --install-extension 在本机验证安装成功。

4.2 package.json

{
  "name": "simple-hello-js",
  "_comment_name": "扩展在 VS Code 市场的唯一标识（使用小写连字符）",
  "displayName": "Simple Hello (JS)",
  "publisher": "local",
  "version": "0.0.1",
  "engines": { "vscode": "^1.70.0" },
  "_comment_activation": "当用户执行 simple-hello.hello 命令时触发激活",
  "activationEvents": [ "onCommand:simple-hello.hello" ],
  "_comment_main": "入口脚本，VS Code 激活时 require 该文件",
  "main": "src/extension.js",
  "repository": {
    "type": "git",
    "url": "https://example.com/your-repo.git"
  },
  "_comment_contributes": "向 VS Code 声明扩展提供的命令、菜单等",
  "contributes": {
    "commands": [
      {
        "command": "simple-hello.hello",
        "title": "Simple Hello: Say Hello"
      }
    ]
  }
}

4.3 extension.js

const vscode = require('vscode');

// 该扩展是命令驱动：激活后注册 simple-hello.hello 命令，执行时打开一个纯文本 Webview。

/**
 * Activate: register a command that opens a WebviewPanel containing a text panel.
 * @param {vscode.ExtensionContext} context
 */
function activate(context) {
  // registerCommand 返回 Disposable；命令 ID 必须与 package.json 中的 contributes.commands 匹配。
  const disposable = vscode.commands.registerCommand('simple-hello.hello', () => {
    // Create and show a new webview panel
    const panel = vscode.window.createWebviewPanel(
      'simpleHelloPanel', // internal type
      'Simple Hello', // title
      vscode.ViewColumn.One, // show in first column
      {
        enableScripts: false // 禁用脚本，示例仅展示静态文本更安全
      }
    );

    // Simple HTML with a readonly textarea showing the message
    panel.webview.html = getWebviewContent();
  });

  // 将 Disposable 放入 subscriptions，方便 VS Code 在停用扩展时自动清理
  context.subscriptions.push(disposable);
}

function getWebviewContent() {
  // 返回完整 HTML；textarea 设置为 readonly，避免用户编辑引起困惑
  return `<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Simple Hello</title>
  <style>
    html, body, textarea { height: 100%; margin: 0; padding: 0; }
    textarea { box-sizing: border-box; width: 100%; height: 100%; resize: none; font-size: 16px; padding: 12px; }
  </style>
</head>
<body>
  <textarea readonly>Hello, Plugin!</textarea>
</body>
</html>`;
}

function deactivate() {}

module.exports = { activate, deactivate };

5. 如何打包，安装，验证

5.1 打包

# 打包（vsce 会自动生成 simple-hello-js-0.0.1.vsix）
npx --yes vsce package

5.2 在本地安装（PowerShell）

# 进入项目目录（可选）
Set-Location -Path 'D:\vscode-plugin\simple-hello-js'

# 从 dist 目录安装
code --install-extension .\dist\simple-hello-js-0.0.1.vsix

5.3 验证

在 VS Code 中执行命令面板（Ctrl+Shift+P），运行 Simple Hello: Say Hello。
会弹出一个标题为 Simple Hello 的面板，内部显示只读文本框：Hello, Plugin!。

posted on 2025-11-22 23:59 ArnoldLu 阅读(50) 评论(0) 收藏举报

刷新页面返回顶部

Arnold Lu@南京