pi-web-theme-studio
v1.0.0
Published
Recolor PI WEB: curated theme presets plus a visual --pi-* color customizer.
Readme
pi-web-theme-studio
PI WEB 主题 / 配色自定义插件。两种方式改配色：
- 精选预设：贡献 7 套完整配色（Tokyo Night / Nord / Catppuccin Mocha / Solarized Light / One Dark / Dracula / Gruvbox Dark），直接出现在 PI WEB 自带的主题选择器里，并支持跟随系统明/暗。
- Theme Studio 面板：可视化调整每一个
--pi-*颜色变量，实时预览、存为预设、导出 CSS、一键重置。
⚠️ 兼容性说明：本插件依赖 pi-web 源码中已存在的
themes/themePairs插件贡献类型（见src/client/src/plugins/types.ts的ThemeContribution/ThemePairContribution）以及那套--pi-*设计变量（src/client/src/theme.ts的THEME_TOKENS，共 35 个）。这是 pi-web 渲染 UI 时实际消费的变量，组件样式里都是var(--pi-*)，没有硬编码颜色。若你的 pi-web 版本较旧、没有themes贡献类型，预设不会出现在选择器里，但 Theme Studio 面板的自定义覆盖仍有效（见下文原理）。
工作原理
- 预设（themes 贡献）：宿主在切换主题时，会把每套主题的全部 35 个
--pi-*token 以内联 style 写到<html>（applyPiWebTheme）。贡献themes即把我们的调色板交给宿主，进入原生主题选择器，持久且能跟随系统。 - 自定义覆盖（Theme Studio）：面板把用户调整的颜色注入一段
<style id="pi-theme-studio-override">，内容为:root { --pi-*: <值> !important }，挂到document.head。因为!important的样式表规则优先于<html>上的非!important内联值，所以它能盖过任何主题，并且在你切换主题 / 系统明暗变化 / 热重载时不会被冲掉——相当于一层持久的自定义配色。 - 持久化：覆盖写入
localStorage（pi-theme-studio:override），插件加载时自动恢复；预设列表存于pi-theme-studio:presets。
功能
- 顶部按钮：
应用并保存（提交覆盖到本地）、保存为预设、导出 CSS（复制:root{...}到剪贴板）、重置全部（清覆盖，回到当前主题）。 - 精选配色区：一键应用 7 套预设。
- 实时预览区：accent / success / warning / danger / purple / surface 色板，改色即时反映。
- 我的预设区：保存 / 加载 / 删除自定义预设。
- 调色板区：按「背景与表面 / 文本 / 边框 / 品牌色 / 表面与状态 / 叠加与阴影」分组，共 35 个
--pi-*变量，每个含「拾色器 + CSS 值文本框（支持 8 位 hex / rgba）+ 单项重置」。 - 命令面板：
Open Theme Studio/Reset Custom Theme/Copy Theme CSS。
安装
推荐（发布版）：在 PI WEB 的 Settings → Pi packages 填入 github:samecorner/pi-web-theme-studio，或命令行 pi install github:samecorner/pi-web-theme-studio。
也可以整目录手动放到插件根下：
~/.pi-web/plugins/theme-studio/~ 即用户主目录（Windows：C:\Users\<你的用户名>\.pi-web\plugins\theme-studio）。
复制安装
# Windows (PowerShell)
$src = "C:\Users\yangj\WorkBuddy\2026-08-13-10-48-04\pi-web-theme-studio"
$dst = "$env:USERPROFILE\.pi-web\plugins\theme-studio"
New-Item -ItemType Directory -Force -Path $dst | Out-Null
Copy-Item -Recurse -Force "$src\*" $dst# macOS / Linux
cp -R ./pi-web-theme-studio ~/.pi-web/plugins/theme-studio启用并验证
- 重启 sessiond 或刷新 pi-web 页面。
- 验证 manifest：
curl http://127.0.0.1:8504/pi-web-plugins/manifest.json应含"id":"theme-studio"。 - 打开 PI WEB：
- 侧栏出现
Theme面板（命令面板搜Theme Studio）。 - 设置里的主题选择器应多出 Tokyo Night / Nord / Catppuccin Mocha / Solarized Light，以及一对「Theme Studio」（跟随系统）。
- 侧栏出现
调试
- 预设没出现在主题选择器：多为 pi-web 版本不支持
themes贡献类型。不影响 Theme Studio 面板的自定义覆盖（走!important注入，不依赖该类型）。可在 DevTools 控制台确认document.getElementById('pi-theme-studio-override')是否存在来排查覆盖是否注入。 - 改了色但没生效：确认覆盖
<style>已注入；!important会盖过内联主题值，但若别的插件/样式也用!important同名变量且后加载，则后者优先。 - 切换系统明暗后自定义色没了：不会——
!important覆盖在切主题时仍占优。若你清空了覆盖，则回归当前选中主题。 - 想还原：面板
重置全部，或命令Reset Custom Theme。
文件结构
pi-web-theme-studio/
├── package.json # 插件清单（piWeb.plugins[].id = "theme-studio"）
├── pi-web-theme.js # 入口：activate() 贡献 themes / themePairs / workspacePanels / actions
├── theme-presets.js # 完整 37 token 基色 + makeTheme + 7 套精选预设 + 分组定义
├── theme-studio.js # <pi-web-theme-studio> 自定义元素：拾色器 / 预览 / 预设 / 导入导出
├── theme-studio-styles.js # 面板样式（复用 --pi-* 主题变量）
├── theme-runtime.js # 覆盖注入（!important）、localStorage 持久化、剪贴板
└── README.md已知限制
- 依赖 pi-web 的
--pi-*变量体系；若某组件未来改用硬编码颜色，对应处不受主题影响。 - 预设仅对支持
themes贡献类型的 pi-web 版本进入原生选择器。 - 自定义覆盖用
!important，如遇同样!important的其它来源竞争，后加载者胜。 <input type=color>仅支持 6 位 hex；含透明通道（8 位 hex / rgba）的颜色请用旁边的文本框编辑。
License
MIT