跳至主要內容
版本：3.5.2

樣式和佈局

提示

此章節重點透過樣式表進行設定樣式。如需更多進階客製化（DOM 結構、React 程式碼...），請參閱 交換指南。

Docusaurus 站台是一個單頁式 React 應用程式。您可以像設定 React 的應用程式樣式一樣設定它。

有幾種方法/架構堪用，視乎您的喜好以及您嘗試建立的網站類型。高度互動且行為更像網路應用程式（Web App）的網站，將會受益於將樣式與元件放在一起處理的更現代樣式方法。在您希望自訂或交換元件時，元件樣式也特別有用。

全域樣式​

這是一種最傳統的樣式設定方式，大多數開發人員（包括非前端開發人員）都會熟悉。對於沒有太多自訂內容的小型網站，這是可行的。

如果您使用 @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 加入任何元素，您可以開啟瀏覽器中的 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 中。

提示

至少瞄準 WCAG-AA 對比度 以確保主色可讀性。使用 Docusaurus 網站本身來預覽您的色票組看起來會如何。您可以在暗模式中使用其他色票組，因為單一顏色通常無法用於明暗兩種模式。

CSS 變數名稱十六進位調整對比評級
--ifm-color-primary-lightest#3CAD6E失敗 🔴
--ifm-color-primary-lighter#359962失敗 🔴
--ifm-color-primary-light#33925D失敗 🔴
--ifm-color-primary#2E85550AA 👍
--ifm-color-primary-dark#29784CAA 👍
--ifm-color-primary-darker#277148AA 👍
--ifm-color-primary-darkest#205D3BAAA 🏅

將 src/css/custom.css 中的變數替換為這些新變數。

/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 範圍，僅限於暗模式。

/* Overriding root Infima variables */
[data-theme='dark'] {
  --ifm-color-primary: #4e89e8;
}
/* Styling one class specially in dark mode */
[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 embedded 一些 Docusaurus 頁面，在這種情況下建立一個替代的顯示模式可能很有用，可以使用像是 https://mysite.com/docs/myDoc?docusaurus-data-mode=iframe 這樣的 iframe url。提供額外的樣式以及決定要保留或隱藏哪些使用者介面元素是你的責任。

行動裝置檢視​

Docusaurus 使用 996px 當作行動裝置螢幕寬度與桌機寬度之間的分界點。如果你希望你的版面配置在行動裝置檢視時是不同的，可以使用媒體查詢。

.banner {
  padding: 4rem;
}
/** In mobile view, reduce the padding */
@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​

警告

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 支援​

若要啟用 TypeScript 對 Sass/SCSS 模組的支援，應更新 TypeScript 設定，以新增 docusaurus-plugin-sass 型別定義。這可以在 tsconfig.json 檔案中進行

{
  "extends": "@tsconfig/docusaurus/tsconfig.json",
  "compilerOptions": {
    ...
+    "types": ["docusaurus-plugin-sass"]
  }
}
編輯此頁面
最後更新日期於 由 Sébastien Lorber 更新