让我们来创建一个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
文件里有三个重要的部分
-
首先,在devDependencies中,有一个依赖包
@theia/plugin
,它的主要作用是调用Theia API(例如:添加新命令和显示消息) -
第二,
engines
部分包括了theiaPlugin
字段。 它可以指定该插件允许运行的Theia版本。 -
第三,
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
作为消息通知。一个命令行对象有一个id
和label
,将会在命令行模式时显示。
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: running
Theia实例修改ts文件src/theia-hello-world-plugin-backend-plugin.ts
,将showInformationMessage('Hello World!');
修改为showInformationMessage('Hello Theia!');
在插件的根目录运行yarn build
命令重新编译源码,然后只需刷新Development Host
实例的tab,插件就会重新加载。
PS:你也可以用watch模式。
插件API
VS Code兼容 (VS Code implementation)
Theia正在逐步提供VS Code API,查看以下的链接可以获取到当前的实施状态。 Compare Theia vs VS Code API
以下为译者注:
原文链接:theia-ide.org/docs/author…
随手翻译以加深理解,如有错误欢迎指出。