wip: 临时提交
This commit is contained in:
ray
311
docs/theme-system-guide.md
Normal file
311
docs/theme-system-guide.md
Normal file
@@ -0,0 +1,311 @@
|
||||
# 主题系统使用指南
|
||||
|
||||
## 概述
|
||||
|
||||
本项目基于 Wot Design Uni 的 ConfigProvider 组件实现了完整的主题系统，支持：
|
||||
|
||||
- 🌙 暗黑/浅色模式切换
|
||||
- 🎨 12种预设主题色
|
||||
- 🎯 自定义主题色
|
||||
- 💾 主题设置持久化存储
|
||||
- 📱 多平台兼容（H5、小程序）
|
||||
|
||||
## 核心文件
|
||||
|
||||
### 1. useTheme Composable (`src/composables/useTheme.ts`)
|
||||
|
||||
主题管理的核心逻辑，提供：
|
||||
|
||||
```typescript
|
||||
const {
|
||||
theme, // 当前主题模式 'light' | 'dark'
|
||||
themeVars, // ConfigProviderThemeVars 主题变量
|
||||
toggleTheme, // 切换主题模式
|
||||
setThemeColor, // 设置主题色
|
||||
resetTheme, // 重置主题
|
||||
initTheme, // 初始化主题
|
||||
colorColumns, // 预设主题色列表
|
||||
} = useTheme();
|
||||
```
|
||||
|
||||
### 2. 布局文件
|
||||
|
||||
#### Tabbar 布局 (`src/layouts/tabbar.vue`)
|
||||
|
||||
```vue
|
||||
<template>
|
||||
<wd-config-provider
|
||||
:theme="theme"
|
||||
:theme-vars="themeVars"
|
||||
custom-style="min-height: 100vh"
|
||||
:class="{ 'wot-theme-dark': theme === 'dark' }"
|
||||
>
|
||||
<!-- 页面内容 -->
|
||||
</wd-config-provider>
|
||||
</template>
|
||||
```
|
||||
|
||||
#### Default 布局 (`src/layouts/default.vue`)
|
||||
|
||||
```vue
|
||||
<template>
|
||||
<wd-config-provider
|
||||
:theme="theme"
|
||||
:theme-vars="themeVars"
|
||||
custom-style="background-color: #f5f5f5;min-height: 100vh"
|
||||
:class="{ 'wot-theme-dark': theme === 'dark' }"
|
||||
>
|
||||
<!-- 页面内容 -->
|
||||
</wd-config-provider>
|
||||
</template>
|
||||
```
|
||||
|
||||
### 3. 主题设置页面 (`src/pages/mine/settings/theme/index.vue`)
|
||||
|
||||
提供用户界面来：
|
||||
|
||||
- 切换暗黑/浅色模式
|
||||
- 选择预设主题色
|
||||
- 输入自定义主题色
|
||||
- 预览主题效果
|
||||
- 重置主题设置
|
||||
|
||||
## 主题变量
|
||||
|
||||
### 支持的 ConfigProviderThemeVars
|
||||
|
||||
根据 Wot Design Uni 文档，主要使用：
|
||||
|
||||
```typescript
|
||||
interface ConfigProviderThemeVars {
|
||||
colorTheme?: string; // 主题色
|
||||
buttonPrimaryBgColor?: string; // 主按钮背景色
|
||||
buttonPrimaryColor?: string; // 主按钮文字色
|
||||
// ... 更多变量
|
||||
}
|
||||
```
|
||||
|
||||
### 预设主题色
|
||||
|
||||
```typescript
|
||||
const colorColumns = [
|
||||
{ value: "#165DFF", label: "蓝色" },
|
||||
{ value: "#0FC6C2", label: "青绿色" },
|
||||
{ value: "#722ED1", label: "紫色" },
|
||||
{ value: "#F5222D", label: "红色" },
|
||||
{ value: "#FA8C16", label: "橙色" },
|
||||
{ value: "#FADB14", label: "黄色" },
|
||||
{ value: "#52C41A", label: "绿色" },
|
||||
{ value: "#EB2F96", label: "粉色" },
|
||||
{ value: "#13C2C2", label: "青色" },
|
||||
{ value: "#1890FF", label: "天蓝色" },
|
||||
{ value: "#CD5C5C", label: "经典红" },
|
||||
{ value: "#228B22", label: "自然绿" },
|
||||
];
|
||||
```
|
||||
|
||||
## 暗黑模式实现
|
||||
|
||||
### 1. ConfigProvider 主题切换
|
||||
|
||||
```vue
|
||||
<wd-config-provider :theme="theme">
|
||||
<!-- theme 为 'dark' 时自动应用暗黑模式 -->
|
||||
</wd-config-provider>
|
||||
```
|
||||
|
||||
### 2. 全局样式适配
|
||||
|
||||
在 `src/uni.scss` 中定义：
|
||||
|
||||
```scss
|
||||
.wot-theme-dark {
|
||||
background-color: #1a1a1a !important;
|
||||
color: #f5f5f5 !important;
|
||||
|
||||
/* H5 环境 body 样式 */
|
||||
body {
|
||||
background-color: #1a1a1a !important;
|
||||
color: #f5f5f5 !important;
|
||||
}
|
||||
|
||||
/* 其他组件暗黑模式适配 */
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 动态 Body 样式
|
||||
|
||||
在 `useTheme` 中自动处理：
|
||||
|
||||
```typescript
|
||||
const applyDarkModeBodyStyle = (isDark: boolean) => {
|
||||
// #ifdef H5
|
||||
if (typeof document !== "undefined") {
|
||||
const body = document.body;
|
||||
if (isDark) {
|
||||
body.style.backgroundColor = "#1a1a1a";
|
||||
body.style.color = "#f5f5f5";
|
||||
body.classList.add("wot-theme-dark");
|
||||
} else {
|
||||
body.style.backgroundColor = "#f8f8f8";
|
||||
body.style.color = "#333";
|
||||
body.classList.remove("wot-theme-dark");
|
||||
}
|
||||
}
|
||||
// #endif
|
||||
};
|
||||
```
|
||||
|
||||
## 持久化存储
|
||||
|
||||
主题设置自动保存到本地存储：
|
||||
|
||||
```typescript
|
||||
// 存储键名
|
||||
const THEME_STORAGE_KEY = "app_theme_mode";
|
||||
const THEME_COLOR_STORAGE_KEY = "app_theme_color";
|
||||
|
||||
// 自动监听变化并保存
|
||||
watch(
|
||||
theme,
|
||||
(newTheme) => {
|
||||
saveThemeToStorage(newTheme);
|
||||
applyDarkModeBodyStyle(newTheme === "dark");
|
||||
},
|
||||
{ immediate: true }
|
||||
);
|
||||
```
|
||||
|
||||
## 使用示例
|
||||
|
||||
### 在页面中使用主题
|
||||
|
||||
```vue
|
||||
<template>
|
||||
<view>
|
||||
<wd-button type="primary">主题色按钮</wd-button>
|
||||
<text :style="{ color: themeVars.colorTheme }">主题色文本</text>
|
||||
</view>
|
||||
</template>
|
||||
|
||||
<script setup>
|
||||
import { useTheme } from "@/composables/useTheme";
|
||||
|
||||
const { theme, themeVars, toggleTheme, setThemeColor } = useTheme();
|
||||
|
||||
// 切换主题模式
|
||||
const handleToggleTheme = () => {
|
||||
toggleTheme();
|
||||
};
|
||||
|
||||
// 设置主题色
|
||||
const handleSetColor = (color: string) => {
|
||||
setThemeColor(color);
|
||||
};
|
||||
</script>
|
||||
```
|
||||
|
||||
### 在组件中响应主题变化
|
||||
|
||||
```vue
|
||||
<template>
|
||||
<view :class="{ 'dark-mode': isDark }">
|
||||
<!-- 组件内容 -->
|
||||
</view>
|
||||
</template>
|
||||
|
||||
<script setup>
|
||||
import { computed } from "vue";
|
||||
import { useTheme } from "@/composables/useTheme";
|
||||
|
||||
const { theme } = useTheme();
|
||||
|
||||
const isDark = computed(() => theme.value === "dark");
|
||||
</script>
|
||||
|
||||
<style>
|
||||
.dark-mode {
|
||||
background-color: #2a2a2a;
|
||||
color: #f5f5f5;
|
||||
}
|
||||
</style>
|
||||
```
|
||||
|
||||
## 最佳实践
|
||||
|
||||
### 1. 组件开发
|
||||
|
||||
- 使用 Wot Design Uni 组件时，主题色会自动应用
|
||||
- 自定义组件需要手动适配暗黑模式
|
||||
- 使用 `:class="{ 'wot-theme-dark': theme === 'dark' }"` 来应用暗黑模式样式
|
||||
|
||||
### 2. 样式编写
|
||||
|
||||
```scss
|
||||
.my-component {
|
||||
background-color: #fff;
|
||||
color: #333;
|
||||
|
||||
// 暗黑模式适配
|
||||
.wot-theme-dark & {
|
||||
background-color: #2a2a2a;
|
||||
color: #f5f5f5;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 主题色使用
|
||||
|
||||
```vue
|
||||
<template>
|
||||
<!-- 直接使用主题色 -->
|
||||
<view :style="{ borderColor: themeVars.colorTheme }">
|
||||
<!-- 内容 -->
|
||||
</view>
|
||||
</template>
|
||||
```
|
||||
|
||||
## 注意事项
|
||||
|
||||
1. **ConfigProvider 包裹**：确保页面被 ConfigProvider 包裹才能应用主题
|
||||
2. **样式优先级**：暗黑模式样式需要足够的优先级，必要时使用 `!important`
|
||||
3. **平台兼容**：小程序和 H5 的样式处理略有不同，使用条件编译处理
|
||||
4. **性能考虑**：主题切换时避免频繁的 DOM 操作
|
||||
|
||||
## 扩展功能
|
||||
|
||||
### 添加新的主题色
|
||||
|
||||
在 `colorColumns` 中添加新的颜色：
|
||||
|
||||
```typescript
|
||||
export const colorColumns = [
|
||||
// ... 现有颜色
|
||||
{ value: "#FF6B6B", label: "珊瑚红" },
|
||||
{ value: "#4ECDC4", label: "薄荷绿" },
|
||||
];
|
||||
```
|
||||
|
||||
### 添加更多主题变量
|
||||
|
||||
```typescript
|
||||
const themeVars = ref<ConfigProviderThemeVars>({
|
||||
colorTheme: getStoredThemeColor(),
|
||||
buttonPrimaryBgColor: getStoredThemeColor(),
|
||||
// 添加更多变量
|
||||
});
|
||||
```
|
||||
|
||||
### 自定义暗黑模式样式
|
||||
|
||||
在 `uni.scss` 中添加更多组件的暗黑模式适配：
|
||||
|
||||
```scss
|
||||
.wot-theme-dark {
|
||||
// 新组件的暗黑模式样式
|
||||
.my-custom-component {
|
||||
background-color: #2a2a2a;
|
||||
color: #f5f5f5;
|
||||
}
|
||||
}
|
||||
```
|
||||
Reference in New Issue
Block a user