升级指南

0.4.1 版本开始，uView Pro 引入了多主题系统、暗黑模式和改进的主题配置工具。本指南帮助你从 0.3.x 升级到 0.4.x。

概述

功能	0.3.x	0.4.x
主题配置	单主题，手动编辑变量	多主题，可视化智能配置工具
暗黑模式	不支持	原生支持，自动/手动切换
色值生成	手动管理	智能生成暗黑色值
导出格式	SCSS + TS 变量	SCSS + TS 数组
配置工具	旧版配置工具	新版配置工具

核心变更

1. 主题配置方式

0.3.x：直接修改 SCSS 变量文件

// old-theme.scss
$u-type-primary: #2979ff;
$u-type-success: #19be6b;
// ... 手动配置每一个变量

0.4.x：使用【主题配置工具】生成主题文件

• 打开工具页面，填写颜色和元信息
• 支持可视化色值选择，即时预览效果
• 可配置单个或多个主题
• 导出为 uview-pro.theme.ts（推荐）或 SCSS

2. 主题文件结构

0.3.x：

$u-type-primary: #2979ff;
$u-type-primary-dark: #2b85e4;
// 所有色值都是静态定义

0.4.x：

// src/uview-pro.theme.ts
export default [
  {
    name: 'default',
    label: '默认主题',
    description: '清爽蓝色主题',
    color: {
      primary: '#2979ff',
      success: '#19be6b',
      error: '#fa3534',
      warning: '#ff9900',
      info: '#909399',
      mainColor: '#303133',
      contentColor: '#606266',
      tipsColor: '#909399',
      lightColor: '#c0c4cc',
      borderColor: '#e4e7ed',
      dividerColor: '#e4e7ed',
      bgColor: '#f3f4f6',
      bgWhite: '#ffffff',
      bgGrayLight: '#f5f7fa',
      bgGrayDark: '#2f343c',
      bgBlack: '#000000',
      maskColor: 'rgba(0, 0, 0, 0.4)',
      shadowColor: 'rgba(0, 0, 0, 0.1)'
    },
    darkColor: {
      // 暗黑色值（可选，未填的会由系统智能生成）
      primary: '#5b9ff5'
      // ... 其他可选的暗黑色覆盖
    }
  },
  // 可以包含多个主题...
];

3. 注册方式变更

0.3.x：在 SCSS 中直接导入变量文件

@import 'path/to/old-theme.scss';

0.4.x：

1. 在 unis.scss 中导入基础主题系统

   @import 'uview-pro/theme.scss';

2. 在 main.ts 中注册主题

   import { createSSRApp } from 'vue';
   import App from './App.vue';
   import theme from '@/uview-pro.theme';  // 导入自定义主题
   import uViewPro from '@/uni_modules/uview-pro';
   
   export function createApp() {
     const app = createSSRApp(App);
     app.use(uViewPro, { theme });  // 传入自定义主题列表
     return { app };
   }

4. 暗黑模式支持

0.3.x：无原生支持

0.4.x：

• 自动跟随系统：设置 darkMode: 'auto'
• 手动切换：setDarkMode('light' | 'dark' | 'auto')
• 快速切换：toggleDarkMode() 在 light/dark 间切换
• 检查状态：isInDarkMode() 返回布尔值

5. 智能暗黑色生成

0.4.x 的核心创新：

• 你只需提供亮色色板 (color)，系统自动为缺失的 darkColor 生成合理的暗色值
• 如果你需要手动调整某个暗色，只在 darkColor 中填写该项，其余仍由系统生成
• 生成算法基于色值混合，确保暗黑模式下的可读性和美观性

例如：

{
  color: {
    primary: '#2979ff',
    bgColor: '#f3f4f6',
    // ... 其他亮色
  },
  darkColor: {
    // 留空，系统自动生成以下内容：
    // primary: '#5b9ff5'（基于 #2979ff 混合生成的暗色）
    // bgColor: '#1a1a1a'（基于 #f3f4f6 反转生成）
    
    // 如果你想手动覆盖某个暗色：
    primary: '#6ba1ff',  // 自定义的暗色 primary
    // bgColor 仍会由系统生成
  }
}

升级步骤

第 1 步：生成新主题文件

1. 访问【主题配置工具】
2. 配置你的主题色和其他色值（可参考 0.3.x 的旧值作为起点）
3. 打开"启用暗黑色值"并检查生成的暗色是否满意（可逐项调整）
4. 点击"下载主题文件(TS 格式导出)"，得到 uview-pro.theme.ts
5. 将文件复制到项目的 src/uview-pro.theme.ts

第 2 步：更新主题注册代码

编辑 main.ts 或你的应用入口文件：

// Before (0.3.x)
import uViewPro from '@/uni_modules/uview-pro';
app.use(uViewPro);

// After (0.4.x)
import theme from '@/uview-pro.theme';
import uViewPro from '@/uni_modules/uview-pro';
app.use(uViewPro, { theme });

第 3 步：更新 SCSS 导入

在 unis.scss 中：

// Before (0.3.x)
// @import 'path/to/your-old-theme.scss';

// After (0.4.x)
@import 'uview-pro/theme.scss';  // 导入系统主题基础
// 自定义的色值会通过 main.ts 的 theme 选项注入，无需再导入

第 4 步：配置多主题/暗黑模式支持

如果你的项目需要暗黑模式，在全局根组件（如 App.vue）中包裹 u-config-provider：

<script setup lang="ts">
import { useTheme } from 'uview-pro';
import { computed } from 'vue';

const { darkMode, themes, currentTheme } = useTheme();

const themeName = computed(() => currentTheme.value?.name);
</script>

<template>
  <u-config-provider :dark-mode="darkMode" :current-theme="themeName" :themes="themes">
    <!-- 你的应用内容 -->
    <KuRootView />
  </u-config-provider>
</template>

样式使用变更

SCSS/CSS 中使用

变量命名规则保持一致（兼容 0.3.x）：

.title {
  color: $u-type-primary;  // 主题色
}
.card {
  background-color: $u-bg-white;  // 背景色
  border-color: $u-border-color;  // 边框色
}

Vue 模板或 JS 中使用

0.3.x（无原生支持）：

// 需要手动管理颜色值
const primaryColor = '#2979ff';

0.4.x（推荐方式）：

import { $u } from 'uview-pro';

// 方式 1：直接取值
const color = $u.color.primary;

// 方式 2：使用 useTheme
import { useTheme } from 'uview-pro';
const { cssVars } = useTheme();
// cssVars 包含所有当前主题的 CSS 变量，会自动响应主题/暗黑切换

行内样式示例：

<template>
  <!-- 使用 CSS 变量（推荐，自动响应切换） -->
  <view :style="{ color: 'var(--u-type-primary)' }">文本</view>
  
  <!-- 使用 $u.color（需要监听响应） -->
  <view :style="{ color: $u.color.primary }">文本</view>
</template>

多主题管理

0.4.x 新增多主题支持：

// src/uview-pro.theme.ts
export default [
  {
    name: 'blue',
    label: '蓝色主题',
    color: { primary: '#2979ff', /* ... */ },
    darkColor: { /* ... */ }
  },
  {
    name: 'purple',
    label: '紫色主题',
    color: { primary: '#7c3aed', /* ... */ },
    darkColor: { /* ... */ }
  },
  // 更多主题...
];

在应用中切换主题：

import { useTheme } from 'uview-pro';
const { setTheme, themes } = useTheme();

// 显示所有可用主题并支持切换
themes.value.forEach(t => {
  console.log(t.name, t.label);
});

// 切换到指定主题
setTheme('purple');

常见问题

Q: 0.3.x 的 SCSS 文件能继续用吗？
A: 不建议混用。建议完全迁移到新的主题系统，使用【主题配置工具】生成统一的 uview-pro.theme.ts。 B: 0.3.x 的 SCSS 文件仍然可用，但必须要迁移到新的主题系统。

Q: 我只想用亮色，不需要暗黑模式？
A: 可以。只需提供 color 字段，不填 darkColor 即可；或设置 darkMode: 'light' 固定禁用暗黑。

Q: 如何在运行时动态加载主题？
A: 调用 useTheme().initTheme(customThemeList) 在运行时初始化或更新主题列表。

Q: 暗黑色是如何生成的？
A: 系统采用色值混合算法，将亮色与预定义的暗色基准混合（ratio=0.6），生成视觉层级合理的暗色。你可以在配置工具中手动调整任何暗色值。

Q: CSS 变量名有变化吗？
A: 无。仍使用 $u-type-primary、$u-bg-color 等，保持向后兼容。新增了 CSS 变量形式（--u-type-primary 等）供 JS 读取。

总结

步骤	说明
1️⃣ 使用工具	访问主题配置工具，配置新主题并导出 uview-pro.theme.ts
2️⃣ 更新注册	修改 main.ts，传入自定义主题
3️⃣ 更新导入	在 unis.scss 导入 uview-pro/theme.scss
4️⃣ 可选配置	若需要暗黑模式，在主题生成工具中启用暗黑色值
5️⃣ 测试验证	确保色值正确应用，暗黑切换正常工作

升级完成后，你将获得：

• ✅ 更灵活的多主题支持
• ✅ 开箱即用的暗黑模式
• ✅ 自动化的色值生成和管理
• ✅ 可视化的主题配置体验

有任何问题，请参考【多主题与暗黑模式完整指南】。