样式与布局

tip

本章节主要关注通过样式表来设置样式。对于更高级的定制（如 DOM 结构、React 代码等），请参阅 Swizzling 指南。

道格龙（Docusaurus）网站是一个单页 React 应用。您可以像为 React 应用设计样式一样为它进行设计。

根据您的偏好和您要构建的网站类型，有几种方法/框架可供选择。对于那些高度互动、更像 Web 应用的网站，采用更现代的、将样式与组件放在一起的方法会更有优势。当您希望自定义或 Swizzle某个组件时，组件化样式也特别有用。

全局样式

这是大多数开发者（包括非前端开发者）都熟悉的最传统的样式设置方式。对于没有太多定制化需求的小型网站来说，这种方式很好用。

如果您正在使用 @docusaurus/preset-classic，您可以创建自己的 CSS 文件（例如 /src/css/custom.css），并通过经典主题的选项将其作为全局样式导入。

docusaurus.config.js
export default {
  // ...
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        theme: {
          customCss: ['./src/css/custom.css'],
        },
      },
    ],
  ],
};

您在该文件中编写的任何 CSS 都将全局可用，并可以直接通过字符串字面量引用。

/src/css/custom.css
.purple-text {
  color: rebeccapurple;
}

function MyComponent() {
  return (
    <main>
      <h1 className="purple-text">Purple Heading!</h1>
    </main>
  );
}

如果您想为任何元素添加 CSS，可以在浏览器中打开开发者工具来检查其类名。类名有以下几种：

主题类名。这些类名在下一小节中已详尽列出。它们没有任何默认属性。您应该始终优先在您的自定义 CSS 中使用这些稳定的类名。
Infima 类名。这些类名在经典主题中可以找到，并且通常遵循 BEM 命名约定，即 block__element--modifier。它们通常是稳定的，但仍被视为实现细节，所以您通常应该避免直接定位它们。不过，您可以修改 Infima 的 CSS 变量。
CSS 模块类名。这些类名以一个可能会随时间变化的哈希值结尾（例如 codeBlockContainer_RIuc）。它们被视为实现细节，您几乎应该总是避免在您的自定义 CSS 中定位它们。如果必须这样做，您可以使用属性选择器（[class*='codeBlockContainer']）来忽略哈希值。

主题类名

我们提供了一些稳定的 CSS 类名，用于实现健壮且可维护的全局布局样式。这些名称与主题无关，旨在供自定义 CSS 使用。

tip

如果您找不到创建健壮 CSS 选择器的方法，请报告您的定制用例，我们会考虑添加新的类名。

稳定类名详细列表

这些类名由 theme-common 提供。您可以在自己的组件中导入它们，以应用与主题组件相同的样式。

import {
  ThemeClassNames,
  useThemeConfig,
} from '@docusaurus/theme-common';

所有主题类名的列表如下。

使用 Infima 设计您的网站样式

@docusaurus/preset-classic 使用 Infima 作为其底层的样式框架。Infima 提供了一套灵活的布局和常见的 UI 组件样式，非常适合以内容为中心的网站（如博客、文档、落地页等）。更多详情，请查看 Infima 网站。

当您使用 create-docusaurus 初始化您的道格龙（Docusaurus）项目时，网站将附带基本的 Infima 样式表和默认样式。您可以全局覆盖 Infima 的 CSS 变量。

/src/css/custom.css
:root {
  --ifm-color-primary: #25c2a0;
  --ifm-code-font-size: 95%;
}

Infima 为每种颜色提供了7个色阶。我们推荐使用 ColorBox 来为您的主色调寻找不同的色阶。

或者，您也可以使用下面的工具为您的网站生成不同的色阶，并将生成的变量复制到 /src/css/custom.css 文件中。

tip

主色建议至少达到 WCAG-AA 对比度标准，以保证可读性。你可以直接在道格龙（Docusaurus）官网预览你的配色方案在不同模式下的效果。深色模式下可以使用不同的色板，因为一种颜色通常无法同时适配浅色和深色模式。

主色：

背景色：

CSS 变量名	十六进制	调整值	对比度评级
`--ifm-color-primary-lightest`	`#459afa`		Fail 🔴
`--ifm-color-primary-lighter`	`#2186f9`		Fail 🔴
`--ifm-color-primary-light`	`#1580f9`		Fail 🔴
`--ifm-color-primary`	`#0673f0`	0	Fail 🔴
`--ifm-color-primary-dark`	`#0568d8`		AA 👍
`--ifm-color-primary-darker`	`#0562cc`		AA 👍
`--ifm-color-primary-darkest`	`#0451a8`		AAA 🏅

请将下方变量替换到 src/css/custom.css 文件中。

/src/css/custom.css
:root {
  --ifm-color-primary: #0673f0;
  --ifm-color-primary-dark: #0568d8;
  --ifm-color-primary-darker: #0562cc;
  --ifm-color-primary-darkest: #0451a8;
  --ifm-color-primary-light: #1580f9;
  --ifm-color-primary-lighter: #2186f9;
  --ifm-color-primary-lightest: #459afa;
}
        

暗黑模式

在亮色模式下，<html> 元素会有一个 data-theme="light" 属性；在暗黑模式下，则是 data-theme="dark"。因此，您可以通过为 html 指定特定属性来将您的 CSS 应用范围限定在仅暗黑模式下。

/* 覆盖 root Infima 变量 */
[data-theme='dark'] {
  --ifm-color-primary: #4e89e8;
}
/* 在暗黑模式下特别为一个类设置样式 */
[data-theme='dark'] .purple-text {
  color: plum;
}

tip

可以通过 docusaurus-theme 查询字符串参数来直接初始化道格龙（Docusaurus）的主题。

示例：

/docusaurus/?docusaurus-theme=dark

/docusaurus/configuration?docusaurus-theme=light

Data 属性

可以通过遵循 docusaurus-data-<key> 模式的查询字符串参数来向 <html> 注入 data 属性。这让您可以根据查询字符串灵活地为页面设置不同的样式。

例如，让我们用一个红色的边框并隐藏导航栏来渲染我们的一个页面：

/src/css/custom.css
html[data-navbar='false'] .navbar {
  display: none;
}

html[data-red-border] div#__docusaurus {
  border: red solid thick;
}

/docusaurus/?docusaurus-data-navbar=false&docusaurus-data-red-border

Iframe 模式

如果您计划通过 iframe 将一些道格龙（Docusaurus）页面嵌入到其他网站中，创建一个备用的显示模式会很有用。您可以使用像 https://mysite.com/docs/myDoc?docusaurus-data-mode=iframe 这样的 iframe URL。您需要自己提供额外的样式，并决定保留或隐藏哪些 UI 元素。

移动端视图

道格龙（Docusaurus）使用 996px 作为移动端和桌面端屏幕宽度的分界点。如果您希望布局在移动端视图下有所不同，可以使用媒体查询。

.banner {
  padding: 4rem;
}
/** 在移动端视图下，减小内边距 */
@media screen and (max-width: 996px) {
  .heroBanner {
    padding: 2rem;
  }
}

自定义断点

一些 React 组件，例如页头和侧边栏，在移动端视图下会执行不同的 JavaScript 逻辑。如果您在自定义 CSS 中更改了断点值，您可能还需要通过 Swizzling 使用到 useWindowSize hook 的组件，并传递一个明确的选项参数来更新它。

CSS 模块

要使用 CSS 模块来为您的组件设置样式，请将您的样式表文件命名为以 .module.css 为后缀（例如 welcome.module.css）。Webpack 会将这类 CSS 文件作为 CSS 模块加载，您必须通过导入的 CSS 模块的属性来引用类名（而不是使用普通字符串）。这与 Create React App 中使用的约定类似。

styles.module.css
.main {
  padding: 12px;
}

.heading {
  font-weight: bold;
}

.contents {
  color: #ccc;
}

import styles from './styles.module.css';

function MyComponent() {
  return (
    <main className={styles.main}>
      <h1 className={styles.heading}>Hello!</h1>
      <article className={styles.contents}>Lorem Ipsum</article>
    </main>
  );
}

在构建过程中，Webpack 会将这些类名处理成全局唯一的类名。

CSS-in-JS

warning

CSS-in-JS 的支持尚在开发中，因此像 MUI 这样的库可能会出现显示异常。我们欢迎大家提交 PR 来改进。

Sass/SCSS

要使用 Sass/SCSS 作为您的 CSS 预处理器，请安装非官方的道格龙（Docusaurus）插件 docusaurus-plugin-sass。这个插件对全局样式和 CSS 模块方法都有效：

安装 docusaurus-plugin-sass：

npm
Yarn
pnpm
Bun

npm install --save docusaurus-plugin-sass sass

yarn add docusaurus-plugin-sass sass

pnpm add docusaurus-plugin-sass sass

bun add docusaurus-plugin-sass sass

在您的 docusaurus.config.js 文件中包含该插件：

docusaurus.config.js
export default {
  // ...
  plugins: ['docusaurus-plugin-sass'],
  // ...
};

正常编写并导入您的 Sass/SCSS 样式表。

使用 Sass/SCSS 的全局样式

您现在可以将 @docusaurus/preset-classic 的 customCss 属性指向您的 Sass/SCSS 文件：

docusaurus.config.js
export default {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        // ...
        theme: {
          customCss: ['./src/css/custom.scss'],
        },
        // ...
      },
    ],
  ],
};

使用 Sass/SCSS 的模块

将您的样式表文件命名为以 .module.scss 为后缀（例如 welcome.module.scss）而不是 .css。Webpack 会使用 sass-loader 来预处理您的样式表，并将它们作为 CSS 模块加载。

styles.module.scss
.main {
  padding: 12px;

  article {
    color: #ccc;
  }
}

import styles from './styles.module.scss';

function MyComponent() {
  return (
    <main className={styles.main}>
      <article>Lorem Ipsum</article>
    </main>
  );
}

TypeScript 支持

要为 Sass/SCSS 模块启用 TypeScript 支持，应更新 TypeScript 配置以添加 docusaurus-plugin-sass 的类型定义。这可以在 tsconfig.json 文件中完成：

{
  "extends": "@docusaurus/tsconfig",
  "compilerOptions": {
    ...
+    "types": ["docusaurus-plugin-sass"]
  }
}

全局样式​

主题类名​

使用 Infima 设计您的网站样式​

暗黑模式​

Data 属性​

移动端视图​

CSS 模块​

CSS-in-JS​

Sass/SCSS​

使用 Sass/SCSS 的全局样式​

使用 Sass/SCSS 的模块​

TypeScript 支持​