VSCode 插件开发经验小结

小绵羊不怕大灰狼2024-07-03 11:26

理解 vscode，我们首先要谈的是 Electron。

Electron 的核心技术主要包括以下几个方面：

  • Chromium: Electron 使用了 Chromium 浏览器作为其渲染引擎。Chromium 是 Google Chrome 的开源版本，负责处理和渲染应用程序的用户界面，包括 HTML、CSS 和 JavaScript。这使得开发者可以利用 Web 开发技术来构建应用的界面。

  • Node.js: Electron 集成了 Node.js，使得开发者可以在应用程序的主进程（后台）中运行 JavaScript 代码。Node.js 提供了对文件系统、网络、进程等系统级 API 的访问，增强了应用程序的功能和交互性。

  • Native API: Electron 提供了一套 API，允许主进程和渲染进程之间进行通信，以及调用操作系统级别的功能。这些 API 包括 ipcRenderer 和 ipcMain（用于进程间通信）、webContents（用于控制页面内容）等。

  • Electron 还有一个很大特点就是多进程。主要的有以下两个进程：

  • 主进程：

    • 1、Electron 中运行 package.json 中的 main 脚本的进程被称为主进程，即 main.js 就是运行在主进程。

    • 2、一个 electron 应用有且只有一个主进程。

    • 3、只有主进程可以直接进行 GUI 相关的原生 API 操作。

  • 渲染进程：

    • 1、运行在 Chromium 的 web 页面姑且叫渲染进程，即运行 index.html 的环境就是渲染进程。

    • 2、一个 electron 应用可以有多个渲染进程。

    • 3、渲染进程在引入 Node.js 模块的前提下，可以在页面中和操作系统进行一些底层交互（如 fs 模块）。

    • 了解了 vscode 的底层设计，下面我们就以真实的需求（创建模板）来一步步探索 vscode 扩展开发。

复制代码

需求分析

在 vscode 活动栏提供视图容器，透出创建模板入口，点击后打开可视化界面，进行简单配置后完成模板创建（注册模板信息到模板平台并生成对应的模板文件)。

要实现以上功能，需要先提炼出几个和 vscode 相关功能：

  • 通过 vscode 指令系统，注册一个命令到菜单栏。

  • 创建一个用于配置的 web 页面。

  • 完成配置后上传配置信息并创建文件。

  • 完成配置后关闭 web 页面。

复制代码

逻辑实现

▐ 注册指令

要实现以上功能，需要先提炼出几个和 vscode 相关功能：

  • 通过 vscode 指令系统，注册一个命令到菜单栏。

  • 创建一个用于配置的 web 页面。

  • 完成配置后上传配置信息并创建文件。

  • 完成配置后关闭 web 页面。

初始化一个插件项目后，暴露在最外面的文件中包含 activate 和 deactvate 两个方法，这俩方法属于 vscode 插件的生命周期，最终会被 export 出去给 vscode 主动调用。而 onXXX 等事件是声明在插件 package.json 文件中的 Activation Events。声明这些 Activation Events 后，vscode 就会在适当的时机回调插件中的 activate 函数。vscode 之所以这么设计，是为了节省资源开销，只在必要的时候才激活你的插件。

// package.json
  "activationEvents": [
    "onCommand:dinamicx.createTemplate",
    ...
  ],
 "commands": [
      {
        "command": "dinamicx.createTemplate",
        "title": "DX: 创建模板"
      },
      ...
  ],
    "menus": {
      "view/title": [
        {
          "command": "dinamicx.createTemplate",
          "group": "navigation@0",
          "when": "view == dinamicx.views.main"
        }
        ...
      ]
    }

也可以在插件激活时注册命令:

import { createTemplate } from './commands/createTemplate';

export function activate(context: vscode.ExtensionContext) {
  // 注册命令
  vscode.commands.registerCommand('dinamicx.createTemplate', (info: any) => {
    createTemplate(context, info.path);
  })
    ...
}

上面这段代码的含义是将 dinamicx.createTemplate 这个命令和函数绑定，具体的逻辑部分应该在 createTemplate 这个方法中实现。

▐ 创建 WebView

如果要创建一个页面，可以使用 vscode 提供的

api------vscode.window.createWebviewPanel：

export function createTemplate(
  context: vscode.ExtensionContext,
  dirPath: string,
) {
  const panel = vscode.window.createWebviewPanel(
    'createTemplate', // viewType
    '创建模板页面', // 视图标题
    vscode.ViewColumn.One, // 显示在编辑器的哪个部位
    // 启用JS，默认禁用 // webview被隐藏时保持状态，避免被重置
    { enableScripts: true, retainContextWhenHidden: true },
  );
  ...
  const htmlContent = this.getHtmlContent(panel.webview, htmlPath);
  panel.webview.html = htmlContent;
  panel.reveal();
  return panel;
}

具体渲染的页面可以通过 html 属性指定，但是 html 属性接收的参数是字符串！那么我们无法使用 vue/react 进行编码，只能写模板字符串了吗？

当然不是！我们可以先编写 react 代码，再打包成 js，套在 index.html 模板中 return 出来，问题就迎刃而解。处理这件事情的就是getHtmlContent

function getHtmlContent(webview, htmlPath) {
    /*
    各种资源的绝对路径
    const getHTMLDependencies = () => (`
    <!-- Dependencies -->
    <script src="${highlightJs}"></script>
    <script src="${reactJs}"></script>
    <script src="${reactDomJs}"></script>
    <script src="${antdJs}"></script>
  `);
   */
    const { getHTMLLinks, getHTMLDependencies } = useWebviewBasic(context);
    return `
  <!DOCTYPE html>
  <html>
      <head>
          <meta charset="UTF-8" />
          ${getHTMLLinks()}
      </head>
      <style>
        body {
          background-color: transparent !important;
        }
</style>
      <body>
          <div id="root"></div>
          ${getHTMLDependencies()}
          <!-- Main -->
          <script src="vscode-resource:${htmlPath}"></script>
          #{endOfBody}
      </body>
  </html>
  `;
}

由上面的代码可见，针对一个命令 / 函数，如果涉及到 webview，只关注渲染代码（即 SPA 的 js 文件），不关心具体页面实现，所以可以将编写 UI 相关的逻辑，提炼到 node 主进程之外。

▐ React 和 Webpack

对于 vscode 插件来讲，UI 是独立的，所以我们可以像创建 react 项目一样来完成页面部分的代码。

const Template: React.FC = () => {
  const [loading, setLoading] = useState(false);
  ...
  return (
    <Spin spinning={loading} tip={loadingText}>
      <div className="template">
           ...
      </div>
    </Spin>
  );
};

ReactDOM.render(<Template />, document.getElementById('root'));

在打包方面，刚才提到了我们要根据不同命令加载不同的页面组件，即不同的 js，所以打包的 entry 是多入口的；为了不重复引入公共库，将 react、antd 等库 external，选择通过 cdn 的方式引入。

const config = {
    mode: env.production ? 'production' : 'development',
    entry: {
      template: createPageEntry('page-template'),
      layout: createPageEntry('page-layout'),
      view: createPageEntry('view-idl'),
      ...
    },
    output: {
      filename: '[name].js',
      path: path.resolve(__dirname, '../dist/webview'),
    },
    ...
    externals: {
        'react': 'root React',
        'react-dom': 'root ReactDOM',
        'antd': 'antd',
    },
  };
▐ 进程通信

当我们实现 Webview 后，下一步是拉取数据，然后渲染到本地项目对应的路径中，可见这一步需要操作系统 api 的支持，我们需要使用 node 进程来做这件事。

那么问题来了，UI 是通过 html 字符串传给 vscode 进程的，他们之间是如何通信的呢。

开发 vscode 扩展最核心（恶心）的事情就是通信，单向的数据流导致不仅是 webview 和插件 node 进程通信复杂，即使在同一个 react 项目中的两个不同页面（webview）也是不能直接进行数据交互的。

流程如图：

vscode 在通信这里，只为我们提供了最简单粗糙的通信方法 ------ acquirevscodeApi，这个对象里面有且仅有以下几个可以和插件通信的 API。

插件发送消息：

window.addEventListener('message', (event) => {
    const message = event.data;
    console.log(message);
});

WebView 给插件发消息：

window.addEventListener('message', (event) => {
    const message = event.data;
    console.log(message);
});

WebView 给插件发消息：

export const vscode = acquirevscodeApi();
vscode.postMessage('xxx');

插件接收消息：

通信封装

基于以上的进程通信方式，如果所有通信逻辑都通过 message 事件监听，那怎么知道某一处该接收哪些消息，该如何发送一个具有唯一标识的消息？

vscode 本身没有提供类似的功能，不过可以自己封装。

流程如图：

Webview 端

export abstract class App<> {
    //    private readonly _api: vscodeApi;

    // 单向通信
    protected sendCommand<TCommand extends IpcCommandType<any>>(
        command: TCommand,
        params: IpcMessageParams<TCommand>
    ): void {
        const id = nextIpcId();
        this.postMessage({ id: id, method: command.method, params: params });
    }

    // 双向通信
    protected async sendCommandWithCompletion<
        TCommand extends IpcCommandType<any>,
        TCompletion extends IpcNotificationType<any>
    >(
        command: TCommand,
        params: IpcMessageParams<TCommand>,
        completion: TCompletion
    ): Promise<IpcMessageParams<TCompletion>> {
        const id = nextIpcId();

        const promise = new Promise<IpcMessageParams<TCompletion>>(
            (resolve, reject) => {
                let timeout: ReturnType<typeof setTimeout> | undefined;

                const disposables = [
                    DOM.on(window, 'message', (e: MessageEvent<IpcMessage>) => {
                        onIpc(completion, e.data, (params) => {
                            if (e.data.completionId === id) {
                                disposables.forEach((d) => d.dispose());
                                queueMicrotask(() => resolve(params));
                            }
                        });
                    }),
                    {
                        dispose: function () {
                            if (timeout != null) {
                                clearTimeout(timeout);
                                timeout = undefined;
                            }
                        },
                    },
                ];

                timeout = setTimeout(() => {
                    timeout = undefined;
                    disposables.forEach((d) => d.dispose());
                    debugger;
                    reject(
                        new Error(
                            `Timed out waiting for completion of ${completion.method}`
                        )
                    );
                }, 600000);
            }
        );

        this.postMessage({
            id: id,
            method: command.method,
            params: params,
            completionId: id,
        });
        return promise;
    }

    private postMessage(e: IpcMessage) {
        this._api.postMessage(e);
    }
}

Node 端：

需求实现

基于以上，视图层、逻辑层、通信层的框架就大致完成了，接下来就是基于需求本身实现视图（react）和逻辑（node）的实现了。

希望此文能帮助大家快速对 vscode 插件开发有一定了解。后续会再介绍基于 vscode 的 DX 插件和使用建议、以及提高 vscode 开发效率的配置分享～

参考资料

相关推荐
汀小烟4 小时前
使用静态成员函数统计学生平均成绩
c语言·开发语言·数据结构·c++·vscode
Eiceblue5 小时前
Python 插入、替换、提取、或删除Excel中的图片
开发语言·vscode·python·pycharm·excel
神奇夜光杯5 小时前
Python酷库之旅-第三方库Pandas(003)
开发语言·ide·python·pandas·基础知识·学习和成长·标准库及第三方库
Leon哉6 小时前
PyCharm中如何将某个文件设置为默认运行文件
ide·python·pycharm
**K9 小时前
how to use Xcode
ide·macos·xcode
changuncle10 小时前
VSCode使用ipynb文件高效地进行功能测试
vscode·功能测试·jupyter·ipynb·方便
syluxhch10 小时前
Pycharm的终端（Terminal）中切换到当前项目所在的虚拟环境
ide·python·pycharm
归&念11 小时前
ONLYOFFICE8.1版本桌面编辑器的测评(您的私人办公室)
编辑器
专注成就自我11 小时前
p标签文本段落中因编辑器换行引起的空格问题完美解决方案
前端·javascript·vue.js·编辑器·html
EEer！12 小时前
vscode(七)：设置不同括号有不同颜色
ide·vscode·编辑器
热门推荐
01Coze扣子平台完整体验和实践（附国内和国际版对比）02组基轨迹建模 GBTM的介绍与实现（Stata 或 R）03【经验分享】Ubuntu22.04安装微信(linux官方版)042024亚太赛（中文赛）数学建模竞赛选题建议+初步分析05yolov8实战第五天——yolov8+ffmpg实时视频流检测并进行实时推流——（推流，保姆教学）06【立创EDA-PCB设计基础】6.布线铺铜实战及细节详解07用友U8 Cloud 反序列化RCE漏洞复现082025张宇考研数学，百度网盘视频课+36讲PDF讲义+真题09浏览器插件——ModHeader 的分享和学习10【漏洞复现】Geoserver远程代码执行漏洞（CVE-2024-36401）