内置组件

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 中继续使用社区中流行的 AntD 组件库,使用时只需要引入我们提供的主题包即可正常使用。

用法如下:

import '@opensumi/antd-theme/lib/index.css';
import { ConfigProvider } from 'antd';

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

其他主题库适配期待社区的贡献。

自定义适配主题的组件

对于不满足以上方案的同学,或者期望自行编写 CSS 样式来适配主题,可以参考下面的 Token 表使用对应的 CSS Token,如 Token 为 kt.disableForeground, 在使用时就可以通过 var(--kt-disableForeground) 引用。

区块文档
主题色板主题色板
基础颜色基础颜色
ButtonButton 按钮
CheckboxCheckbox 多选框
InputInput 输入框
SelectSelect 选择器
EditorEditor 编辑器
ActionBarActionBar 操作组
ActivityBarActivityBar 左右侧活动栏
Bottom PanelBottom Panel 底部面板
ExplorerExplorer 资源管理器
KeybindingKeybinding 快捷键页
MenuBarMenuBar 菜单栏
MessageMessage 全局提示
ModalModal 对话框
NotificationNotification 通知提醒框
PopoverPopover 气泡卡片
SCMSCM 源代码管理
SearchSearch 搜索
SettingSetting 设置页
SidebarSidebar 侧边栏面板
StatusBarStatusBar 底部状态栏
TabTab 标签页
ToolBarToolBar 工具栏
TooltipTooltip 文字提示

大部分自定义 Token 通常会向下兼容到 VS Code 的 Theme Color,你也可以直接使用这些 Token。

如果你觉得这部分色值表的定义不能满足你的需求,一方面,你可以考虑为 OpenSumi 提供一个 PR 拓展一下,另一方面,你也可以绕开这部分限制,通过在集成侧处理的方式解决,下面介绍两种常用手段:

通过 ClassName 进行样式自定义

通过 ClassName 的作用域进行自定义,如:

.vs-dark {
  .a {
    color: #fff; // 暗色主题下 `.a` 的字体颜色为白色
  }
}

.vs {
  .a {
    color: #000; // 亮色主题下 `.a` 的字体颜色为黑色
  }
}

使用 registerColor 方法注册自定义 Token

这里需要注意的是需要保证 registerColor 方法的调用在应用启动前,建议放在 renderApp 阶段引入。

// 入口文件
import './custom-token';
// ...

renderApp({...});
// custom-token.ts
import {
  registerColor,
  ktPrimaryButtonForeground,
  ktPrimaryButtonBackground,
  ktPrimaryButtonClickBackground
} from '@opensumi/ide-theme';
import { localize } from '@opensumi/ide-core-browser';

export const ktToolbarButtonSelectionForeground = registerColor(
  'kt.toolbarButton.selectionForeground',
  {
    dark: ktPrimaryButtonForeground,
    light: ktPrimaryButtonForeground,
    hcDark: null,
    hcLight: null
  },
  localize('Active toolbar button foreground.')
);
export const ktToolbarButtonSelectionBackground = registerColor(
  'kt.toolbarButton.selectionBackground',
  {
    dark: ktPrimaryButtonBackground,
    light: ktPrimaryButtonBackground,
    hcDark: null,
    hcLight: null
  },
  localize('Active toolbar button background.')
);
export const ktToolbarButtonForeground = registerColor(
  'kt.toolbarButton.foreground',
  {
    dark: ktPrimaryButtonForeground,
    light: ktPrimaryButtonForeground,
    hcDark: null,
    hcLight: null
  },
  localize('Default toolbar button foreground.')
);
export const ktToolbarButtonBackground = registerColor(
  'kt.toolbarButton.background',
  {
    dark: ktPrimaryButtonClickBackground,
    light: ktPrimaryButtonClickBackground,
    hcDark: null,
    hcLight: null
  },
  localize('Default toolbar button background.')
);

使用浮动组件

在编写插件中我们难免会使用浮窗让用户进行二次交互,在 OpenSumi Browser 端中编写这类代码,由于整体方案采用了一种沙箱的隔离机制,插件内的 Browser 层是获取不到顶部的 Document 的,故在使用一部分库的 ModalDialogSelect 等带浮动属性的组件时,你需要重新为这类组件绑定一个渲染容器。

以 AntD 中的 Modal 组件为例,你在使用时需要传入一下当前组件的渲染容器,否则对应的组件将不能正常工作。

// ...
<Modal title="Basic Modal" getContainer={ref.current}>
  <p>Some contents...</p>
  <p>Some contents...</p>
  <p>Some contents...</p>
</Modal>