开启掘金成长之旅！这是我参与「掘金日新计划 · 12 月更文挑战」的第4天，点击查看活动详情
好久不见，我是 new_cheng。
想必已经有不少小伙伴在学习 vue3 或在项目中使用了；vue3 的文档结构友好，且一直以来对中文文档的支持都很棒👍
那么对于官方的文档，我们除了学习 vue3 的语法和使用之外，还有什么文档之外的东西能够学习的呢？
vue 新的官网设计上比之前的更加有质感，研读了文档的代码后，发现新官网是用 vitepress 开发，样式和布局则是采用了 vuejs/theme 主题，markdown 的解析用的是 markdown-it，又继续深挖，学习了如何给 markdown-it 开发插件，把自己的博客用 vitepress 重写了，还自己编写了几个实用的 markdown-ite 插件。
这种挖掘探索的行为不仅扩宽了自己的眼界，也学习了不少开发技巧。
比如，尤大大对于深色模式的适配让我又学了几招。
深色模式
深色模式的实现并不难，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 都会使用这些颜色变量。
接着就是用户交互的控制逻辑：
- 先获取到 html 元素的 class 列表：
const classList = document.documentElement.classList
- 切换显示模式 class 的函数：
const setClass = (dark: boolean) =>
classList[dark ? 'add' : 'remove']('dark')
- 用户点击时调用函数：
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 文档是如何实现深色模式的：
- 给根元素(:root)添加 css 颜色变量；
- 创建一个深色模式的 .dark class 颜色变量；
- 利用
document.documentElement.classList来切换 class； - 用 localStorage 来持久化用户的选择；
- 用
prefers-color-scheme: dark监测用户的系统外观 - 用自执行的函数来同步系统外观；
一个完整而又全面的深色模式的实现示例，你学会了吗？不妨也在你的项目或博客上试试吧💯
欢迎关注我的个人公众号 @JSHub：提供最新的开发信息速报，优质的技术干货推荐。
或是查看我的个人博客：Devcursor。
👍点赞：如果有收获和帮助，请点个赞支持一下！
🌟收藏：欢迎收藏文章，随时查看！
💬评论：欢迎评论交流学习，共同进步！
