OpenSumi 插件文档更新啦！深入了解 OpenSumi API

OpenSumi团队
507 阅读6分钟

OpenSumi 文档站又更新啦！ 一起来了解下 OpenSumi 插件开发和OpenSumi API 等最新内容吧~

opensumi.com/zh/docs/ext…

在 OpenSumi 中，我们提供了一个强大的插件生态系统，在兼容 VS Code 插件 API 的同时，我们也有着自己的 OpenSumi API 用于进一步拓展 IDE 界面及能力。
▲插件能力实现结构图

OpenSumi 插件开发

OpenSumi 提供了内置图标、内置命令、内置组件能力。

内置图标

OpenSumi 提供了一套内置的图标集，这些图标是基于 iconfont 维护的，在注册视图等面板时可以直接使用 iconClass: <iconname> 来引用这些图标。 在线地址：OpenSumi built-in icon list。

内置命令

OpenSumi 提供了一套内置命令，部分实现了 VS Code 内置实现的命令，这些命令可能会在某些插件被使用，如果遇到了没有实现的内置命令，可以前往 OpenSumi Issues 提适配需求。

例如使用 vscode.open 打开一个带协议的文件

import * as sumi from 'sumi';

// 参数说明
type VSCodeOpen = (
  resource: vscode.Uri,
  columnOrOptions?: vscode.ViewColumn | vscode.TextDocumentShowOptions,
  label?: string
) => void;

sumi.commands.executeCommand(
  'vscode.open',
  {
    preserveFocus: true,
    preview: false
  } as vscode.TextDocumentShowOptions,
  'test-title'
);

内置组件

OpenSumi 内置了一些基础的组件，在 Browser 端插件运行时可以通过 sumi-browser 模块引入这些组件来使用。
目前的内置组件包括：

├── Badge
├── Button
├── Checkbox
├── Dialog
├── Icon
├── Input
├── Message
├── Notification
├── Overlay
├── Popover
├── RecycleList
├── BasicRecycleTree
├── Scrollbars
├── Select
├── Tabs
├── Tooltip

部分使用示例见：Use Built-in Components。

OpenSumi API

Toolbar

Toolbar 默认位于 IDE 顶部菜单栏右侧，根据不同集成方的配置，也可以展现为单独的一栏，类似支付宝小程序开发者工具。如下图所示：

在 sumi.toolbar 命名空间内包含 toolbar 相关的 API，可以结合 Toolbar 贡献点 对工具栏进行更细致的控制。 

由于历史原因，当前框架内声明 OpenSumi 贡献点需要使用 kaitianContributes 进行声明，在升级至 OpenSumi 2.25.0 版本后，可以使用 sumiContributes 进行声明，同时也会兼容旧的 kaitianContributes 声明。

Toolbar 贡献点可以通过 JSON 配置来描述工具栏上的元素，目前支持 button 及 select 两种方式，我们称之为 action，在某些情况下需搭配 Toolbar API 来使用。

Button 按钮

button 是一个可点击的元素，支持仅图标、图标+文字两种显示模式，用户可以通过设置的方式修改按钮样式。插件中可以通过配置 contributes 的方式自定义按钮样式及其图标等。

通过 kaitianContributes 中声明 toolbar.actions 的方式可以注册一个 button 类型的 action。

这会在右侧渲染一个只有图标的按钮，现在点击按钮并不会有任何反应，因为还没有对按钮的点击事件做处理，处理点击事件有两种方式：

  1. 绑定 Command

  2. 通过 Toolbar API 获取按钮的实例，监听点击事件

绑定 Command，效果如下：

自定义 Popover，效果如下：

Select 下拉选项

Select 是一个可选择的下拉框，可通过贡献点声明一组值列表，同样可以给 Select 绑定一个 command，或通过 Toolbar API 注册选择事件。

效果如下：

Event

在 OpenSumi 中，你可以通过 Event 机制来实现跨插件的通信，如：

import * as sumi from 'sumi';

// 插件 A 中发出事件
function activate() {
  sumi.event.fire('event-from-extension-a', { data: 'a' });
}

// 插件 B 中接收事件
function activate() {
  sumi.event.subscribe('event-from-extension-a', data => {
    console.log(data); // a
  });
}

同样的，你也可以通过 Command（命令） 的方式来实现类似逻辑，参考：VS Code API#commands。

i18n

完整的插件包括 VS Code 插件， OpenSumi 插件，package.json 贡献点共同组成，针对不同环境及插件不同功能，国际化的实现在兼容 VS Code 插件的同时也具备了一定程度的扩展能力。

VS Code 插件

OpenSumi 兼容了 VS Code 官方提供的一些语言包插件（建议使用 2.23.6 以上的 OpenSumi 版本），如：

  • Chinese (Simplified) (简体中文) Language Pack for Visual Studio Code

  • ...

当前仅支持 zh-cn 及 en-us 两种语言的切换能力，如有进一步需求，可到 issues 提交适配需求。
VS Code 插件在 1.74 版本后废弃了原有的 i18n 方案，推荐在插件中采用新的 l10n作为替代方案，如遇到无法正常被国际化的文本，可检查插件版本，考虑使用旧一点的插件版本。
当前 OpenSumi 暂未支持通过 vscode.l10n 实现的本地化能力插件，如遇到相关问题，可以在 #2341 留言或 +1，我们会进一步加快适配进度。
同时，OpenSumi 内也支持了以下三种国际化代码方式：

  1. 通过 PackageJSON 声明
  2. Node 层的声明及使用
  3. Browser 层的声明及使用\

Layout

OpenSumi 扩展 API 中包含名为 layout 的 namespace，除了直观的 toggleBottomPanel、toggleLeftPanel、toggleRightPanel 等方法之外，可以使用 getTabbarHandler 传入特定 Tabbar 面板的 ID 获取一个 handler 对象，用于更精细的控制 Tabbar。这个 ID 是指插件 UI 侧注册视图的 ID，一般我们可以简单的通过 Dom 结构上找到这些信息，如：

使用方法

import * as sumi from 'sumi';

const tabbar = sumi.layout.getTabbarHandler(`explorer`);
tabbar.setSize(500); // 设置面板尺寸
tabbar.activate(); //展开面板
tabbar.deactivate(); // 收起面板
tabbar.setVisible(); // 设置为隐藏状态
tabbar.onActivate(); // 面板展开时的事件
tabbar.onInActivate(); // 面板收起时的事件
tabbar.setIcon(); // 设置对应 Tab 上的图标
tabbar.setTitle(); // 设置对应 Tab 上的文字
tabbar.setBadge('12'); // 设置 Tab 的徽章

对于其他插件注册的视图，可以通过 getExtensionTabbarHandler 方法获取其实例，使用时需要传入对应插件的 ID，如：

const tabbar = sumi.layout.getExtensionTabbarHandler('viewId', 'extensionId');

如有疑问，欢迎在 Issue 中提问交流 ~

Terminal

终端（Terminal） 是 IDE 重要的组成部分，能帮助用户快速地进行系统命令的执行及文件操作等，下面介绍一些常见的插件内的拓展场景。

效果如下：

06

**自定义编辑器组件
**

在 OpenSumi 的 Browser 插件中，支持通过指定 scheme 的方式自定义编辑器区域的组件，这个功能类似 VS Code 的 Webview API，不同之处在于，这里的编辑器组件可以是一个 React 组件的形式。

注册

注册一个编辑器组件，需要提供自定义的 scheme , 打开这个组件可以使用 vscode.commands.executeCommand 执行 vscode.open，注意这里执行需要在插件 Node 层逻辑。

在调用 vscode.commands.executeCommand 执行命令打开编辑器时可以通过 uri

的 queryString 传入参数，这些参数会作为编辑器组件的 props 在 Browser 侧传入。

特殊用法请点击文末阅读原文~

Components

第三方组件

在 OpenSumi 的 Browser 插件中，sumi-browser 已导出 @ali/ide-components 中所有的组件，所以当我们需要使用组件，直接通过 sumi-browser 引用即可，示例如下：

import * as React from 'react';
import { Button, Input } from 'sumi-browser';

export class Sample extends React.Component {
  render() {
    return (
      <div>
        <Button>This is a button</Button>
        <Input />
      </div>
    );
  }
}

在 OpenSumi 的 sumi-browser 中导出的组件多为 OpenSumi 中的常用组件，可能你会需要使用更多组件，比如 antd 之类组件库，需要注意的是，若你的插件运行环境已开启 ShadowDom 模式（避免样式污染，目前是默认开启），请注意在使用全局通知类的组件如 notification/dialog 等需要注意 css 可能被隔离导致样式失效，请选择 sumi-browser 中导出的 messsage/dialog 组件以满足开发需求，或将组件挂载至当前组件下，详见：视图隔离注意事项。

我们也提供了针对 AntD 4 版本的主题包 opensumi/antd-theme，你可以通过如下的方式使用：

import '@opensumi/antd-theme/lib/index.css';
...

return (
  <ConfigProvider prefixCls="sumi_antd">
    <App />
  </ConfigProvider>
);

开发同类主题文件，可参考 opensumi/antd-theme 仓库。

欢迎了解 OpenSumi，参与开源共建～

GitHub 地址：

github.com/opensumi

OpenSumi 官网：

opensumi.com/zh

扫二维码，加入 OpenSumi 社区交流： opensumi.com/zh/communit…

avatar
文章
阅读
粉丝