方法

了解在不同情況下，建議使用哪種方法來自訂 Joy UI 組件。

若要僅自訂特定組件的單一實例，請使用 sx 屬性。
為了確保應用程式中每個特定組件的實例看起來都相同，請使用主題。
若要建立 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 鍵開始編輯