1. 核心概念
  2. 暗黑模式

核心概念

暗黑模式

使用变体在暗黑模式下为网站设置样式。

概述

随着深色模式成为许多操作系统的原生功能,为网站设计深色版本以配合默认设计变得越来越普遍。

为了让这一过程尽可能简单,Tailwind 提供了一个 dark 变体,让你可以在启用深色模式时以不同方式设计网站样式:

浅色模式

倒立书写

零重力笔可以在任何方向书写,包括倒立状态。它甚至在外太空也能使用。

深色模式

倒立书写

零重力笔可以在任何方向书写,包括倒立状态。它甚至在外太空也能使用。

<div class="bg-white dark:bg-gray-800 rounded-lg px-6 py-8 ring shadow-xl ring-gray-900/5">  <div>    <span class="inline-flex items-center justify-center rounded-md bg-indigo-500 p-2 shadow-lg">      <svg class="h-6 w-6 stroke-white" ...>        <!-- ... -->      </svg>    </span>  </div>  <h3 class="text-gray-900 dark:text-white mt-5 text-base font-medium tracking-tight ">倒立书写</h3>  <p class="text-gray-500 dark:text-gray-400 mt-2 text-sm ">    零重力笔可以在任何方向书写,包括倒立状态。它甚至在外太空也能使用。  </p></div>

默认情况下,这会使用 CSS 的 prefers-color-scheme 媒体特性,但你也可以通过覆盖 dark 变体来构建支持手动切换深色模式的网站。

手动切换暗黑模式

如果你想通过 CSS 选择器而非 prefers-color-scheme 媒体查询来控制暗黑主题,可以覆盖 dark 变体来使用自定义选择器:

app.css
@import "tailwindcss";@custom-variant dark (&:where(.dark, .dark *));

现在 dark:* 工具类将不再基于 prefers-color-scheme 应用,而是当 HTML 树中存在 dark 类时生效:

HTML
<html class="dark">  <body>    <div class="bg-white dark:bg-black">      <!-- ... -->    </div>  </body></html>

如何向 html 元素添加 dark 类由你决定,常见做法是使用 JavaScript 更新 class 属性并将该偏好同步到 localStorage 等位置。

使用数据属性

要使用数据属性而非类来激活暗黑模式,只需用属性选择器覆盖 dark 变体:

app.css
@import "tailwindcss";@custom-variant dark (&:where([data-theme=dark], [data-theme=dark] *));

现在当树结构中存在 data-theme 属性且值为 dark 时,暗黑模式工具类就会生效:

HTML
<html data-theme="dark">  <body>    <div class="bg-white dark:bg-black">      <!-- ... -->    </div>  </body></html>

支持系统主题

要构建支持浅色模式、深色模式以及系统主题的三向主题切换器,可以使用自定义的深色模式选择器配合 window.matchMedia() API 来检测系统主题,并在需要时更新 html 元素。

以下是一个简单示例,展示如何同时支持浅色模式、深色模式以及遵循操作系统偏好设置:

spaghetti.js
// 在页面加载或主题变更时,最好将代码内联在 `head` 中以避免 FOUC(无样式内容闪烁)document.documentElement.classList.toggle(  "dark",  localStorage.theme === "dark" ||    (!("theme" in localStorage) && window.matchMedia("(prefers-color-scheme: dark)").matches),);// 当用户明确选择浅色模式时localStorage.theme = "light";// 当用户明确选择深色模式时localStorage.theme = "dark";// 当用户明确选择遵循操作系统偏好时localStorage.removeItem("theme");

你可以根据自己的需求灵活管理这个功能,甚至可以将偏好设置存储在服务端的数据库中,并在服务器端渲染类名——这完全取决于你的实现方式。

Copyright © 2025 Tailwind Labs Inc.·Trademark Policy