跳到主要内容

样式和布局

提示

本节重点介绍通过样式表进行样式设置。有关更高级的自定义（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">紫色标题！</h1>
    </main>
  );
}

如果您想向任何元素添加 CSS，您可以打开浏览器中的 DevTools 来检查其类名。类名有多种类型：

  • 主题类名 。这些类名在 下一小节 中详尽列出。它们没有任何默认属性。您应该始终优先在自定义 CSS 中定位这些稳定的类名。
  • Infima 类名 。这些类名存在于经典主题中，通常遵循 block__element--modifier 的 BEM 约定 。它们通常是稳定的，但仍然被认为是实现细节，因此您通常应避免定位它们。但是，您可以 修改 Infima CSS 变量 。
  • CSS 模块类名 。这些类名以哈希结尾，可能会随着时间的推移而改变（codeBlockContainer_RIuc）。它们被认为是实现细节，您几乎总是应该避免在自定义 CSS 中定位它们。如果必须，您可以使用 属性选择器 （[class*='codeBlockContainer']）忽略哈希值。

主题类名​

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

提示

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

稳定类名的详尽列表
export const ThemeClassNames = {
  page: {
    blogListPage: 'blog-list-page',
    blogPostPage: 'blog-post-page',
    blogTagsListPage: 'blog-tags-list-page',
    blogTagPostListPage: 'blog-tags-post-list-page',
    blogAuthorsListPage: 'blog-authors-list-page',
    blogAuthorsPostsPage: 'blog-authors-posts-page',
    docsDocPage: 'docs-doc-page',
    docsTagsListPage: 'docs-tags-list-page',
    docsTagDocListPage: 'docs-tags-doc-list-page',
    mdxPage: 'mdx-page',
  },
  wrapper: {
    main: 'main-wrapper',
    blogPages: 'blog-wrapper',
    docsPages: 'docs-wrapper',
    mdxPages: 'mdx-wrapper',
  },
  common: {
    editThisPage: 'theme-edit-this-page',
    lastUpdated: 'theme-last-updated',
    backToTopButton: 'theme-back-to-top-button',
    codeBlock: 'theme-code-block',
    admonition: 'theme-admonition',
    unlistedBanner: 'theme-unlisted-banner',
    draftBanner: 'theme-draft-banner',
    admonitionType: (type: string) => `theme-admonition-${type}`,
  },
  layout: {
  },
  docs: {
    docVersionBanner: 'theme-doc-version-banner',
    docVersionBadge: 'theme-doc-version-badge',
    docBreadcrumbs: 'theme-doc-breadcrumbs',
    docMarkdown: 'theme-doc-markdown',
    docTocMobile: 'theme-doc-toc-mobile',
    docTocDesktop: 'theme-doc-toc-desktop',
    docFooter: 'theme-doc-footer',
    docFooterTagsRow: 'theme-doc-footer-tags-row',
    docFooterEditMetaRow: 'theme-doc-footer-edit-meta-row',
    docSidebarContainer: 'theme-doc-sidebar-container',
    docSidebarMenu: 'theme-doc-sidebar-menu',
    docSidebarItemCategory: 'theme-doc-sidebar-item-category',
    docSidebarItemLink: 'theme-doc-sidebar-item-link',
    docSidebarItemCategoryLevel: (level: number) =>
      `theme-doc-sidebar-item-category-level-${level}` as const,
    docSidebarItemLinkLevel: (level: number) =>
      `theme-doc-sidebar-item-link-level-${level}` as const,
  },
  blog: {
    blogFooterTagsRow: 'theme-blog-footer-tags-row',
    blogFooterEditMetaRow: 'theme-blog-footer-edit-meta-row',
  },
  pages: {
    pageFooterEditMetaRow: 'theme-pages-footer-edit-meta-row',
  },
} as const;

使用 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 中。

提示

Aim for at least WCAG-AA contrast ratio for the primary color to ensure readability. Use the Docusaurus website itself to preview how your color palette would look like. You can use alternative palettes in dark mode because one color doesn't usually work in both light and dark mode.

CSS Variable NameHexAdjustmentContrast Rating
--ifm-color-primary-lightest#3cad6eFail 🔴
--ifm-color-primary-lighter#359962Fail 🔴
--ifm-color-primary-light#33925dFail 🔴
--ifm-color-primary#2e85550AA 👍
--ifm-color-primary-dark#29784cAA 👍
--ifm-color-primary-darker#277148AA 👍
--ifm-color-primary-darkest#205d3bAAA 🏅

Replace the variables in src/css/custom.css with these new variables.

/src/css/custom.css
:root {
  --ifm-color-primary: #2e8555;
  --ifm-color-primary-dark: #29784c;
  --ifm-color-primary-darker: #277148;
  --ifm-color-primary-darkest: #205d3b;
  --ifm-color-primary-light: #33925d;
  --ifm-color-primary-lighter: #359962;
  --ifm-color-primary-lightest: #3cad6e;
}

深色模式​

在浅色模式下，<html> 元素具有 data-theme="light" 属性；在深色模式下，它是 data-theme="dark"。因此，您可以通过使用特定属性定位 html 来将 CSS 的范围限定为仅深色模式。

/* 覆盖根 Infima 变量 */
[data-theme='dark'] {
  --ifm-color-primary: #4e89e8;
}
/* 特别在深色模式下样式化一个类 */
[data-theme='dark'] .purple-text {
  color: plum;
}
提示

可以从 docusaurus-theme 查询字符串参数直接初始化 Docusaurus 主题。

示例：

/docs/?docusaurus-theme=dark
/docs/configuration?docusaurus-theme=light

数据属性​

可以使用 docusaurus-data-<key> 模式的查询字符串参数注入 <html> 数据属性。这使您可以根据查询字符串以不同的方式设置页面的样式。

例如，让我们用红色边框和没有导航栏来渲染我们的页面之一：

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

html[data-red-border] div#__docusaurus {
  border: red solid thick;
}
/docs/?docusaurus-data-navbar=false&docusaurus-data-red-border
iframe 模式

如果您计划通过 iframe 在另一个站点上嵌入一些 Docusaurus 页面，则创建替代显示模式并使用 iframe url（例如 https://mysite.com/docs/myDoc?docusaurus-data-mode=iframe）可能很有用。您有责任提供额外的样式并决定要保留或隐藏哪些 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}>你好！</h1>
      <article className={styles.contents}>Lorem Ipsum</article>
    </main>
  );
}

类名将在构建期间由 webpack 处理成全局唯一的类名。

CSS-in-JS​

注意

CSS-in-JS 支持正在开发中，因此像 MUI 这样的库可能存在显示问题。 欢迎 PR 。

Sass/SCSS​

要使用 Sass/SCSS 作为您的 CSS 预处理器，请安装非官方的 Docusaurus 插件 docusaurus-plugin-sass 。此插件适用于全局样式和 CSS 模块方法：

  1. 安装 docusaurus-plugin-sass ：
npm install --save docusaurus-plugin-sass sass
  1. 将插件包含在您的 docusaurus.config.js 文件中：
docusaurus.config.js
export default {
  // ...
  plugins: ['docusaurus-plugin-sass'],
  // ...
};
  1. 像往常一样编写和导入您的 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"]
  }
}
编辑此页
最后由 HomeUbuntu 于 更新