暗色主题使用指南

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

概述

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

使用方法

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

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

// 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中定义了一系列暗色主题相关的变量，您可以在组件的样式中使用这些变量：

/* 示例组件的样式 */
.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是一个包装组件，它会自动传递当前的主题模式，并提供暗色主题的根容器：

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

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

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

DarkModeStyles

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

<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中定义的暗色主题相关变量，您可以在组件样式中使用：

/* 背景色 */
$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;    // 主题切换过渡时间

最佳实践

总是为可能受主题影响的元素添加theme-transition类，以确保主题切换时有平滑的过渡效果
使用预定义的变量而不是硬编码颜色值，以保持整个应用的视觉一致性
在设计组件时考虑两种主题模式，确保在暗色模式下内容仍然清晰可见

对于特定于组件的变量，可以基于全局主题变量派生：

$my-component-bg: $dark-bg-color;
$my-component-text: $dark-text-color-primary;

注意事项

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

4.1 KiB Raw Permalink Blame History