想必已经有不少小伙伴在学习 vue3 或在项目中使用了；vue3 的文档结构友好，且一直以来对中文文档的支持都很棒

那么对于官方的文档，我们除了学习 vue3 的语法和使用之外，还有什么文档之外的东西能够学习的呢？

有，深色模式！尤大大对于深色模式的适配让我又学了几招。

深色模式

深色模式的切换并不神秘，vue3 文档对其的实现其实很简单，来看看关键代码。

vue3 文档使用了 vuejs/theme 主题，该主题提供关于深色模式的实现逻辑。

首先是大量使用了 css 变量：

// 根元素实则颜色变量
:root {
    --vt-c-white: #ffffff;
    --vt-c-white-soft: #f9f9f9;
    --vt-c-white-mute: #f1f1f1;
    
    --vt-c-black: #1a1a1a;
    --vt-c-black-pure: #000000;
    --vt-c-black-soft: #242424;
    --vt-c-black-mute: #2f2f2f;
    // ...
}

然后又添加了一个 .dark 类：

// 用于浅色的颜色变量
:root {
    --vt-c-bg: var(--vt-c-white);
    --vt-c-bg-soft: var(--vt-c-white-soft);
    --vt-c-bg-mute: var(--vt-c-white-mute);
    // ...
}
// 用于深色的颜色变量
.dark {
    --vt-c-bg: var(--vt-c-black);
    --vt-c-bg-soft: var(--vt-c-black-soft);
    --vt-c-bg-mute: var(--vt-c-black-mute);
    // ...
}

后面在页面开发中关于颜色的 css 都会使用这些颜色变量。

接着就是用户交互的控制逻辑：

1. 先获取到 html 元素的 class 列表：

  const classList = document.documentElement.classList

2. 切换显示模式 class 的函数：

  const setClass = (dark: boolean) =>
    classList[dark ? 'add' : 'remove']('dark')

3. 用户点击时调用函数：

    setClass((isDark = !isDark))

以上是切换显示模式的最简实现代码。

在编写 css 时，文档还给颜色的切换添加了过渡效果，让切换体验更加丝滑。

.description {
  color: var(--vt-c-text-2);
  transition: color 0.5s;
}

自动跟随系统外观

这里有一点值得注意的是，深色模式的切换是通过用户手动触发的，为什么我们在切换系统外观的时候，网页会检测到当前系统的显示模式，自动进行同步呢？

文档默认是浅色模式，但也支持跟随系统，这主要是通过媒体查询来实现的。

以下代码中的 query 是一个用来判定 Document 是否匹配特定媒体查询的对象，在这里的 prefers-color-scheme: dark 用于检测用户是否有将系统的主题色设置为暗色。

  const query = window.matchMedia(`(prefers-color-scheme: dark)`)
  let isDark = userPreference === 'auto' ? query.matches : userPreference === 'dark'

当用户将外观改变为深色的时候，query.matches 的值为 true，vue3 文档就会给 html 元素添加 .dark 来使用深色模式。

vue3 文档注入了一个自执行的匿名函数来检测系统外观的变化。

;(() => {
  const saved = localStorage.getItem('vue-theme-appearance')
  if (
    saved === 'auto'
      ? window.matchMedia(`(prefers-color-scheme: dark)`).matches
      : saved === 'dark'
  ) {
    document.documentElement.classList.add('dark')
  }
})()

打开控制台可以看到这段编译后的代码：

关键代码

vue3 文档在做深色模式时，整个过程考虑的很充分，用户切换的交互关键逻辑代码如下：

function useAppearance() {
  let userPreference = localStorage.getItem(storageKey) || 'auto'
  const query = window.matchMedia(`(prefers-color-scheme: dark)`)
  const classList = document.documentElement.classList
  let isDark =
    userPreference === 'auto' ? query.matches : userPreference === 'dark'
  const setClass = (dark: boolean) => classList[dark ? 'add' : 'remove']('dark')

  query.onchange = (e) => {
    if (userPreference === 'auto') {
      setClass((isDark = e.matches))
    }
  }

  const toggle = () => {
    setClass((isDark = !isDark))
    localStorage.setItem(
      storageKey,
      (userPreference = isDark
        ? query.matches
          ? 'auto'
          : 'dark'
        : query.matches
        ? 'light'
        : 'auto')
    )
  }

  return toggle
}

而在新版本的代码中，则使用了 @vueuse/core 来简化代码：

import { UseDarkOptions, useDark, useToggle } from '@vueuse/core'

export type UseAppearanceOptions = UseDarkOptions

export function useAppearance(options: UseAppearanceOptions = {}) {
  const isDark = useDark({
    storageKey: 'vue-theme-appearance',
    ...options
  })

  const toggle = useToggle(isDark)

  return {
    isDark,
    toggle
  }
}

总结

最后来总结一下，vue3 文档是如何实现深色模式的：

1. 给根元素(:root)添加 css 颜色变量；
2. 创建一个深色模式的 .dark class 颜色变量；
3. 利用 document.documentElement.classList 来切换 class；
4. 用 localStorage 来持久化用户的选择；
5. 用 prefers-color-scheme: dark 监测用户的系统外观
6. 用自执行的函数来同步系统外观；

一个完整而又全面的深色模式的实现示例，你学会了吗？不妨也在你的项目或博客上试试吧

欢迎关注我的个人公众号 @JSHub：提供最新的开发信息速报，优质的技术干货推荐。

或是查看我的个人博客：Devcursor。

点赞：如果有收获和帮助，请点个赞支持一下！

收藏：欢迎收藏文章，随时查看！

评论：欢迎评论交流学习，共同进步！