【译】Eclipse Theia插件开发指引 - Authoring Theia Plug-ins

2,220 阅读5分钟

让我们来创建一个Theia插件,例如,我们将注册一个命令Hello World,执行命令显示通知“Hello world!”。本文将指导您完成所有必要的步骤。

Theia项目架构(Theia’s Architecture)

插件 vs 扩展(Plug-in vs Extension)

Theia是一个可扩展的IDE,你也许已经知道了扩展是自定义IDE的一种方式。插件是Theia近期提供的一种新的扩展模式,以下是插件与扩展之间的主要区别。

优点:

  • 代码隔离:插件的代码在单独的进程中运行的,它不会阻塞Theia核心进程。
  • 运行时加载,无需重新编译Theia。
  • 减少编译时间
  • 高内聚的,插件可以打包成单个文件,然后直接加载,无需额外从npmjs等获取依赖项等
  • API简洁
    • 无需学习inversify或其它框架。
    • 单一入口, 会根据相关的JsDoc文件进行自动代码补全
    • API向下兼容,因此可以轻松地升级theia版本

缺点:

  • 依赖于预设的API。 如果contribution point没有提供相关的API,那就无法调整某些内容。另外,可以扩展当前的API以支持更多内容 ;-)

设计(Design)

Theia应用由特定功能的一系列组件、命令、逻辑构成。 Theia定义了一个运行时API,允许插件自定义IDE、为其添加各种行为。在Theia中,插件可以通过名为theia的对象访问 API,该对象在所有插件中都可用。有关API的详细信息可访问 github.com/eclipse-the…

插件有两种性质:

  • 后端插件。如果你熟悉VS Code扩展的话,二者是非常相似的。插件的代码在服务器端独自的进程中运行。 API被调用将会发送指令给浏览器以注册新命令等。所有回调函数都在服务器端由专用进程执行。

  • 前端插件。在这种场景下,回调函数会在浏览器上的worker线程中执行。这些插件仅可以使用在“浏览器兼容”模块。例如,打开或写入文件是无法实现的,因为插件的所有代码都在浏览器端运行。但是如果你想要在客户端搞点东西,这种方法还是很有帮助的。

环境要求(Prerequisites)

一个正在运行的Theia实例(v0.3.12+),可以从Theia仓库中获得相关指引。

项目布局(Project Layout)

我们需要创建一个新的项目,为此,我们会新建一个theia-hello-world-plugin文件夹,其包含了项目的源码。 为了更快捷的完成仓库配置,可以安装一个Yeoman代码生成器,使用它来生成项目。

使用以下命令安装和执行代码生成器,可以直接在Theia实例中的终端输入这些命令。

npm install -g yo @theia/generator-plugin
mkdir theia-hello-world-plugin
cd theia-hello-world-plugin
yo @theia/plugin

上述命令中:

  • npm install -g yo @theia/generator-plugin命令全局安装的Theia生成器
  • yo @theia/plugin会调用Yeoman生成器,将Theia生成器的使用方式模板化

这是一个生成器运行的动态截图:

每个问题都选择默认值就好, 至此,theia-hello-world-plugin文件夹就有一个经过相关源码编译的插件了

实施插件(Implementing the Plug-in)

现在我们看看生成的代码

{
      "name": "theia-hello-world-plugin",
      "publisher": "theia",
      "keywords": [
        "theia-plugin"
      ],
      "version": "0.0.1",
      "files": [
        "src"
      ],
      "devDependencies": {
        "@theia/plugin": "latest", <-- 1. Theia API dependency
        "rimraf": "^2.6.2",
        "typescript": "^2.9.2"
      },
      "scripts": {
        "prepare": "yarn run clean && yarn run build",
        "clean": "rimraf lib",
        "build": "tsc"
      },
      "engines": {
        "theiaPlugin": "latest"  <-- 2. this plug-in requires Theia runtime
      },
      "theiaPlugin": {
        "backend": "lib/theia-hello-world-plugin-backend-plugin.js" 3. <-- entrypoint
      }
}

package.json文件里有三个重要的部分

  1. 首先,在devDependencies中,有一个依赖包@theia/plugin,它的主要作用是调用Theia API(例如:添加新命令和显示消息)

  2. 第二, engines部分包括了theiaPlugin字段。 它可以指定该插件允许运行的Theia版本。

  3. 第三,theiaPlugin部分包含插件的入口文件。对于后端插件,backend字段表示为插件的js文件路径。

我们来看看生成的源代码文件,这个文件的路径是src/theia-hello-world-plugin-backend-plugin.ts,它是用TypeScript代码写的

import * as theia from '@theia/plugin';

export function start() {
    const informationMessageTestCommand = {
        id: 'hello-world-example-generated',
        label: "Hello World"
    };
    theia.commands.registerCommand(informationMessageTestCommand, (...args: any[]) => {
        theia.window.showInformationMessage('Hello World!');
    });

}

export function stop() {

}

如上,只需要简单的几行代码就能实现注册命令和显示消息通知的插件。 第一行代码import * as theia from '@theia/plugin'导入API是重要的,它会通过一个theia对象提供所有可用的Theia插件API。 这段代码中,有两个方法start()andstop() start()方法会在加载插件时调用,这个方法中,有一个操作是注册一个hello world命令和一个回调方法显示Hello World作为消息通知。一个命令行对象有一个idlabel,将会在命令行模式时显示。

stop()方法会在插件停止时被调用,这个方法是可选。

执行插件(Executing the Plug-in)

现在我们想看看插件的行为,为此,Theia内置了一种托管模式hosted mode,在这个模式下,我们可以在一个Theia实例上开发插件,在另一个Theia实例调试插件。所以开发和测试插件是非常简单便捷的。

首先,确认你已经在Theia里打开插件代码的文件夹(将文件夹添加至工作区),然后打开命令行看板(按F1)搜索Hosted mode: start instance并选择它。

然后从工作区中选择插件的文件夹(包含package.json文件)

此时会在端口3030生成一个新的theia实例,运行在一个新tab,称呼其为Development host.(可以在状态栏看到名称Development host)

Development host实例中,打开命令面板然后搜索Hello World命令

选择这个命令然后你就会看到屏幕上出现了一个Hello World消息通知

开发插件(Developing the Plug-in)

正如上述所说,Theia API 是用TypeScript编写的,因此在开发时会具备代码自动补齐和必要的注释。

更新插件 (Updating the Plug-in)

假如你现在想把消息通知由Hello World改为Hello Theia,首先我们进入到名称为Hosted Plugin: runningTheia实例修改ts文件src/theia-hello-world-plugin-backend-plugin.ts,将showInformationMessage('Hello World!');修改为showInformationMessage('Hello Theia!');

在插件的根目录运行yarn build命令重新编译源码,然后只需刷新Development Host实例的tab,插件就会重新加载。

PS:你也可以用watch模式。

插件API

Browse typedoc of plug-ins

VS Code兼容 (VS Code implementation)

Theia正在逐步提供VS Code API,查看以下的链接可以获取到当前的实施状态。 Compare Theia vs VS Code API


以下为译者注:

原文链接:theia-ide.org/docs/author…

随手翻译以加深理解,如有错误欢迎指出。