ExUI

Appearance

🔄 主题迁移指南 ​

概述 ​

ExUI v1.0.0 对三个主题（Neon Pink、Dark、High Contrast）进行了重大配色升级，以提升主题区分度和用户体验。本指南将帮助你平滑迁移到新主题。

🎯 变更摘要 ​

Neon Pink 主题变更 ​

变更项旧值新值影响
主色#ff3bd1#ff007f更鲜艳的玫瑰粉
次色#29abe2#00f0ff改为霓虹青
强调色#a86bff#b366ff深紫罗兰
背景#0f0b14#1a0a1e更深的紫色调
发光中等更强视觉冲击力增强

设计理念变化: 从"蓝粉互换"改为"粉青紫三色渐变"

Dark 主题变更 ​

变更项旧值新值影响
主色#29abe2#5b9bd5降低饱和度
次色#a86bff#7a8fa3改为深灰蓝
强调色#ff3bd1#70c0e8改为冰蓝
背景#000000#0d1117GitHub Dark 风格
发光无微弱增加细微发光

设计理念变化: 从"纯黑无发光"改为"GitHub Dark 风格冷灰蓝"

High Contrast 主题变更 ​

变更项旧值新值影响
主色#00d4ff#00ff41改为矩阵绿
次色#ff00ff#00ffff改为电子蓝
强调色#ffff00#ffff00保持不变
背景#000000#000000保持纯黑
边框#ffffff#00ff41改为矩阵绿
文字#ffffff#e6ffe6绿色调白

设计理念变化: 从"纯白高对比"改为"矩阵绿黑客风格"

🚀 迁移步骤 ​

步骤 1: 更新依赖 ​

bash
npm update vue-ex-ui
# 或
pnpm update vue-ex-ui

步骤 2: 检查自定义样式 ​

如果你的项目中有覆盖主题变量的代码，需要检查以下变量：

Neon Pink 主题 ​

scss
// ❌ 旧代码可能失效
[data-theme='neon-pink'] {
  --ex-color-primary: #ff3bd1;  // 已改为 #ff007f
  --ex-color-secondary: #29abe2; // 已改为 #00f0ff
}

// ✅ 新代码
[data-theme='neon-pink'] {
  --ex-color-primary: #ff007f;   // 玫瑰粉
  --ex-color-secondary: #00f0ff; // 霓虹青
}

Dark 主题 ​

scss
// ❌ 旧代码可能失效
[data-theme='dark'] {
  --ex-color-bg-primary: #000000;  // 已改为 #0d1117
  --ex-color-primary: #29abe2;     // 已改为 #5b9bd5
}

// ✅ 新代码
[data-theme='dark'] {
  --ex-color-bg-primary: #0d1117;  // GitHub Dark
  --ex-color-primary: #5b9bd5;     // 冷蓝
}

High Contrast 主题 ​

scss
// ❌ 旧代码可能失效
[data-theme='high-contrast'] {
  --ex-color-primary: #00d4ff;     // 已改为 #00ff41
  --ex-color-border-primary: #ffffff; // 已改为 #00ff41
}

// ✅ 新代码
[data-theme='high-contrast'] {
  --ex-color-primary: #00ff41;     // 矩阵绿
  --ex-color-border-primary: #00ff41; // 矩阵绿边框
}

步骤 3: 测试所有主题 ​

typescript
import { setTheme } from 'vue-ex-ui';

// 测试所有主题
const themes = ['neon-blue', 'neon-pink', 'dark', 'high-contrast'];
themes.forEach(theme => {
  setTheme(theme);
  // 检查 UI 显示是否正常
});

步骤 4: 更新文档和截图 ​

如果你的文档中有主题截图或颜色说明，请更新它们。

⚠️ 破坏性变更 ​

1. Neon Pink 主色变更 ​

影响: 如果你硬编码了 #ff3bd1，现在会显示为旧的粉色而非新的玫瑰粉。

解决方案:

scss
// ❌ 不要硬编码颜色
.my-button {
  background: #ff3bd1;
}

// ✅ 使用 CSS 变量
.my-button {
  background: var(--ex-color-primary);
}

2. Dark 主题背景色变更 ​

影响: 纯黑背景改为深灰蓝，可能影响截图对比或设计稿。

解决方案:

scss
// 如果你确实需要纯黑背景
[data-theme='dark'] {
  --ex-color-bg-primary: #000000 !important;
}

3. High Contrast 边框颜色变更 ​

影响: 白色边框改为矩阵绿，视觉风格完全不同。

解决方案:

scss
// 如果你需要保持白色边框
[data-theme='high-contrast'] {
  --ex-color-border-primary: #ffffff !important;
  --ex-color-border-secondary: #cccccc !important;
}

🔍 兼容性检查清单 ​

视觉检查 ​

  • [ ] 所有按钮在新主题下显示正常
  • [ ] 表单输入框边框颜色正确
  • [ ] 卡片组件背景和边框协调
  • [ ] 文字在所有背景上可读
  • [ ] 图标颜色与主题匹配
  • [ ] 加载动画颜色正确
  • [ ] 通知/消息组件颜色正确

功能检查 ​

  • [ ] 主题切换功能正常
  • [ ] 主题持久化正常
  • [ ] 系统主题跟随正常
  • [ ] 无障碍功能正常
  • [ ] 打印样式正常

性能检查 ​

  • [ ] 主题切换无卡顿
  • [ ] 首次加载速度正常
  • [ ] 内存占用正常

🎨 自定义主题适配 ​

如果你创建了自定义主题，建议参考新的设计理念：

旧的设计模式 ​

scss
// 简单的颜色互换
[data-theme='my-theme'] {
  --ex-color-primary: #color1;
  --ex-color-secondary: #color2;
}

新的设计模式 ​

scss
// 完整的色彩体系
[data-theme='my-theme'] {
  // 1. 定义主色系（有明确的设计理念）
  --ex-color-primary: #your-brand-color;
  --ex-color-secondary: #complementary-color;
  --ex-color-accent: #highlight-color;
  
  // 2. 定义背景色系（与主色协调）
  --ex-color-bg-primary: #dark-bg;
  --ex-color-bg-secondary: #slightly-lighter;
  --ex-color-bg-tertiary: #even-lighter;
  
  // 3. 定义文本色系（确保对比度）
  --ex-color-text-primary: #high-contrast-text;
  --ex-color-text-secondary: #medium-contrast-text;
  
  // 4. 定义边框色系（与背景协调）
  --ex-color-border-primary: #subtle-border;
  
  // 5. 定义渐变（增强视觉效果）
  --ex-gradient-primary: linear-gradient(...);
  
  // 6. 定义阴影（符合主题风格）
  --ex-shadow-neon-md: 0 0 10px rgba(...);
}

📚 参考资源 ​

新主题设计文档 ​

设计工具 ​

🐛 常见问题 ​

Q1: 为什么我的自定义颜色不生效？ ​

A: 检查 CSS 优先级，可能需要添加 !important 或提高选择器权重。

scss
// 提高优先级
[data-theme='neon-pink'].my-app {
  --ex-color-primary: #your-color;
}

Q2: 新主题太亮/太暗怎么办？ ​

A: 可以调整背景色的透明度：

scss
[data-theme='neon-pink'] {
  --ex-color-bg-primary-alpha-90: rgba(26, 10, 30, 0.95);
}

Q3: 如何恢复旧主题？ ​

A: 创建一个自定义主题使用旧的颜色值：

scss
[data-theme='neon-pink-legacy'] {
  --ex-color-primary: #ff3bd1;
  --ex-color-secondary: #29abe2;
  --ex-color-bg-primary: #0f0b14;
  // ... 其他旧值
}

Q4: 主题切换时有闪烁怎么办？ ​

A: 确保在 <head> 中内联关键 CSS：

html
<head>
  <style>
    :root {
      --ex-color-bg-primary: #0b0f14;
      --ex-color-text-primary: #e6f0ff;
    }
  </style>
</head>

Q5: 如何禁用主题过渡动画？ ​

A: 设置 ConfigProvider 的 animation 属性：

vue
<ex-config-provider :animation="false">
  <your-app />
</ex-config-provider>

💡 最佳实践 ​

1. 始终使用 CSS 变量 ​

scss
// ✅ 好
.my-component {
  color: var(--ex-color-primary);
}

// ❌ 差
.my-component {
  color: #29abe2;
}

2. 测试所有主题 ​

typescript
// 自动化测试
describe('Theme Compatibility', () => {
  const themes = ['neon-blue', 'neon-pink', 'dark', 'high-contrast'];
  
  themes.forEach(theme => {
    it(`should render correctly in ${theme} theme`, () => {
      setTheme(theme);
      // 测试渲染
    });
  });
});

3. 提供主题预览 ​

vue
<template>
  <div class="theme-preview">
    <button @click="setTheme('neon-blue')">Neon Blue</button>
    <button @click="setTheme('neon-pink')">Neon Pink</button>
    <button @click="setTheme('dark')">Dark</button>
    <button @click="setTheme('high-contrast')">High Contrast</button>
  </div>
</template>

4. 记住用户选择 ​

typescript
import { usePersistedTheme } from 'vue-ex-ui';

// 自动保存和恢复主题
const { theme, setTheme } = usePersistedTheme();

📞 获取帮助 ​

如果你在迁移过程中遇到问题：

  1. 查看 主题设计指南
  2. 查看 色彩参考手册
  3. 提交 GitHub Issue
  4. 加入社区讨论

📝 更新日志 ​

v1.0.0 (2025-01-23) ​

  • 🎨 重新设计 Neon Pink 主题配色
  • 🌑 重新设计 Dark 主题配色
  • 🟢 重新设计 High Contrast 主题配色
  • 📊 大幅提升主题区分度
  • ♿ 改善无障碍支持
  • 📚 完善主题文档

维护者: ExUI Team
最后更新: 2025-01-23