方法

了解在不同情况下，推荐使用哪种方法来自定义 Joy UI 组件。

对于仅自定义给定组件的特定实例，使用 sx prop。
为了确保给定组件的每个实例在您的应用中看起来都相同，使用主题。
要创建 Joy UI 开箱即用不支持但仍具有设计一致性的内容，请创建一个使用 Joy UI 主题设计令牌的可重用组件。

sx 属性

sx 属性提供 CSS 的超集（包含所有 CSS 属性/选择器，以及自定义属性/选择器），它可以根据所使用的 CSS 属性，直接从主题映射值。

每个 Joy UI 组件都支持它，它是一个允许您快速即时自定义组件的工具。访问 sx 属性文档以了解更多信息。

主题

主题是一个对象，您可以在其中定义您的设计语言，包括基础令牌（如配色方案、排版和间距比例），以及每个组件及其不同的变体和状态如何使用它们。

这里有一些重现流行设计的示例（尽管仅限浅色模式）

更改主题

import { CssVarsProvider, extendTheme } from '@mui/joy/styles';
import Button from '@mui/joy/Button';

const githubTheme = extendTheme({
  colorSchemes: {
    light: {
      palette: {
        success: {
          solidBg: '#2DA44E',
          solidHoverBg: '#2C974B',
          solidActiveBg: '#298E46',
        },
        neutral: {
          outlinedBg: '#F6F8FA',
          outlinedHoverBg: '#F3F4F6',
          outlinedActiveBg: 'rgba(238, 239, 242, 1)',
          outlinedBorder: 'rgba(27, 31, 36, 0.15)',
        },
        focusVisible: 'rgba(3, 102, 214, 0.3)',
      },
    },
  },
  focus: {
    default: {
      outlineWidth: '3px',
    },
  },
  fontFamily: {
    body: 'SF Pro Text, var(--gh-fontFamily-fallback)',
  },
  components: {
    JoyButton: {
      styleOverrides: {
        root: ({ ownerState }) => ({
          borderRadius: '6px',
          boxShadow: '0 1px 0 0 rgba(27, 31, 35, 0.04)',
          transition: '80ms cubic-bezier(0.33, 1, 0.68, 1)',
          transitionProperty: 'color,background-color,box-shadow,border-color',
          ...(ownerState.size === 'md' && {
            fontWeight: 600,
            minHeight: '32px',
            fontSize: '14px',
            '--Button-paddingInline': '1rem',
          }),
          ...(ownerState.color === 'success' &&
            ownerState.variant === 'solid' && {
              '--gh-palette-focusVisible': 'rgba(46, 164, 79, 0.4)',
              border: '1px solid rgba(27, 31, 36, 0.15)',
              '&:active': {
                boxShadow: 'inset 0px 1px 0px rgba(20, 70, 32, 0.2)',
              },
            }),
          ...(ownerState.color === 'neutral' &&
            ownerState.variant === 'outlined' && {
              '&:active': {
                boxShadow: 'none',
              },
            }),
        }),
      },
    },
  },
});

function App() {
  return (
    <CssVarsProvider theme={githubTheme}>
      <Button>Solid</Button>
      ...other buttons
    </CssVarsProvider>
  );
};

自定义主题令牌

主题令牌指的是低级别和全局变体设计令牌。

例如，您不必每次想要更改给定组件的背景颜色时都分配相同的十六进制代码，而是分配一个主题令牌。如果在任何时候您想要更改它，您只需在一个地方更改，从而确保所有使用该主题令牌的组件的一致性。

要将您自己的设计语言融入 Joy UI 组件，请首先自定义这些令牌，因为每个组件都使用它们。

为此，请始终使用 extendTheme 函数，因为自定义的令牌将被深度合并到默认主题中。在底层，Joy UI 会将令牌转换为 CSS 变量，使您可以通过 theme.vars.* 获取它们，这非常方便，因为您可以使用任何样式解决方案来读取这些 CSS 变量。

import { CssVarsProvider, extendTheme } from '@mui/joy/styles';

const theme = extendTheme({
  colorSchemes: {
    light: {
      palette: {
        // affects all Joy components that has `color="primary"` prop.
        primary: {
          50: '#fffbeb',
          100: '#fef3c7',
          200: '#fde68a',
          // 300, 400, ..., 800,
          900: '#78350f',
        },
      },
    },
  },
  fontFamily: {
    display: 'Inter, var(--joy-fontFamily-fallback)',
    body: 'Inter, var(--joy-fontFamily-fallback)',
  },
});

function App() {
  return <CssVarsProvider theme={theme}>...</CssVarsProvider>;
}

自定义组件

每个 Joy UI 组件都使用预定义的一组主题令牌。例如，默认的小号 Button 默认带有 fontSize: sm。要在更改它的同时确保它的每个实例都具有相同的样式，请直接从主题定位组件进行更改。

这是一个如何将按钮的字体大小更改为大的预览

import { CssVarsProvider, extendTheme } from '@mui/joy/styles';
import Button from '@mui/joy/Button';

const theme = extendTheme({
  components: {
    // The component identifier always start with `Joy${ComponentName}`.
    JoyButton: {
      styleOverrides: {
        root: ({ theme }) => {
          // theme.vars.* return the CSS variables.
          fontSize: theme.vars.fontSize.lg, // 'var(--joy-fontSize-lg)'
        },
      },
    },
  },
});

function MyApp() {
  return (
    <CssVarsProvider theme={theme}>
      <Button>Text</Button>
    </CssVarsProvider>
  );
}

可重用组件

当您没有找到完全符合您需求的内容时，创建新的和自定义的组件始终是一个选择。但是，您可以通过 styled 函数从主题中提取样式，从而确保与其他 Joy UI 组件的设计一致性。

您还可以使用 sx 属性，它也接受主题令牌，来自定义这个新创建的组件。

<ToggleButton
  aria-pressed={muted ? 'true' : 'false'}
  onClick={() => setMuted((bool) => !bool)}
  sx={{ minWidth: 120 }}
>
  Mute {muted ? <VolumeOffRoundedIcon /> : <VolumeUpRoundedIcon />}
</ToggleButton>

<ToggleButton
  aria-pressed={muted ? 'true' : 'false'}
  onClick={() => setMuted((bool) => !bool)}
  sx={{ minWidth: 120 }}
>
  Mute {muted ? <VolumeOffRoundedIcon /> : <VolumeUpRoundedIcon />}
</ToggleButton>

按 Enter 开始编辑