novel-front-app/doc/dark-mode-guide.md

# 暗色主题使用指南

本文档介绍如何在项目中使用暗色主题功能。

## 概述

我们的应用支持白天/黑夜两种主题模式，用户可以根据自己的偏好切换。主题的状态保存在Vuex中，并且会持久化保存在本地存储中，以便下次打开应用时恢复用户的偏好设置。

## 使用方法

### 1. 在组件中使用主题混入器

我们提供了一个方便的混入器，可以轻松地在任何组件中使用主题相关的功能：

```js
// 1. 导入主题混入器
import themeMixin from '@/mixins/themeMode.js'

export default {
  // 2. 在组件中注册混入器
  mixins: [themeMixin],
  
  methods: {
    someMethod() {
      // 3. 直接使用混入器提供的属性和方法
      console.log(this.isDarkMode) // 是否为暗色模式
      console.log(this.currentTheme) // 当前主题模式：'light'或'dark'
      
      // 切换主题
      this.toggleThemeMode()
      
      // 设置为特定主题
      this.setThemeMode('dark') // 或 'light'
    }
  }
}
```

### 2. 为组件添加暗色主题样式

我们在`uni.scss`中定义了一系列暗色主题相关的变量，您可以在组件的样式中使用这些变量：

```scss
/* 示例组件的样式 */
.my-component {
  background-color: #fff;
  color: #333;
  
  /* 添加主题过渡效果 */
  @extend .theme-transition;
  
  /* 定义暗色主题下的样式 */
  .dark-mode & {
    background-color: $dark-bg-color;
    color: $dark-text-color-primary;
  }
}
```

### 3. 使用主题组件

我们还提供了两个便捷的组件：

#### ThemeProvider

ThemeProvider是一个包装组件，它会自动传递当前的主题模式，并提供暗色主题的根容器：

```html
<template>
  <ThemeProvider>
    <!-- 您的组件内容 -->
    <view class="my-content">
      这里的内容会自动响应主题变化
    </view>
  </ThemeProvider>
</template>

<script>
import ThemeProvider from '@/components/theme/ThemeProvider.vue'

export default {
  components: {
    ThemeProvider
  }
}
</script>
```

#### DarkModeStyles

DarkModeStyles是一个提供通用暗色主题样式的无渲染组件，可以导入到您的页面中使用：

```html
<template>
  <view>
    <!-- 这里不会渲染任何内容，但会应用样式 -->
    <DarkModeStyles />
    
    <!-- 您的组件内容 -->
    <view class="card">
      <view class="card-title">标题</view>
      <view class="card-content">内容</view>
    </view>
  </view>
</template>

<script>
import DarkModeStyles from '@/components/theme/DarkModeStyles.vue'

export default {
  components: {
    DarkModeStyles
  }
}
</script>
```

## 可用的主题变量

以下是在`uni.scss`中定义的暗色主题相关变量，您可以在组件样式中使用：

```scss
/* 背景色 */
$dark-bg-color: #1a1a1a;           // 主背景色
$dark-bg-color-secondary: #222;     // 次要背景色
$dark-bg-color-tertiary: #333;      // 第三级背景色

/* 文本颜色 */
$dark-text-color-primary: #eee;     // 主要文本颜色
$dark-text-color-secondary: #bbb;   // 次要文本颜色
$dark-text-color-tertiary: #999;    // 第三级文本颜色

/* 边框和阴影 */
$dark-border-color: #444;           // 边框颜色
$dark-shadow: 0 2rpx 10rpx rgba(0, 0, 0, 0.2); // 阴影

/* 强调色 */
$dark-accent-color: #4a90e2;        // 强调色

/* 过渡动画时间 */
$theme-transition-duration: 0.3s;    // 主题切换过渡时间
```

## 最佳实践

1. 总是为可能受主题影响的元素添加`theme-transition`类，以确保主题切换时有平滑的过渡效果
2. 使用预定义的变量而不是硬编码颜色值，以保持整个应用的视觉一致性
3. 在设计组件时考虑两种主题模式，确保在暗色模式下内容仍然清晰可见
4. 对于特定于组件的变量，可以基于全局主题变量派生：
   ```scss
   $my-component-bg: $dark-bg-color;
   $my-component-text: $dark-text-color-primary;
   ```

## 注意事项

- 当用户切换主题时，会立即应用新的主题并保存到本地存储中
- 主题状态在整个应用中共享，任何组件都可以访问和修改它
- 对于复杂的组件，考虑分别定义亮色和暗色两套图标或图片资源