如何将 Material UI 引入到 Docusaurus 中使用

最近因为要发布一个关于统计工具的介绍页面，要用到表单的功能，Docusaurus 中样式库用的是 Infima，里面并没有涉及到表单组件的样式。

想到网站后面肯定要用到很多交互方面的样式，纯手写比较麻烦。于是干脆直接引入一款前端 UI 库，基于个人审美选择了 Material UI。

安装 Material UI 库

安装免费开源的基于 React 函数式组件版的 MUI Core

npm install @mui/material @emotion/react @emotion/styled

安装好之后，我们可以直接在 jsx 和 mdx 格式的文件中使用它们提供的组件：

import Container from "@mui/system/Container";
import Card from "@mui/material/Card";
import Grid from "@mui/material/Grid";
import Typography from "@mui/material/Typography";

<Grid container justifyContent="center" sx={{ paddingBottom: 8 }}>
  <Grid item xs={12}>
    <Card
      variant="outlined"
      sx={{
        textAlign: "center",
        boxShadow: 3,
      }}
    >
      <Typography variant="h4">This is an example</Typography>
    </Card>
  </Grid>
</Grid>;

Material UI CSS 主题变量

为了将 MUI 的主题与 Docusaurus 进行集成，我选择了 MUI 实验性质的功能 CSS Theme Variables，它允许我们 在同一个主题里创建浅色和深色的风格。而且可以通过 useColorScheme hook 的 setMode 进行切换。

创建 MUI 颜色主题

在全局组件目录下创建 /src/components/MuiTheme/index.jsx，和 MUI 的 createTheme 方法一样，只需要为提供的变量属性赋值即可

import { experimental_extendTheme as extendTheme } from "@mui/material/styles";

// General MUI theme
const extTheme = extendTheme({
  colorSchemes: {
    light: {
      palette: {
        primary: {
          main: "hsl(237, 45%, 40%)",
        },
        background: {
          paper: "hsl(240, 15%, 95%)",
        },
      },
    },
    dark: {
      palette: {
        primary: {
          main: "hsl(131, 43%, 46%)",
        },
        background: {
          paper: "hsl(210, 3%, 15%)",
        },
      },
    },
  },
});

export default extTheme;

应用 MUI 主题颜色到 Docusaurus 网站

首先我们将 MUI 主题配置导入进来，然后包裹进整个网站。这里可以通过 Swizzing 方式对 <Root> 组件进行封装。创建 /src/theme/Root.js，编写一下代码：

import React from "react";
import { getInitColorSchemeScript } from "@mui/material/styles";
import { Experimental_CssVarsProvider as CssVarsProvider } from "@mui/material/styles";
import theme from "@site/src/components/MuiTheme";

export default function Root({ children }) {
  return (
    <>
      {getInitColorSchemeScript()}
      <CssVarsProvider theme={theme}>{children}</CssVarsProvider>
    </>
  );
}

匹配 Docusaurus 和 MUI 主题

我们根据 Docusaurus 的网站深浅模式（light or dark）来同步设置 MUI 的主题颜色

同样还是采用 Swizzing 方式对 ColorModeToggle 组件进行包裹。

npm run swizzle @docusaurus/theme-classic ColorModeToggle -- --wrap

然后修改 /src/theme/ColorModeToggle/index.js 中的代码

import React, { useEffect } from "react";
import ColorModeToggle from "@theme-original/ColorModeToggle";
import { useColorScheme } from "@mui/material/styles";

export default function ColorModeToggleWrapper(props) {
  // MUI color mode setting
  const { setMode } = useColorScheme();

  // "value" holds the color theme. Either "light" or "dark"
  const { value } = props;

  // change mode based on "value" prop
  // "dark" or "light" are also used for MUI
  useEffect(() => {
    setMode(value);
  }, [value]);

  return (
    <>
      <ColorModeToggle {...props} />
    </>
  );
}

使用 MUI 组件演示效果

我使用 Material UI 提供的 TextField 和 Button 组件搭建了一个简单的登录表单

name *

name *

password *

password *

右上角切换网站的深浅模式，可以看到提交按钮颜色的变化，对应以上 MUI 主题配置 light -> hsl(237, 45%, 40%)，dark -> hsl(131, 43%, 46%)