Quartz 暗色模式（Darkmode）完全指南：跟随系统主题、本地持久化与自定义切换

Quartz 暗色模式Darkmode完全指南跟随系统主题、本地持久化与自定义切换【免费下载链接】quartz a fast, batteries-included static-site generator that transforms Markdown content into fully functional websites项目地址: https://gitcode.com/GitHub_Trending/qua/quartzQuartz 内置了开箱即用的暗色模式支持能够自动尊重访问者的系统主题偏好prefers-color-scheme并将用户手动的明暗切换结果保存在浏览器 localStorage 中实现跨页面加载的持久化记忆。读完本文你将掌握如何在 Quartz 中启用/禁用暗色模式、通过quartz.config.yaml定制明暗两套配色、安装社区 darkmode 插件以及如何监听themechange事件在主题切换时执行自己的业务逻辑。暗色模式的工作机制按照 docs/features/darkmode.md 的说明Quartz 的暗色模式具备两大开箱能力尊重系统主题偏好首次访问时站点会根据操作系统或浏览器的prefers-color-scheme自动选择亮色或暗色主题无需用户任何操作。本地持久化一旦用户手动点击了暗色模式开关该选择会被写入浏览器的 localStorage在后续的所有页面加载中保持生效直到用户再次手动切换或清除站点数据。这种系统偏好为默认、手动选择优先的设计兼顾了无感体验与用户控制权是典型的现代网站主题切换实现方式。从仓库实现看这一功能由社区插件quartz-community/darkmode提供Quartz 5 采用插件化架构暗色模式开关本质上是挂在页面工具栏上的一个组件Component对应文档 docs/plugins/Darkmode.md 中的 API 定义Category 为Component函数名为ExternalPlugin.Darkmode()enabled选项默认值为true。默认配置暗色开关在工具栏中的位置在 Quartz 5 中暗色模式组件默认已启用。以仓库根目录的 quartz.config.default.yaml以及 CLI 模板 quartz/cli/templates/default.yaml为例插件列表中相关配置如下- source: quartz-community/darkmode enabled: true layout: position: left priority: 30 group: toolbar各字段含义source插件来源标识此处为官方社区插件quartz-community/darkmode。enabled是否启用暗色模式开关true为启用默认值false为禁用。layout.position组件在页面布局中的位置此处为left左侧工具栏与阅读模式reader-modepriority: 35相邻排列。layout.priority同位置下组件的排序优先级数值越小越靠前30意味着它位于 page-titlepriority: 10之后、reader-modepriority: 35之前。layout.group组件所属分组toolbar表示它渲染在页面工具栏区域。移除或禁用暗色模式如果你不需要暗色模式开关有两种等价做法删除条目直接从quartz.config.yaml的plugins列表中移除quartz-community/darkmode这一整条配置显式禁用保留条目但将enabled设为false- source: quartz-community/darkmode enabled: false两种方式的效果相同工具栏上不再出现明暗切换按钮。注意禁用开关并不会影响主题本身站点的明暗配色依然由configuration.theme.colors中的lightMode/darkMode两套色板控制见下文。安装 darkmode 插件如果你的站点是精简安装、配置中没有该插件可以通过 Quartz CLI 的一键命令安装npx quartz plugin add github:quartz-community/darkmode该命令会将插件注册到quartz.config.yaml的插件列表中。安装与配置插件的通用方法可参考 docs/configuration.md 中关于 Plugins 部分的说明。默认的插件选项极其简单只需enabled: true- source: github:quartz-community/darkmode enabled: true自定义明暗两套主题配色暗色模式不只是开关这么简单Quartz 允许你分别定义亮色与暗色两套完整的色板。在 quartz.config.default.yaml 的configuration.theme.colors中可以看到默认的完整配色示例theme: fontOrigin: googleFonts cdnCaching: true typography: header: Schibsted Grotesk body: Source Sans Pro code: IBM Plex Mono colors: lightMode: light: #faf8f8 lightgray: #e5e5e5 gray: #b8b8b8 darkgray: #4e4e4e dark: #2b2b2b secondary: #284b63 tertiary: #84a59d highlight: rgba(143, 159, 169, 0.15) textHighlight: #fff23688 darkMode: light: #161618 lightgray: #393639 gray: #646464 darkgray: #d4d4d4 dark: #ebebec secondary: #7b97aa tertiary: #84a59d highlight: rgba(143, 159, 169, 0.15) textHighlight: #b3aa0288两套色板的语义一致各颜色变量的作用如下light页面主背景色lightgray较浅的辅助背景如代码块、引用块背景gray边框与分隔线等中间色调darkgray次要文字颜色dark正文主文字颜色secondary强调色链接、标题装饰等tertiary三级强调色highlight选中/悬停高亮背景支持rgba透明色textHighlight文本高亮标记色。可以看到暗色模式下的light/dark恰好与亮色模式互换语义暗色模式背景深、文字浅通过分别维护两套色板Quartz 可以保证任意页面元素在两种主题下都有恰当的对比度。修改theme.colors下的任意颜色值后重新构建站点即可生效。监听 themechange 事件并注入自定义逻辑除了内置的切换行为Quartz 还向document派发了名为themechange的自定义事件。任何页面脚本都可以监听该事件在用户切换明暗主题的瞬间执行自己的逻辑例如上报埋点、动态调整第三方组件的配色等。原文档 docs/features/darkmode.md 给出的用法如下document.addEventListener(themechange, (e) { console.log(Theme changed to e.detail.theme) // either light or dark // your logic here })事件对象的detail.theme字段取值为字符串light或dark代表切换后的目标主题。典型的应用场景包括当主题切换为dark时自动给第三方嵌入组件如图表、地图追加暗色样式类根据主题上报用户偏好统计同步更新站点内其他独立 UI 元素的配色。小结Quartz 的暗色模式在默认配置下即可工作首次访问跟随系统偏好手动切换后写入 localStorage 持久生效。通过 quartz.config.default.yaml 中的theme.colors.lightMode/darkMode可以分别定制两套配色在plugins列表删除或禁用quartz-community/darkmode条目即可移除开关使用npx quartz plugin add github:quartz-community/darkmode可随时重新安装。最后别忘了利用themechange事件让站点在主题变化时执行你自定义的逻辑这是将暗色模式与业务深度整合的推荐做法。【免费下载链接】quartz a fast, batteries-included static-site generator that transforms Markdown content into fully functional websites项目地址: https://gitcode.com/GitHub_Trending/qua/quartz创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考