acf592ab2c
- 添加模板管理故障排除清单，以帮助用户解决模板管理中遇到的常见问题。 - 统一服务注入逻辑，移除不必要的props定义，增强错误处理机制。 - 优化模板管理，统一服务注入与存储键管理。 - 更新 `TemplateSelect.vue`，移除 `services` prop，改用 `inject` 注入服务。 - 整合 `useTemplateManager`，统一模板选择保存逻辑及存储键管理。 - 新增 `storage-keys.ts`，集中管理存储键常量，避免重复定义，便于维护与遍历。 - 更新相关组件以适配新的模板管理方式，确保模板选择状态正确保存和恢复。 - 修正了模板类型错误的问题，确保在管理界面切换分类后添加的模板类型与当前显示的分类一致。 - 修复了模板管理器打开位置错误的问题，确保从不同入口打开模板管理器时，定位到正确的分类。 - 优化了模板保存和导入逻辑，增加了错误处理和提示。 - 确保所有异步模板操作都使用了 `await` 关键字，避免潜在的时序问题。 - 移除了 `usePromptOptimizer` 中 `selectedOptimizationMode` 的默认值，强制传入该参数。 - 优化了 `TemplateSelect` 组件中 `optimizationMode` prop 的处理，设为 `required`。
5.1 KiB
主题系统开发经验
📋 概述
多主题功能开发过程中的核心经验，重点关注与第三方库样式冲突的处理方案和主题系统的最佳实践。
🎨 UI 主题系统与第三方库样式冲突处理
问题场景
在开发多主题功能（特别是紫色、绿色等自定义深色主题）时，发现集成了 Tailwind Typography (prose) 插件的 Markdown 渲染组件，其背景和文本颜色无法正确应用主题色，而是被覆盖为不协调的亮色样式（如白色背景）。
根本原因分析
问题的核心在于项目自定义的、基于 data-theme 属性的颜色主题系统，与 Tailwind Typography (prose) 插件预设的、自成体系的颜色方案发生了直接冲突。
-
prose的强主张:@tailwindcss/typography插件不仅仅是一个布局工具，它会为 HTML 内容注入一套完整的视觉方案，其中包含了固定的颜色、字体、背景等样式。 -
默认亮色偏好:
prose的默认配置（如prose-stone）是为亮色背景设计的，它会强制设定深色的文本颜色。 -
dark:模式的局限性:prose的颜色反转机制 (dark:prose-invert) 强依赖于<html>标签上的dark类。我们自定义的深色主题（如data-theme="purple"）虽然视觉上是深色的，但并未触发 Tailwind 的dark模式，因此prose依然应用其默认的亮色样式，导致了颜色覆盖。
解决方案与最佳实践
面对这种强样式主张的第三方库，必须采取彻底隔离的策略，不能试图"混合"使用。
1. 禁止部分应用
实践证明，试图通过 @apply prose-sm 等方式只"借用" prose 的布局功能是行不通的。这依然会引入我们不希望的颜色样式，导致不可预测的覆盖问题。
2. 手动重建布局
最稳健的解决方案是，在需要应用自定义主题的组件中，完全移除 @apply prose 或其任何变体。然后，参考 prose 的文档或默认样式，手动为各个 Markdown 元素 (h1, p, ul 等) 添加纯粹的、不包含颜色的布局和间距样式。
3. 控制权归还
通过手动重建布局，我们将样式的控制权完全收归到自己的主题系统中。这样，我们在各个主题下为元素定义的颜色、背景、边框等样式才能不受干扰地、正确地应用。
示例 - 手动重建的 Markdown 布局
/* 在全局 theme.css 中定义，不属于任何特定主题 */
.theme-markdown-content {
@apply max-w-none;
}
.theme-markdown-content > :first-child { @apply mt-0; }
.theme-markdown-content > :last-child { @apply mb-0; }
.theme-markdown-content h1 { @apply text-2xl font-bold my-4; }
.theme-markdown-content h2 { @apply text-xl font-semibold my-3; }
.theme-markdown-content p { @apply my-3 leading-relaxed; }
.theme-markdown-content ul,
.theme-markdown-content ol { @apply my-3 pl-6 space-y-2; }
.theme-markdown-content pre { @apply my-4 p-4 rounded-lg text-sm; }
/* ... etc ... */
通过这种方式，我们既保留了优美的排版，又确保了自定义主题的颜色能够正确渲染。
🎯 主题系统设计原则
1. 基于 CSS 变量的主题系统
/* 主题定义 */
[data-theme="purple"] {
--theme-bg: #1a1625;
--theme-text: #e2e8f0;
--theme-primary: #8b5cf6;
/* ... */
}
[data-theme="green"] {
--theme-bg: #0f1419;
--theme-text: #e2e8f0;
--theme-primary: #10b981;
/* ... */
}
2. 语义化的 CSS 类
/* 使用语义化类名，而不是直接使用颜色值 */
.theme-bg { background-color: var(--theme-bg); }
.theme-text { color: var(--theme-text); }
.theme-primary { color: var(--theme-primary); }
3. 第三方库隔离策略
- 完全隔离: 对于有强样式主张的库，完全避免使用
- 手动重建: 参考第三方库的布局，手动实现样式
- 控制权保留: 确保主题系统拥有最终的样式控制权
🔧 实施经验
成功案例
- Markdown 渲染: 完全移除
prose插件，手动实现排版样式 - 代码高亮: 使用支持主题切换的语法高亮库
- 图标系统: 使用 SVG 图标，通过 CSS 变量控制颜色
避免的陷阱
- 部分应用第三方样式: 试图只使用布局而忽略颜色
- 依赖
dark:模式: 自定义主题不应依赖 Tailwind 的 dark 模式 - 样式优先级冲突: 确保主题样式有足够的优先级
💡 核心经验总结
- 彻底隔离原则: 对于有强样式主张的第三方库，必须采取彻底隔离策略
- 控制权归还: 通过手动重建，将样式控制权完全收归到自己的主题系统
- 语义化设计: 使用语义化的 CSS 类和变量，提高可维护性
- 测试覆盖: 每个主题都需要全面测试，确保样式正确应用
- 文档记录: 详细记录第三方库的处理方案，避免重复踩坑
🔗 相关文档
文档类型: 经验总结
适用范围: 主题系统开发
最后更新: 2025-07-01