mirror of
https://github.com/fastapiadmin/FastapiAdmin.git
synced 2026-10-03 00:41:15 +00:00
403 lines
9.9 KiB
Markdown
403 lines
9.9 KiB
Markdown
---
|
||
iframeFormatter: pages/index/index
|
||
---
|
||
|
||
# 暗黑模式
|
||
|
||
## 什么是暗黑模式
|
||
|
||
暗黑模式（Dark Mode），也被称为夜间模式或深色模式，是一种使用深色背景和浅色文字的界面显示模式。
|
||
|
||
### 主要特点
|
||
|
||
- **护眼体验**: 在光线较暗的环境下减少眼部疲劳
|
||
- **节省电量**: 在 OLED 屏幕设备上能够显著节省电池消耗
|
||
- **视觉美观**: 提供现代化的视觉体验和专业感
|
||
|
||
## 使用指南
|
||
|
||
本章节将介绍在 uni-app 项目中实现h5和微信小程序的暗黑模式功能的方案。你可以结合本文内容并参考 uni-app 官方的 [DarkMode 适配指南](https://uniapp.dcloud.net.cn/tutorial/darkmode.html) 来完成适配。
|
||
|
||
:::tip 提示
|
||
App端的暗黑模式适配，请参考 [App 端暗黑模式适配](https://uniapp.dcloud.net.cn/tutorial/darkmode.html#app-plus)完成，本章节暂不涉及。
|
||
:::
|
||
|
||
## 适配组成
|
||
|
||
暗黑模式的完整适配包含以下几个核心部分：
|
||
|
||
- **uni-app 平台配置**: 开启 [DarkMode](https://uniapp.dcloud.net.cn/tutorial/darkmode.html) 官方支持
|
||
- **UI 组件适配**: [Wot UI](https://wot-ui.cn/component/config-provider.html#%E6%B7%B1%E8%89%B2%E6%A8%A1%E5%BC%8F) 组件库的暗黑模式支持
|
||
- **样式系统适配**: [UnoCSS](https://unocss.dev/presets/mini#dark-mode) 暗黑模式工具类
|
||
|
||
## uni-app 平台配置
|
||
|
||
uni-app 提供了官方的暗黑模式配置方案，通过 `manifest.json` 和 `theme.json` 实现平台级的主题支持，其指南已经比较详细，本章节将简单介绍一下，具体可以参考官方文档。
|
||
|
||
> 📖 **详细文档**: [uni-app 暗黑模式适配指南](https://uniapp.dcloud.net.cn/tutorial/darkmode.html#get-theme)
|
||
|
||
### 配置步骤
|
||
|
||
1. **在 `manifest.config.ts` 中开启暗黑模式**
|
||
|
||
```json
|
||
// H5 配置
|
||
"h5": {
|
||
"darkmode": true,
|
||
"themeLocation": "theme.json"
|
||
}
|
||
|
||
// 微信小程序配置
|
||
"mp-weixin": {
|
||
"darkmode": true,
|
||
"themeLocation": "theme.json"
|
||
}
|
||
```
|
||
|
||
2. **创建 `theme.json` 主题变量文件**
|
||
|
||
```json
|
||
{
|
||
"light": {
|
||
"navBgColor": "#f8f8f8",
|
||
"navTxtStyle": "black",
|
||
"bgColor": "#ffffff",
|
||
"tabBgColor": "#ffffff",
|
||
"tabSelectedColor": "#0165FF"
|
||
},
|
||
"dark": {
|
||
"navBgColor": "#000000",
|
||
"navTxtStyle": "white",
|
||
"bgColor": "#000000",
|
||
"tabBgColor": "#1a1a1a",
|
||
"tabSelectedColor": "#0165FF"
|
||
}
|
||
}
|
||
```
|
||
|
||
3. **在 `pages.config.ts` 中引用主题变量**
|
||
|
||
```json
|
||
{
|
||
"globalStyle": {
|
||
"navigationBarBackgroundColor": "@navBgColor",
|
||
"navigationBarTextStyle": "@navTxtStyle",
|
||
"backgroundColor": "@bgColor"
|
||
},
|
||
"tabBar": {
|
||
"backgroundColor": "@tabBgColor",
|
||
"selectedColor": "@tabSelectedColor"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 获取当前主题
|
||
|
||
```javascript
|
||
// 获取系统主题信息
|
||
const systemInfo = uni.getSystemInfoSync()
|
||
console.log('当前主题:', systemInfo.theme) // 'light' 或 'dark'
|
||
|
||
// 监听主题变化
|
||
uni.onThemeChange((res) => {
|
||
console.log('主题已切换到:', res.theme)
|
||
})
|
||
```
|
||
|
||
### CSS 媒体查询适配
|
||
|
||
```css
|
||
/* 默认样式 */
|
||
.some-background {
|
||
background: white;
|
||
}
|
||
|
||
/* 暗黑模式样式 */
|
||
@media (prefers-color-scheme: dark) {
|
||
.some-background {
|
||
background: #1b1b1b;
|
||
}
|
||
}
|
||
```
|
||
|
||
## 主题管理 API
|
||
|
||
本项目提供了两种主题管理方案，**推荐优先使用自动暗黑模式方案**：
|
||
|
||
> 📝 **项目说明**: 本演示项目为了展示完整的主题管理功能，默认使用了 `useManualTheme()`。在实际项目中，建议根据需求选择合适的方案，大多数情况下使用 `useTheme()` 即可满足需求。
|
||
|
||
### 🌙 自动暗黑模式 - `useTheme()` ⭐ 推荐
|
||
|
||
**适用场景：**
|
||
- 大多数应用的首选方案
|
||
- 只需要系统主题适应的应用
|
||
- 追求简洁和用户体验的应用
|
||
|
||
**功能特性：**
|
||
- ✅ 自动跟随系统主题
|
||
- ✅ 导航栏颜色通过 theme.json 自动处理
|
||
- ✅ 轻量级，性能优秀
|
||
- ✅ 用户体验一致
|
||
|
||
```vue
|
||
<script setup>
|
||
import { useTheme } from '@/composables/useTheme'
|
||
|
||
const { theme, isDark, themeVars } = useTheme()
|
||
</script>
|
||
|
||
<template>
|
||
<wd-config-provider :theme="theme" :theme-vars="themeVars">
|
||
<view :class="{ 'dark-mode': isDark }">
|
||
<text>当前主题: {{ theme }}</text>
|
||
</view>
|
||
</wd-config-provider>
|
||
</template>
|
||
```
|
||
|
||
### 🎨 手动主题管理 - `useManualTheme()`
|
||
|
||
**适用场景：**
|
||
- 需要用户手动控制主题的特殊应用
|
||
- 需要主题色自定义功能的应用
|
||
- 需要完整主题管理功能的复杂应用
|
||
|
||
**功能特性：**
|
||
- ✅ 手动切换暗黑模式
|
||
- ✅ 主题色选择（6种预设颜色）
|
||
- ✅ 跟随系统主题
|
||
- ✅ 自动同步导航栏颜色
|
||
- ✅ 持久化用户设置
|
||
|
||
> 💡 **建议**：除非有特殊需求，否则推荐使用 `useTheme()` 自动暗黑模式方案，它能提供更好的用户体验和性能表现。
|
||
|
||
```vue
|
||
<script setup>
|
||
import { useManualTheme } from '@/composables/useManualTheme'
|
||
|
||
const {
|
||
theme,
|
||
isDark,
|
||
toggleTheme,
|
||
openThemeColorPicker,
|
||
currentThemeColor,
|
||
themeVars
|
||
} = useManualTheme()
|
||
</script>
|
||
|
||
<template>
|
||
<wd-config-provider :theme="theme" :theme-vars="themeVars">
|
||
<view :class="{ 'dark-mode': isDark }">
|
||
<wd-button @click="toggleTheme">
|
||
切换主题
|
||
</wd-button>
|
||
<wd-button @click="openThemeColorPicker">
|
||
选择主题色
|
||
</wd-button>
|
||
</view>
|
||
</wd-config-provider>
|
||
</template>
|
||
```
|
||
|
||
## UI 组件适配 (Wot UI)
|
||
|
||
[Wot Design Uni](https://wot-ui.cn/) 组件库原生支持暗黑模式，通过 `wd-config-provider` 组件可以轻松开启全局暗黑模式支持。
|
||
|
||
### 全局配置
|
||
|
||
```vue
|
||
<!-- App.vue -->
|
||
<script setup>
|
||
// 根据需求选择合适的主题管理方案
|
||
import { useTheme } from '@/composables/useTheme' // 简化版
|
||
// 或者
|
||
// import { useManualTheme } from '@/composables/useManualTheme' // 完整版
|
||
|
||
const { theme, themeVars } = useTheme()
|
||
</script>
|
||
|
||
<template>
|
||
<wd-config-provider :theme="theme" :theme-vars="themeVars">
|
||
<!-- 你的应用内容 -->
|
||
</wd-config-provider>
|
||
</template>
|
||
```
|
||
|
||
### 组件级配置
|
||
|
||
```vue
|
||
<!-- 单个页面或组件 -->
|
||
<template>
|
||
<wd-config-provider theme="dark">
|
||
<wd-button type="primary">
|
||
暗黑模式按钮
|
||
</wd-button>
|
||
<wd-cell title="暗黑模式单元格" />
|
||
</wd-config-provider>
|
||
</template>
|
||
```
|
||
|
||
> 📖 **详细文档**: [Wot UI 暗黑模式配置](https://wot-ui.cn/component/config-provider.html#%E6%B7%B1%E8%89%B2%E6%A8%A1%E5%BC%8F)
|
||
|
||
## 样式系统适配 (UnoCSS)
|
||
|
||
### UnoCSS dark 前缀
|
||
|
||
如果你使用 [UnoCSS](https://unocss.dev/presets/mini#dark-mode)，可以使用 `dark:` 前缀来实现暗黑模式样式。
|
||
|
||
```html
|
||
<view class="bg-white dark:bg-gray-900 text-gray-900 dark:text-gray-100">
|
||
内容区域
|
||
</view>
|
||
```
|
||
|
||
### 样式适配方案
|
||
|
||
```html
|
||
<!-- 使用 UnoCSS dark 前缀 -->
|
||
<view class="bg-white dark:bg-[var(--wot-dark-background)]
|
||
text-gray-800 dark:text-[var(--wot-dark-color)]">
|
||
自动适配暗黑模式的内容
|
||
</view>
|
||
|
||
<!-- 使用主题变量 -->
|
||
<view class="bg-[var(--wot-bg-color)] text-[var(--wot-text-color)]">
|
||
使用主题变量的内容
|
||
</view>
|
||
|
||
```
|
||
|
||
### 最佳实践
|
||
|
||
```html
|
||
<!-- ✅ 推荐：结合官方配置和自定义样式 -->
|
||
<view class="bg-white dark:bg-[var(--wot-dark-background2)]">
|
||
|
||
<!-- ❌ 不推荐：硬编码颜色 -->
|
||
<view style="background: #000; color: #fff;">
|
||
```
|
||
|
||
## 移除暗黑模式功能
|
||
|
||
如果你的项目不需要暗黑模式功能，可以按照以下步骤完全移除相关代码：
|
||
|
||
### 1. 移除官方配置
|
||
|
||
```json
|
||
// src/manifest.config.ts
|
||
{
|
||
"h5": {
|
||
// "darkmode": true, // 删除这行
|
||
// "themeLocation": "theme.json" // 删除这行
|
||
},
|
||
"mp-weixin": {
|
||
// "darkmode": true, // 删除这行
|
||
// "themeLocation": "theme.json" // 删除这行
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2. 删除主题配置文件
|
||
|
||
```bash
|
||
# 删除主题配置文件
|
||
rm src/theme.json
|
||
```
|
||
|
||
### 3. 简化主题管理逻辑
|
||
|
||
```typescript
|
||
// src/composables/useTheme.ts - 简化版本（仅保留系统主题跟随）
|
||
export function useTheme() {
|
||
const currentThemeColor = ref(themeColorOptions[0])
|
||
|
||
// 只保留主题色功能，移除明暗模式切换逻辑
|
||
function selectThemeColor(option: ThemeColorOption) {
|
||
currentThemeColor.value = option
|
||
}
|
||
|
||
return {
|
||
currentThemeColor: computed(() => currentThemeColor.value),
|
||
themeColorOptions,
|
||
selectThemeColor,
|
||
}
|
||
}
|
||
|
||
// 如果需要完全移除主题功能，删除以下文件：
|
||
// - src/composables/useTheme.ts
|
||
// - src/composables/useManualTheme.ts
|
||
// - src/store/themeStore.ts
|
||
// - src/store/manualThemeStore.ts
|
||
```
|
||
|
||
### 4. 清理样式代码
|
||
|
||
```css
|
||
/* 移除暗黑模式相关样式 */
|
||
.container {
|
||
background: white;
|
||
color: black;
|
||
/* 移除：dark:bg-gray-900 dark:text-white */
|
||
}
|
||
|
||
/* 移除媒体查询 */
|
||
/*
|
||
@media (prefers-color-scheme: dark) {
|
||
.container {
|
||
background: #1a1a1a;
|
||
color: white;
|
||
}
|
||
}
|
||
*/
|
||
```
|
||
|
||
### 5. 更新组件使用
|
||
|
||
```vue
|
||
<script setup>
|
||
// 移除主题相关的响应式数据
|
||
// const { theme, isDark } = useTheme() // 删除这行
|
||
|
||
// 移除主题监听
|
||
// watch(theme, (newTheme) => { ... }) // 删除这块
|
||
</script>
|
||
|
||
<template>
|
||
<!-- 移除暗黑模式相关的条件渲染和样式 -->
|
||
<view class="bg-white text-gray-900">
|
||
<!-- 移除：dark:bg-gray-900 dark:text-white -->
|
||
内容区域
|
||
</view>
|
||
</template>
|
||
```
|
||
|
||
### 6. 完全移除（可选）
|
||
|
||
如果要完全移除主题功能：
|
||
|
||
```bash
|
||
# 删除主题相关文件
|
||
rm src/composables/useTheme.ts
|
||
rm src/composables/useManualTheme.ts
|
||
rm src/store/themeStore.ts
|
||
rm src/store/manualThemeStore.ts
|
||
|
||
# 从 pages.json 中移除主题变量引用
|
||
# 将 @navBgColor 等变量替换为具体颜色值
|
||
```
|
||
|
||
```json
|
||
// pages.json - 替换主题变量
|
||
{
|
||
"globalStyle": {
|
||
"navigationBarBackgroundColor": "#ffffff", // 替换 @navBgColor
|
||
"navigationBarTextStyle": "black", // 替换 @navTxtStyle
|
||
"backgroundColor": "#f8f8f8" // 替换 @bgColor
|
||
}
|
||
}
|
||
```
|
||
|
||
移除后，你的应用将只使用固定的明亮主题，减少代码复杂度和包体积。
|
||
|
||
> 📖 **了解更多**: [uni-app 暗黑模式适配指南](https://uniapp.dcloud.net.cn/tutorial/darkmode.html)
|