内置组件
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
组件库,使用时只需要引入我们提供的主题包即可正常使用。
- opensumi/antd-theme —— AntD 基于 OpenSumi 的主题包
用法如下:
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)
引用。
区块 | 文档 |
---|---|
主题色板 | 主题色板 |
基础颜色 | 基础颜色 |
Button | Button 按钮 |
Checkbox | Checkbox 多选框 |
Input | Input 输入框 |
Select | Select 选择器 |
Editor | Editor 编辑器 |
ActionBar | ActionBar 操作组 |
ActivityBar | ActivityBar 左右侧活动栏 |
Bottom Panel | Bottom Panel 底部面板 |
Explorer | Explorer 资源管理器 |
Keybinding | Keybinding 快捷键页 |
MenuBar | MenuBar 菜单栏 |
Message | Message 全局提示 |
Modal | Modal 对话框 |
Notification | Notification 通知提醒框 |
Popover | Popover 气泡卡片 |
SCM | SCM 源代码管理 |
Search | Search 搜索 |
Setting | Setting 设置页 |
Sidebar | Sidebar 侧边栏面板 |
StatusBar | StatusBar 底部状态栏 |
Tab | Tab 标签页 |
ToolBar | ToolBar 工具栏 |
Tooltip | Tooltip 文字提示 |
大部分自定义 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
的,故在使用一部分库的 Modal
、 Dialog
、 Select
等带浮动属性的组件时,你需要重新为这类组件绑定一个渲染容器。
以 AntD 中的 Modal
组件为例,你在使用时需要传入一下当前组件的渲染容器,否则对应的组件将不能正常工作。
// ...
<Modal title="Basic Modal" getContainer={ref.current}>
<p>Some contents...</p>
<p>Some contents...</p>
<p>Some contents...</p>
</Modal>