深色模式 | EmDash CMS Everything

站点通过两种方式在浅色和深色之间做出选择：访客的系统偏好，或站点为该访客存储的明确选择。EmDash 组件通过 <html> 元素上的约定读取这两个信号。本页描述了该约定、如何为图片字段提供深色变体，以及如何使用 emdash/ui 的 Image 组件渲染它。

主题约定

组件和模板按以下顺序使用这两个信号：

<html> 上的 dark 或 light 类固定配色方案。类优先于系统偏好。
没有类时，配色方案跟随 prefers-color-scheme 媒体查询。

捆绑的模板将明确选择存储在 theme cookie 中，并在 <head> 中使用内联脚本在首次渲染前应用。以下脚本读取 cookie 并设置类，当没有存储选择时不执行任何操作：

<script is:inline>
	(function () {
		var c = document.cookie;
		var i = c.indexOf("theme=");
		var theme = i >= 0 ? c.slice(i + 6).split(";")[0] : null;
		if (theme === "dark" || theme === "light") {
			document.documentElement.classList.add(theme);
		}
	})();
</script>

使用 light-dark() 定义一次颜色，让类固定配色方案：

:root {
	color-scheme: light dark;
	--color-bg: light-dark(#ffffff, #0d0d0d);
	--color-text: light-dark(#1a1a1a, #ededed);
}
:root.light {
	color-scheme: light;
}
:root.dark {
	color-scheme: dark;
}

没有主题切换器的站点不需要脚本：让 <html> 没有类，系统偏好就会生效。

深色图片变体

图片字段可以包含用于深色配色方案的第二张图片。编辑在主图片旁边选择它，Image 组件显示与访客配色方案匹配的那张。

在字段上启用插槽

插槽默认关闭。在管理后台或种子文件中按字段启用。

在管理后台中，打开 Content Types，编辑图片字段，打开 Dark mode variant。

在种子文件中，在字段上设置 darkVariant 组件选项：

{
	"slug": "featured_image",
	"label": "Featured Image",
	"type": "image",
	"options": { "darkVariant": true }
}

在编辑器中选择变体

打开一个条目，像往常一样选择主图片。
点击图片下方的 Add dark mode variant，从媒体库中选择深色变体。
保存条目。

变体存储在字段值中的 darkVariant。删除主图片会一并删除变体；替换主图片会保留变体直到您替换或删除它。

渲染变体

当值包含 darkVariant 时，Image 组件渲染两张图片，并使用 CSS 显示匹配的那张。模板中无需任何更改：

---
import { Image } from "emdash/ui";
import { getEmDashEntry } from "emdash";

const { entry: post } = await getEmDashEntry("posts", Astro.params.slug);
---

{post?.data.featured_image && <Image image={post.data.featured_image} priority />}

输出包含两个 <img> 元素。主图片获得类 emdash-image--light，变体获得 emdash-image--dark。两者都使用主图片的 alt 文本、宽高覆盖和加载属性。每个保留自己的占位符颜色。

您传递的 id 保留在主图片上；变体获得相同的 id 加上 --dark 后缀，因此 id="hero" 产生 hero 和 hero--dark。

当深色图片来自其他地方，例如第二个图片字段，请明确传递：

<Image image={post.data.hero} darkVariant={post.data.hero_dark} />

加载行为

两张图片默认是懒加载的。浏览器不会获取使用 display: none 隐藏的懒加载图片，因此访客只下载其配色方案的变体，另一个在配色方案更改时加载。

使用 priority 时，两张图片都获得 loading="eager" 和 fetchpriority="high"，在每种配色方案中都会下载。主题在浏览器中决定，因此服务器无法知道访客将看到哪个变体。在首屏图片上使用 priority，其他图片保持懒加载。

使用不同的主题约定

附带的 CSS 隐藏与配色方案不匹配的变体。其选择器在 <html> 部分使用 :where()，因此任何使用类或属性定位 <html> 的规则都会优先。

如果您的切换器设置了 data-theme 等属性，最简单的修复是在同一代码路径中也设置 dark 和 light 类。否则，在您自己的样式表中覆盖四种情况：

:root[data-theme="dark"] .emdash-image--light,
:root[data-theme="light"] .emdash-image--dark {
	display: none;
}
:root[data-theme="dark"] .emdash-image--dark,
:root[data-theme="light"] .emdash-image--light {
	display: block;
}

将 display 值与您的样式表在其他地方给图片的值匹配，例如当您不将 img 重置为 block 时使用 inline。