usePreferredColorScheme 介绍

📋 这是什么？

usePreferredColorScheme 是一个 VueUse 组合式函数，用于检测用户系统的颜色主题偏好。

🎯 核心功能 ★

检测用户操作系统或浏览器设置的颜色主题：

• 🌙 dark - 深色模式
• ☀️ light - 浅色模式
• 🖥️ no-preference - 无偏好

💡 基本使用 ★

import { usePreferredColorScheme } from '@vueuse/core'

// 使用
const colorScheme = usePreferredColorScheme()

console.log(colorScheme.value) // 'light' 或 'dark'

🔧 实际应用

1. 自动跟随系统主题

<script setup>
import { usePreferredColorScheme } from '@vueuse/core'
import { watch } from 'vue'

// 获取系统主题偏好
const preferredScheme = usePreferredColorScheme()

// 应用到页面
watch(preferredScheme, (newScheme) => {
  if (newScheme === 'dark') {
    document.documentElement.classList.add('dark')
  } else {
    document.documentElement.classList.remove('dark')
  }
}, { immediate: true })
</script>

📊 浏览器 API 基础

usePreferredColorScheme 基于浏览器 API：

1. window.matchMedia

// 原生的实现方式
const darkModeQuery = window.matchMedia('(prefers-color-scheme: dark)')
const lightModeQuery = window.matchMedia('(prefers-color-scheme: light)')

if (darkModeQuery.matches) {
  console.log('用户偏好深色模式')
} else if (lightModeQuery.matches) {
  console.log('用户偏好浅色模式')
}

2. VueUse 的封装

// VueUse 内部实现
function usePreferredColorScheme() {
  const isDark = useMediaQuery('(prefers-color-scheme: dark)')
  const isLight = useMediaQuery('(prefers-color-scheme: light)')

  return computed(() => {
    if (isDark.value) return 'dark'
    if (isLight.value) return 'light'
    return 'no-preference'
  })
}

🔄 完整主题管理示例

<script setup>
import { usePreferredColorScheme } from '@vueuse/core'
import { useThemeStore } from '@/stores/theme'

// 获取系统偏好
const preferredScheme = usePreferredColorScheme()
const themeStore = useThemeStore()

// 初始化时应用系统主题
onMounted(() => {
  if (themeStore.followSystem) {
    themeStore.setTheme(preferredScheme.value)
  }
})

// 监听系统主题变化
watch(preferredScheme, (newScheme) => {
  if (themeStore.followSystem) {
    themeStore.setTheme(newScheme)
  }
})
</script>

<template>
  <div :class="themeStore.currentTheme">
    <!-- 页面内容 -->
  </div>
</template>

<style>
/* 深色模式样式 */
.dark {
  background-color: #1a1a1a;
  color: #ffffff;
}

/* 浅色模式样式 */
.light {
  background-color: #ffffff;
  color: #333333;
}
</style>

📈 响应式特性

自动响应变化

// 当用户在系统中切换主题时
// 会自动更新
const scheme = usePreferredColorScheme()

console.log(scheme.value) // 初始值

// 用户在系统设置中切换主题
// scheme.value 会自动更新

响应式组件

<template>
  <div>
    <!-- 自动更新显示 -->
    <p>系统主题偏好: {{ scheme }}</p>

    <!-- 根据主题显示不同图标 -->
    <n-icon v-if="scheme === 'dark'" name="moon" />
    <n-icon v-if="scheme === 'light'" name="sun" />
  </div>
</template>

<script setup>
import { usePreferredColorScheme } from '@vueuse/core'

const scheme = usePreferredColorScheme()
</script>

⚡ 性能优化

1. 防抖处理

import { usePreferredColorScheme, useDebounceFn } from '@vueuse/core'

// 防抖处理，避免频繁更新
const scheme = usePreferredColorScheme()
const debouncedUpdate = useDebounceFn((newScheme) => {
  updateTheme(newScheme)
}, 200)

watch(scheme, debouncedUpdate)

2. 条件监听

// 只有需要时才监听
const shouldListen = ref(false)
const scheme = usePreferredColorScheme({ disabled: () => !shouldListen.value })

// 用户开启"跟随系统"时开始监听
const toggleFollowSystem = () => {
  shouldListen.value = !shouldListen.value
}

💡 浏览器支持

• ✅ Chrome 76+
• ✅ Firefox 67+
• ✅ Safari 12.1+
• ✅ Edge 79+
• ❌ IE 不支持

📊 使用场景总结

🎓 关键点

1. 响应式：自动监听系统主题变化
2. 简单：一行代码获取主题偏好
3. 实用：提升用户体验
4. 标准化：基于 Web 标准

📋 总结

usePreferredColorScheme 是 VueUse 提供的主题检测工具，它能：

• 🔍 检测用户系统主题偏好
• 🔄 自动响应主题变化
• 🎨 帮助实现无障碍设计
• 💡 提升用户体验