.theme.json 加一个可选的 .icls 编辑器配色方案)一样,它没有代码:
没有 WebAssembly,不需要编译,也不需要任何权限。
openidea-plugin new my-theme --template theme,它会复制
Harbor Night:
一个设置了全部可设置 token 的完整深色主题。
清单
wasm,也没有 [capabilities]。路径相对包目录,且不能超出包目录。清单的其他字段见 清单。
主题文件
tokens是src/styles/tokens.css中的 CSS 变量,也是 IDE 唯一的颜色来源。组件从不直接写颜色值,所以每个表面、边框、文字颜色、语法颜色和状态颜色都可以通过 token 设置。 下文的“Token 参考”列出了全部 token。kind选择内置的基础主题。主题生效时,IDE 实际运行在 Islands 深色或 Islands 浅色上,主题没有设置的 token 都保留基础主题的值。图标也会使用与 kind 对应的浅色或深色版本。只设置部分 token 的主题依然协调,但把所有 token 都列出来, 可以在 IDE 自身配色变化时保持稳定。- token 名称是
--加小写字母、数字和-(最多 64 字节)。 - 取值是普通的 CSS 值:十六进制(
#rgb、#rrggbb、#rrggbbaa)、rgb()、hsl()、color-mix()、var(--other-token), 少数非颜色 token 可以用关键字(italic、normal、none)或阴影列表。url()、image()、;、花括号、<、>、\和换行都会被拒绝。 - 允许
//和/* */注释,与 VS Code 主题文件相同。 - tokens.css 中由其他 token 推导出的 token(例如
--bg-editor是var(--bg-island),覆盖率和火焰图颜色由状态颜色混合而来) 会自动跟随变化,当然也可以单独设置。 - 尺寸(
--fs-*、--h-*、--radius-*)和字体(--font-ui、--font-mono)也能覆盖,但主题通常不动它们, 以免影响紧凑模式和用户的字体设置。
编辑器配色方案文件
.icls 文件里的部分。拆分只是为了组织文件:主题也可以把全部 token 都放进主题文件。
主题如何生效
选中的主题会作为一份作用于:root 的样式表注入,优先级高于内置主题,同时 data-theme 切换为主题的 kind。
有三样东西仍然叠加在它之上:
- 在 设置 › 外观与行为 › 外观 中选择的 强调色(非默认值时),
- 设置 › 编辑器 › 配色方案 中明确选择的配色方案或属性覆盖,
- 只改变尺寸的外观选项(紧凑模式)。
--bg-stripe-tooltip、--fg-stripe-tooltip、--border-stripe-tooltip 和 --shadow-stripe-tooltip。
主题没有设置时,沿用基础主题对应的提示框 token。
安装、应用与迭代
没有构建步骤:包就是文件夹本身。1
从模板开始
运行
openidea-plugin new my-theme --template theme(或复制 plugins/official/harbor-night),然后修改
id、name 和主题文件名。2
修改颜色
kind 要如实填写(浅色背景用 light)。3
安装
在 设置 › 插件 中打开齿轮菜单,选择 从磁盘安装插件…(也可以在查找操作中执行这个动作)并选择包文件夹; 或选择
从插件包文件安装…,再选择其中的
plugin.toml 或该文件夹的 .zip。4
应用
在 设置 › 插件 中选中该插件,点击主题旁的 应用。使用默认主题 可以切回。插件主题也会列在 设置 ›
外观与行为 › 外观 的 主题 中。
openidea-plugin link 链接文件夹(直接从原处读取),或者把它放进(或软链接到)受信任项目的
<project>/.openidea/plugins/<name>/。之后在插件上点 重新加载,或执行 重新加载插件 动作,即可加载修改。
文件或取值无效时,设置 › 插件 会显示加载错误以及所在文件和行号。
分享主题的方式与其他插件相同,见 打包。
导入 IntelliJ 主题
要使用已经装在 JetBrains IDE 里的主题,在 设置 › 插件 中打开齿轮菜单(需要已打开项目):- 从 JetBrains IDE 导入主题… 列出本机 JetBrains IDE(以及 Android Studio)中安装的主题插件,每个 IDE 的每个插件一行,
各 IDE 正在使用的主题所属插件排在前面。它读取每个 IDE 最新版本的设置目录:
~/Library/Application Support/JetBrains(macOS)、%APPDATA%\JetBrains(Windows)、~/.config/JetBrains和~/.local/share/JetBrains(Linux)。 - 从文件导入 IntelliJ 主题… 接受从 JetBrains Marketplace 下载的主题插件(
.jar,或包含插件lib/*.jar的.zip), 或者一个.theme.json(其editorScheme文件从同一目录读取)。
intellij.<plugin id>,包含其中的每个主题及其编辑器配色方案。它通过常规的安装页面安装,
当前使用的主题不会改变:请在 设置 › 外观与行为 › 外观 的 主题 中选择。再次导入同一插件会替换它。
这两个命令也是动作(plugins.importInstalledIntellijTheme、plugins.importIntellijTheme)。
移植 IntelliJ 主题以便发布
只移植许可证允许再分发的主题,保留其许可证文件,并在authors 和 description 中注明原作者。
仓库中的 scripts/theme/import-intellij-theme.ts 可以把 IntelliJ 的 .theme.json(以及可选的 .icls 编辑器配色方案)
转换为一个插件文件夹,发布前可以再编辑。它只依赖 Node 22。
colors 部分中的命名颜色和 * 通配符,并根据 "dark"(或 .icls 的 parent_scheme)确定 kind。
没有 IntelliJ 对应项的 token 保留该 kind 的内置值。只附带 .theme.json 且其中写了 editorScheme 路径的主题,需要把那个
.icls 作为第二个参数传入;完全没有 .icls 的主题保留内置的语法颜色。
.theme.json 到 UI 主题
完整的表是
src/features/plugins/intellijTheme.ts
中的 UI_KEYS。
.icls 到编辑器配色方案
完整的表是同一文件中的
ICLS_COLORS 和 ICLS_ATTRIBUTES。写成 <value /> 的属性没有自己的颜色,与 IntelliJ 一样按普通文本
(TEXT 的前景色)显示,而不是使用父配色方案的颜色。
移植 VS Code 主题
VS Code 主题(扩展中的themes/*.json)包含 type(dark / light / hc)、colors(工作台)和 tokenColors(TextMate scope)。
根据 type 设置 kind,然后手动映射:
tokenColors 按 TextMate scope 映射到语法 token:
注释上的
fontStyle: "italic" 对应 "--syn-comment-style": "italic"。
测试主题
- 安装(或链接)并应用主题后,逐一检查:带选中项的项目工具窗口、几种语言的编辑器、随处搜索、弹出菜单、提示框、设置、
终端(
ls --color)、差异视图,以及提交工具窗口中的版本控制颜色。 - 文字与背景至少要达到 WCAG AA 对比度(4.5:1)。内置主题由
src/features/settings/__tests__/contrast.test.ts检查。 - 修改仓库自带的模板时:
pnpm vitest run scripts/theme会对照 tokens.css 校验模板并保证 token 参考是最新的,cargo test -p ide-plugin会通过插件宿主加载模板。
Token 参考
以下是两个基础主题的取值,由src/styles/tokens.css 生成(pnpm gen:theme-docs 会重新生成 plugins/themes.md 中的副本)。
标为 UI 主题 的分组按惯例放在主题文件中,标为 编辑器配色方案 的分组放在配色方案文件中。
共 256 个可设置的 token:UI 主题文件 125 个,编辑器配色方案文件 131 个。